XR_ANDROID_enumerate_system_extension_properties

Nazwa ciągu znaków

XR_ANDROID_enumerate_system_extension_properties

Typ rozszerzenia

Rozszerzenie instancji

Zarejestrowany numer rozszerzenia

725

Wersja

1

Stan ratyfikacji

Niezatwierdzone

Zależności rozszerzenia i wersji

OpenXR 1.0

Data ostatniej modyfikacji

2026-02-11

Stan IP

Brak znanych roszczeń dotyczących własności intelektualnej.

Twórcy

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

Przegląd

To rozszerzenie umożliwia aplikacjom określenie, które rozszerzenia są obsługiwane przez bieżącą konfigurację systemu. Nawet jeśli rozszerzenie jest obsługiwane przez środowisko wykonawcze, może nie być obsługiwane przez obecny sprzęt systemowy.

Struktura XrSystemExtensionPropertiesANDROID jest zdefiniowana w ten sposób:

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

Opisy elementów

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur.
  • properties to XrExtensionProperties z nazwą rozszerzenia.
  • isSupported to wartość logiczna wskazująca, czy rozszerzenie jest obecnie obsługiwane przez system.

Prawidłowe użycie (niejawne)

Struktura XrEventDataSystemPropertiesChangedANDROID jest zdefiniowana w ten sposób:

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

Opisy elementów

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur.

Środowisko wykonawcze musi umieścić to zdarzenie w kolejce, gdy zmienią się właściwości rozszerzenia systemu. Na przykład gdy podłączone są nowe urządzenia peryferyjne, które umożliwiają korzystanie z nowych funkcji.

Wszystkie wywołania xrEnumerateSystemExtensionPropertiesANDROID muszą zwracać te same wartości, dopóki nie zostanie umieszczone w kolejce nowe zdarzenie XrEventDataSystemPropertiesChangedANDROID.

Gdy aplikacja otrzyma to zdarzenie, powinna ponownie wywołać xrEnumerateSystemExtensionPropertiesANDROID, aby określić najnowsze właściwości rozszerzenia systemu, ewentualnie tworząc lub niszcząc powiązane z tymi rozszerzeniami śledzenie.

Prawidłowe użycie (niejawne)

Funkcja xrEnumerateSystemExtensionPropertiesANDROID jest zdefiniowana w ten sposób:

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

Opisy parametrów

  • instance to prawidłowa wartość XrInstance .
  • systemId to prawidłowa wartość sliink:XrSystemId systemu, dla którego mają zostać pobrane właściwości rozszerzenia.
  • propertyCapacityInput to pojemność tablicy properties lub 0, aby wskazać prośbę o pobranie wymaganej pojemności.
  • propertyCountOutput to liczba żądanych właściwości rozszerzenia.
  • properties to tablica struktur XrSystemExtensionPropertiesANDROID. Jeśli propertyCapacityInput ma wartość 0, może mieć wartość NULL.
  • Szczegółowy opis pobierania wymaganego rozmiaru properties znajdziesz w sekcji Parametry rozmiaru bufora.

Prawidłowe użycie (niejawne)

Kody powrotu

Sukces

  • XR_SUCCESS

Błąd

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

Przykład

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()
);

Problemy

Historia zmian

  • Wersja 1, 17 marca 2026 r. (Kenny Vercaemer)

    • Pierwsza wersja rozszerzenia.