XR_ANDROID_global_passthrough_dimming

String Nama

XR_ANDROID_global_passthrough_dimming

Jenis Ekstensi

Ekstensi instance

Nomor Ekstensi Terdaftar

797

Revisi

1

Status Ratifikasi

Belum diratifikasi

Dependensi Ekstensi dan Versi

OpenXR 1.0

Tanggal Terakhir Diubah

2026-03-10

Status IP

Tidak ada klaim kekayaan intelektual yang diketahui.

Kontributor

Brian Chen, Google
Kyle Chen, Google
Nihav Jain, Google
Spencer Quin, Google

Ringkasan

Saat perangkat tembus pandang optik diperkenalkan, penting untuk tidak hanya mengizinkan aplikasi menyesuaikan kegelapan passthrough guna memberikan perpaduan terbaik dengan konteks aplikasi kepada pengguna, tetapi juga mengizinkan sistem mencerahkan passthrough untuk alasan keamanan.

Ekstensi ini menyediakan dua fungsi bagi aplikasi untuk menetapkan dan mendapatkan tingkat peredupan saat ini, serta peristiwa untuk disiarkan saat tingkat peredupan berubah.

Memeriksa kemampuan sistem

Struktur XrSystemGlobalDimmingPropertiesANDROID didefinisikan sebagai:

typedef struct XrSystemGlobalDimmingPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsGlobalDimming;
} XrSystemGlobalDimmingPropertiesANDROID;

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. Tidak ada struktur seperti itu yang ditentukan dalam OpenXR inti atau ekstensi ini.
  • supportsGlobalDimming adalah XrBool32 , yang menunjukkan apakah sistem saat ini mendukung peredupan global.

Aplikasi dapat memeriksa apakah sistem mendukung peredupan global dengan merantai struktur XrSystemGlobalDimmingPropertiesANDROID ke XrSystemProperties saat memanggil xrGetSystemProperties .

Jika runtime menampilkan XR_FALSE untuk supportsGlobalDimming , runtime harus menampilkan XR_ERROR_FEATURE_UNSUPPORTED saat xrGetGlobalDimmingLevelANDROID dipanggil.

Penggunaan yang Valid (Implisit)

Menghitung tingkat peredupan global yang didukung

Struktur xrEnumerateSupportedGlobalDimmingLevelsANDROID didefinisikan sebagai:

XrResult xrEnumerateSupportedGlobalDimmingLevelsANDROID(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    uint32_t                                    supportedGlobalDimmingLevelCapacityInput,
    uint32_t*                                   supportedGlobalDimmingLevelCountOutput,
    float*                                      supportedGlobalDimmingLevels);

Deskripsi Anggota

  • instance adalah instance tempat systemId diambil.
  • systemId adalah XrSystemId yang tingkat dukungannya akan dihitung.
  • supportedGlobalDimmingLevelCapacityInput adalah kapasitas array supportedGlobalDimmingLevels, atau 0 untuk menunjukkan permintaan guna mengambil kapasitas yang diperlukan.
  • supportedGlobalDimmingLevelCountOutput adalah pointer ke jumlah supportedGlobalDimmingLevels yang ditulis, atau pointer ke kapasitas yang diperlukan jika supportedGlobalDimmingLevelCapacityInput tidak mencukupi.
  • supportedGlobalDimmingLevels adalah pointer ke array level yang didukung, tetapi dapat berupa NULL jika supportedGlobalDimmingLevelCapacityInput adalah 0.

Jika supportedGlobalDimmingLevelCountOutput yang ditampilkan adalah 0, semua tingkat peredupan global antara 0,0 dan 1,0 akan didukung.

xrEnumerateSupportedGlobalDimmingLevelsANDROID menghitung tingkat peredupan global yang didukung oleh XrSystemId . Level yang didukung tidak boleh berubah selama masa aktif XrInstance-nya. Daftar level yang ditampilkan harus diurutkan dalam urutan menaik.

