XR_ANDROID_spatial_annotation_tracking

Stringa del nome

XR_ANDROID_spatial_annotation_tracking

Tipo di estensione

Estensione dell'istanza

Numero di interno registrato

795

Revisione

1

Stato di ratifica

Non ratificato

Dipendenze da estensioni e versioni

XR_EXT_spatial_entity
e
XR_EXT_spatial_image_tracking

Data ultima modifica

2026-01-12

Stato IP

Nessuna rivendicazione di proprietà intellettuale nota.

Collaboratori

Levana Chen, Google
Christopher Feil, Google
Martin Sundermeyer, Google
David Joseph Tan, Google
Jared Finder, Google
Nihav Jain, Google

Panoramica

Questa estensione fornisce la funzionalità di monitoraggio delle annotazioni per l'estensione XR_EXT_spatial_entity per il monitoraggio di varie annotazioni nella scena. Consente alle applicazioni di inserire overlay su oggetti fisici o virtuali definiti da riferimenti di runtime.

Questa estensione fornisce un tipo di annotazione di base "Quad", ovvero un poligono con esattamente 4 lati, ovvero un quadrilatero convesso, che rappresenta un riquadro di delimitazione 2D generalizzato all'interno di un riferimento di runtime. Un'annotazione quad tracciata è rappresentata come un'entità spaziale con i seguenti componenti:

• XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID

Le applicazioni possono in genere utilizzare l'estensione di monitoraggio delle annotazioni spaziali nei seguenti pattern:

• Un'applicazione crea innanzitutto un handle di XrSpatialReferenceCacheANDROID che inizia a registrare i riferimenti di runtime dalla sorgente specificata.
• L'applicazione acquisisce quindi un riferimento di runtime di XrSpatialReferenceImageEXT e definisce un'annotazione desiderata all'interno del riferimento durante l'intervallo di tempo della cache dei riferimenti.
• L'applicazione crea quindi un handle XrSpatialContextEXT basato su XrSpatialReferenceImageEXT fornito da XrSpatialCapabilityConfigurationAnnotationTrackingANDROID .
• L'applicazione può eliminare l'handle XrSpatialReferenceCacheANDROID per interrompere la registrazione dei riferimenti di runtime e ridurre la memoria utilizzata oppure attendere l'evento XR_TYPE_EVENT_DATA_SPATIAL_ANNOTATION_TRACKING_ANDROID per confermare il risultato dell'inizializzazione.
• L'applicazione esegue il pull dell'evento XR_TYPE_EVENT_DATA_SPATIAL_ANNOTATION_TRACKING_ANDROID per confermare il risultato dell'inizializzazione dell'annotazione.
• Se l'inizializzazione ha esito positivo, l'applicazione può estrarre l'evento XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT per monitorare l'annotazione.
• Se l'inizializzazione non va a buon fine, l'applicazione può utilizzare il codice di errore restituito nell'evento per determinare il motivo dell'errore ed eliminare l'handle XrSpatialContextEXT esistente per avviare una nuova annotazione.
• Indipendentemente dal risultato dell'inizializzazione, l'applicazione può rilasciare il buffer delle immagini per ridurre la memoria utilizzata dopo aver ricevuto l'evento.
• L'applicazione rileva ed esegue query sulle annotazioni in base ai pattern di accesso delle entità spaziali.
• L'applicazione può creare un handle XrSpatialContextEXT aggiuntivo per monitorare le annotazioni all'interno di un nuovo riferimento durante l'intervallo di tempo di un XrSpatialReferenceCacheANDROID valido .
• L'applicazione può eliminare gli handle XrSpatialContextEXT per ridurre dinamicamente in fase di runtime l'insieme di annotazioni rilevabili e monitorabili.

Supporto di runtime

Un runtime deve pubblicizzare il supporto della funzionalità di monitoraggio delle annotazioni utilizzando xrEnumerateSpatialCapabilitiesEXT elencando la seguente funzionalità:

• XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID

Quando il runtime supporta la funzionalità di monitoraggio delle annotazioni:

• Deve supportare almeno un componente di annotazione, elencando i componenti di annotazione supportati tramite xrEnumerateSpatialCapabilityComponentTypesEXT .
• Deve supportare almeno uno dei formati XrSpatialReferenceImageFormatEXT , elencando i formati di riferimento supportati tramite xrEnumerateSpatialReferenceImageFormatsEXT con l'impostazione capability su XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID .
• Deve supportare almeno uno dei valori di XrSpatialAnnotationReferenceSourceANDROID , elencando le origini di riferimento supportate tramite xrEnumerateSpatialAnnotationReferenceSourcesANDROID con l'impostazione capability su XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID .

La funzione xrEnumerateSpatialAnnotationReferenceSourcesANDROID è definita come:

