XR_ANDROID_enumerate_system_extension_properties

String Nama

XR_ANDROID_enumerate_system_extension_properties

Jenis Ekstensi

Ekstensi instance

Nomor Ekstensi Terdaftar

725

Revisi

1

Status Ratifikasi

Tidak diratifikasi

Dependensi Ekstensi dan Versi

OpenXR 1.0

Tanggal Terakhir Diubah

2026-02-11

Status IP

Tidak ada klaim IP yang diketahui.

Kontributor

Spencer Quin, Google
Nihav Jain, Google
Kenny Vercaemer, Google

Ringkasan

Ekstensi ini memungkinkan aplikasi menentukan ekstensi mana yang didukung oleh konfigurasi sistem saat ini. Meskipun ekstensi didukung oleh runtime, ekstensi tersebut mungkin tidak didukung oleh hardware sistem saat ini.

Struktur XrSystemExtensionPropertiesANDROID ditentukan sebagai:

typedef struct XrSystemExtensionPropertiesANDROID {
    XrStructureType          type;
    void*                    next;
    XrExtensionProperties    properties;
    XrBool32                 isSupported;
} XrSystemExtensionPropertiesANDROID;

Deskripsi Anggota

  • type adalah XrStructureType dari struktur ini.
  • next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur.
  • properties adalah XrExtensionProperties dengan nama ekstensi.
  • isSupported adalah boolean yang menunjukkan apakah ekstensi saat ini didukung oleh sistem.

Penggunaan yang Valid (Implisit)

Struktur XrEventDataSystemPropertiesChangedANDROID ditentukan sebagai:

typedef struct XrEventDataSystemPropertiesChangedANDROID {
    XrStructureType    type;
    const void*        next;
} XrEventDataSystemPropertiesChangedANDROID;

Deskripsi Anggota

  • type adalah XrStructureType dari struktur ini.
  • next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur.

Runtime harus mengantrekan peristiwa ini saat properti ekstensi sistem telah berubah. Misalnya, saat periferal baru terhubung, fungsi baru akan diaktifkan.

Semua panggilan ke xrEnumerateSystemExtensionPropertiesANDROID harus menampilkan nilai yang sama hingga peristiwa XrEventDataSystemPropertiesChangedANDROID baru dimasukkan dalam antrean.

Saat menerima peristiwa ini, aplikasi harus memanggil xrEnumerateSystemExtensionPropertiesANDROID lagi untuk menentukan properti ekstensi sistem terbaru, yang mungkin membuat atau menghancurkan pelacak yang terkait dengan ekstensi tersebut sesuai kebutuhan.

Penggunaan yang Valid (Implisit)

Fungsi xrEnumerateSystemExtensionPropertiesANDROID ditentukan sebagai:

XrResult xrEnumerateSystemExtensionPropertiesANDROID(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    uint32_t                                    propertyCapacityInput,
    uint32_t*                                   propertyCountOutput,
    XrSystemExtensionPropertiesANDROID*         properties);

Deskripsi Parameter

  • instance adalah XrInstance yang valid .
  • systemId adalah sliink:XrSystemId yang valid dari sistem untuk mengambil properti ekstensi.
  • propertyCapacityInput adalah kapasitas array properties, atau 0 untuk menunjukkan permintaan guna mengambil kapasitas yang diperlukan.
  • propertyCountOutput adalah jumlah properti ekstensi yang diminta.
  • properties adalah array struktur XrSystemExtensionPropertiesANDROID. Nilainya dapat berupa NULL jika propertyCapacityInput adalah 0.
  • Lihat bagian Parameter Ukuran Buffer untuk mengetahui deskripsi mendetail tentang pengambilan ukuran properties yang diperlukan.

Penggunaan yang Valid (Implisit)

Kode Status

Berhasil

  • XR_SUCCESS

Kegagalan

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SYSTEM_INVALID
  • XR_ERROR_VALIDATION_FAILURE

Contoh

XrInstance instance; // XrInstance previously created

XrSystemId systemId; // XrSystemId from a previously created instance

PFN_xrEnumerateSystemExtensionPropertiesANDROID xrEnumerateSystemExtensionPropertiesANDROID;

// Poll events for recommended resolution changes.
XrEventDataBuffer event = {XR_TYPE_EVENT_DATA_BUFFER};
XrResult result = xrPollEvent(instance, &event);

if (result == XR_SUCCESS) {
    switch (event.type) {
        case XR_TYPE_EVENT_DATA_SYSTEM_PROPERTIES_CHANGED_ANDROID:
            // It's possible that the system was lost and a new id will be returned
            XrSystemId newSystemId;
            XrSystemGetInfo getInfo = {XR_TYPE_SYSTEM_GET_INFO};
            getInfo.formFactor = XR_FORM_FACTOR_HEAD_MOUNTED_DISPLAY;
            if(XR_SUCCESS == xrGetSystem(instance, &getInfo, &newSystemId)) {
                if(systemId != newSystemId) {
                    //Do things like recreate the session
                    systemId = newSystemId;
                }
            }

            // Enumerate the extensions to see which ones are now supported based on hardware changes
            uint32_t extensionsCount;
            xrEnumerateSystemExtensionPropertiesANDROID(instance, systemId, 0, &extensionsCount, NULL);

            std::vector<XrSystemExtensionPropertiesANDROID> properties(extensionsCount,
                {.type = XR_TYPE_SYSTEM_EXTENSION_PROPERTIES_ANDROID});

            XrResult result = xrEnumerateSystemExtensionPropertiesANDROID(
                instance,
                systemId,
                extensionsCount,
                &extensionsCount,
                properties.data()
            );

            // Do something based on which extensions are now supported by the system
            break;
    }
}

PFN_xrEnumerateSystemExtensionPropertiesANDROID xrEnumerateSystemExtensionPropertiesANDROID;

XrInstance instance;
XrInstanceCreateInfo createInfo = {XR_TYPE_INSTANCE_CREATE_INFO};
// Initialize the createInfo with appropriate values for the application
CHK_XR(xrCreateInstance(&createInfo, &instance));

// Get the systemId for the system.
XrSystemId systemId;
XrSystemGetInfo getInfo = {XR_TYPE_SYSTEM_GET_INFO};
getInfo.formFactor = XR_FORM_FACTOR_HEAD_MOUNTED_DISPLAY;
CHK_XR(xrGetSystem(instance, &getInfo, &systemId));

// Enumerate the system extension properties.
uint32_t extensionsCount;
xrEnumerateSystemExtensionPropertiesANDROID(instance, systemId, 0, &extensionsCount, NULL);

std::vector<XrSystemExtensionPropertiesANDROID> properties(extensionsCount,
    {.type = XR_TYPE_SYSTEM_EXTENSION_PROPERTIES_ANDROID});

XrResult result = xrEnumerateSystemExtensionPropertiesANDROID(
    instance,
    systemId,
    extensionsCount,
    &extensionsCount,
    properties.data()
);

Masalah

Histori Versi

  • Revisi 1, 17-03-2026 (Kenny Vercaemer)

    • Versi ekstensi awal.