Ekstensi OpenXR XR_ANDROID_light_estimation

String Nama

XR_ANDROID_light_estimation

Jenis Ekstensi

Ekstensi instance

Nomor Ekstensi Terdaftar

701

Revisi

1

Dependensi Ekstensi dan Versi

OpenXR 1.0

Tanggal Terakhir Diubah

2025-01-17

Status IP

Tidak ada klaim IP yang diketahui.

Kontributor

Jared Finder, Google

Cairn Overturf, Google

Spencer Quin, Google

Levana Chen, Google

Nihav Jain, Google

Salar Khan, Google

Scott Chung, Google

Ringkasan

Ekstensi ini memungkinkan aplikasi meminta data yang merepresentasikan pencahayaan lingkungan dunia nyata di sekitar headset. Informasi ini dapat digunakan saat merender objek virtual untuk meneranginya dalam kondisi yang sama dengan adegan tempat objek tersebut ditempatkan.

Memeriksa kemampuan sistem

Aplikasi dapat memeriksa apakah sistem mendukung estimasi cahaya dengan menautkan struktur XrSystemLightEstimationPropertiesANDROID ke XrSystemProperties saat memanggil xrGetSystemProperties. 

typedef struct XrSystemLightEstimationPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsLightEstimation;
} XrSystemLightEstimationPropertiesANDROID;

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.
  • supportsLightEstimation adalah XrBool32, yang menunjukkan apakah sistem saat ini mendukung estimasi cahaya.

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

Jika sistem tidak dapat mendukung estimasi cahaya, sistem akan menampilkan XR_FALSE untuk supportsLightEstimation, dan XR_ERROR_FEATURE_UNSUPPORTED dari xrCreateLightEstimatorANDROID.

Penggunaan yang Valid (Implisit)

Membuat handle estimator cahaya

XR_DEFINE_HANDLE(XrLightEstimatorANDROID)

Handle XrLightEstimatorANDROID merepresentasikan estimator cahaya. Handle ini dapat digunakan untuk mengakses informasi estimasi cahaya menggunakan fungsi lain dalam ekstensi ini.

Fungsi xrCreateLightEstimatorANDROID ditentukan sebagai: 

XrResult xrCreateLightEstimatorANDROID(
    XrSession                                   session,
    XrLightEstimatorCreateInfoANDROID*          createInfo,
    XrLightEstimatorANDROID*                    outHandle);

Deskripsi Parameter

Aplikasi dapat menggunakan fungsi xrCreateLightEstimatorANDROID untuk membuat estimator cahaya.

Handle estimator cahaya yang ditampilkan dapat digunakan dalam panggilan API berikutnya. Jika aplikasi ingin menunjukkan kepada runtime bahwa aplikasi telah selesai mengakses data estimasi cahaya, aplikasi harus menghancurkan handle menggunakan xrDestroyLightEstimatorANDROID.

Penggunaan yang Valid (Implisit)

Kode Status

Berhasil

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Kegagalan

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_LIMIT_REACHED

Struktur XrLightEstimatorCreateInfoANDROID menjelaskan informasi untuk membuat handle XrLightEstimatorANDROID. 

typedef struct XrLightEstimatorCreateInfoANDROID {
    XrStructureType    type;
    void*              next;
} XrLightEstimatorCreateInfoANDROID;

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.

Penggunaan yang Valid (Implisit)

Fungsi xrDestroyLightEstimatorANDROID melepaskan estimator dan resource pokok apa pun. 

XrResult xrDestroyLightEstimatorANDROID(
    XrLightEstimatorANDROID                     estimator);

Deskripsi Parameter

Penggunaan yang Valid (Implisit)

Keamanan Thread

  • Akses ke estimator, dan semua nama sebutan turunannya, harus disinkronkan secara eksternal

Kode Status

Berhasil

  • XR_SUCCESS

Kegagalan

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID

Mengakses data estimasi cahaya

Fungsi xrGetLightEstimateANDROID ditentukan sebagai: 

XrResult xrGetLightEstimateANDROID(
    XrLightEstimatorANDROID                     estimator,
    const XrLightEstimateGetInfoANDROID*        input,
    XrLightEstimateANDROID*                     output);

Deskripsi Parameter

Penggunaan yang Valid (Implisit)

Kode Status

Berhasil

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Kegagalan

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_VALIDATION_FAILURE
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_TIME_INVALID

XrLightEstimateGetInfoANDROID menjelaskan informasi yang diperlukan untuk mendapatkan data perkiraan cahaya. 

typedef struct XrLightEstimateGetInfoANDROID {
    XrStructureType    type;
    void*              next;
    XrSpace            space;
    XrTime             time;
} XrLightEstimateGetInfoANDROID;

Deskripsi Anggota

  • type adalah XrStructureType dari struktur ini.
  • next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur.
  • space adalah XrSpace yang menentukan ruang referensi tempat arah cahaya, harmonik bola, dan rotasi cubemap yang ditampilkan dinyatakan.
  • time adalah XrTime yang menjelaskan waktu saat aplikasi ingin mengkueri estimasi cahaya.

