XR_ANDROID_light_estimation_cubemap

String Nama

XR_ANDROID_light_estimation_cubemap

Jenis Ekstensi

Ekstensi instance

Nomor Ekstensi Terdaftar

722

Revisi

1

Status Ratifikasi

Tidak diratifikasi

Dependensi Ekstensi dan Versi

XR_ANDROID_light_estimation

Tanggal Terakhir Diubah

2025-08-06

Status IP

Tidak ada klaim IP 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. API ini menambahkan dukungan untuk mendapatkan estimasi pencahayaan cubemap, yang memberikan estimasi yang lebih mendetail tentang pencahayaan di lingkungan fisik.

Catatan

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

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 cahaya cubemap.

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

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

Penggunaan yang Valid (Implisit)

• Ekstensi XR_ANDROID_light_estimation_cubemap harus diaktifkan sebelum menggunakan XrSystemCubemapLightEstimationPropertiesANDROID
• type harus XR_TYPE_SYSTEM_CUBEMAP_LIGHT_ESTIMATION_PROPERTIES_ANDROID
• next harus berupa NULL atau pointer yang valid ke struktur berikutnya dalam rantai struktur

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 dapat memilih untuk menggunakan salah satu resolusi yang didukung di XrCubemapLightEstimatorCreateInfoANDROID :: cubemapResolution saat membuat handle estimator cahaya. Aplikasi harus mengalokasikan jumlah memori yang sesuai untuk anggota buffer 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 adalah 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 adalah 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 dapat memilih untuk menggunakan salah satu format warna yang didukung di XrCubemapLightEstimatorCreateInfoANDROID :: colorFormat saat membuat handle estimator cahaya. Aplikasi harus mengalokasikan jumlah memori yang sesuai untuk anggota buffer gambar XrCubemapLightingDataANDROID berdasarkan format warna yang dipilih.

Penggunaan yang Valid (Implisit)

• Ekstensi XR_ANDROID_light_estimation_cubemap harus diaktifkan sebelum memanggil xrEnumerateCubemapLightingColorFormatsANDROID
• instance harus berupa handle XrInstance yang valid
• colorFormatCountOutput harus berupa pointer ke nilai uint32_t
• Jika colorFormatCapacityInput bukan 0 , colorFormats harus berupa pointer ke array nilai XrCubemapLightingColorFormatANDROID colorFormatCapacityInput

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 yang mampu memberikan estimasi pencahayaan cubemap. Anggota XrCubemapLightEstimatorCreateInfoANDROID :: cubemapResolution harus disetel ke salah satu resolusi yang ditampilkan oleh xrEnumerateCubemapLightingResolutionsANDROID . Anggota XrCubemapLightEstimatorCreateInfoANDROID :: colorFormat harus disetel ke salah satu format warna yang ditampilkan oleh xrEnumerateCubemapLightingColorFormatsANDROID . Jika aplikasi tidak menyetel 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)

• Ekstensi XR_ANDROID_light_estimation_cubemap harus diaktifkan sebelum menggunakan XrCubemapLightEstimatorCreateInfoANDROID
• type harus XR_TYPE_CUBEMAP_LIGHT_ESTIMATOR_CREATE_INFO_ANDROID
• next harus berupa NULL atau pointer yang valid ke struktur berikutnya dalam rantai struktur
• colorFormat must berupa nilai XrCubemapLightingColorFormatANDROID yang valid

Estimasi cahaya 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 merepresentasikan status estimasi cahaya.
• imageBufferSize adalah uint32_t yang menunjukkan ukuran byte setiap buffer gambar wajah dalam cubemap.
• imageBufferRight adalah buffer uint8_t yang berisi gambar wajah kanan kubus peta.
• imageBufferLeft adalah buffer uint8_t yang berisi gambar wajah kiri cubemap.
• imageBufferTop adalah buffer uint8_t yang berisi gambar sisi atas cubemap.
• imageBufferBottom adalah buffer uint8_t yang berisi gambar sisi bawah cubemap.
• imageBufferFront adalah buffer uint8_t yang berisi gambar wajah depan cubemap.
• imageBufferBack adalah buffer uint8_t yang berisi gambar sisi belakang cubemap.
• rotation adalah XrQuaternionf yang menunjukkan rotasi cubemap.
• centerExposureTime adalah XrTime yang menunjukkan waktu pengambilan cubemap.

Struktur can ini dapat dirangkai 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 buffer gambar yang bergantung pada nilai yang ditetapkan di XrCubemapLightEstimatorCreateInfoANDROID :: cubemapResolution dan XrCubemapLightEstimatorCreateInfoANDROID :: colorFormat saat membuat handle estimator cahaya. Aplikasi harus menyetel XrCubemapLightingDataANDROID :: imageBufferSize ke kapasitas setiap buffer gambar sisi dalam byte. Jika aplikasi tidak menggunakan estimasi cahaya cubemap atau jika XrCubemapLightingDataANDROID :: imageBufferSize tidak cukup besar bagi runtime untuk mengisi buffer gambar, runtime harus menyetel 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 kubus peta yang dirotasi secara internal diproyeksikan ulang ke wajah kubus peta identitas di ruang dasar aplikasi.

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

Gambar 24. Tata letak cubemap.

Penggunaan yang Valid (Implisit)

• Ekstensi XR_ANDROID_light_estimation_cubemap harus diaktifkan sebelum menggunakan XrCubemapLightingDataANDROID
• type harus 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 cahaya

Contoh kode berikut menunjukkan cara mendapatkan semua kemungkinan kuantitas estimasi cahaya 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

• xrEnumerateCubemapLightingColorFormatsANDROID
• xrEnumerateCubemapLightingResolutionsANDROID

Struktur Baru

• Memperluas XrLightEstimateANDROID :

  • XrCubemapLightingDataANDROID

• Memperluas XrLightEstimatorCreateInfoANDROID :

  • XrCubemapLightEstimatorCreateInfoANDROID

• Memperluas XrSystemProperties :

  • XrSystemCubemapLightEstimationPropertiesANDROID

Enum Baru

• XrCubemapLightingColorFormatANDROID

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