Runtime harus selalu menampilkan konten buffer yang identik dari enumerasi ini untuk systemId tertentu dan selama masa aktif instance .

Penggunaan yang Valid (Implisit)

  • Ekstensi XR_ANDROID_global_passthrough_dimming harus diaktifkan sebelum memanggil xrEnumerateSupportedGlobalDimmingLevelsANDROID
  • instance harus berupa handle XrInstance yang valid
  • supportedGlobalDimmingLevelCountOutput harus berupa pointer ke nilai uint32_t
  • Jika supportedGlobalDimmingLevelCapacityInput bukan 0 , supportedGlobalDimmingLevels harus berupa pointer ke array nilai supportedGlobalDimmingLevelCapacityInput float

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

Mengonfigurasi Tingkat Redup Global

Struktur XrGlobalDimmingFrameEndInfoANDROID didefinisikan sebagai:

typedef struct XrGlobalDimmingFrameEndInfoANDROID {
    XrStructureType    type;
    const void*        next;
    float              globalDimmingLevel;
} XrGlobalDimmingFrameEndInfoANDROID;

Deskripsi Parameter

  • 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.
  • globalDimmingLevel adalah nilai antara 0,0 (transparan) dan 1,0 (buram). Runtime dapat memetakan nilai ini ke tingkat peredupan global terdekat yang didukung. Aplikasi dapat menetapkan nilai ini ke -1,0 untuk menunjukkan bahwa tingkat peredupan saat ini lebih disukai.

Nilai globalDimmingLevel menentukan persentase cahaya yang diblokir, dengan nilai 0,0 berarti 0% pemblokiran cahaya dan 1,0 berarti 100% pemblokiran cahaya. Persentase cahaya yang terhalang dapat direpresentasikan secara umum sebagai:

100% - Light Transmittance%

Persentase transmisi cahaya, menurut ISO 8980-3:2022 , dapat diukur sebagai rasio fluks radiasi yang ditransmisikan terhadap fluks radiasi yang datang pada panjang gelombang cahaya tampak (380 nm hingga 780 nm).

XrGlobalDimmingFrameEndInfoANDROID adalah struktur yang dapat dihubungkan oleh aplikasi di XrFrameEndInfo untuk meminta tingkat peredupan global yang diinginkan.

Runtime harus mematuhi tingkat peredupan yang diminta jika tingkat peredupan yang diminta berbeda dengan tingkat peredupan saat ini.

Runtime akan memiliki kontrol atas tingkat peredupan global dan dapat mengabaikan tingkat peredupan global yang diinginkan karena alasan keamanan.

Penggunaan yang Valid (Implisit)

Fungsi xrGetGlobalDimmingLevelANDROID didefinisikan sebagai:

XrResult xrGetGlobalDimmingLevelANDROID(
    XrSession                                   session,
    float*                                      dimmingLevel);

Deskripsi Parameter

  • session adalah handle XrSession yang valid.
  • dimmingLevel adalah pointer ke tingkat peredupan saat ini.

dimmingLevel yang ditampilkan harus antara 0,0 dan 1,0, dengan 0,0 berarti sepenuhnya transparan dan 1,0 berarti sepenuhnya redup.

Jika tingkat peredupan belum ditetapkan, runtime harus menetapkan tingkat peredupan ke 0,0 saat passthrough diaktifkan dan 1,0 saat passthrough dinonaktifkan.

Penggunaan yang Valid (Implisit)

  • Ekstensi XR_ANDROID_global_passthrough_dimming harus diaktifkan sebelum memanggil xrGetGlobalDimmingLevelANDROID
  • session harus berupa handle XrSession yang valid
  • dimmingLevel harus berupa pointer ke nilai float

Kode Status

Berhasil

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Kegagalan

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

Peristiwa Perubahan Tingkat Peredupan

Struktur XrEventDataGlobalDimmingLevelChangedANDROID didefinisikan sebagai:

typedef struct XrEventDataGlobalDimmingLevelChangedANDROID {
    XrStructureType    type;
    const void*        next;
    XrSession          session;
} XrEventDataGlobalDimmingLevelChangedANDROID;

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.
  • session adalah handle XrSession yang valid.

Aplikasi dapat mengambil peristiwa ini menggunakan xrPollEvent . Peristiwa ini akan dikirim saat tingkat peredupan diubah oleh aplikasi atau tombol fisik di perangkat.

Peristiwa ini tidak akan dikirim saat aplikasi yang difokuskan beralih ke aplikasi lain.

Aplikasi harus merespons peristiwa dengan memanggil xrGetGlobalDimmingLevelANDROID untuk mendapatkan tingkat peredupan baru dan memperbarui XrGlobalDimmingFrameEndInfoANDROID :: globalDimmingLevel. Merespons peristiwa akan menjamin runtime akan diberi sinyal saat aplikasi mengubah tingkat peredupan yang diinginkan.

Penggunaan yang Valid (Implisit)

Kode contoh

Memeriksa kemampuan sistem & Menghitung level peredupan global yang didukung

Kode contoh berikut menunjukkan cara memeriksa apakah peredupan global didukung.

XrInstance instance; // previously initialized
XrSystemId systemId; // previously initialized

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrEnumerateSupportedGlobalDimmingLevelsANDROID xrEnumerateSupportedGlobalDimmingLevelsANDROID;

XrSystemGlobalDimmingPropertiesANDROID dimmingControlSystemProperties { XR_TYPE_SYSTEM_GLOBAL_DIMMING_PROPERTIES_ANDROID };

XrSystemProperties systemProperties; // Chain dimmingControlSystemProperties

// ...
// Run xrGetSystemProperties()
// ...

if (!dimmingControlSystemProperties.supportsGlobalDimming) {
  // The system does not support global dimming
  return;
}

// Enumerate supported levels
uint32_t count = 0;
CHK_XR(xrEnumerateSupportedGlobalDimmingLevelsANDROID(instance, systemId, count, &count, nullptr));

std::vector<float> supportedLevels(count);
CHK_XR(xrEnumerateSupportedGlobalDimmingLevelsANDROID(instance, systemId, count, &count, supportedLevels.data()));

Peristiwa Perubahan Tingkat Peredupan Polling

Contoh kode berikut menunjukkan cara melakukan polling peristiwa perubahan tingkat peredupan.

XrEventDataBuffer event{ XR_TYPE_EVENT_DATA_BUFFER };

// ...
// Run xrPollEvent()
// ...

switch (event.type) {
  // This event will not be sent when focused app switches
  case XR_TYPE_EVENT_DATA_GLOBAL_DIMMING_LEVEL_CHANGED_ANDROID:
  {
    const XrEventDataGlobalDimmingLevelChangedANDROID &dimmingLevelChangedEvent =
            *reinterpret_cast<XrEventDataGlobalDimmingLevelChangedANDROID *>(&event);

    // Query new dimming level using xrGetGlobalDimmingLevelANDROID()
  }
}

Perintah Baru

Struktur Baru

Konstanta Enum Baru

  • XR_ANDROID_GLOBAL_PASSTHROUGH_DIMMING_EXTENSION_NAME
  • XR_ANDROID_global_passthrough_dimming_SPEC_VERSION

  • Memperluas XrStructureType :

    • XR_TYPE_EVENT_DATA_GLOBAL_DIMMING_LEVEL_CHANGED_ANDROID
    • XR_TYPE_GLOBAL_DIMMING_FRAME_END_INFO_ANDROID
    • XR_TYPE_SYSTEM_GLOBAL_DIMMING_PROPERTIES_ANDROID

Masalah

Riwayat Versi

  • Revisi 1, 07-10-2025 (Brian Chen)

    • Deskripsi ekstensi awal.