Penggunaan yang Valid (Implisit)

Struktur XrLightEstimateANDROID berisi data estimasi cahaya. 

typedef struct XrLightEstimateANDROID {
    XrStructureType                type;
    void*                          next;
    XrLightEstimateStateANDROID    state;
    XrTime                         lastUpdatedTime;
} XrLightEstimateANDROID;

Deskripsi Anggota

Untuk mendapatkan informasi estimasi cahaya untuk cubemap pencahayaan lingkungan, cahaya sekitar, harmonik sferis, dan cahaya terarah primer, aplikasi dapat merangkai instance dari struktur berikut, XrEnvironmentLightingCubemapANDROID, XrAmbientLightANDROID, XrSphericalHarmonicsANDROID, dan XrDirectionalLightANDROID masing-masing ke XrLightEstimateANDROID::next.

Penggunaan yang Valid (Implisit)

Struktur XrEnvironmentLightingCubemapANDROID berisi data estimasi cahaya dalam format cubemap tentang pencahayaan lingkungan adegan. 

typedef struct XrEnvironmentLightingCubemapANDROID {
    XrStructureType                type;
    void*                          next;
    XrLightEstimateStateANDROID    state;
    const float*                   cubemapRightImage;
    const float*                   cubemapLeftImage;
    const float*                   cubemapTopImage;
    const float*                   cubemapBottomImage;
    const float*                   cubemapFrontImage;
    const float*                   cubemapBackImage;
    uint32_t                       resolution;
    XrQuaternionf                  rotation;
    XrTime                         centerExposureTime;
} XrEnvironmentLightingCubemapANDROID;

Deskripsi Anggota

  • type adalah XrStructureType dari struktur ini.
  • next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur. Struktur yang valid adalah XrSphericalHarmonicsANDROID, XrAmbientLightANDROID, dan XrDirectionalLightANDROID.
  • state adalah XrLightEstimateStateANDROID yang merepresentasikan status perkiraan cahaya.
  • cubemapRightImage adalah float* yang merepresentasikan buffer R32G32B32_SFLOAT di sisi kanan cubemap. Perhatikan bahwa ini adalah HDR sehingga nilai float dapat lebih besar dari 1,0.
  • cubemapLeftImage adalah float* yang merepresentasikan buffer R32G32B32_SFLOAT di sisi kiri cubemap. Perhatikan bahwa ini adalah HDR sehingga nilai float dapat lebih besar dari 1,0.
  • cubemapTopImage adalah float* yang merepresentasikan buffer R32G32B32_SFLOAT dari sisi atas cubemap. Perhatikan bahwa ini adalah HDR sehingga nilai float dapat lebih besar dari 1,0.
  • cubemapBottomImage adalah float* yang merepresentasikan buffer R32G32B32_SFLOAT dari sisi bawah cubemap. Perhatikan bahwa ini adalah HDR sehingga nilai float dapat lebih besar dari 1,0.
  • cubemapFrontImage adalah float* yang merepresentasikan buffer R32G32B32_SFLOAT di sisi depan cubemap. Perhatikan bahwa ini adalah HDR sehingga nilai float dapat lebih besar dari 1,0.
  • resolution adalah uint32_t yang merepresentasikan lebar dan tinggi gambar di setiap sisi cubemap.
  • rotation adalah XrQuaternionf yang merepresentasikan rotasi cubemap.
  • centerExposureTime adalah XrTime yang menunjukkan waktu pengambilan cubemap. Berguna untuk interpolasi antar-cubemap.

Penggunaan yang Valid (Implisit)

  • Ekstensi XR_ANDROID_light_estimation harus diaktifkan sebelum menggunakan XrEnvironmentLightingCubemapANDROID
  • type harus berupa XR_TYPE_ENVIRONMENT_LIGHTING_CUBEMAP_ANDROID
  • next harus berupa NULL atau pointer yang valid ke struktur berikutnya dalam rantai struktur
  • state harus berupa nilai XrLightEstimateStateANDROID yang valid
  • cubemapRightImage harus berupa pointer ke nilai float yang valid
  • cubemapLeftImage harus berupa pointer ke nilai float yang valid
  • cubemapTopImage harus berupa pointer ke nilai float yang valid
  • cubemapBottomImage harus berupa pointer ke nilai float yang valid
  • cubemapFrontImage harus berupa pointer ke nilai float yang valid
  • cubemapBackImage harus berupa pointer ke nilai float yang valid

Struktur XrAmbientLightANDROID berisi data estimasi cahaya tentang cahaya sekitar dalam adegan. 

typedef struct XrAmbientLightANDROID {
    XrStructureType                type;
    void*                          next;
    XrLightEstimateStateANDROID    state;
    XrVector3f                     intensity;
    XrVector3f                     colorCorrection;
} XrAmbientLightANDROID;

Deskripsi Anggota

Penggunaan yang Valid (Implisit)

