XR_ANDROID_spatial_annotation_tracking
Chaîne de nom
XR_ANDROID_spatial_annotation_tracking
Type d'extension
Extension d'instance
Numéro d'extension enregistré
795
Révision
1
État de ratification
Non ratifié
Dépendances des extensions et des versions
XR_EXT_spatial_entity
et
XR_EXT_spatial_image_tracking
Date de dernière modification
2026-01-12
État de l'adresse IP
Aucune réclamation connue pour atteinte à la propriété intellectuelle.
Contributeurs
Levana Chen, Google
Christopher Feil, Google
Martin Sundermeyer, Google
David Joseph Tan, Google
Jared Finder, Google
Nihav Jain, Google
Présentation
Cette extension permet de suivre les annotations de l'extension XR_EXT_spatial_entity pour suivre différentes annotations dans la scène. Elle permet aux applications de superposer des éléments sur des objets physiques ou virtuels définis par des références d'exécution.
Cette extension fournit un type d'annotation de base "Quad", qui est un polygone à quatre côtés exactement, c'est-à-dire un quadrilatère convexe, représentant un cadre de sélection 2D généralisé dans une référence d'exécution. Une annotation de quad suivie est représentée sous la forme d'une entité spatiale avec (ou "qui comporte") les composants suivants :
XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID
Les applications peuvent généralement utiliser l'extension de suivi des annotations spatiales selon les modèles suivants :
- Une application crée d'abord un handle XrSpatialReferenceCacheANDROID qui commence à enregistrer les références d'exécution à partir de la source donnée.
- L'application capture ensuite une référence d'exécution de XrSpatialReferenceImageEXT et définit une annotation souhaitée dans la référence pendant la période du cache de référence.
- L'application crée ensuite un handle XrSpatialContextEXT basé sur XrSpatialReferenceImageEXT fourni par XrSpatialCapabilityConfigurationAnnotationTrackingANDROID .
- L'application peut détruire le handle XrSpatialReferenceCacheANDROID pour arrêter l'enregistrement des références d'exécution afin de réduire l'utilisation de la mémoire, ou attendre l'événement
XR_TYPE_EVENT_DATA_SPATIAL_ANNOTATION_TRACKING_ANDROIDpour confirmer le résultat de l'initialisation. - L'application extrait ensuite l'événement
XR_TYPE_EVENT_DATA_SPATIAL_ANNOTATION_TRACKING_ANDROIDpour confirmer le résultat de l'initialisation de l'annotation. - Si l'initialisation réussit, l'application peut ensuite extraire l'événement
XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXTpour suivre l'annotation. - Si l'initialisation échoue, l'application peut utiliser le code d'erreur renvoyé dans l'événement pour déterminer la raison de l'échec et détruire le handle XrSpatialContextEXT existant pour démarrer une nouvelle annotation.
- Quel que soit le résultat de l'initialisation, l'application peut libérer le tampon d'image pour réduire l'utilisation de la mémoire après avoir reçu l'événement.
- L'application découvre et interroge les annotations en fonction des modèles d'accès aux entités spatiales.
- L'application peut créer un handle XrSpatialContextEXT supplémentaire pour suivre les annotations dans une nouvelle référence pendant la période de validité d'un XrSpatialReferenceCacheANDROID .
- L'application peut détruire les handles XrSpatialContextEXT pour réduire l'ensemble des annotations détectables et suivables de manière dynamique au moment de l'exécution.
Compatibilité des environnements d'exécution
Un moteur d'exécution doit annoncer sa compatibilité avec la fonctionnalité de suivi des annotations à l'aide de xrEnumerateSpatialCapabilitiesEXT en listant la fonctionnalité suivante :
XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID
Lorsque l'environnement d'exécution est compatible avec la fonctionnalité de suivi des annotations :
- Il doit prendre en charge au moins un composant d'annotation en listant les composants d'annotation compatibles via xrEnumerateSpatialCapabilityComponentTypesEXT .
- Il doit être compatible avec au moins l'un des formats XrSpatialReferenceImageFormatEXT , en listant les formats de référence compatibles via xrEnumerateSpatialReferenceImageFormatsEXT avec
capabilitydéfini surXR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID. - Il doit prendre en charge au moins l'une des XrSpatialAnnotationReferenceSourceANDROID , en listant les sources de référence prises en charge via xrEnumerateSpatialAnnotationReferenceSourcesANDROID avec le paramètre
capabilitydéfini surXR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID.
La fonction xrEnumerateSpatialAnnotationReferenceSourcesANDROID est définie comme suit :
XrResult xrEnumerateSpatialAnnotationReferenceSourcesANDROID(
XrInstance instance,
XrSystemId systemId,
XrSpatialCapabilityEXT capability,
uint32_t sourceCapacityInput,
uint32_t* sourceCountOutput,
XrSpatialAnnotationReferenceSourceANDROID* sources);
Descriptions des paramètres
instanceest un handle vers une XrInstance .systemIdcorrespond à l'XrSystemIddont les sources de référence seront énumérées.capabilityest la XrSpatialCapabilityEXT pour laquelle les sources de référence seront énumérées.sourceCapacityInputcorrespond à la capacité du tableausourcesou à 0 pour indiquer une requête visant à récupérer la capacité requise.sourceCountOutputcorrespond au nombre de sources ou à la capacité requise sisourceCapacityInputest insuffisant.sourcesest un tableau de XrSpatialAnnotationReferenceSourceANDROID . Elle peut êtreNULLsisourceCapacityInputest défini sur 0.- Pour obtenir une description détaillée de la récupération de la taille
sourcesrequise, consultez la section Paramètres de taille du tampon.
L'application peut énumérer la liste des sources de référence compatibles avec un XrSystemId donné à l'aide de xrEnumerateSpatialAnnotationReferenceSourcesANDROID .
L'exécution ne doit pas énumérer les sources de référence dont l'extension n'est pas activée pour instance .
Utilisation valide (implicite)
- L'extension
XR_ANDROID_spatial_annotation_trackingdoit être activée avant d'appeler xrEnumerateSpatialAnnotationReferenceSourcesANDROID. -
instancedoit être un handle XrInstance valide -
capabilitydoit être une valeur XrSpatialCapabilityEXT valide. -
sourceCountOutputmust être un pointeur vers une valeuruint32_t - Si
sourceCapacityInputn'est pas0,sourcesdoit être un pointeur vers un tableau de valeurssourceCapacityInputXrSpatialAnnotationReferenceSourceANDROID.
Codes de retour
XR_SUCCESS
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_RUNTIME_FAILUREXR_ERROR_SIZE_INSUFFICIENTXR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXTXR_ERROR_SYSTEM_INVALIDXR_ERROR_VALIDATION_FAILURE
typedef enum XrSpatialAnnotationReferenceSourceANDROID {
XR_SPATIAL_ANNOTATION_REFERENCE_SOURCE_CAMERA_ANDROID = 0,
XR_SPATIAL_ANNOTATION_REFERENCE_SOURCE_MEDIA_PROJECTION_ANDROID = 1,
XR_SPATIAL_ANNOTATION_REFERENCE_SOURCE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSpatialAnnotationReferenceSourceANDROID;
L'énumération XrSpatialAnnotationReferenceSourceANDROID décrit la source de la référence qui fournit les métadonnées d'une annotation.
Les énumérations ont les significations suivantes :
Description de l'enum
XR_SPATIAL_ANNOTATION_REFERENCE_SOURCE_CAMERA_ANDROID
L'image de référence est une image non recadrée générée par une API d'appareil photo Android, par exemple une image provenant d'un ImageReader associé à un CameraDevice Camera2 ou un ImageProxy provenant d'une ImageAnalysis associée à CameraX. Il s'agit généralement de l'une des caméras RVB orientées vers l'avant.
XR_SPATIAL_ANNOTATION_REFERENCE_SOURCE_MEDIA_PROJECTION_ANDROID
L'image de référence est une image non recadrée générée par l'API Android MediaProjection, par exemple une image provenant d'un ImageReader associé à un écran virtuel MediaProjection. Il peut inclure du contenu virtuel et réel.
La structure XrSystemSpatialAnnotationPropertiesANDROID est définie comme suit :
typedef struct XrSystemSpatialAnnotationPropertiesANDROID {
XrStructureType type;
void* next;
uint32_t referenceCacheTimespan;
uint32_t maxReferencePixelWidth;
uint32_t maxReferencePixelHeight;
uint32_t maxReferenceCount;
uint32_t maxAnnotationCount;
} XrSystemSpatialAnnotationPropertiesANDROID;
Descriptions des membres
typeest le XrStructureType de cette structure.nextestNULLou un pointeur vers la structure suivante dans une chaîne de structures.referenceCacheTimespanindique la durée en secondes d'un handle XrSpatialReferenceCacheANDROID valide.maxReferencePixelWidthindique la largeur maximale du bord des images de référence en pixels.maxReferencePixelHeightindique la hauteur maximale du bord des images de référence en pixels.maxReferenceCountindique le nombre maximal d'images de référence à allouer en même temps.maxAnnotationCountindique le nombre maximal d'annotations à suivre en même temps.
Lorsque le runtime est compatible avec la fonctionnalité de suivi des annotations, une application peut inspecter les propriétés système pertinentes en chaînant une structure XrSystemSpatialAnnotationPropertiesANDROID à XrSystemProperties lors de l'appel de xrGetSystemProperties .
Si XrSpatialReferenceImageEXT :: width de XrSpatialCapabilityConfigurationAnnotationTrackingANDROID :: reference dépasse maxReferencePixelWidth , le runtime doit renvoyer XR_ERROR_VALIDATION_FAILURE lors de l'appel de xrCreateSpatialContextAsyncEXT .
Si XrSpatialReferenceImageEXT :: height de XrSpatialCapabilityConfigurationAnnotationTrackingANDROID :: reference dépasse maxReferencePixelHeight , le runtime doit renvoyer XR_ERROR_VALIDATION_FAILURE lors de l'appel de xrCreateSpatialContextAsyncEXT .
Si XrSpatialCapabilityConfigurationAnnotationTrackingANDROID :: time se trouve en dehors de la période de XrSpatialReferenceCacheANDROID :: cache , le runtime doit renvoyer XR_ERROR_TIME_INVALID lors de l'appel de xrCreateSpatialContextAsyncEXT . L'application peut recréer le handle XrSpatialContextEXT avec une nouvelle référence pendant la période XrSpatialReferenceCacheANDROID .
Si le nombre d'images de référence allouées dépasse maxReferenceCount , le runtime doit renvoyer XR_ERROR_LIMIT_REACHED et indiquer l'échec de l'initialisation via XrEventDataSpatialAnnotationTrackingANDROID :: initializationResult . L'application peut détruire le handle XrSpatialContextEXT et réessayer une fois l'initialisation en attente terminée.
Si le nombre d'annotations actives dépasse maxAnnotationCount , le runtime doit renvoyer XR_ERROR_VALIDATION_FAILURE lors de l'appel de xrCreateSpatialContextAsyncEXT .
Utilisation valide (implicite)
- L'extension
XR_ANDROID_spatial_annotation_trackingdoit être activée avant d'utiliser XrSystemSpatialAnnotationPropertiesANDROID. -
typedoit êtreXR_TYPE_SYSTEM_SPATIAL_ANNOTATION_PROPERTIES_ANDROID. -
nextdoit êtreNULLou un pointeur valide vers la structure suivante dans une chaîne de structures.
Cache de référence d'exécution
XR_DEFINE_HANDLE(XrSpatialReferenceCacheANDROID)
Le handle XrSpatialReferenceCacheANDROID représente un cache de références d'exécution enregistrées à partir d'une source donnée.
La fonction xrCreateSpatialReferenceCacheAsyncANDROID est définie comme suit :
XrResult xrCreateSpatialReferenceCacheAsyncANDROID(
XrSession session,
const XrSpatialReferenceCacheCreateInfoANDROID* createInfo,
XrFutureEXT* future);
Descriptions des paramètres
sessionest une XrSession dans laquelle le cache de référence sera actif.createInfoest un pointeur vers un XrSpatialReferenceCacheCreateInfoANDROID utilisé pour spécifier les paramètres du cache de référence.futureest un pointeur vers le handle de sortie d'unXrFutureEXT.
L'application peut créer un handle XrSpatialReferenceCacheANDROID en appelant xrCreateSpatialReferenceCacheAsyncANDROID . L'environnement d'exécution peut prendre un certain temps pour initialiser les services de suivi. L'application peut ensuite appeler xrCreateSpatialReferenceCacheCompleteANDROID à plusieurs reprises pour vérifier la fin de cette opération asynchrone.
Le temps d'exécution doit renvoyer XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT si XrSpatialReferenceCacheCreateInfoANDROID :: capability n'est pas listé par xrEnumerateSpatialCapabilitiesEXT .
Le runtime doit renvoyer XR_ERROR_FEATURE_UNSUPPORTED si XrSpatialReferenceCacheCreateInfoANDROID :: source n'est pas listé par xrEnumerateSpatialAnnotationReferenceSourcesANDROID pour la fonctionnalité donnée.
L'application ne peut créer qu'un seul handle par source pour une fonctionnalité donnée. Sinon, le runtime doit renvoyer XR_ERROR_LIMIT_REACHED .
L'application peut ensuite capturer les références d'exécution pendant la durée du handle XrSpatialReferenceCacheANDROID pour configurer un nouveau handle XrSpatialContextEXT.
Utilisation valide (implicite)
- L'extension
XR_ANDROID_spatial_annotation_trackingdoit être activée avant d'appeler xrCreateSpatialReferenceCacheAsyncANDROID. -
sessiondoit être un handle XrSession valide -
createInfomust être un pointeur vers une structure XrSpatialReferenceCacheCreateInfoANDROID valide -
futuremust être un pointeur vers une valeurXrFutureEXT
Codes de retour
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FEATURE_UNSUPPORTEDXR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_LIMIT_REACHEDXR_ERROR_OUT_OF_MEMORYXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXTXR_ERROR_VALIDATION_FAILURE
La structure XrSpatialReferenceCacheCreateInfoANDROID est définie comme suit :
typedef struct XrSpatialReferenceCacheCreateInfoANDROID {
XrStructureType type;
const void* next;
XrSpatialCapabilityEXT capability;
XrSpatialAnnotationReferenceSourceANDROID source;
} XrSpatialReferenceCacheCreateInfoANDROID;
Descriptions des membres
typeest le XrStructureType de cette structure.nextestNULLou un pointeur vers la structure suivante dans une chaîne de structures. Aucune structure de ce type n'est définie dans l'extension ni dans le cœur d'OpenXR.capabilityest un XrSpatialCapabilityEXT décrivant la capacité pour laquelle le cache de référence est créé.sourceest un XrSpatialAnnotationReferenceSourceANDROID décrivant la source du cache de référence.
La structure XrSpatialReferenceCacheCreateInfoANDROID décrit les informations permettant de créer un handle XrSpatialReferenceCacheANDROID.
Utilisation valide (implicite)
- L'extension
XR_ANDROID_spatial_annotation_trackingdoit être activée avant d'utiliser XrSpatialReferenceCacheCreateInfoANDROID. -
typedoit êtreXR_TYPE_SPATIAL_REFERENCE_CACHE_CREATE_INFO_ANDROID. -
nextdoit êtreNULLou un pointeur valide vers la structure suivante dans une chaîne de structures. -
capabilitydoit être une valeur XrSpatialCapabilityEXT valide. -
sourcemust be a valid XrSpatialAnnotationReferenceSourceANDROID value
La fonction xrCreateSpatialReferenceCacheCompleteANDROID est définie comme suit :
XrResult xrCreateSpatialReferenceCacheCompleteANDROID(
XrSession session,
XrFutureEXT future,
XrCreateSpatialReferenceCacheCompletionANDROID* completion);
Descriptions des paramètres
sessionest la XrSession précédemment transmise à xrCreateSpatialReferenceCacheAsyncANDROID :session.futurecorrespond àXrFutureEXTreçu de xrCreateSpatialReferenceCacheAsyncANDROID ::future.completionest un pointeur vers un XrCreateSpatialReferenceCacheCompletionANDROID .
L'application peut appeler xrCreateSpatialReferenceCacheCompleteANDROID pour attendre la fin de l'opération asynchrone lancée par xrCreateSpatialReferenceCacheAsyncANDROID .
L'exécution doit renvoyer XR_ERROR_FUTURE_PENDING_EXT si future n'est pas prêt. L'exécution doit renvoyer XR_ERROR_FUTURE_INVALID_EXT si future a déjà été effectuée ou annulée.
Utilisation valide (implicite)
- L'extension
XR_ANDROID_spatial_annotation_trackingdoit être activée avant d'appeler xrCreateSpatialReferenceCacheCompleteANDROID. -
sessiondoit être un handle XrSession valide -
completionmust être un pointeur vers une structure XrCreateSpatialReferenceCacheCompletionANDROID.
Codes de retour
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FEATURE_UNSUPPORTEDXR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_FUTURE_INVALID_EXTXR_ERROR_FUTURE_PENDING_EXTXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_LIMIT_REACHEDXR_ERROR_OUT_OF_MEMORYXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_VALIDATION_FAILURE
La structure XrCreateSpatialReferenceCacheCompletionANDROID est définie comme suit :
typedef struct XrCreateSpatialReferenceCacheCompletionANDROID {
XrStructureType type;
void* next;
XrResult futureResult;
XrSpatialReferenceCacheANDROID referenceCache;
} XrCreateSpatialReferenceCacheCompletionANDROID;
Descriptions des membres
typeest le XrStructureType de cette structure.nextestNULLou un pointeur vers la structure suivante dans une chaîne de structures. Aucune structure de ce type n'est définie dans l'extension ni dans le cœur d'OpenXR.futureResultest le XrResult de l'opération de création du cache de référence.referenceCacheest le handle XrSpatialReferenceCacheANDROID si l'opération réussit.
Codes de retour futurs
Valeurs futureResult :
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FEATURE_UNSUPPORTEDXR_ERROR_RUNTIME_FAILUREXR_ERROR_INSTANCE_LOSTXR_ERROR_SESSION_LOSTXR_ERROR_OUT_OF_MEMORYXR_ERROR_LIMIT_REACHED
Si futureResult est un code de réussite, le runtime doit renvoyer un handle referenceCache valide. Si referenceCache est valide, il ne le reste que pendant la durée de vie de xrCreateSpatialReferenceCacheAsyncANDROID :: session ou jusqu'à ce que l'application détruise le handle avec xrDestroySpatialReferenceCacheANDROID, selon la première éventualité.
Lorsque referenceCache est valide, il enregistre les caches dans XrSystemSpatialAnnotationPropertiesANDROID :: referenceCacheTimespan .
Utilisation valide (implicite)
- L'extension
XR_ANDROID_spatial_annotation_trackingdoit être activée avant d'utiliser XrCreateSpatialReferenceCacheCompletionANDROID. -
typedoit êtreXR_TYPE_CREATE_SPATIAL_REFERENCE_CACHE_COMPLETION_ANDROID. -
nextdoit êtreNULLou un pointeur valide vers la structure suivante dans une chaîne de structures. -
futureResultmust être une valeur XrResult valide -
referenceCachemust be a valid XrSpatialReferenceCacheANDROID handle
La fonction xrDestroySpatialReferenceCacheANDROID est définie comme suit :
XrResult xrDestroySpatialReferenceCacheANDROID(
XrSpatialReferenceCacheANDROID cacheHandle);
Descriptions des paramètres
cacheHandleest un XrSpatialReferenceCacheANDROID précédemment créé par xrCreateSpatialReferenceCacheAsyncANDROID .
L'application peut appeler la fonction xrDestroySpatialReferenceCacheANDROID pour libérer le handle cacheHandle et les ressources sous-jacentes une fois la création du contexte spatial terminée.
Utilisation valide (implicite)
- L'extension
XR_ANDROID_spatial_annotation_trackingdoit être activée avant d'appeler xrDestroySpatialReferenceCacheANDROID. -
cacheHandlemust be a valid XrSpatialReferenceCacheANDROID handle
Sécurité des threads
- L'accès à
cacheHandleet à tous les identifiants enfants doit être synchronisé en externe.
Codes de retour
XR_SUCCESS
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALID
Configuration
La structure XrSpatialCapabilityConfigurationAnnotationTrackingANDROID est définie comme suit :
typedef struct XrSpatialCapabilityConfigurationAnnotationTrackingANDROID {
XrStructureType type;
const void* next;
XrSpatialCapabilityEXT capability;
uint32_t enabledComponentCount;
const XrSpatialComponentTypeEXT* enabledComponents;
XrSpatialReferenceCacheANDROID cache;
XrTime time;
XrSpatialReferenceImageEXT reference;
} XrSpatialCapabilityConfigurationAnnotationTrackingANDROID;
Descriptions des membres
typeest le XrStructureType de cette structure.nextestNULLou un pointeur vers la structure suivante dans une chaîne de structures.capabilityest une XrSpatialCapabilityEXT et doit êtreXR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID.enabledComponentCountest unuint32_tdécrivant le nombre d'éléments dans le tableauenabledComponents.enabledComponentsest un pointeur vers un tableau de XrSpatialComponentTypeEXT .cacheest un XrSpatialReferenceCacheANDROID précédemment créé pour enregistrer les références d'exécution de la configurationreference.timecorrespond auXrTimeauquel lereferenceest capturé.referenceest une XrSpatialReferenceImageEXT avec des annotations chaînées à son pointeur suivant.
Les applications peuvent activer la fonctionnalité spatiale XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID en ajoutant un pointeur à la structure XrSpatialCapabilityConfigurationAnnotationTrackingANDROID dans XrSpatialContextCreateInfoEXT :: capabilityConfigs .
L'exécution doit renvoyer XR_ERROR_VALIDATION_FAILURE si capability n'est pas XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID .
L'exécution doit renvoyer XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT si reference ne contient aucune annotation.
Le runtime doit renvoyer XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT si le composant d'annotation est listé dans enabledComponents, mais qu'aucune annotation correspondante n'est associée à reference .
Le runtime doit renvoyer XR_ERROR_VALIDATION_FAILURE si cache n'appartient pas à la même XrSession qui est transmise à xrCreateSpatialContextAsyncEXT .
L'exécution doit renvoyer XR_ERROR_TIME_INVALID si time est en dehors de la période de cache .
Utilisation valide (implicite)
- L'extension
XR_ANDROID_spatial_annotation_trackingdoit être activée avant d'utiliser XrSpatialCapabilityConfigurationAnnotationTrackingANDROID. -
typedoit êtreXR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_ANNOTATION_TRACKING_ANDROID. -
nextdoit êtreNULLou un pointeur valide vers la structure suivante dans une chaîne de structures. -
capabilitydoit être une valeur XrSpatialCapabilityEXT valide. -
enabledComponentsdoit être un pointeur vers un tableau deenabledComponentCountvaleurs XrSpatialComponentTypeEXT valides. -
cachemust be a valid XrSpatialReferenceCacheANDROID handle -
referencemust be a valid XrSpatialReferenceImageEXT structure - Le paramètre
enabledComponentCountdoit être supérieur à0
Événements de suivi des annotations
La structure XrEventDataSpatialAnnotationTrackingANDROID est définie comme suit :
typedef struct XrEventDataSpatialAnnotationTrackingANDROID {
XrStructureType type;
const void* next;
XrSpatialContextEXT spatialContext;
uint32_t annotationIndex;
XrResult initializationResult;
} XrEventDataSpatialAnnotationTrackingANDROID;
Descriptions des membres
typeest le XrStructureType de cette structure.nextestNULLou un pointeur vers la structure suivante dans une chaîne de structures.spatialContextest le XrSpatialContextEXT pour lequel le suivi des annotations a été activé.annotationIndexcorrespond à l'index du tableau d'annotations associé à XrSpatialCapabilityConfigurationAnnotationTrackingANDROID ::reference.initializationResultindique le résultat de l'initialisation de l'annotation. Si ce n'est pas le cas , l'application peut détruire et recréer le handle XrSpatialContextEXT pour réinitialiser l'annotation, ou continuer à utiliserspatialContextpour suivre d'autres annotations.XR_SUCCESS
Utilisation valide (implicite)
- L'extension
XR_ANDROID_spatial_annotation_trackingdoit être activée avant d'utiliser XrEventDataSpatialAnnotationTrackingANDROID. -
typedoit êtreXR_TYPE_EVENT_DATA_SPATIAL_ANNOTATION_TRACKING_ANDROID. -
nextdoit êtreNULLou un pointeur valide vers la structure suivante dans une chaîne de structures.
L'exécution doit remplir XrEventDataSpatialAnnotationTrackingANDROID pour chaque annotation afin d'indiquer la fin de son initialisation. Quel que soit le résultat de l'initialisation, l'application peut libérer le tampon d'image pour réduire l'utilisation de la mémoire après avoir reçu l'événement.
L'exécution doit remplir initializationResult avec XR_SUCCESS si l'annotation est initialisée correctement. L'application peut ensuite extraire l'événement XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT pour suivre l'annotation.
Sinon, le runtime doit renseigner initializationResult avec un code d'erreur approprié pour indiquer la raison de l'échec. L'application peut détruire le handle XrSpatialContextEXT pour démarrer une nouvelle annotation ou continuer à utiliser spatialContext pour suivre d'autres annotations.
Annotation de quad
Un moteur d'exécution doit indiquer qu'il prend en charge les annotations de quad en utilisant xrEnumerateSpatialCapabilityComponentTypesEXT et en listant le type de composant suivant :
XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID
Quad Reference
La structure XrSpatialAnnotationQuadReferenceANDROID est définie comme suit :
typedef struct XrSpatialAnnotationQuadReferenceANDROID {
XrStructureType type;
const void* next;
uint32_t quadCount;
const XrSpatialAnnotationQuadANDROID* quads;
} XrSpatialAnnotationQuadReferenceANDROID;
Descriptions des membres
typeest le XrStructureType de cette structure.nextestNULLou un pointeur vers la structure suivante dans une chaîne de structures.quadCountest unuint32_tdécrivant le nombre d'éléments dans le tableauquads.quadsest le pointeur vers un tableau de XrSpatialAnnotationQuadANDROID .
Lorsque le runtime est compatible avec les annotations de quad, une application peut configurer des annotations en chaînant une structure XrSpatialAnnotationQuadReferenceANDROID à XrSpatialReferenceImageEXT :: next et en définissant la référence dans XrSpatialCapabilityConfigurationAnnotationTrackingANDROID :: reference lors de la création du handle XrSpatialContextEXT.
L'exécution doit renvoyer XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT à partir de xrCreateSpatialContextAsyncEXT si quadCount est défini sur 0.
Utilisation valide (implicite)
- L'extension
XR_ANDROID_spatial_annotation_trackingdoit être activée avant d'utiliser XrSpatialAnnotationQuadReferenceANDROID. -
typedoit êtreXR_TYPE_SPATIAL_ANNOTATION_QUAD_REFERENCE_ANDROID. -
nextdoit êtreNULLou un pointeur valide vers la structure suivante dans une chaîne de structures. -
quadsmust être un pointeur vers un tableau de structures XrSpatialAnnotationQuadANDROID validesquadCount - Le paramètre
quadCountdoit être supérieur à0
La structure XrSpatialAnnotationQuadANDROID est définie comme suit :
typedef struct XrSpatialAnnotationQuadANDROID {
XrSpatialAnnotationQuadAlignmentANDROID alignment;
XrVector2f upperLeft;
XrVector2f upperRight;
XrVector2f lowerRight;
XrVector2f lowerLeft;
} XrSpatialAnnotationQuadANDROID;
Descriptions des membres
alignmentest le XrSpatialAnnotationQuadAlignmentANDROID du quad.upperLeftest un XrVector2f décrivant la coordonnée de l'angle supérieur gauche du quad par rapport à l'origine.upperRightest un XrVector2f décrivant la coordonnée du coin supérieur droit du quad par rapport à l'origine.lowerRightest un XrVector2f décrivant la coordonnée de l'angle inférieur droit du quad par rapport à l'origine.lowerLeftest un XrVector2f décrivant la coordonnée de l'angle inférieur gauche du quad par rapport à l'origine.
Dans un espace 2D, un quad est un quadrilatère convexe dont les sommets sont ordonnés dans le sens des aiguilles d'une montre. La valeur des quatre coins est liée à l'origine (0, 0) à laquelle le quad est associé.
- Lorsqu'il est associé à une XrSpatialReferenceImageEXT, l'origine correspond à l'angle supérieur gauche de l'image, où X correspond au pixel sur la largeur et Y correspond au pixel sur la hauteur.
- Lorsqu'il est associé à un XrSpatialAnnotationQuadDataANDROID , l'origine est indiquée par XrSpaceLocationData ::
posede XrSpatialAnnotationQuadDataANDROID ::origin.
Utilisation valide (implicite)
- L'extension
XR_ANDROID_spatial_annotation_trackingdoit être activée avant d'utiliser XrSpatialAnnotationQuadANDROID. -
alignmentmust être une valeur XrSpatialAnnotationQuadAlignmentANDROID valide
typedef enum XrSpatialAnnotationQuadAlignmentANDROID {
XR_SPATIAL_ANNOTATION_QUAD_ALIGNMENT_SCREEN_ANDROID = 0,
XR_SPATIAL_ANNOTATION_QUAD_ALIGNMENT_OBJECT_ANDROID = 1,
XR_SPATIAL_ANNOTATION_QUAD_ALIGNMENT_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSpatialAnnotationQuadAlignmentANDROID;
L'énumération XrSpatialAnnotationQuadAlignmentANDROID décrit l'alignement de l'annotation quad.
Les énumérations ont les significations suivantes :
Description de l'enum
XR_SPATIAL_ANNOTATION_QUAD_ALIGNMENT_SCREEN_ANDROID
Le quad d'annotation est parallèle au plan de l'écran, tandis que sa rotation dans le plan reste verrouillée sur la gravité mondiale. Le résultat apparaît sous la forme d'un cadre de sélection droit et normal.
XR_SPATIAL_ANNOTATION_QUAD_ALIGNMENT_OBJECT_ANDROID
Le quad d'annotation est ancré directement à l'objet, en fonction de l'alignement défini dans l'image de référence. La sortie est un quadrilatère convexe, dont la forme est ajustée pour correspondre à la perspective de l'objet.
Composants Quad
La structure XrSpatialAnnotationQuadDataANDROID est définie comme suit :
typedef struct XrSpatialAnnotationQuadDataANDROID {
uint32_t annotationIndex;
XrSpaceLocationData origin;
XrSpatialAnnotationQuadANDROID quad;
} XrSpatialAnnotationQuadDataANDROID;
Descriptions des membres
annotationIndexest le mappage d'index vers le tableau XrSpatialAnnotationQuadReferenceANDROID ::quadsassocié à la référence transmise par XrSpatialCapabilityConfigurationAnnotationTrackingANDROID ::reference.originest un XrSpaceLocationData décrivant l'origine d'un plan 2D où le quad est ancré. Le runtime doit définir XrSpaceLocationData::locationFlagspour indiquer les bits valides de la pose d'origine.quadest un XrSpatialAnnotationQuadANDROID représentant le quad dans l'espace local. Utilisezoriginpour transformer le quad en espace de pose.
Utilisation valide (implicite)
- L'extension
XR_ANDROID_spatial_annotation_trackingdoit être activée avant d'utiliser XrSpatialAnnotationQuadDataANDROID. -
originmust être une structure XrSpaceLocationData valide -
quadmust être une structure XrSpatialAnnotationQuadANDROID valide
La structure XrSpatialComponentAnnotationQuadListANDROID est définie comme suit :
typedef struct XrSpatialComponentAnnotationQuadListANDROID {
XrStructureType type;
void* next;
uint32_t quadCount;
XrSpatialAnnotationQuadDataANDROID* quads;
} XrSpatialComponentAnnotationQuadListANDROID;
Descriptions des membres
typeest le XrStructureType de cette structure.nextestNULLou un pointeur vers la structure suivante dans une chaîne de structures.quadCountest unuint32_tdécrivant le nombre d'éléments dans le tableauquads.quadsest un tableau de XrSpatialAnnotationQuadDataANDROID .
L'application peut interroger le composant d'annotation quad des entités spatiales dans un XrSpatialSnapshotEXT en ajoutant XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID dans XrSpatialComponentDataQueryConditionEXT :: componentTypes et en ajoutant XrSpatialComponentAnnotationQuadListANDROID à la chaîne de pointeurs suivante de XrSpatialComponentDataQueryResultEXT .
Le runtime doit renvoyer XR_ERROR_VALIDATION_FAILURE à partir de xrQuerySpatialComponentDataEXT si XrSpatialComponentAnnotationQuadListANDROID se trouve dans la chaîne suivante de XrSpatialComponentDataQueryResultEXT :: next, mais que XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID n'est pas inclus dans XrSpatialComponentDataQueryConditionEXT :: componentTypes .
Le runtime doit renvoyer XR_ERROR_SIZE_INSUFFICIENT à partir de xrQuerySpatialComponentDataEXT si quadCount est inférieur à XrSpatialComponentDataQueryResultEXT::entityIdCountOutput .
Utilisation valide (implicite)
- L'extension
XR_ANDROID_spatial_annotation_trackingdoit être activée avant d'utiliser XrSpatialComponentAnnotationQuadListANDROID. -
typedoit êtreXR_TYPE_SPATIAL_COMPONENT_ANNOTATION_QUAD_LIST_ANDROID. -
nextdoit êtreNULLou un pointeur valide vers la structure suivante dans une chaîne de structures. -
quadsmust être un pointeur vers un tableau de structuresquadCountXrSpatialAnnotationQuadDataANDROID - Le paramètre
quadCountdoit être supérieur à0
Exemple de code
Vérifier la compatibilité de l'environnement d'exécution
L'exemple de code suivant montre comment vérifier si le runtime est compatible avec la fonctionnalité de suivi des annotations.
XrInstance instance; // previously initialized
XrSystemId systemId; // previously initialized
XrSession session; // previously initialized
XrSpace localSpace; // previously initialized, e.g. from
// XR_REFERENCE_SPACE_TYPE_LOCAL
PFN_xrEnumerateSpatialCapabilitiesEXT xrEnumerateSpatialCapabilitiesEXT;
PFN_xrEnumerateSpatialAnnotationReferenceSourcesANDROID xrEnumerateSpatialAnnotationReferenceSourcesANDROID;
PFN_xrEnumerateSpatialReferenceImageFormatsEXT xrEnumerateSpatialReferenceImageFormatsEXT;
PFN_xrEnumerateSpatialCapabilityComponentTypesEXT xrEnumerateSpatialCapabilityComponentTypesEXT;
// Check spatial annotation tracking capability
uint32_t capabilityCount;
CHK_XR(xrEnumerateSpatialCapabilitiesEXT(instance, systemId, 0,
&capabilityCount, nullptr));
std::vector<XrSpatialCapabilityEXT> capabilities(capabilityCount);
CHK_XR(xrEnumerateSpatialCapabilitiesEXT(instance, systemId, capabilityCount,
&capabilityCount,
capabilities.data()));
if (std::find(capabilities.begin(), capabilities.end(),
XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID) ==
capabilities.end()) {
// System does not support spatial annotation tracking.
return;
}
// Inspect system properties for annotation tracking variables
XrSystemSpatialAnnotationPropertiesANDROID annotationSystemProperties{
XR_TYPE_SYSTEM_SPATIAL_ANNOTATION_PROPERTIES_ANDROID};
XrSystemProperties systemProperties{.type = XR_TYPE_SYSTEM_PROPERTIES,
.next = &annotationSystemProperties,
.systemId = systemId};
CHK_XR(xrGetSystemProperties(instance, systemId, &systemProperties));
if (annotationSystemProperties.maxAnnotationCount == 0) {
// System does not support any active annotations.
return;
}
// Enumerate supported reference sources
uint32_t sourceCountOutput = 0;
XrSpatialAnnotationReferenceSourceANDROID desiredSource =
XR_SPATIAL_ANNOTATION_REFERENCE_SOURCE_CAMERA_ANDROID;
CHK_XR(xrEnumerateSpatialAnnotationReferenceSourcesANDROID(
instance, systemId, XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID,
0, &sourceCountOutput, nullptr));
std::vector<XrSpatialAnnotationReferenceSourceANDROID> sources(sourceCountOutput);
CHK_XR(xrEnumerateSpatialAnnotationReferenceSourcesANDROID(
instance, systemId, XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID,
sourceCountOutput, &sourceCountOutput, sources.data()));
if (std::find(sources.begin(), sources.end(), desiredSource) == sources.end()) {
// The desired source is not supported.
return;
}
// Enumerate supported reference image formats, provided by XR_EXT_spatial_image_tracking.
uint32_t formatCountOutput = 0;
XrSpatialReferenceImageFormatEXT desiredFormat =
XR_SPATIAL_REFERENCE_IMAGE_FORMAT_YUV_420_888_EXT; // Or XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGBA_8888_EXT for screenshot.
CHK_XR(xrEnumerateSpatialReferenceImageFormatsEXT(
instance, systemId, XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID, 0,
&formatCountOutput, nullptr));
std::vector<XrSpatialReferenceImageFormatEXT> formats(formatCountOutput);
CHK_XR(xrEnumerateSpatialReferenceImageFormatsEXT(
instance, systemId, XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID,
formats.size(), &formatCountOutput, formats.data()));
if (std::find(formats.begin(), formats.end(), desiredFormat) == formats.end()) {
// The desired format is not supported
return;
}
// Enumerate supported components for annotation tracking capability.
XrSpatialCapabilityComponentTypesEXT capabilityComponentTypes{
XR_TYPE_SPATIAL_CAPABILITY_COMPONENT_TYPES_EXT};
CHK_XR(xrEnumerateSpatialCapabilityComponentTypesEXT(
instance, systemId, XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID,
&capabilityComponentTypes));
std::vector<XrSpatialComponentTypeEXT>
annotationTypes(capabilityComponentTypes.componentTypeCountOutput);
capabilityComponentTypes.componentTypeCapacityInput = annotationTypes.size();
capabilityComponentTypes.componentTypes = annotationTypes.data();
CHK_XR(xrEnumerateSpatialCapabilityComponentTypesEXT(
instance, systemId, XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID,
&capabilityComponentTypes));
// Check supported annotation components.
XrSpatialComponentTypeEXT desiredComponent =
XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID;
const auto supportedComponent = [&annotationTypes](
XrSpatialComponentTypeEXT component) {
return std::find(annotationTypes.begin(), annotationTypes.end(), component) !=
annotationTypes.end();
};
if (!supportedComponent(desiredComponent)) {
// The desired annotation is not supported.
return;
}
Configurer l'annotation de quad
L'exemple de code suivant montre comment configurer l'annotation quad.
XrInstance instance; // previously initialized
XrSystemId systemId; // previously initialized
XrSession session; // previously initialized
XrSpace localSpace; // previously initialized, e.g. from
// XR_REFERENCE_SPACE_TYPE_LOCAL
PFN_xrCreateSpatialReferenceCacheAsyncANDROID xrCreateSpatialReferenceCacheAsyncANDROID;
PFN_xrCreateSpatialReferenceCacheCompleteANDROID xrCreateSpatialReferenceCacheCompleteANDROID;
PFN_xrDestroySpatialReferenceCacheANDROID xrDestroySpatialReferenceCacheANDROID;
PFN_xrCreateSpatialContextAsyncEXT xrCreateSpatialContextAsyncEXT;
PFN_xrCreateSpatialContextCompleteEXT xrCreateSpatialContextCompleteEXT;
void (*waitUntilReady)(XrFutureEXT);
XrSpatialReferenceImageFormatEXT desiredFormat;
XrSpatialAnnotationReferenceSourceANDROID desiredSource;
XrSpatialComponentTypeEXT desiredComponent;
// Create and start reference cache to prepare for capturing reference images.
XrSpatialReferenceCacheANDROID referenceCache;
XrSpatialReferenceCacheCreateInfoANDROID cacheCreateInfo{
.type = XR_TYPE_SPATIAL_REFERENCE_CACHE_CREATE_INFO_ANDROID,
.next = nullptr,
.capability = XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID,
.source = desiredSource,
};
XrFutureEXT cacheFuture = XR_NULL_FUTURE_EXT;
CHK_XR(xrCreateSpatialReferenceCacheAsyncANDROID(session, &cacheCreateInfo, &cacheFuture));
waitUntilReady(cacheFuture);
XrCreateSpatialReferenceCacheCompletionANDROID cacheCompletion{
XR_TYPE_CREATE_SPATIAL_REFERENCE_CACHE_COMPLETION_ANDROID};
CHK_XR(xrCreateSpatialReferenceCacheCompleteANDROID(session, cacheFuture,
&cacheCompletion));
if (cacheCompletion.futureResult != XR_SUCCESS) {
// Error, reference cache creation failed
return;
}
referenceCache = cacheCompletion.referenceCache;
// Create the reference image with quad annotations
// YUV 4:2:0 Planar:
// ----------------------
// | Y |Cb |Cr |
// ----------------------
XrSpatialReferenceImagePlaneEXT cameraImagePlanes[3];
// for each plane (0=Y, 1=U(cb), 2=V(Cr)) return by Image#getPlanes().
for (int i = 0; i < 3; ++i) {
cameraImagePlanes[i].buffer; // read from Plane#getBuffer().
cameraImagePlanes[i].bufferSize; // set each buffer size. Y = width * height (bytes); U = Y / 4 (bytes); V = Y / 4 (bytes).
cameraImagePlanes[i].rowStride; // read from Plane#getRowStride().
cameraImagePlanes[i].pixelStride; // read from Plane#getPixelStride().
}
XrSpatialReferenceImageEXT referenceImage{
XR_TYPE_SPATIAL_REFERENCE_IMAGE_EXT};
referenceImage.width = 640;
referenceImage.height = 480;
referenceImage.format = desiredFormat;
referenceImage.planeCount = 3;
referenceImage.planes = cameraImagePlanes;
XrSpatialAnnotationQuadANDROID
quad; // quad coordinates within the reference image.
quad.alignment = XR_SPATIAL_ANNOTATION_QUAD_ALIGNMENT_OBJECT_ANDROID;
// Set unnormalized pixel coordinates of 4 corners.
quad.upperLeft = {0.0, 0.0};
quad.upperRight = {0.0, 100.0};
quad.lowerRight = {100.0, 100.0};
quad.lowerLeft = {0.0, 100.0};
XrSpatialAnnotationQuadReferenceANDROID quadReference{
XR_TYPE_SPATIAL_ANNOTATION_QUAD_REFERENCE_ANDROID};
quadReference.quads = &quad;
quadReference.quadCount = 1;
referenceImage.next = &quadReference;
// Create the spatial context with annotation configuration.
XrSpatialContextEXT spatialContext{};
{
const std::array<XrSpatialComponentTypeEXT, 1> enabledComponents = {
desiredComponent,
};
// Configure annotation tracking
XrSpatialCapabilityConfigurationAnnotationTrackingANDROID annotationConfig{
XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_ANNOTATION_TRACKING_ANDROID};
annotationConfig.capability =
XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID;
annotationConfig.enabledComponentCount = enabledComponents.size();
annotationConfig.enabledComponents = enabledComponents.data();
annotationConfig.cache = referenceCache;
annotationConfig.time; // The time when this reference image is captured.
annotationConfig.reference = referenceImage;
std::vector<XrSpatialCapabilityConfigurationBaseHeaderEXT *>
capabilityConfigs;
capabilityConfigs.push_back(
reinterpret_cast<XrSpatialCapabilityConfigurationBaseHeaderEXT *>(
&annotationConfig));
XrSpatialContextCreateInfoEXT spatialContextCreateInfo{
XR_TYPE_SPATIAL_CONTEXT_CREATE_INFO_EXT};
spatialContextCreateInfo.capabilityConfigCount = capabilityConfigs.size();
spatialContextCreateInfo.capabilityConfigs = capabilityConfigs.data();
XrFutureEXT createContextFuture = XR_NULL_FUTURE_EXT;
CHK_XR(xrCreateSpatialContextAsyncEXT(session, &spatialContextCreateInfo,
&createContextFuture));
waitUntilReady(createContextFuture);
XrCreateSpatialContextCompletionEXT completion{
XR_TYPE_CREATE_SPATIAL_CONTEXT_COMPLETION_EXT};
CHK_XR(xrCreateSpatialContextCompleteEXT(session, createContextFuture,
&completion));
if (completion.futureResult != XR_SUCCESS) {
// Error, spatial context creation failed
return;
}
spatialContext = completion.spatialContext;
CHK_XR(xrDestroySpatialReferenceCacheANDROID(referenceCache));
}
Découvrir les annotations actives
L'exemple de code suivant montre comment découvrir et interroger des annotations.
XrInstance instance; // previously initialized
XrSession session; // previously initialized
XrSpace localSpace; // previously initialized, e.g. from
// XR_REFERENCE_SPACE_TYPE_LOCAL
XrSpatialContextEXT spatialContext; // previously created
PFN_xrCreateSpatialDiscoverySnapshotAsyncEXT xrCreateSpatialDiscoverySnapshotAsyncEXT;
PFN_xrCreateSpatialDiscoverySnapshotCompleteEXT xrCreateSpatialDiscoverySnapshotCompleteEXT;
PFN_xrQuerySpatialComponentDataEXT xrQuerySpatialComponentDataEXT;
PFN_xrDestroySpatialSnapshotEXT xrDestroySpatialSnapshotEXT;
PFN_xrPollEvent xrPollEvent;
PFN_xrDestroySpatialContextEXT xrDestroySpatialContextEXT;
void (*waitUntilReady)(XrFutureEXT);
XrSpatialComponentTypeEXT desiredComponent; // e.g. XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID
auto discoverAnnotations = [&](XrSpatialContextEXT spatialContext, XrTime time,
XrSpace baseSpace) {
std::array<XrSpatialComponentTypeEXT, 1> snapshotComponents{desiredComponent};
XrSpatialDiscoverySnapshotCreateInfoEXT snapshotCreateInfo{
XR_TYPE_SPATIAL_DISCOVERY_SNAPSHOT_CREATE_INFO_EXT};
snapshotCreateInfo.componentTypeCount = snapshotComponents.size();
snapshotCreateInfo.componentTypes = snapshotComponents.data();
XrFutureEXT discoveryFuture = XR_NULL_FUTURE_EXT;
CHK_XR(xrCreateSpatialDiscoverySnapshotAsyncEXT(
spatialContext, &snapshotCreateInfo, &discoveryFuture));
waitUntilReady(discoveryFuture);
XrCreateSpatialDiscoverySnapshotCompletionInfoEXT completionInfo{
XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_INFO_EXT};
completionInfo.baseSpace = baseSpace;
completionInfo.time = time;
completionInfo.future = discoveryFuture;
XrCreateSpatialDiscoverySnapshotCompletionEXT completion{
XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_EXT};
CHK_XR(xrCreateSpatialDiscoverySnapshotCompleteEXT(
spatialContext, &completionInfo, &completion));
if (completion.futureResult == XR_SUCCESS) {
// Query for desired annotation data, e.g. quad.
XrSpatialComponentTypeEXT componentsToQuery[] = {
XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID};
XrSpatialComponentDataQueryConditionEXT queryCond{
XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT};
queryCond.componentTypeCount = 1;
queryCond.componentTypes = componentsToQuery;
XrSpatialComponentDataQueryResultEXT queryResult{
XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_RESULT_EXT};
CHK_XR(xrQuerySpatialComponentDataEXT(completion.snapshot, &queryCond,
&queryResult));
std::vector<XrSpatialEntityIdEXT> entityIds(
queryResult.entityIdCountOutput);
std::vector<XrSpatialEntityTrackingStateEXT> entityStates(
queryResult.entityStateCountOutput);
queryResult.entityIdCapacityInput = entityIds.size();
queryResult.entityIds = entityIds.data();
queryResult.entityStateCapacityInput = entityStates.size();
queryResult.entityStates = entityStates.data();
std::vector<XrSpatialAnnotationQuadDataANDROID> quads(
queryResult.entityIdCountOutput);
XrSpatialComponentAnnotationQuadListANDROID quadList{
XR_TYPE_SPATIAL_COMPONENT_ANNOTATION_QUAD_LIST_ANDROID};
quadList.quadCount = quads.size();
quadList.quads = quads.data();
queryResult.next = &quadList;
CHK_XR(xrQuerySpatialComponentDataEXT(completion.snapshot, &queryCond,
&queryResult));
for (int32_t i = 0; i < queryResult.entityIdCountOutput; ++i) {
if (entityStates[i] == XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT) {
const XrSpatialAnnotationQuadDataANDROID ¤tQuad = quads[i];
// Rendering quad in the view.
}
}
CHK_XR(xrDestroySpatialSnapshotEXT(completion.snapshot));
}
};
while (1) {
// For every frame in frame loop
XrSpace space; // Application's play space.
XrFrameState frameState; // Previously returned from xrWaitFrame
const XrTime time = frameState.predictedDisplayTime;
// Poll for the XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT event
XrEventDataBuffer event = {XR_TYPE_EVENT_DATA_BUFFER};
XrResult result = xrPollEvent(instance, &event);
if (result == XR_SUCCESS) {
switch (event.type) {
case XR_TYPE_EVENT_DATA_SPATIAL_ANNOTATION_TRACKING_ANDROID: {
const XrEventDataSpatialAnnotationTrackingANDROID &eventdata =
*reinterpret_cast<XrEventDataSpatialAnnotationTrackingANDROID *>(
&event);
if (eventdata.initializationResult != XR_SUCCESS) {
// handle initialization failure.
// e.g. CHK_XR(xrDestroySpatialContextEXT(spatialContext));
}
break;
}
case XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT: {
const XrEventDataSpatialDiscoveryRecommendedEXT &eventdata =
*reinterpret_cast<XrEventDataSpatialDiscoveryRecommendedEXT *>(
&event);
// Discover spatial entities for the context that we received the
// "discovery recommended" event for.
//discoverSpatialEntities(eventdata.spatialContext, time, space);
break;
}
}
}
// Finish frame loop
}
CHK_XR(xrDestroySpatialContextEXT(spatialContext));
Nouveaux types d'objets
Nouvelles commandes
- xrCreateSpatialReferenceCacheAsyncANDROID
- xrCreateSpatialReferenceCacheCompleteANDROID
- xrDestroySpatialReferenceCacheANDROID
- xrEnumerateSpatialAnnotationReferenceSourcesANDROID
Nouvelles structures
- XrCreateSpatialReferenceCacheCompletionANDROID
- XrEventDataSpatialAnnotationTrackingANDROID
- XrSpatialAnnotationQuadANDROID
- XrSpatialAnnotationQuadDataANDROID
- XrSpatialCapabilityConfigurationAnnotationTrackingANDROID
- XrSpatialReferenceCacheCreateInfoANDROID
Extension de XrSpatialComponentDataQueryResultEXT :
Extension de XrSpatialReferenceImageEXT :
Étendre XrSystemProperties :
Nouveaux enums
Nouvelles constantes d'énumération
XR_ANDROID_SPATIAL_ANNOTATION_TRACKING_EXTENSION_NAMEXR_ANDROID_spatial_annotation_tracking_SPEC_VERSIONExtension de XrObjectType :
XR_OBJECT_TYPE_SPATIAL_REFERENCE_CACHE_ANDROID
Extension de XrSpatialCapabilityEXT :
XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID
Extension de XrSpatialComponentTypeEXT :
XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID
Extension de XrStructureType :
XR_TYPE_CREATE_SPATIAL_REFERENCE_CACHE_COMPLETION_ANDROIDXR_TYPE_EVENT_DATA_SPATIAL_ANNOTATION_TRACKING_ANDROIDXR_TYPE_SPATIAL_ANNOTATION_QUAD_REFERENCE_ANDROIDXR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_ANNOTATION_TRACKING_ANDROIDXR_TYPE_SPATIAL_COMPONENT_ANNOTATION_QUAD_LIST_ANDROIDXR_TYPE_SPATIAL_REFERENCE_CACHE_CREATE_INFO_ANDROIDXR_TYPE_SYSTEM_SPATIAL_ANNOTATION_PROPERTIES_ANDROID
Problèmes
Historique des versions
Révision 1, 17/09/2025 (Levana Chen)
- Description initiale de l'extension.