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

2024-09-18

Status IP

Tidak ada klaim IP yang diketahui.

Kontributor

Jared Finder, Google

Cairn Overturf, Google

Spencer Quin, Google

Levana Chen, Google

Nihav Jain, 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 semacam 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 semacam 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 dan harmonik sferis dinyatakan.
  • 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 cahaya ambient, harmonik bola, dan cahaya terarah utama, aplikasi dapat membuat rantai instance struktur berikut, XrAmbientLightANDROID, XrSphericalHarmonicsANDROID, dan XrDirectionalLightANDROID masing-masing ke XrLightEstimateANDROID::next.

Penggunaan yang Valid (Implisit)

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

  • type adalah XrStructureType dari struktur ini.
  • next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur. Struktur yang valid adalah XrSphericalHarmonicsANDROID dan XrDirectionalLightANDROID.
  • state adalah XrLightEstimateStateANDROID yang mewakili status estimasi cahaya.
  • intensity adalah XrVector3 yang mewakili intensitas cahaya sekitar. Setiap komponen vektor sesuai dengan saluran merah, hijau, dan biru.
  • colorCorrection adalah XrVector3 dengan nilai dalam ruang gamma. Komponen-komponennya akan mengalikan warna render yang dikoreksi gamma dengan nilai ini.

Penggunaan yang Valid (Implisit)

Struktur XrSphericalHarmonicsANDROID berisi harmoni sferis 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,
};

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 directionalLight, totalSh, ambientSh, ambientLight 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

Enum Baru

Struktur Baru

Fungsi Baru

Masalah

Histori Versi

  • Revisi 1, 16-09-2024 (Cairn Overturf)
    • Deskripsi ekstensi awal