XR_ANDROID_enumerate_system_extension_properties

Chaîne de nom

XR_ANDROID_enumerate_system_extension_properties

Type d'extension

Extension d'instance

Numéro d'extension enregistré

725

Révision

1

État de ratification

Non ratifié

Dépendances des extensions et des versions

OpenXR 1.0

Date de dernière modification

2026-02-11

État de l'adresse IP

Aucune réclamation connue pour atteinte à la propriété intellectuelle.

Contributeurs

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

Présentation

Cette extension permet aux applications de déterminer quelles extensions sont compatibles avec la configuration système actuelle. Même si une extension est prise en charge par le runtime, il est possible qu'elle ne soit pas compatible avec le matériel du système actuel.

La structure XrSystemExtensionPropertiesANDROID est définie comme suit :

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

Descriptions des membres

  • type est le XrStructureType de cette structure.
  • next est NULL ou un pointeur vers la structure suivante dans une chaîne de structures.
  • properties est XrExtensionProperties avec le nom de l'extension.
  • isSupported est une valeur booléenne indiquant si l'extension est actuellement prise en charge par le système.

Utilisation valide (implicite)

La structure XrEventDataSystemPropertiesChangedANDROID est définie comme suit :

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

Descriptions des membres

  • type est le XrStructureType de cette structure.
  • next est NULL ou un pointeur vers la structure suivante dans une chaîne de structures.

L'exécution doit mettre en file d'attente cet événement lorsque les propriétés de l'extension système ont changé. Par exemple, lorsque de nouveaux périphériques sont connectés, ce qui permet de nouvelles fonctionnalités.

Tous les appels à xrEnumerateSystemExtensionPropertiesANDROID doivent renvoyer les mêmes valeurs jusqu'à ce qu'un nouvel événement XrEventDataSystemPropertiesChangedANDROID soit mis en file d'attente.

Lorsqu'une application reçoit cet événement, elle doit appeler à nouveau xrEnumerateSystemExtensionPropertiesANDROID pour déterminer les dernières propriétés d'extension système, en créant ou en détruisant éventuellement les trackers associés à ces extensions selon les besoins.

Utilisation valide (implicite)

La fonction xrEnumerateSystemExtensionPropertiesANDROID est définie comme suit :

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

Descriptions des paramètres

  • instance est une XrInstance valide .
  • systemId est un sliink:XrSystemId valide du système pour lequel récupérer les propriétés d'extension.
  • propertyCapacityInput correspond à la capacité du tableau properties ou à 0 pour indiquer une requête visant à récupérer la capacité requise.
  • propertyCountOutput correspond au nombre de propriétés d'extension demandées.
  • properties est un tableau de structures XrSystemExtensionPropertiesANDROID. Elle peut être NULL si propertyCapacityInput est défini sur 0.
  • Pour obtenir une description détaillée de la récupération de la taille properties requise, consultez la section Paramètres de taille du tampon.

Utilisation valide (implicite)

Codes de retour

Opération réussie

  • XR_SUCCESS

Échec

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

Exemple

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

Problèmes

Historique des versions

  • Révision 1, 17/03/2026 (Kenny Vercaemer)

    • Version initiale de l'extension.