Struktur XrSphericalHarmonicsANDROID berisi harmonik bola yang merepresentasikan pencahayaan adegan. 

typedef struct XrSphericalHarmonicsANDROID {
    XrStructureType                    type;
    void*                              next;
    XrLightEstimateStateANDROID        state;
    XrSphericalHarmonicsKindANDROID    kind;
    float                              coefficients[9][3];
} XrSphericalHarmonicsANDROID;

Deskripsi Anggota

Penggunaan yang Valid (Implisit)

Struktur XrDirectionalLightANDROID berisi data estimasi cahaya. 

typedef struct XrDirectionalLightANDROID {
    XrStructureType                type;
    void*                          next;
    XrLightEstimateStateANDROID    state;
    XrVector3f                     intensity;
    XrVector3f                     direction;
} XrDirectionalLightANDROID;

Deskripsi Anggota

Penggunaan yang Valid (Implisit)

Enumerasi XrSphericalHarmonicsKindANDROID mengidentifikasi ke runtime, jenis harmonik sferis yang diminta aplikasi. 

typedef enum XrSphericalHarmonicsKindANDROID {
    XR_SPHERICAL_HARMONICS_KIND_TOTAL_ANDROID = 0,
    XR_SPHERICAL_HARMONICS_KIND_AMBIENT_ANDROID = 1
} XrSphericalHarmonicsKindANDROID;

Enum memiliki arti berikut:

Enum

Deskripsi

XR_SPHERICAL_HARMONICS_KIND_TOTAL_ANDROID

Koefisien harmonik bola merepresentasikan fungsi radiasi cahaya lingkungan, termasuk kontribusi dari cahaya utama.

XR_SPHERICAL_HARMONICS_KIND_AMBIENT_ANDROID

Koefisien harmonik bola merepresentasikan fungsi radiasi cahaya lingkungan, tidak termasuk kontribusi dari cahaya utama.

Enumerasi XrLightEstimateStateANDROID mengidentifikasi ke runtime, jenis harmonik sferis yang diminta aplikasi. 

typedef enum XrLightEstimateStateANDROID {
    XR_LIGHT_ESTIMATE_STATE_VALID_ANDROID = 0,
    XR_LIGHT_ESTIMATE_STATE_INVALID_ANDROID = 1
} XrLightEstimateStateANDROID;

Enum memiliki arti berikut:

Enum

Deskripsi

XR_LIGHT_ESTIMATE_STATE_VALID_ANDROID

Estimasi cahaya valid

XR_LIGHT_ESTIMATE_STATE_INVALID_ANDROID

Estimasi cahaya tidak valid

Contoh kode untuk estimasi cahaya

Contoh kode berikut menunjukkan cara mendapatkan semua kemungkinan kuantitas estimasi cahaya dari runtime.

XrSession session;  // Created at app startup
XrSpace appSpace;   // Created previously.

XrLightEstimatorANDROID estimator;
XrLightEstimatorCreateInfoANDROID createInfo = {
    .type = XR_TYPE_LIGHT_ESTIMATOR_CREATE_INFO_ANDROID};
CHK_XR(xrCreateLightEstimatorANDROID(session, &createInfo, &estimator));

// 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,
};

XrDirectionalLightANDROID directionalLight = {
    .type = XR_TYPE_DIRECTIONAL_LIGHT_ANDROID,
};

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

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

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


XrEnvironmentLightingCubemapANDROID lightingCubemap {
    .type = XR_TYPE_ENVIRONMENT_LIGHTING_CUBEMAP_ANDROID,
    .next = &ambientLight,
}

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

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

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

Jenis Objek Baru

  • XrLightEstimator

Enumerasi XrObjectType diperluas dengan:

  • XR_OBJECT_TYPE_LIGHT_ESTIMATOR_ANDROID

Enumerasi XrStructureType diperluas dengan:

  • XR_TYPE_LIGHT_ESTIMATOR_CREATE_INFO_ANDROID
  • XR_TYPE_LIGHT_ESTIMATE_GET_INFO_ANDROID
  • XR_TYPE_LIGHT_ESTIMATE_ANDROID
  • XR_TYPE_DIRECTIONAL_LIGHT_ANDROID
  • XR_TYPE_SPHERICAL_HARMONICS_ANDROID
  • XR_TYPE_AMBIENT_LIGHT_ANDROID
  • XR_TYPE_ENVIRONMENT_LIGHTING_CUBEMAP_ANDROID

Enum Baru

Struktur Baru

Fungsi Baru

Masalah

Histori Versi

  • Revisi 2, 17-01-2025 (Salar Khan)
    • Menambahkan dukungan cubemap pencahayaan sekitar
  • Revisi 1, 16-09-2024 (Cairn Overturf)
    • Deskripsi ekstensi awal

OpenXR™ dan logo OpenXR adalah merek dagang yang dimiliki oleh The Khronos Group Inc. dan terdaftar sebagai merek dagang di China, Uni Eropa, Jepang, dan Inggris Raya.