XR_ANDROID_enumerate_system_extension_properties

Name String

XR_ANDROID_enumerate_system_extension_properties

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

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

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

725

Revision

1

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

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

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

OpenXR 1.0

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

2026-02-11

Статус IP-адреса

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

Авторы

Спенсер Куин (Spencer Quin), Google
Нихав Джайн (Nihav Jain), Google
Кенни Веркамер (Kenny Vercaemer), 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 марта 2026 г. (Кенни Веркамер)

    • Исходная версия расширения.