XrResult xrEnumerateSpatialAnnotationReferenceSourcesANDROID(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    XrSpatialCapabilityEXT                      capability,
    uint32_t                                    sourceCapacityInput,
    uint32_t*                                   sourceCountOutput,
    XrSpatialAnnotationReferenceSourceANDROID*  sources);

Descrizioni dei parametri

• instance è un handle per un XrInstance .
• systemId è il XrSystemId le cui fonti di riferimento verranno enumerate.
• capability è XrSpatialCapabilityEXT per cui verranno enumerati i riferimenti.
• sourceCapacityInput è la capacità dell'array sources o 0 per indicare una richiesta di recupero della capacità richiesta.
• sourceCountOutput è il numero di origini o la capacità richiesta nel caso in cui sourceCapacityInput non sia sufficiente.
• sources è un array di XrSpatialAnnotationReferenceSourceANDROID . Può essere NULL se sourceCapacityInput è 0.
• Consulta la sezione Parametri delle dimensioni del buffer per una descrizione dettagliata del recupero delle dimensioni sources richieste.

L'applicazione può enumerare l'elenco delle origini di riferimento supportate da un determinato XrSystemId utilizzando xrEnumerateSpatialAnnotationReferenceSourcesANDROID .

Il runtime non deve enumerare le origini di riferimento la cui estensione non è abilitata per instance .

Utilizzo valido (implicito)

• L'estensione XR_ANDROID_spatial_annotation_tracking deve essere attivata prima di chiamare xrEnumerateSpatialAnnotationReferenceSourcesANDROID
• instance deve essere un handle XrInstance valido
• capability deve essere un valore XrSpatialCapabilityEXT valido
• sourceCountOutput deve essere un puntatore a un valore uint32_t
• Se sourceCapacityInput non è 0 , sources deve essere un puntatore a un array di valori sourceCapacityInput XrSpatialAnnotationReferenceSourceANDROID

Codici di ritorno

Operazione riuscita

• XR_SUCCESS

Errore

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_HANDLE_INVALID
• XR_ERROR_INSTANCE_LOST
• XR_ERROR_RUNTIME_FAILURE
• XR_ERROR_SIZE_INSUFFICIENT
• XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT
• XR_ERROR_SYSTEM_INVALID
• XR_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'enumerazione XrSpatialAnnotationReferenceSourceANDROID descrive l'origine del riferimento che fornisce i metadati per un'annotazione.

Gli enum hanno i seguenti significati:

Descrizione enum

XR_SPATIAL_ANNOTATION_REFERENCE_SOURCE_CAMERA_ANDROID

L'immagine di riferimento è un'immagine non ritagliata generata da un'API fotocamera Android, ad esempio un'immagine di un ImageReader associato a un CameraDevice Camera2 o un ImageProxy di un'ImageAnalysis associata a CameraX. In genere si tratta di una delle fotocamere RGB rivolte in avanti.

XR_SPATIAL_ANNOTATION_REFERENCE_SOURCE_MEDIA_PROJECTION_ANDROID

L'immagine di riferimento è un'immagine non ritagliata generata dall'API Android MediaProjection, ad esempio un'immagine di un ImageReader associato a un display virtuale MediaProjection. Può includere contenuti virtuali e reali.

La struttura XrSystemSpatialAnnotationPropertiesANDROID è definita come segue:

typedef struct XrSystemSpatialAnnotationPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    uint32_t           referenceCacheTimespan;
    uint32_t           maxReferencePixelWidth;
    uint32_t           maxReferencePixelHeight;
    uint32_t           maxReferenceCount;
    uint32_t           maxAnnotationCount;
} XrSystemSpatialAnnotationPropertiesANDROID;

Descrizioni dei membri

• type è l'XrStructureType di questa struttura.
• next è NULL o un puntatore alla struttura successiva in una catena di strutture.
• referenceCacheTimespan indica l'intervallo di tempo in secondi di un handle XrSpatialReferenceCacheANDROID valido.
• maxReferencePixelWidth indica la larghezza massima del bordo delle immagini di riferimento in pixel.
• maxReferencePixelHeight indica l'altezza massima del bordo delle immagini di riferimento in pixel.
• maxReferenceCount indica il numero massimo di immagini di riferimento da allocare contemporaneamente.
• maxAnnotationCount indica il numero massimo di annotazioni da monitorare contemporaneamente.

Quando il runtime supporta la funzionalità di monitoraggio delle annotazioni, un'applicazione può ispezionare le proprietà di sistema pertinenti concatenando una struttura XrSystemSpatialAnnotationPropertiesANDROID a XrSystemProperties quando chiama xrGetSystemProperties .

Se XrSpatialReferenceImageEXT :: width da XrSpatialCapabilityConfigurationAnnotationTrackingANDROID :: reference supera maxReferencePixelWidth , il runtime deve restituire XR_ERROR_VALIDATION_FAILURE quando viene chiamato xrCreateSpatialContextAsyncEXT .

