XR_ANDROID_light_estimation_cubemap

String Nama

XR_ANDROID_light_estimation_cubemap

Jenis Ekstensi

Ekstensi instance

Nomor Ekstensi Terdaftar

722

Revisi

1

Status Ratifikasi

Belum diratifikasi

Dependensi Ekstensi dan Versi

XR_ANDROID_light_estimation

Tanggal Terakhir Diubah

2025-08-06

Status IP

Tidak ada klaim kekayaan intelektual yang diketahui.

Kontributor

Salar Khan, Google
Scott Chung, Google
Jared Finder, Google
Spencer Quin, Google
Levana Chen, Google
Nihav Jain, Google
Jürgen Sturm, Google

Ringkasan

Ekstensi ini dibuat berdasarkan ekstensi XR_ANDROID_light_estimation dasar. Fitur ini menambahkan dukungan untuk mendapatkan estimasi pencahayaan cubemap, yang memberikan estimasi lebih mendetail tentang pencahayaan di lingkungan fisik.

Catatan

Mekanisme untuk mendapatkan data estimasi pencahayaan sama dengan ekstensi dasar, kecuali bahwa XrCubemapLightEstimatorCreateInfoANDROID harus dihubungkan ke XrLightEstimatorCreateInfoANDROID saat membuat handle estimator pencahayaan.

Memeriksa kemampuan sistem

typedef struct XrSystemCubemapLightEstimationPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsCubemapLightEstimation;
} XrSystemCubemapLightEstimationPropertiesANDROID;

Deskripsi Anggota

  • type adalah XrStructureType dari struktur ini.
  • next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur. Tidak ada struktur seperti itu yang ditentukan dalam OpenXR inti atau ekstensi ini.
  • supportsCubemapLightEstimation adalah XrBool32 , yang menunjukkan apakah sistem saat ini mendukung estimasi pencahayaan cubemap.

Aplikasi dapat memeriksa apakah sistem mampu mendukung estimasi pencahayaan cubemap dengan memperluas XrSystemProperties dengan struktur XrSystemCubemapLightEstimationPropertiesANDROID saat memanggil xrGetSystemProperties .

Jika runtime menampilkan XR_FALSE untuk supportsCubemapLightEstimation dan XrCubemapLightEstimatorCreateInfoANDROID telah dihubungkan ke XrLightEstimatorCreateInfoANDROID , runtime harus menampilkan XR_ERROR_FEATURE_UNSUPPORTED dari xrCreateLightEstimatorANDROID .

Penggunaan yang Valid (Implisit)

Mendapatkan resolusi cubemap yang didukung

XrResult xrEnumerateCubemapLightingResolutionsANDROID(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    uint32_t                                    resolutionCapacityInput,
    uint32_t*                                   resolutionCountOutput,
    uint32_t*                                   resolutions);

Deskripsi Parameter

  • instance adalah XrInstance yang dibuat sebelumnya.
  • systemId adalah XrSystemId yang sebelumnya diambil oleh xrGetSystem untuk mendapatkan resolusi cubemap yang didukung.
  • resolutionCapacityInput adalah uint32_t yang menunjukkan jumlah maksimum elemen yang dapat disimpan dalam array resolutions.
  • resolutionCountOutput adalah pointer ke uint32_t yang ditetapkan oleh runtime yang menunjukkan jumlah elemen yang ditulis ke array resolutions oleh runtime.
  • resolutions adalah array uint32_t yang diisi oleh runtime dengan resolusi cubemap yang didukung.

Resolusi cubemap menunjukkan lebar dan tinggi setiap sisi cubemap dalam piksel. Idiom 2 panggilan Aplikasi kemudian dapat memilih untuk menggunakan salah satu resolusi yang didukung di XrCubemapLightEstimatorCreateInfoANDROID :: cubemapResolution saat membuat handle estimator pencahayaan. Aplikasi harus mengalokasikan jumlah memori yang sesuai untuk anggota buffering gambar XrCubemapLightingDataANDROID berdasarkan resolusi yang dipilih dan format warna.

Penggunaan yang Valid (Implisit)

  • Ekstensi XR_ANDROID_light_estimation_cubemap harus diaktifkan sebelum memanggil xrEnumerateCubemapLightingResolutionsANDROID
  • instance harus berupa handle XrInstance yang valid
  • resolutionCountOutput harus berupa pointer ke nilai uint32_t
  • Jika resolutionCapacityInput bukan 0 , resolutions harus berupa pointer ke array nilai resolutionCapacityInput uint32_t

Kode Status

Berhasil

  • XR_SUCCESS

