XR_ANDROID_enumerate_system_extension_properties

String de nome

XR_ANDROID_enumerate_system_extension_properties

Tipo de extensão

Extensão de instância

Número de extensão registrada

725

Revisão

1

Status de ratificação

Não ratificado

Dependências de extensão e versão

OpenXR 1.0

Data da última modificação

2026-02-11

Status de IP

Nenhuma reivindicação de IP conhecida.

Colaboradores

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

Visão geral

Essa extensão permite que os aplicativos determinem quais extensões são compatíveis com a configuração atual do sistema. Mesmo que uma extensão seja compatível com o ambiente de execução, ela pode não ser compatível com o hardware do sistema atual.

A estrutura XrSystemExtensionPropertiesANDROID é definida como:

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

Descrições de membros

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas.
  • properties é o XrExtensionProperties com o nome da extensão.
  • isSupported é um booleano que indica se a extensão é compatível com o sistema.

Uso válido (implícito)

A estrutura XrEventDataSystemPropertiesChangedANDROID é definida como:

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

Descrições de membros

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas.

O ambiente de execução precisa enfileirar esse evento quando as propriedades da extensão do sistema mudarem. Por exemplo, quando novos periféricos são conectados, ativando novas funcionalidades.

Todas as chamadas para xrEnumerateSystemExtensionPropertiesANDROID precisam retornar os mesmos valores até que um novo evento XrEventDataSystemPropertiesChangedANDROID seja enfileirado.

Quando um aplicativo recebe esse evento, ele precisa chamar xrEnumerateSystemExtensionPropertiesANDROID novamente para determinar as propriedades mais recentes da extensão do sistema, possivelmente criando ou destruindo rastreadores associados a essas extensões, conforme necessário.

Uso válido (implícito)

A função xrEnumerateSystemExtensionPropertiesANDROID é definida como:

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

Descrições dos parâmetros

  • instance é um XrInstance válido .
  • systemId é um sliink:XrSystemId válido do sistema para recuperar as propriedades da extensão.
  • propertyCapacityInput é a capacidade da matriz properties ou 0 para indicar uma solicitação para recuperar a capacidade necessária.
  • propertyCountOutput é o número de propriedades de extensão solicitadas.
  • properties é uma matriz de estruturas XrSystemExtensionPropertiesANDROID. Ela pode ser NULL se propertyCapacityInput for 0.
  • Consulte a seção Parâmetros de tamanho do buffer para uma descrição detalhada da recuperação do tamanho properties necessário.

Uso válido (implícito)

Códigos de retorno

Sucesso

  • XR_SUCCESS

Falha

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

Exemplo

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

Problemas

Histórico de versões

  • Revisão 1, 17/03/2026 (Kenny Vercaemer)

    • Versão inicial da extensão.