XR_ANDROID_enumerate_system_extension_properties

Строка имени

XR_ANDROID_enumerate_system_extension_properties

Тип расширения

Расширение экземпляра

Зарегистрированный добавочный номер

725

Пересмотр

1

Статус ратификации

Не ратифицировано

Зависимости расширений и версий

OpenXR 1.0

Дата последнего изменения

2026-02-11

Статус IP

Известных претензий на интеллектуальную собственность нет.

Авторы

Спенсер Куин, Google
Нихав Джайн, Google
Кенни Веркамер, Google

Обзор

Это расширение позволяет приложениям определять, какие расширения поддерживаются текущей конфигурацией системы. Даже если расширение поддерживается средой выполнения, оно может не поддерживаться текущим аппаратным обеспечением системы.

Структура XrSystemExtensionPropertiesANDROID определяется следующим образом: 

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

Описание участников

  • type — это XrStructureType данной структуры.
  • next — это NULL или указатель на следующую структуру в цепочке структур.
  • properties — это объект XrExtensionProperties с именем расширения.
  • isSupported — это логическое значение, указывающее, поддерживается ли расширение в данный момент системой.

Допустимое использование (неявное)

Структура XrEventDataSystemPropertiesChangedANDROID определяется следующим образом: 

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

Описание участников

  • type — это XrStructureType данной структуры.
  • next — это NULL или указатель на следующую структуру в цепочке структур.

Среда выполнения должна ставить это событие в очередь, когда изменяются свойства расширения системы. Например, когда подключаются новые периферийные устройства, активирующие новые функции.

Все вызовы функции xrEnumerateSystemExtensionPropertiesANDROID должны возвращать одни и те же значения до тех пор, пока в очередь не будет поставлено новое событие XrEventDataSystemPropertiesChangedANDROID .

Когда приложение получает это событие, оно должно снова вызвать функцию xrEnumerateSystemExtensionPropertiesANDROID , чтобы определить последние свойства системных расширений, при необходимости создавая или уничтожая трекеры, связанные с этими расширениями.

Допустимое использование (неявное)

Функция xrEnumerateSystemExtensionPropertiesANDROID определена следующим образом: 

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

Описание параметров

  • instance является допустимым XrInstance .
  • systemId — это допустимый sliink:XrSystemId системы, для которой необходимо получить свойства расширения.
  • propertyCapacityInput — это емкость массива properties , или 0, указывающее на запрос на получение требуемой емкости.
  • propertyCountOutput — это количество запрошенных дополнительных свойств.
  • properties — это массив структур XrSystemExtensionPropertiesANDROID . Он может быть NULL если propertyCapacityInput равен 0.
  • Подробное описание получения необходимого размера properties см. в разделе « Параметры размера буфера» .

Допустимое использование (неявное)

  • Расширение XR_ANDROID_enumerate_system_extension_properties необходимо включить перед вызовом функции xrEnumerateSystemExtensionPropertiesANDROID.
  • instance должен быть допустимым дескриптором XrInstance.
  • propertyCountOutput должен быть указателем на значение типа uint32_t
  • Если propertyCapacityInput не равно 0 , properties должно быть указателем на массив структур propertyCapacityInput XrSystemExtensionPropertiesANDROID.

Коды возврата

Успех

  • XR_SUCCESS

Отказ

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

Пример 

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

Проблемы

История версий

  • Редакция 1, 17.03.2026 (Кенни Веркамер)

    • Первоначальная версия расширения.