XR_ANDROID_light_estimation

String Nama

XR_ANDROID_light_estimation

Jenis Ekstensi

Ekstensi instance

Nomor Ekstensi Terdaftar

701

Revisi

1

Status Ratifikasi

Tidak diratifikasi

Dependensi Ekstensi dan Versi

OpenXR 1.0

Tanggal Terakhir Diubah

2025-03-13

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. Aplikasi dapat menggunakan informasi ini untuk menerangi objek virtual dalam kondisi yang sama dengan adegan dunia nyata tempat objek tersebut ditempatkan.

Izin

Aplikasi Android harus mencantumkan izin android.permission.SCENE_UNDERSTANDING_COARSE dalam manifesnya karena ekstensi ini mengekspos informasi pencahayaan tentang lingkungan. Izin android.permission.SCENE_UNDERSTANDING_COARSE dianggap sebagai izin berbahaya. Aplikasi harus meminta izin saat runtime untuk menggunakan fungsi ini:

(tingkat perlindungan: berbahaya)

Memeriksa kemampuan sistem

Struktur XrSystemLightEstimationPropertiesANDROID ditentukan sebagai:

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 dan hanya jika runtime menampilkan XR_FALSE untuk supportsLightEstimation , runtime harus menampilkan XR_ERROR_FEATURE_UNSUPPORTED dari xrCreateLightEstimatorANDROID .

Penggunaan yang Valid (Implisit)

Membuat handle estimator cahaya

XR_DEFINE_HANDLE(XrLightEstimatorANDROID)

Data estimasi cahaya dihasilkan oleh runtime dan dibagikan ke aplikasi menggunakan handle XrLightEstimatorANDROID.

Handle can 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 menggunakan fungsi xrCreateLightEstimatorANDROID untuk membuat estimator cahaya.

  • Runtime harus menampilkan XR_ERROR_FEATURE_UNSUPPORTED jika sistem tidak mendukung estimasi cahaya.
  • Runtime harus menampilkan XR_ERROR_PERMISSION_INSUFFICIENT jika izin yang diperlukan belum diberikan ke aplikasi panggilan.

Jika aplikasi ingin menunjukkan kepada runtime bahwa aplikasi telah selesai mengakses data estimasi cahaya, aplikasi harus menghancurkan handle melalui xrDestroyLightEstimatorANDROID .

Penggunaan yang Valid (Implisit)

Kode Status

Berhasil

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Kegagalan

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

Struktur XrLightEstimatorCreateInfoANDROID menjelaskan informasi untuk membuat handle XrLightEstimatorANDROID.