Se XrSpatialReferenceImageEXT :: height da XrSpatialCapabilityConfigurationAnnotationTrackingANDROID :: reference supera maxReferencePixelHeight , il runtime deve restituire XR_ERROR_VALIDATION_FAILURE quando viene chiamato xrCreateSpatialContextAsyncEXT .

Se XrSpatialCapabilityConfigurationAnnotationTrackingANDROID :: time non rientra nell'intervallo di tempo di XrSpatialReferenceCacheANDROID :: cache , il runtime deve restituire XR_ERROR_TIME_INVALID quando viene chiamato xrCreateSpatialContextAsyncEXT . L'applicazione può ricreare l'handle XrSpatialContextEXT con un nuovo riferimento durante l'intervallo di tempo di XrSpatialReferenceCacheANDROID .

Se il numero di immagini di riferimento allocate supera maxReferenceCount , il runtime deve restituire XR_ERROR_LIMIT_REACHED e indicare l'errore di inizializzazione tramite XrEventDataSpatialAnnotationTrackingANDROID :: initializationResult . L'applicazione può eliminare l'handle XrSpatialContextEXT e riprovare dopo il completamento dell'inizializzazione in attesa.

Se il numero di annotazioni attive supera maxAnnotationCount , il runtime deve restituire XR_ERROR_VALIDATION_FAILURE quando viene chiamato xrCreateSpatialContextAsyncEXT .

Utilizzo valido (implicito)

• L'estensione XR_ANDROID_spatial_annotation_tracking deve essere attivata prima di utilizzare XrSystemSpatialAnnotationPropertiesANDROID
• type deve essere XR_TYPE_SYSTEM_SPATIAL_ANNOTATION_PROPERTIES_ANDROID
• next deve essere NULL o un puntatore valido alla struttura successiva in una catena di strutture

Cache di riferimento del runtime

XR_DEFINE_HANDLE(XrSpatialReferenceCacheANDROID)

L'handle XrSpatialReferenceCacheANDROID rappresenta una cache di riferimenti di runtime registrati da una determinata origine.

La funzione xrCreateSpatialReferenceCacheAsyncANDROID è definita come:

XrResult xrCreateSpatialReferenceCacheAsyncANDROID(
    XrSession                                   session,
    const XrSpatialReferenceCacheCreateInfoANDROID* createInfo,
    XrFutureEXT*                                future);

Descrizioni dei parametri

• session è una XrSession in cui la cache di riferimento sarà attiva.
• createInfo è un puntatore a un XrSpatialReferenceCacheCreateInfoANDROID utilizzato per specificare i parametri della cache di riferimento.
• future è un puntatore all'handle di output di un XrFutureEXT .

L'applicazione può creare un handle XrSpatialReferenceCacheANDROID chiamando xrCreateSpatialReferenceCacheAsyncANDROID . L'inizializzazione dei servizi di monitoraggio del runtime potrebbe richiedere del tempo. L'applicazione può quindi chiamare ripetutamente xrCreateSpatialReferenceCacheCompleteANDROID per verificare il completamento di questa operazione asincrona.

Il runtime deve restituire XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT se XrSpatialReferenceCacheCreateInfoANDROID :: capability non è elencato da xrEnumerateSpatialCapabilitiesEXT .

Il runtime deve restituire XR_ERROR_FEATURE_UNSUPPORTED se XrSpatialReferenceCacheCreateInfoANDROID :: source non è elencato da xrEnumerateSpatialAnnotationReferenceSourcesANDROID per la funzionalità specificata.

L'applicazione può creare un solo handle per origine per una determinata funzionalità. In caso contrario, il runtime deve restituire XR_ERROR_LIMIT_REACHED .

L'applicazione può quindi acquisire i riferimenti di tempo di esecuzione durante il periodo di tempo dell'handle XrSpatialReferenceCacheANDROID per configurare un nuovo handle XrSpatialContextEXT.

Utilizzo valido (implicito)

• L'estensione XR_ANDROID_spatial_annotation_tracking deve essere attivata prima di chiamare xrCreateSpatialReferenceCacheAsyncANDROID
• session deve essere un handle XrSession valido
• createInfo deve essere un puntatore a una struttura XrSpatialReferenceCacheCreateInfoANDROID valida
• future deve essere un puntatore a un valore XrFutureEXT

Codici di ritorno

Operazione riuscita

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Errore

• XR_ERROR_FEATURE_UNSUPPORTED
• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_HANDLE_INVALID
• XR_ERROR_INSTANCE_LOST
• XR_ERROR_LIMIT_REACHED
• XR_ERROR_OUT_OF_MEMORY
• XR_ERROR_RUNTIME_FAILURE
• XR_ERROR_SESSION_LOST
• XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT
• XR_ERROR_VALIDATION_FAILURE

