Ekstensi OpenXR XR_ANDROID_light_estimation

String Nama

XR_ANDROID_light_estimation

Jenis Ekstensi

Ekstensi instance

Registered Extension Number

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 mewakili 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 mengaitkan 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 di 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 nama sebutan pengestima cahaya

XR_DEFINE_HANDLE(XrLightEstimatorANDROID)

Nama sebutan XrLightEstimatorANDROID mewakili estimator cahaya. ID 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 mungkin akan digunakan dalam panggilan API. Jika aplikasi ingin menunjukkan ke 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 di OpenXR inti atau ekstensi ini.

Penggunaan yang Valid (Implisit)

Fungsi xrDestroyLightEstimatorANDROID merilis estimator dan resource pokok apa pun. 

XrResult xrDestroyLightEstimatorANDROID(
    XrLightEstimatorANDROID                     estimator);

Deskripsi Parameter

Penggunaan yang Valid (Implisit)

Keamanan Thread

  • Akses ke estimator, dan setiap nama sebutan turunan, 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 estimasi 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 yang ditampilkan, harmonik sferis, dan rotasi cubemap diekspresikan.
  • time adalah XrTime yang menjelaskan waktu saat aplikasi ingin membuat kueri 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 ambient, harmonik sferis, dan cahaya directional utama, aplikasi dapat membuat rantai instance 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 tampilan. 

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 mewakili status estimasi cahaya.
  • cubemapRightImage adalah float* yang mewakili buffering R32G32B32_SFLOAT di sisi kanan cubemap. Perhatikan bahwa ini adalah HDR sehingga nilai float dapat lebih besar dari 1,0.
  • cubemapLeftImage adalah float* yang mewakili buffer R32G32B32_SFLOAT dari sisi kiri cubemap. Perhatikan bahwa ini adalah HDR sehingga nilai float dapat lebih besar dari 1,0.
  • cubemapTopImage adalah float* yang mewakili buffering R32G32B32_SFLOAT dari sisi atas cubemap. Perhatikan bahwa ini adalah HDR sehingga nilai float dapat lebih besar dari 1,0.
  • cubemapBottomImage adalah float* yang mewakili buffering R32G32B32_SFLOAT dari sisi bawah cubemap. Perhatikan bahwa ini adalah HDR sehingga nilai float dapat lebih besar dari 1,0.
  • cubemapFrontImage adalah float* yang mewakili buffering R32G32B32_SFLOAT dari sisi depan cubemap. Perhatikan bahwa ini adalah HDR sehingga nilai float dapat lebih besar dari 1,0.
  • resolution adalah uint32_t yang mewakili lebar dan tinggi gambar setiap sisi cubemap. Perhatikan bahwa ini adalah HDR sehingga nilai float dapat lebih besar dari 1,0.
  • rotation adalah XrQuaternionf yang mewakili rotasi cubemap.
  • centerExposureTime adalah XrTime yang mewakili waktu cubemap diambil. Berguna untuk interpolasi di antara 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 di tampilan. 

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

Deskripsi Anggota

Penggunaan yang Valid (Implisit)

Struktur XrSphericalHarmonicsANDROID berisi harmonik sfera yang mewakili pencahayaan tampilan. 

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 harmonis bola merepresentasikan fungsi radian cahaya lingkungan, tidak termasuk kontribusi dari cahaya utama.

XR_SPHERICAL_HARMONICS_KIND_AMBIENT_ANDROID

Koefisien harmonis bola merepresentasikan fungsi radian cahaya lingkungan, 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

Kode contoh berikut menunjukkan cara mendapatkan semua kemungkinan jumlah 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 lingkungan
  • Revisi 1, 16-09-2024 (Cairn Overturf)
    • Deskripsi ekstensi awal