Kegagalan

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SYSTEM_INVALID
  • XR_ERROR_VALIDATION_FAILURE

Mendapatkan format warna cubemap yang didukung

Enumerasi XrCubemapLightingColorFormatANDROID mengidentifikasi ke runtime, format warna pencahayaan cubemap yang akan digunakan.

typedef enum XrCubemapLightingColorFormatANDROID {
    XR_CUBEMAP_LIGHTING_COLOR_FORMAT_R32G32B32_SFLOAT_ANDROID = 1,
    XR_CUBEMAP_LIGHTING_COLOR_FORMAT_R32G32B32A32_SFLOAT_ANDROID = 2,
    XR_CUBEMAP_LIGHTING_COLOR_FORMAT_R16G16B16A16_SFLOAT_ANDROID = 3,
    XR_CUBEMAP_LIGHTING_COLOR_FORMAT_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrCubemapLightingColorFormatANDROID;

Enum memiliki arti berikut:

Deskripsi Enum

XR_CUBEMAP_LIGHTING_COLOR_FORMAT_R32G32B32_SFLOAT_ANDROID

Format warna dengan 3 saluran, yang setiap salurannya merupakan nilai floating point 32-bit.

XR_CUBEMAP_LIGHTING_COLOR_FORMAT_R32G32B32A32_SFLOAT_ANDROID

Format warna dengan 4 saluran, yang setiap salurannya adalah nilai floating point 32-bit.

XR_CUBEMAP_LIGHTING_COLOR_FORMAT_R16G16B16A16_SFLOAT_ANDROID

Format warna dengan 4 saluran, yang setiap salurannya merupakan nilai floating point 16-bit.

XrResult xrEnumerateCubemapLightingColorFormatsANDROID(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    uint32_t                                    colorFormatCapacityInput,
    uint32_t*                                   colorFormatCountOutput,
    XrCubemapLightingColorFormatANDROID*        colorFormats);

Deskripsi Parameter

  • instance adalah XrInstance yang dibuat sebelumnya.
  • systemId adalah XrSystemId yang sebelumnya diambil oleh xrGetSystem untuk mendapatkan resolusi cubemap yang didukung.
  • colorFormatCapacityInput adalah uint32_t yang menunjukkan jumlah maksimum elemen yang dapat disimpan dalam array colorFormats.
  • colorFormatCountOutput adalah pointer ke uint32_t yang ditetapkan oleh runtime yang menunjukkan jumlah elemen yang ditulis ke array colorFormats oleh runtime.
  • colorFormats adalah array XrCubemapLightingColorFormatANDROID yang diisi oleh runtime dengan format warna cubemap yang didukung.

Idiom 2 panggilan Aplikasi kemudian dapat memilih untuk menggunakan salah satu format warna yang didukung di XrCubemapLightEstimatorCreateInfoANDROID :: colorFormat saat membuat handle estimator pencahayaan. Aplikasi harus mengalokasikan jumlah memori yang sesuai untuk anggota buffering gambar XrCubemapLightingDataANDROID berdasarkan format warna yang dipilih.

Penggunaan yang Valid (Implisit)

Kode Status

Berhasil

  • XR_SUCCESS

Kegagalan

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SYSTEM_INVALID
  • XR_ERROR_VALIDATION_FAILURE

Membuat handle estimator cahaya cubemap

typedef struct XrCubemapLightEstimatorCreateInfoANDROID {
    XrStructureType                        type;
    const void*                            next;
    uint32_t                               cubemapResolution;
    XrCubemapLightingColorFormatANDROID    colorFormat;
    XrBool32                               reproject;
} XrCubemapLightEstimatorCreateInfoANDROID;

Deskripsi Anggota

  • type adalah XrStructureType dari struktur ini.
  • next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur.
  • cubemapResolution adalah uint32_t yang menunjukkan resolusi pencahayaan cubemap yang akan digunakan.
  • colorFormat adalah XrCubemapLightingColorFormatANDROID yang menunjukkan format warna data pencahayaan cubemap yang akan digunakan.
  • reproject adalah XrBool32 yang menunjukkan apakah pencahayaan cubemap harus diproyeksikan ulang ke ruang dasar aplikasi.

Struktur XrCubemapLightEstimatorCreateInfoANDROID menjelaskan informasi untuk membuat handle XrLightEstimatorANDROID agar dapat memberikan estimasi pencahayaan cubemap. Anggota XrCubemapLightEstimatorCreateInfoANDROID :: cubemapResolution harus ditetapkan ke salah satu resolusi yang ditampilkan oleh xrEnumerateCubemapLightingResolutionsANDROID . Anggota XrCubemapLightEstimatorCreateInfoANDROID :: colorFormat harus ditetapkan ke salah satu format warna yang ditampilkan oleh xrEnumerateCubemapLightingColorFormatsANDROID . Jika aplikasi tidak menetapkan resolusi ke salah satu resolusi yang didukung atau format warna ke salah satu format warna yang didukung, runtime harus menampilkan XR_ERROR_FEATURE_UNSUPPORTED dari xrCreateLightEstimatorANDROID .

Penggunaan yang Valid (Implisit)

Estimasi pencahayaan peta kubus

typedef struct XrCubemapLightingDataANDROID {
    XrStructureType                type;
    void*                          next;
    XrLightEstimateStateANDROID    state;
    uint32_t                       imageBufferSize;
    uint8_t*                       imageBufferRight;
    uint8_t*                       imageBufferLeft;
    uint8_t*                       imageBufferTop;
    uint8_t*                       imageBufferBottom;
    uint8_t*                       imageBufferFront;
    uint8_t*                       imageBufferBack;
    XrQuaternionf                  rotation;
    XrTime                         centerExposureTime;
} XrCubemapLightingDataANDROID;

Deskripsi Anggota

  • type adalah XrStructureType dari struktur ini.
  • next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur. Struktur yang valid adalah XrAmbientLightANDROID , XrSphericalHarmonicsANDROID , XrDirectionalLightANDROID .
  • state adalah XrLightEstimateStateANDROID yang mewakili status estimasi pencahayaan.
  • imageBufferSize adalah uint32_t yang menunjukkan ukuran byte setiap buffer gambar sisi dalam cubemap.
  • imageBufferRight adalah buffering uint8_t yang berisi gambar wajah kanan cubemap.
  • imageBufferLeft adalah buffer uint8_t yang berisi gambar sisi kiri cubemap.
  • imageBufferTop adalah buffering uint8_t yang berisi gambar permukaan atas cubemap.
  • imageBufferBottom adalah buffering uint8_t yang berisi gambar permukaan bawah cubemap.
  • imageBufferFront adalah buffer uint8_t yang berisi gambar sisi depan cubemap.
  • imageBufferBack adalah buffering uint8_t yang berisi gambar sisi belakang cubemap.
  • rotation adalah XrQuaternionf yang menunjukkan rotasi cubemap.
  • centerExposureTime adalah XrTime yang menunjukkan waktu cubemap diambil.

Struktur ini dapat dihubungkan ke XrLightEstimateANDROID . Runtime harus hanya mengisi struktur ini di xrGetLightEstimateANDROID jika XrCubemapLightEstimatorCreateInfoANDROID digunakan untuk membuat handle estimator cahaya. Aplikasi harus mengalokasikan jumlah memori yang sesuai untuk buffering gambar yang bergantung pada nilai yang ditetapkan di XrCubemapLightEstimatorCreateInfoANDROID :: cubemapResolution dan XrCubemapLightEstimatorCreateInfoANDROID :: colorFormat saat membuat handle estimator cahaya. Aplikasi harus menetapkan XrCubemapLightingDataANDROID :: imageBufferSize ke kapasitas setiap buffer gambar sisi dalam byte. Jika aplikasi tidak menggunakan estimasi pencahayaan cubemap atau jika XrCubemapLightingDataANDROID :: imageBufferSize tidak cukup besar untuk runtime mengisi buffer gambar, runtime harus menetapkan XrCubemapLightingDataANDROID :: state ke XR_LIGHT_ESTIMATE_STATE_INVALID_ANDROID .

Jika aplikasi menetapkan XrCubemapLightEstimatorCreateInfoANDROID :: reproject ke XR_TRUE saat membuat handle estimator cahaya, runtime harus menetapkan XrCubemapLightingDataANDROID :: rotation ke rotasi identitas dan memastikan cubemap yang diputar secara internal diproyeksikan ulang ke permukaan cubemap identitas di ruang dasar aplikasi.

Tata letak cubemap pencahayaan sama dengan tata letak cubemap OpenGL, seperti yang ditunjukkan pada gambar berikut

Tata letak cubemap estimasi pencahayaan XR ANDROID

Gambar 31. Tata letak peta kubus.

Penggunaan yang Valid (Implisit)

  • Ekstensi XR_ANDROID_light_estimation_cubemap harus diaktifkan sebelum menggunakan XrCubemapLightingDataANDROID
  • type harus berupa XR_TYPE_CUBEMAP_LIGHTING_DATA_ANDROID
  • next harus berupa NULL atau pointer yang valid ke struktur berikutnya dalam rantai struktur
  • state harus berupa nilai XrLightEstimateStateANDROID yang valid
  • imageBufferRight harus berupa pointer ke array nilai imageBufferSize uint8_t
  • imageBufferLeft harus berupa pointer ke array nilai imageBufferSize uint8_t
  • imageBufferTop harus berupa pointer ke array nilai imageBufferSize uint8_t
  • imageBufferBottom harus berupa pointer ke array nilai imageBufferSize uint8_t
  • imageBufferFront harus berupa pointer ke array nilai imageBufferSize uint8_t
  • imageBufferBack harus berupa pointer ke array nilai imageBufferSize uint8_t
  • Parameter imageBufferSize harus lebih besar dari 0

Contoh kode untuk estimasi pencahayaan

Kode contoh berikut menunjukkan cara mendapatkan semua kemungkinan jumlah estimasi pencahayaan dari runtime

XrSession session;  // Created at app startup
XrInstance instance; // Created at app startup
XrSpace appSpace;   // Created previously.
XrSystemId systemId; // Retrieved previously by xrGetSystem
PFN_xrCreateLightEstimatorANDROID xrCreateLightEstimatorANDROID; // Created previously.
PFN_xrDestroyLightEstimatorANDROID xrDestroyLightEstimatorANDROID; // Created previously.
PFN_xrGetLightEstimateANDROID xrGetLightEstimateANDROID; // Created previously.
PFN_xrEnumerateCubemapLightingResolutionsANDROID xrEnumerateCubemapLightingResolutionsANDROID; // Created previously.
PFN_xrEnumerateCubemapLightingColorFormatsANDROID xrEnumerateCubemapLightingColorFormatsANDROID; // Created previously.

XrSystemCubemapLightEstimationPropertiesANDROID props = {
  .type = XR_TYPE_SYSTEM_CUBEMAP_LIGHT_ESTIMATION_PROPERTIES_ANDROID};
XrSystemProperties base = {.type = XR_TYPE_SYSTEM_PROPERTIES,
                           .next = &props};
CHK_XR(xrGetSystemProperties(instance, systemId, &base));
if (!props.supportsCubemapLightEstimation) {
   // Cubemap light estimation is not supported
}

uint32_t cubemapResolution = 0;
std::vector<uint32_t> supportedCubemapResolutions;
uint32_t resolutionCount;
CHK_XR(xrEnumerateCubemapLightingResolutionsANDROID(
  instance, systemId, 0, &resolutionCount, nullptr));
supportedCubemapResolutions.resize(resolutionCount);
if (resolutionCount == 0) {
  // No cubemap lighting supported
} else {
  CHK_XR(xrEnumerateCubemapLightingResolutionsANDROID(
    instance, systemId, 0, &resolutionCount, supportedCubemapResolutions.data()));
  cubemapResolution = supportedCubemapResolutions[0];
}

uint32_t pixelCount = cubemapResolution * cubemapResolution;

XrCubemapLightingColorFormatANDROID colorFormat;
std::vector<XrCubemapLightingColorFormatANDROID> supportedColorFormats;
uint32_t colorFormatCount;
CHK_XR(xrEnumerateCubemapLightingColorFormatsANDROID(
  instance, systemId, 0, &colorFormatCount, nullptr));
supportedColorFormats.resize(colorFormatCount);
if (colorFormatCount == 0) {
  // No supported color formats for cubemap lighting. Cannot use cubemap
  // light estimation.
} else {
  CHK_XR(xrEnumerateCubemapLightingColorFormatsANDROID(
    instance, systemId, 0, &colorFormatCount, supportedColorFormats.data()));
  colorFormat = supportedColorFormats[0];
}

uint32_t pixelSize = 0;
switch (colorFormat) {
  case XR_CUBEMAP_LIGHTING_COLOR_FORMAT_R32G32B32_SFLOAT_ANDROID:
    pixelSize = 3 * sizeof(float);
    break;
  case XR_CUBEMAP_LIGHTING_COLOR_FORMAT_R32G32B32A32_SFLOAT_ANDROID:
    pixelSize = 4 * sizeof(float);
    break;
  case XR_CUBEMAP_LIGHTING_COLOR_FORMAT_R16G16B16A16_SFLOAT_ANDROID:
    pixelSize = 4 * sizeof(uint16_t);
    break;
  default:
    // Should not happen since the color format was validated previously.
    break;
}

uint32_t perFaceImageBufferSize = pixelCount * pixelSize;

XrLightEstimatorANDROID estimator;
XrCubemapLightEstimatorCreateInfoANDROID cubemapCreateInfo = {
    .type = XR_TYPE_CUBEMAP_LIGHT_ESTIMATOR_CREATE_INFO_ANDROID,
    .cubemapResolution = cubemapResolution,
    .colorFormat = colorFormat,
    .reproject = XR_TRUE
};
XrLightEstimatorCreateInfoANDROID basicCreateInfo = {
    .type = XR_TYPE_LIGHT_ESTIMATOR_CREATE_INFO_ANDROID,
    .next = &cubemapCreateInfo};
CHK_XR(xrCreateLightEstimatorANDROID(session, &basicCreateInfo, &estimator));

std::vector<uint8_t> cubemapBuffer(perFaceImageBufferSize * 6); // 6 faces * perFaceImageBufferSize

// Every frame
XrTime updateTime;  // Time used for the current frame's simulation update.

XrLightEstimateGetInfoANDROID info = {
    .type = XR_TYPE_LIGHT_ESTIMATE_GET_INFO_ANDROID,
    .space = appSpace,
    .time = updateTime,
};

XrCubemapLightingDataANDROID cubemap = {
    .type = XR_TYPE_CUBEMAP_LIGHTING_DATA_ANDROID,
    .next = nullptr,
    .imageBufferSize = perFaceImageBufferSize,
    .imageBufferRight = cubemapBuffer.data() + 0 * perFaceImageBufferSize,
    .imageBufferLeft = cubemapBuffer.data() + 1 * perFaceImageBufferSize,
    .imageBufferTop = cubemapBuffer.data() + 2 * perFaceImageBufferSize,
    .imageBufferBottom = cubemapBuffer.data() + 3 * perFaceImageBufferSize,
    .imageBufferFront = cubemapBuffer.data() + 4 * perFaceImageBufferSize,
    .imageBufferBack = cubemapBuffer.data() + 5 * perFaceImageBufferSize,
};

XrDirectionalLightANDROID directionalLight = {
    .type = XR_TYPE_DIRECTIONAL_LIGHT_ANDROID,
    .next = &cubemap,
};

XrSphericalHarmonicsANDROID totalSh = {
    .type = XR_TYPE_SPHERICAL_HARMONICS_ANDROID,
    .next = &directionalLight,
    .kind = XR_SPHERICAL_HARMONICS_KIND_TOTAL_ANDROID,
};

XrSphericalHarmonicsANDROID ambientSh = {
    .type = XR_TYPE_SPHERICAL_HARMONICS_ANDROID,
    .next = &totalSh,
    .kind = XR_SPHERICAL_HARMONICS_KIND_AMBIENT_ANDROID,
};

XrAmbientLightANDROID ambientLight = {
    .type = XR_TYPE_AMBIENT_LIGHT_ANDROID,
    .next = &ambientSh,
};

XrLightEstimateANDROID estimate = {
    .type = XR_TYPE_LIGHT_ESTIMATE_ANDROID,
    .next = &ambientLight,
};

XrResult result = xrGetLightEstimateANDROID(estimator, &info, &estimate);
if (result == XR_SUCCESS &&
    estimate.state == XR_LIGHT_ESTIMATE_STATE_VALID_ANDROID) {
  // use cubemap, directionalLight, totalSh, ambientSh, and
  // ambientLight if each struct has a valid state field

  if (cubemap.state == XR_LIGHT_ESTIMATE_STATE_VALID_ANDROID) {
    // use cubemap
    if (cubemapCreateInfo.reproject == XR_TRUE) {
      XrQuaternionf identityQuaternion = {0.0f, 0.0f, 0.0f, 1.0f};
      assert(memcmp(&cubemap.rotation, &identityQuaternion, sizeof(XrQuaternionf)) == 0);
    }
  }
}

// When you want to disable light estimation
CHK_XR(xrDestroyLightEstimatorANDROID(estimator));

Perintah Baru

Struktur Baru

Enum Baru

Konstanta Enum Baru

  • XR_ANDROID_LIGHT_ESTIMATION_CUBEMAP_EXTENSION_NAME
  • XR_ANDROID_light_estimation_cubemap_SPEC_VERSION

  • Memperluas XrStructureType :

    • XR_TYPE_CUBEMAP_LIGHTING_DATA_ANDROID
    • XR_TYPE_CUBEMAP_LIGHT_ESTIMATOR_CREATE_INFO_ANDROID
    • XR_TYPE_SYSTEM_CUBEMAP_LIGHT_ESTIMATION_PROPERTIES_ANDROID

Masalah

Histori Versi

  • Revisi 1, 05-12-2025 (Salar Khan)

    • Deskripsi ekstensi awal