La struttura XrSpatialReferenceCacheCreateInfoANDROID è definita come:

typedef struct XrSpatialReferenceCacheCreateInfoANDROID {
    XrStructureType                              type;
    const void*                                  next;
    XrSpatialCapabilityEXT                       capability;
    XrSpatialAnnotationReferenceSourceANDROID    source;
} XrSpatialReferenceCacheCreateInfoANDROID;

Descrizioni dei membri

• type è l'XrStructureType di questa struttura.
• next è NULL o un puntatore alla struttura successiva in una catena di strutture. Nessuna struttura di questo tipo è definita in OpenXR di base o in questa estensione.
• capability è un XrSpatialCapabilityEXT che descrive per quale funzionalità viene creata la cache di riferimento.
• source è un XrSpatialAnnotationReferenceSourceANDROID che descrive l'origine della cache di riferimento.

La struttura XrSpatialReferenceCacheCreateInfoANDROID descrive le informazioni per creare un handle XrSpatialReferenceCacheANDROID.

Utilizzo valido (implicito)

• L'estensione XR_ANDROID_spatial_annotation_tracking deve essere abilitata prima di utilizzare XrSpatialReferenceCacheCreateInfoANDROID
• type deve essere XR_TYPE_SPATIAL_REFERENCE_CACHE_CREATE_INFO_ANDROID
• next deve essere NULL o un puntatore valido alla struttura successiva in una catena di strutture
• capability deve essere un valore XrSpatialCapabilityEXT valido
• source deve essere un valore XrSpatialAnnotationReferenceSourceANDROID valido

La funzione xrCreateSpatialReferenceCacheCompleteANDROID è definita come:

XrResult xrCreateSpatialReferenceCacheCompleteANDROID(
    XrSession                                   session,
    XrFutureEXT                                 future,
    XrCreateSpatialReferenceCacheCompletionANDROID* completion);

Descrizioni dei parametri

• session è l'XrSession precedentemente passato a xrCreateSpatialReferenceCacheAsyncANDROID :: session .
• future è il XrFutureEXT ricevuto da xrCreateSpatialReferenceCacheAsyncANDROID :: future .
• completion è un puntatore a un XrCreateSpatialReferenceCacheCompletionANDROID .

L'applicazione può chiamare xrCreateSpatialReferenceCacheCompleteANDROID per attendere il completamento dell'operazione asincrona avviata da xrCreateSpatialReferenceCacheAsyncANDROID .

Il runtime deve restituire XR_ERROR_FUTURE_PENDING_EXT se future non è nello stato pronto. Il runtime deve restituire XR_ERROR_FUTURE_INVALID_EXT se future è già stato completato o annullato.

Utilizzo valido (implicito)

• L'estensione XR_ANDROID_spatial_annotation_tracking deve essere abilitata prima di chiamare xrCreateSpatialReferenceCacheCompleteANDROID
• session deve essere un handle XrSession valido
• completion deve essere un puntatore a una struttura XrCreateSpatialReferenceCacheCompletionANDROID

Codici di ritorno

Operazione riuscita

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Errore

• XR_ERROR_FEATURE_UNSUPPORTED
• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_FUTURE_INVALID_EXT
• XR_ERROR_FUTURE_PENDING_EXT
• XR_ERROR_HANDLE_INVALID
• XR_ERROR_INSTANCE_LOST
• XR_ERROR_LIMIT_REACHED
• XR_ERROR_OUT_OF_MEMORY
• XR_ERROR_RUNTIME_FAILURE
• XR_ERROR_SESSION_LOST
• XR_ERROR_VALIDATION_FAILURE

La struttura XrCreateSpatialReferenceCacheCompletionANDROID è definita come:

typedef struct XrCreateSpatialReferenceCacheCompletionANDROID {
    XrStructureType                   type;
    void*                             next;
    XrResult                          futureResult;
    XrSpatialReferenceCacheANDROID    referenceCache;
} XrCreateSpatialReferenceCacheCompletionANDROID;

Descrizioni dei membri

• type è l'XrStructureType di questa struttura.
• next è NULL o un puntatore alla struttura successiva in una catena di strutture. Nessuna struttura di questo tipo è definita in OpenXR di base o in questa estensione.
• futureResult è l'XrResult dell'operazione di creazione della cache di riferimento.
• referenceCache è l'handle XrSpatialReferenceCacheANDROID se l'operazione ha esito positivo.

Codici di reso futuri

Valori futureResult:

Operazione riuscita

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Errore

• XR_ERROR_FEATURE_UNSUPPORTED
• XR_ERROR_RUNTIME_FAILURE
• XR_ERROR_INSTANCE_LOST
• XR_ERROR_SESSION_LOST
• XR_ERROR_OUT_OF_MEMORY
• XR_ERROR_LIMIT_REACHED

