XR_ANDROID_enumerate_system_extension_properties

Ciąg znaków nazwy

XR_ANDROID_enumerate_system_extension_properties

Typ rozszerzenia

Rozszerzenie instancji

Zarejestrowany numer wewnętrzny

725

Wersja

1

Stan ratyfikacji

Nie ratyfikowano

Zależności rozszerzeń i wersji

OpenXR 1.0

Data ostatniej modyfikacji

2026-02-11

Stan adresu IP

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

Twórcy

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

Omówienie

To rozszerzenie umożliwia aplikacjom określanie, 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 członkó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 (domyślne)

Struktura XrEventDataSystemPropertiesChangedANDROID jest zdefiniowana w ten sposób:

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

Opisy członkó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 systemowego. Na przykład po podłączeniu nowych urządzeń peryferyjnych, które umożliwiają korzystanie z nowych funkcji.

Wszystkie wywołania funkcji 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ć funkcję xrEnumerateSystemExtensionPropertiesANDROID, aby określić najnowsze właściwości rozszerzenia systemu, w razie potrzeby tworząc lub usuwając trackery powiązane z tymi rozszerzeniami.

Prawidłowe użycie (domyślne)

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 jest prawidłową wartością XrInstance .
  • systemId to prawidłowy identyfikator sliink:XrSystemId systemu, z którego mają zostać pobrane właściwości rozszerzenia.
  • propertyCapacityInput to pojemność tablicy properties lub 0, aby wskazać żądanie pobrania wymaganej pojemności.
  • propertyCountOutput to liczba żądanych właściwości rozszerzenia.
  • properties to tablica struktur XrSystemExtensionPropertiesANDROID. Może to być NULL, jeśli propertyCapacityInput wynosi 0.
  • Szczegółowy opis pobierania wymaganego rozmiaru properties znajdziesz w sekcji Parametry rozmiaru bufora.

Prawidłowe użycie (domyślne)

  •  Rozszerzenie XR_ANDROID_enumerate_system_extension_properties musi być włączone przed wywołaniem funkcji xrEnumerateSystemExtensionPropertiesANDROID.
  • instance musi być prawidłowym uchwytem XrInstance.
  • propertyCountOutput musi być wskaźnikiem wartości uint32_t
  •  Jeśli propertyCapacityInput nie jest równe 0 , properties musi być wskaźnikiem do tablicy struktur propertyCapacityInput XrSystemExtensionPropertiesANDROID.

Kody zwrotne

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.03.2026 (Kenny Vercaemer)

    • Początkowa wersja rozszerzenia.