typedef struct XrLightEstimatorCreateInfoANDROID {
    XrStructureType    type;
    const 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 ditentukan sebagai:

XrResult xrDestroyLightEstimatorANDROID(
    XrLightEstimatorANDROID                     estimator);

Deskripsi Parameter

Fungsi xrDestroyLightEstimatorANDROID melepaskan estimator dan semua resource yang mendasarinya.

Penggunaan yang Valid (Implisit)

Keamanan Thread

  • Akses ke estimator , dan semua handle 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_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

Struktur XrLightEstimateGetInfoANDROID ditentukan sebagai:

typedef struct XrLightEstimateGetInfoANDROID {
    XrStructureType    type;
    const 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 dan harmonik bola yang ditampilkan 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 setiap struct perkiraan cahaya, jika state adalah XR_LIGHT_ESTIMATE_STATE_INVALID_ANDROID, maka semua kolom lain dalam struct bersifat arbitrer, yang berarti nilainya tidak ditentukan.

Untuk mendapatkan informasi perkiraan cahaya untuk cahaya sekitar, harmonik sferis, dan cahaya terarah utama, aplikasi dapat membuat rantai instance dari struktur berikut, XrAmbientLightANDROID, XrSphericalHarmonicsANDROID, dan XrDirectionalLightANDROID masing-masing ke XrLightEstimateANDROID :: next .

Penggunaan yang Valid (Implisit)

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

  • type adalah XrStructureType dari struktur ini.
  • next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur. Struktur yang valid mencakup XrSphericalHarmonicsANDROID dan XrDirectionalLightANDROID .
  • state adalah XrLightEstimateStateANDROID yang merepresentasikan status estimasi cahaya.
  • intensity adalah XrVector3f yang merepresentasikan intensitas cahaya sekitar. Setiap komponen vektor masing-masing sesuai dengan saluran merah, hijau, dan biru.

  • colorCorrection adalah XrVector3f dengan nilai dalam ruang gamma. Jika merender dalam ruang warna gamma, kalikan komponen tersebut dengan warna akhir yang dihitung setelah rendering. Jika merender dalam ruang linear, konversikan terlebih dahulu nilai ke ruang linear dengan menaikkan ke pangkat 2,2, lalu kalikan per komponen dengan warna akhir yang dihitung setelah rendering.

    The purpose of pname:colorCorrection is to make a scene appear natural and
blend with the real world.

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

coefficients akan digunakan dalam fungsi khusus yang mengambil arah sebagai input dan menghasilkan warna cahaya yang berasal dari arah tersebut. Detail selengkapnya tersedia di dokumen ini .

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,
    XR_SPHERICAL_HARMONICS_KIND_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSphericalHarmonicsKindANDROID;

Nilai enumerasi memiliki arti berikut:

Deskripsi Enum

XR_SPHERICAL_HARMONICS_KIND_TOTAL_ANDROID

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

XR_SPHERICAL_HARMONICS_KIND_AMBIENT_ANDROID

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

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 XrLightEstimateStateANDROID menunjukkan status estimasi cahaya yang ditampilkan oleh runtime.

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

Nilai enumerasi memiliki arti berikut:

Deskripsi Enum

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.
PFN_xrCreateLightEstimatorANDROID xrCreateLightEstimatorANDROID; // Created previously.
PFN_xrDestroyLightEstimatorANDROID xrDestroyLightEstimatorANDROID; // Created previously.
PFN_xrGetLightEstimateANDROID xrGetLightEstimateANDROID; // 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 sphericalHarmonics = {
    .type = XR_TYPE_SPHERICAL_HARMONICS_ANDROID,
    .next = &directionalLight,
};

// Querying both TOTAL or AMBIENT spherical harmonics in one call will result in an error because chaining two structs with the same type is not allowed
bool useTotalSH;
if (useTotalSH) {
  sphericalHarmonics.kind = XR_SPHERICAL_HARMONICS_KIND_TOTAL_ANDROID;
} else {
  sphericalHarmonics.kind = XR_SPHERICAL_HARMONICS_KIND_AMBIENT_ANDROID;
}

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

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

Perintah Baru

Struktur Baru

Enum Baru

Konstanta Enum Baru

  • XR_ANDROID_LIGHT_ESTIMATION_EXTENSION_NAME
  • XR_ANDROID_light_estimation_SPEC_VERSION

  • Memperluas XrObjectType :

    • XR_OBJECT_TYPE_LIGHT_ESTIMATOR_ANDROID

  • Memperluas XrStructureType :

    • XR_TYPE_AMBIENT_LIGHT_ANDROID
    • XR_TYPE_DIRECTIONAL_LIGHT_ANDROID
    • XR_TYPE_LIGHT_ESTIMATE_ANDROID
    • XR_TYPE_LIGHT_ESTIMATE_GET_INFO_ANDROID
    • XR_TYPE_LIGHT_ESTIMATOR_CREATE_INFO_ANDROID
    • XR_TYPE_SPHERICAL_HARMONICS_ANDROID
    • XR_TYPE_SYSTEM_LIGHT_ESTIMATION_PROPERTIES_ANDROID

Masalah

Histori Versi

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

    • Deskripsi ekstensi awal