Se futureResult è un codice di operazione riuscita, il runtime deve restituire un handle referenceCache valido. Se referenceCache è valido, rimane tale solo per la durata di xrCreateSpatialReferenceCacheAsyncANDROID :: session o finché l'applicazione non distrugge l'handle con xrDestroySpatialReferenceCacheANDROID, a seconda di quale evento si verifica per primo.

Quando referenceCache è valido, registra le cache all'interno di XrSystemSpatialAnnotationPropertiesANDROID :: referenceCacheTimespan .

Utilizzo valido (implicito)

• L'estensione XR_ANDROID_spatial_annotation_tracking deve essere abilitata prima di utilizzare XrCreateSpatialReferenceCacheCompletionANDROID
• type deve essere XR_TYPE_CREATE_SPATIAL_REFERENCE_CACHE_COMPLETION_ANDROID
• next deve essere NULL o un puntatore valido alla struttura successiva in una catena di strutture
• futureResult deve essere un valore XrResult valido
• referenceCache deve essere un handle XrSpatialReferenceCacheANDROID valido

La funzione xrDestroySpatialReferenceCacheANDROID è definita come:

XrResult xrDestroySpatialReferenceCacheANDROID(
    XrSpatialReferenceCacheANDROID              cacheHandle);

Descrizioni dei parametri

• cacheHandle è un XrSpatialReferenceCacheANDROID creato in precedenza da xrCreateSpatialReferenceCacheAsyncANDROID .

L'applicazione può chiamare la funzione xrDestroySpatialReferenceCacheANDROID per rilasciare l'handle cacheHandle e le risorse sottostanti al termine della creazione del contesto spaziale.

Utilizzo valido (implicito)

• L'estensione XR_ANDROID_spatial_annotation_tracking deve essere abilitata prima di chiamare xrDestroySpatialReferenceCacheANDROID
• cacheHandle deve essere un handle XrSpatialReferenceCacheANDROID valido

Thread Safety

• L'accesso a cacheHandle e a tutti gli handle secondari deve essere sincronizzato esternamente

Codici di ritorno

Operazione riuscita

• XR_SUCCESS

Errore

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_HANDLE_INVALID

Configurazione

La struttura XrSpatialCapabilityConfigurationAnnotationTrackingANDROID è definita come:

typedef struct XrSpatialCapabilityConfigurationAnnotationTrackingANDROID {
    XrStructureType                     type;
    const void*                         next;
    XrSpatialCapabilityEXT              capability;
    uint32_t                            enabledComponentCount;
    const XrSpatialComponentTypeEXT*    enabledComponents;
    XrSpatialReferenceCacheANDROID      cache;
    XrTime                              time;
    XrSpatialReferenceImageEXT          reference;
} XrSpatialCapabilityConfigurationAnnotationTrackingANDROID;

Descrizioni dei membri

• type è l'XrStructureType di questa struttura.
• next è NULL o un puntatore alla struttura successiva in una catena di strutture.
• capability è un XrSpatialCapabilityEXT e deve essere XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID .
• enabledComponentCount è un uint32_t che descrive il conteggio degli elementi nell'array enabledComponents.
• enabledComponents è un puntatore a un array di XrSpatialComponentTypeEXT .
• cache è un XrSpatialReferenceCacheANDROID creato in precedenza per registrare i riferimenti di runtime per la configurazione reference.
• time è il XrTime in cui viene acquisito il reference.
• reference è un XrSpatialReferenceImageEXT con annotazioni concatenate al relativo puntatore successivo.

Le applicazioni possono attivare la funzionalità spaziale XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID aggiungendo un puntatore alla struttura XrSpatialCapabilityConfigurationAnnotationTrackingANDROID in XrSpatialContextCreateInfoEXT :: capabilityConfigs .

Il runtime deve restituire XR_ERROR_VALIDATION_FAILURE se capability non è XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID .

Il runtime deve restituire XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT se reference non contiene annotazioni.

Il runtime deve restituire XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT se il componente di annotazione è elencato in enabledComponents, ma non sono associate annotazioni corrispondenti a reference .

Il runtime deve restituire XR_ERROR_VALIDATION_FAILURE se cache non è di proprietà della stessa XrSession che passa a xrCreateSpatialContextAsyncEXT .

Il runtime deve restituire XR_ERROR_TIME_INVALID se time non rientra nell'intervallo di tempo di cache .

Utilizzo valido (implicito)

• L'estensione XR_ANDROID_spatial_annotation_tracking deve essere attivata prima di utilizzare XrSpatialCapabilityConfigurationAnnotationTrackingANDROID
• type deve essere XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_ANNOTATION_TRACKING_ANDROID
• next deve essere NULL o un puntatore valido alla struttura successiva in una catena di strutture
• capability deve essere un valore XrSpatialCapabilityEXT valido
• enabledComponents deve essere un puntatore a un array di enabledComponentCount valori XrSpatialComponentTypeEXT validi
• cache deve essere un handle XrSpatialReferenceCacheANDROID valido
• reference deve essere una struttura XrSpatialReferenceImageEXT valida
• Il parametro enabledComponentCount deve essere maggiore di 0

Eventi di monitoraggio delle annotazioni

La struttura XrEventDataSpatialAnnotationTrackingANDROID è definita come segue:

typedef struct XrEventDataSpatialAnnotationTrackingANDROID {
    XrStructureType        type;
    const void*            next;
    XrSpatialContextEXT    spatialContext;
    uint32_t               annotationIndex;
    XrResult               initializationResult;
} XrEventDataSpatialAnnotationTrackingANDROID;

Descrizioni dei membri

• type è l'XrStructureType di questa struttura.
• next è NULL o un puntatore alla struttura successiva in una catena di strutture.
• spatialContext è XrSpatialContextEXT per cui è stato attivato il monitoraggio delle annotazioni.
• annotationIndex corrisponde all'indice della matrice di annotazioni associata a XrSpatialCapabilityConfigurationAnnotationTrackingANDROID :: reference .
• initializationResult indica il risultato dell'inizializzazione dell'annotazione. Se non è XR_SUCCESS , l'applicazione può eliminare e ricreare l'handle XrSpatialContextEXT per reinizializzare l'annotazione o continuare a utilizzare spatialContext per monitorare altre annotazioni.

Utilizzo valido (implicito)

• L'estensione XR_ANDROID_spatial_annotation_tracking deve essere attivata prima di utilizzare XrEventDataSpatialAnnotationTrackingANDROID
• type deve essere XR_TYPE_EVENT_DATA_SPATIAL_ANNOTATION_TRACKING_ANDROID
• next deve essere NULL o un puntatore valido alla struttura successiva in una catena di strutture

Il runtime deve compilare XrEventDataSpatialAnnotationTrackingANDROID per ogni annotazione per indicare il completamento dell'inizializzazione. Indipendentemente dal risultato dell'inizializzazione, l'applicazione può rilasciare il buffer dell'immagine per ridurre la memoria utilizzata dopo aver ricevuto l'evento.

Se l'annotazione viene inizializzata correttamente, il runtime deve compilare initializationResult con XR_SUCCESS. L'applicazione può quindi eseguire il pull dell'evento XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT per monitorare l'annotazione.

In caso contrario, il runtime deve compilare initializationResult con un codice di errore appropriato per indicare il motivo dell'errore. L'applicazione può eliminare l'handle XrSpatialContextEXT per avviare una nuova annotazione o continuare a utilizzare spatialContext per monitorare altre annotazioni.

Annotazione quad

Un runtime deve pubblicizzare il supporto delle annotazioni quad utilizzando xrEnumerateSpatialCapabilityComponentTypesEXT elencando il seguente tipo di componente:

• XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID

Quad Reference

La struttura XrSpatialAnnotationQuadReferenceANDROID è definita come:

typedef struct XrSpatialAnnotationQuadReferenceANDROID {
    XrStructureType                          type;
    const void*                              next;
    uint32_t                                 quadCount;
    const XrSpatialAnnotationQuadANDROID*    quads;
} XrSpatialAnnotationQuadReferenceANDROID;

Descrizioni dei membri

• type è l'XrStructureType di questa struttura.
• next è NULL o un puntatore alla struttura successiva in una catena di strutture.
• quadCount è un uint32_t che descrive il conteggio degli elementi nell'array quads.
• quads è il puntatore a un array di XrSpatialAnnotationQuadANDROID .

Quando il runtime supporta le annotazioni quad, un'applicazione può configurare le annotazioni concatenando una struttura XrSpatialAnnotationQuadReferenceANDROID a XrSpatialReferenceImageEXT :: next e impostando il riferimento in XrSpatialCapabilityConfigurationAnnotationTrackingANDROID :: reference durante la creazione dell'handle XrSpatialContextEXT.

Il runtime deve restituire XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT da xrCreateSpatialContextAsyncEXT se quadCount è 0.

Utilizzo valido (implicito)

• L'estensione XR_ANDROID_spatial_annotation_tracking deve essere attivata prima di utilizzare XrSpatialAnnotationQuadReferenceANDROID
• type deve essere XR_TYPE_SPATIAL_ANNOTATION_QUAD_REFERENCE_ANDROID
• next deve essere NULL o un puntatore valido alla struttura successiva in una catena di strutture
• quads must be a pointer to an array of quadCount valid XrSpatialAnnotationQuadANDROID structures
• Il parametro quadCount deve essere maggiore di 0

La struttura XrSpatialAnnotationQuadANDROID è definita come:

typedef struct XrSpatialAnnotationQuadANDROID {
    XrSpatialAnnotationQuadAlignmentANDROID    alignment;
    XrVector2f                                 upperLeft;
    XrVector2f                                 upperRight;
    XrVector2f                                 lowerRight;
    XrVector2f                                 lowerLeft;
} XrSpatialAnnotationQuadANDROID;

Descrizioni dei membri

• alignment è l'XrSpatialAnnotationQuadAlignmentANDROID del quadrilatero.
• upperLeft è un XrVector2f che descrive la coordinata dell'angolo superiore sinistro del quadrilatero rispetto all'origine.
• upperRight è un XrVector2f che descrive la coordinata dell'angolo in alto a destra del quadrilatero rispetto all'origine.
• lowerRight è un XrVector2f che descrive la coordinata dell'angolo in basso a destra del quadrilatero rispetto all'origine.
• lowerLeft è un XrVector2f che descrive la coordinata dell'angolo in basso a sinistra del quadrilatero rispetto all'origine.

Un quadrilatero in uno spazio 2D è un quadrilatero convesso con ordine orario. Il valore dei quattro angoli è correlato all'origine (0, 0) a cui è associato il quadrilatero.

• Quando è associata a un'XrSpatialReferenceImageEXT, l'origine è l'angolo in alto a sinistra dell'immagine, dove X corrisponde al pixel sulla larghezza e Y al pixel sull'altezza.
• Quando è associato a un XrSpatialAnnotationQuadDataANDROID , l'origine è indicata da XrSpaceLocationData :: pose di XrSpatialAnnotationQuadDataANDROID :: origin .

Utilizzo valido (implicito)

• L'estensione XR_ANDROID_spatial_annotation_tracking deve essere attivata prima di utilizzare XrSpatialAnnotationQuadANDROID
• alignment deve essere un valore XrSpatialAnnotationQuadAlignmentANDROID valido

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'enumerazione XrSpatialAnnotationQuadAlignmentANDROID descrive l'allineamento dell'annotazione quad.

Gli enum hanno i seguenti significati:

Descrizione enum

XR_SPATIAL_ANNOTATION_QUAD_ALIGNMENT_SCREEN_ANDROID

Il quadrilatero dell'annotazione è parallelo al piano dello schermo, mentre la rotazione sul piano rimane bloccata alla gravità del mondo. L'output viene visualizzato come un riquadro di delimitazione normale e verticale.

XR_SPATIAL_ANNOTATION_QUAD_ALIGNMENT_OBJECT_ANDROID

Il quadrilatero dell'annotazione è ancorato direttamente all'oggetto, in modo che corrisponda all'allineamento definito nell'immagine di riferimento. L'output è un quadrilatero convesso, la cui forma viene modificata per corrispondere alla prospettiva dell'oggetto.

Quad Components

La struttura XrSpatialAnnotationQuadDataANDROID è definita come:

typedef struct XrSpatialAnnotationQuadDataANDROID {
    uint32_t                          annotationIndex;
    XrSpaceLocationData               origin;
    XrSpatialAnnotationQuadANDROID    quad;
} XrSpatialAnnotationQuadDataANDROID;

Descrizioni dei membri

• annotationIndex è la mappatura dell'indice all'array XrSpatialAnnotationQuadReferenceANDROID :: quads associato al riferimento passato da XrSpatialCapabilityConfigurationAnnotationTrackingANDROID :: reference .
• origin è un XrSpaceLocationData che descrive l'origine di un piano 2D in cui è radicato il quadrilatero. Il runtime deve impostare XrSpaceLocationData :: locationFlags per indicare i bit validi della posa dell'origine.
• quad è un XrSpatialAnnotationQuadANDROID che rappresenta il quadrilatero nello spazio locale. Utilizza origin per trasformare il quad in spazio di posa.

Utilizzo valido (implicito)

• L'estensione XR_ANDROID_spatial_annotation_tracking deve essere attivata prima di utilizzare XrSpatialAnnotationQuadDataANDROID
• origin deve essere una struttura XrSpaceLocationData valida
• quad deve essere una struttura XrSpatialAnnotationQuadANDROID valida

La struttura XrSpatialComponentAnnotationQuadListANDROID è definita come:

typedef struct XrSpatialComponentAnnotationQuadListANDROID {
    XrStructureType                        type;
    void*                                  next;
    uint32_t                               quadCount;
    XrSpatialAnnotationQuadDataANDROID*    quads;
} XrSpatialComponentAnnotationQuadListANDROID;

Descrizioni dei membri

• type è l'XrStructureType di questa struttura.
• next è NULL o un puntatore alla struttura successiva in una catena di strutture.
• quadCount è un uint32_t che descrive il conteggio degli elementi nell'array quads.
• quads è un array di XrSpatialAnnotationQuadDataANDROID .

L'applicazione può eseguire query sul componente di annotazione quad delle entità spaziali in un XrSpatialSnapshotEXT aggiungendo XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID in XrSpatialComponentDataQueryConditionEXT :: componentTypes e aggiungendo XrSpatialComponentAnnotationQuadListANDROID alla catena di puntatori successiva di XrSpatialComponentDataQueryResultEXT .

Il runtime deve restituire XR_ERROR_VALIDATION_FAILURE da xrQuerySpatialComponentDataEXT se XrSpatialComponentAnnotationQuadListANDROID si trova nella catena successiva di XrSpatialComponentDataQueryResultEXT :: next ma XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID non è incluso in XrSpatialComponentDataQueryConditionEXT :: componentTypes .

Il runtime deve restituire XR_ERROR_SIZE_INSUFFICIENT da xrQuerySpatialComponentDataEXT se quadCount è inferiore a XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .

Utilizzo valido (implicito)

• L'estensione XR_ANDROID_spatial_annotation_tracking deve essere attivata prima di utilizzare XrSpatialComponentAnnotationQuadListANDROID
• type deve essere XR_TYPE_SPATIAL_COMPONENT_ANNOTATION_QUAD_LIST_ANDROID
• next deve essere NULL o un puntatore valido alla struttura successiva in una catena di strutture
• quads deve essere un puntatore a un array di strutture quadCount XrSpatialAnnotationQuadDataANDROID
• Il parametro quadCount deve essere maggiore di 0

Codice di esempio

Controllare il supporto del runtime

Il seguente codice di esempio mostra come verificare se il runtime supporta la funzionalità di monitoraggio delle annotazioni.

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;
}

Configurare l'annotazione quadrata

Il seguente codice di esempio mostra come configurare l'annotazione quadrata.

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

Scopri le annotazioni attive

Il seguente codice di esempio mostra come scoprire ed eseguire query sulle annotazioni.

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 &currentQuad = 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));

Nuovi tipi di oggetti

• XrSpatialReferenceCacheANDROID

Nuovi comandi

• xrCreateSpatialReferenceCacheAsyncANDROID
• xrCreateSpatialReferenceCacheCompleteANDROID
• xrDestroySpatialReferenceCacheANDROID
• xrEnumerateSpatialAnnotationReferenceSourcesANDROID

Nuove strutture

• XrCreateSpatialReferenceCacheCompletionANDROID
• XrEventDataSpatialAnnotationTrackingANDROID
• XrSpatialAnnotationQuadANDROID
• XrSpatialAnnotationQuadDataANDROID
• XrSpatialCapabilityConfigurationAnnotationTrackingANDROID
• XrSpatialReferenceCacheCreateInfoANDROID

• Estensione di XrSpatialComponentDataQueryResultEXT :

  • XrSpatialComponentAnnotationQuadListANDROID

• Estensione di XrSpatialReferenceImageEXT :

  • XrSpatialAnnotationQuadReferenceANDROID

• Estensione di XrSystemProperties :

  • XrSystemSpatialAnnotationPropertiesANDROID

Nuovi enum

• XrSpatialAnnotationQuadAlignmentANDROID
• XrSpatialAnnotationReferenceSourceANDROID

Nuove costanti enum

• XR_ANDROID_SPATIAL_ANNOTATION_TRACKING_EXTENSION_NAME
• XR_ANDROID_spatial_annotation_tracking_SPEC_VERSION

• Estensione di XrObjectType :

  • XR_OBJECT_TYPE_SPATIAL_REFERENCE_CACHE_ANDROID

• Estensione di XrSpatialCapabilityEXT :

  • XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID

• Estensione di XrSpatialComponentTypeEXT :

  • XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID

• Estensione di XrStructureType :

  • XR_TYPE_CREATE_SPATIAL_REFERENCE_CACHE_COMPLETION_ANDROID
  • XR_TYPE_EVENT_DATA_SPATIAL_ANNOTATION_TRACKING_ANDROID
  • XR_TYPE_SPATIAL_ANNOTATION_QUAD_REFERENCE_ANDROID
  • XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_ANNOTATION_TRACKING_ANDROID
  • XR_TYPE_SPATIAL_COMPONENT_ANNOTATION_QUAD_LIST_ANDROID
  • XR_TYPE_SPATIAL_REFERENCE_CACHE_CREATE_INFO_ANDROID
  • XR_TYPE_SYSTEM_SPATIAL_ANNOTATION_PROPERTIES_ANDROID

Problemi

Cronologia delle versioni

• Revisione 1, 17/09/2025 (Levana Chen)

  • Descrizione iniziale dell'estensione.