XR_EXT_spatial_image_tracking

Name String

XR_EXT_spatial_image_tracking

Tipo di estensione

Estensione dell'istanza

Numero di interno registrato

783

Revisione

1

Stato della ratifica

Non ratificato

Dipendenze di estensioni e versioni

XR_EXT_spatial_entity

Collaboratori

Daniel Guttenberg, Qualcomm
Nihav Jain, Google
Jared Finder, Google
Zhipeng Liu, ByteDance

Panoramica

Questa estensione fornisce la funzionalità di monitoraggio delle immagini per l'estensione XR_EXT_spatial_entity. Consente alle applicazioni di rilevare e monitorare immagini planari specifiche, come indicato da insiemi di immagini di riferimento di input.

Un'immagine monitorata è rappresentata come un'entità spaziale con (o "che ha") i seguenti componenti:

  • XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT
  • XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT

In genere, le applicazioni utilizzano l'estensione di monitoraggio delle immagini spaziali nel seguente pattern:

  • Un'applicazione crea prima uno o più handle XrSpatialImageTrackingDatabaseEXT in base a set di dati di immagini di riferimento precaricati.
  • L'applicazione crea quindi un handle XrSpatialContextEXT in base agli handle XrSpatialImageTrackingDatabaseEXT creati in precedenza.
  • L'applicazione rilascia quindi i dati dell'immagine di riferimento per ridurre il consumo di memoria.
  • L'applicazione rileva ed esegue query sulle immagini in base ai pattern di accesso alle entità spaziali.
  • L'applicazione può caricare set aggiuntivi di immagini di riferimento e creare altri XrSpatialImageTrackingDatabaseEXT e successivamente XrSpatialContextEXT da questi per estendere il set di immagini rilevabili e tracciabili in modo dinamico in fase di runtime.
  • L'applicazione può distruggere gli handle XrSpatialImageTrackingDatabaseEXT per ridurre l'insieme di immagini rilevabili e tracciabili in modo dinamico in fase di runtime.
  • L'applicazione può eliminare gli handle XrSpatialContextEXT per ridurre l'insieme di immagini rilevabili e tracciabili in modo dinamico in fase di runtime.

Supporto di runtime

Un runtime deve annunciare il proprio supporto per la funzionalità di tracciamento delle immagini utilizzando xrEnumerateSpatialCapabilitiesEXT elencando la seguente funzionalità:

  • XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT

Configurazione

Per attivare il rilevamento e il monitoraggio delle immagini planari, l'applicazione può passare strutture XrSpatialCapabilityConfigurationImageTrackingEXT in XrSpatialContextCreateInfoEXT :: capabilityConfigs quando chiama la funzione xrCreateSpatialContextAsyncEXT e passa array di strutture XrSpatialImageTrackingDatabaseEXT in ogni XrSpatialCapabilityConfigurationImageTrackingEXT :: imageTrackingDatabases .

Creazione del set di immagini di input

Per specificare le immagini di riferimento da rilevare e monitorare, l'applicazione deve creare almeno un set di immagini di riferimento di input. Un insieme di immagini di riferimento di input è rappresentato da un handle XrSpatialImageTrackingDatabaseEXT e contiene almeno un'immagine.

XR_DEFINE_HANDLE(XrSpatialImageTrackingDatabaseEXT)

L'handle XrSpatialImageTrackingDatabaseEXT rappresenta le risorse per scoprire e aggiornare un certo numero di immagini spaziali nell'ambiente dell'utente. Le applicazioni possono utilizzare questo handle per rilevare e aggiornare le immagini spaziali utilizzando altre funzioni di questa estensione.

Crea il database di monitoraggio delle immagini spaziali

La funzione xrCreateSpatialImageTrackingDatabaseAsyncEXT è definita come:

XrResult xrCreateSpatialImageTrackingDatabaseAsyncEXT(
    XrSession                                   session,
    const XrSpatialImageTrackingDatabaseCreateInfoEXT* createInfo,
    XrFutureEXT*                                future);

Descrizioni dei parametri

  • session è un XrSession in cui sarà attivo il database di monitoraggio delle immagini spaziali.
  • createInfo è l'oggetto XrSpatialImageTrackingDatabaseCreateInfoEXT utilizzato per specificare i parametri del database di monitoraggio delle immagini spaziali.
  • future è un puntatore a un XrFutureEXT .

Un'applicazione può creare un handle XrSpatialImageTrackingDatabaseEXT utilizzando la funzione xrCreateSpatialImageTrackingDatabaseAsyncEXT e configurare i set di immagini di riferimento di input del database di monitoraggio delle immagini con createInfo .

Il runtime deve restituire XR_ERROR_SPATIAL_IMAGE_FORMAT_UNSUPPORTED_EXT se XrSpatialReferenceImageEXT :: format di una qualsiasi delle immagini di riferimento di input non è enumerato da xrEnumerateSpatialReferenceImageFormatsEXT .

Il runtime deve restituire XR_ERROR_SPATIAL_IMAGE_INVALID_EXT se l'array XrSpatialReferenceImageEXT :: planes di una qualsiasi delle immagini di riferimento di input non può essere valutato in base ai metadati dell'immagine di riferimento di XrSpatialReferenceImageEXT .

Il runtime deve restituire XR_ERROR_SPATIAL_IMAGE_INVALID_EXT se l'array XrSpatialReferenceImageEXT :: planes di una qualsiasi delle immagini di riferimento di input non fornisce esattamente lo stesso numero di piani dei canali di colore di XrSpatialReferenceImageEXT :: format.

Se un runtime applica un sistema di autorizzazioni per controllare l'accesso dell'applicazione alla funzionalità di rilevamento delle immagini, il runtime deve restituire XR_ERROR_PERMISSION_INSUFFICIENT se queste autorizzazioni non sono state concesse all'applicazione.

Questa funzione avvia un'operazione asincrona e crea un XrFutureEXT corrispondente, utilizzabile con xrPollFutureEXT e le funzioni correlate. Il valore restituito da questa funzione indica solo se i parametri erano accettabili per pianificare l'operazione asincrona. La funzione di completamento corrispondente è xrCreateSpatialImageTrackingDatabaseCompleteEXT , utilizzabile quando un future di questa funzione è nello stato READY, con gli output compilati da questa funzione nella struttura di completamento XrCreateSpatialImageTrackingDatabaseCompletionEXT .

Utilizzo valido (implicito)

Codici di risposta

Operazione riuscita

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Errore

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_PERMISSION_INSUFFICIENT
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_IMAGE_FORMAT_UNSUPPORTED_EXT
  • XR_ERROR_SPATIAL_IMAGE_INVALID_EXT
  • XR_ERROR_SPATIAL_IMAGE_SIZE_MISSING_EXT
  • XR_ERROR_VALIDATION_FAILURE

La struttura XrSpatialImageTrackingDatabaseCreateInfoEXT è definita come:

typedef struct XrSpatialImageTrackingDatabaseCreateInfoEXT {
    XrStructureType                      type;
    const void*                          next;
    uint32_t                             spatialReferenceImageCount;
    const XrSpatialReferenceImageEXT*    spatialReferenceImages;
} XrSpatialImageTrackingDatabaseCreateInfoEXT;

Descrizioni dei membri

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture.
  • spatialReferenceImageCount è il numero di elementi nell'array spatialReferenceImages.
  • spatialReferenceImages è un array di XrSpatialReferenceImageEXT .

La struttura XrSpatialImageTrackingDatabaseCreateInfoEXT descrive le informazioni per creare un handle XrSpatialImageTrackingDatabaseEXT.

Ogni XrSpatialImageTrackingDatabaseEXT deve essere creato con almeno un XrSpatialReferenceImageEXT nell'array XrSpatialImageTrackingDatabaseCreateInfoEXT :: spatialReferenceImages.

Utilizzo valido (implicito)

La funzione xrCreateSpatialImageTrackingDatabaseCompleteEXT è definita come:

XrResult xrCreateSpatialImageTrackingDatabaseCompleteEXT(
    XrSession                                   session,
    XrFutureEXT                                 future,
    XrCreateSpatialImageTrackingDatabaseCompletionEXT* completion);

Descrizioni dei parametri

xrCreateSpatialImageTrackingDatabaseCompleteEXT completa l'operazione asincrona avviata da xrCreateSpatialImageTrackingDatabaseAsyncEXT .

Il runtime non deve accedere ad alcun puntatore XrSpatialReferenceImagePlaneEXT :: buffer fornito dall'array di input XrSpatialImageTrackingDatabaseCreateInfoEXT :: spatialReferenceImages per questa chiamata xrCreateSpatialImageTrackingDatabaseAsyncEXT dopo che è stata completata. L'applicazione può liberare i dati XrSpatialReferenceImagePlaneEXT :: buffer dopo il completamento di xrCreateSpatialImageTrackingDatabaseAsyncEXT per ridurre il footprint della memoria.

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

Utilizzo valido (implicito)

Codici di risposta

Operazione riuscita

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Errore

  • 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 XrCreateSpatialImageTrackingDatabaseCompletionEXT è definita come:

typedef struct XrCreateSpatialImageTrackingDatabaseCompletionEXT {
    XrStructureType                      type;
    void*                                next;
    XrResult                             futureResult;
    XrSpatialImageTrackingDatabaseEXT    database;
} XrCreateSpatialImageTrackingDatabaseCompletionEXT;

Descrizioni dei membri

Codici di reso futuri

Valori futureResult:

Operazione riuscita

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Errore

  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_SPATIAL_IMAGE_FORMAT_UNSUPPORTED_EXT
  • XR_ERROR_SPATIAL_IMAGE_INVALID_EXT

Se futureResult è un codice di esito positivo, database deve essere un handle valido. Se database è valido, rimane tale solo all'interno del ciclo di vita di xrCreateSpatialImageTrackingDatabaseAsyncEXT :: session o finché l'applicazione non distrugge database con xrDestroySpatialImageTrackingDatabaseEXT , a seconda di quale evento si verifica per primo.

Utilizzo valido (implicito)

Elimina il database di monitoraggio delle immagini spaziali

La funzione xrDestroySpatialImageTrackingDatabaseEXT è definita come:

XrResult xrDestroySpatialImageTrackingDatabaseEXT(
    XrSpatialImageTrackingDatabaseEXT           database);

Descrizioni dei parametri

L'applicazione può chiamare la funzione xrDestroySpatialImageTrackingDatabaseEXT per rilasciare l'handle database e le risorse sottostanti al termine delle attività di rilevamento e aggiornamento delle immagini spaziali.

L'applicazione può chiamare la funzione xrDestroySpatialImageTrackingDatabaseEXT prima di chiamare xrDestroySpatialContextEXT . Il runtime non deve più segnalare le immagini gestite da questo XrSpatialImageTrackingDatabaseEXT eliminato. Il runtime deve continuare a segnalare le immagini gestite da altri database.

Il runtime deve garantire che gli snapshot di rilevamento restituiti da xrCreateSpatialDiscoverySnapshotCompleteEXT non contengano immagini relative a handle XrSpatialImageTrackingDatabaseEXT distrutti o altrimenti non validi, anche se l'handle è stato distrutto dopo che l'applicazione ha chiamato xrCreateSpatialDiscoverySnapshotAsyncEXT . Dato che i dati in uno snapshot spaziale sono immutabili, l'applicazione dovrebbe distruggere tutti gli handle XrSpatialSnapshotEXT creati prima di distruggere database , altrimenti l'applicazione potrebbe ricevere handle XrSpatialImageTrackingDatabaseEXT non validi quando utilizza xrQuerySpatialComponentDataEXT .

L'applicazione può chiamare la funzione xrDestroySpatialContextEXT per rilasciare l'handle XrSpatialContextEXT prima di distruggere uno degli handle XrSpatialImageTrackingDatabaseEXT con cui è stato creato XrSpatialContextEXT. Il runtime non deve distruggere implicitamente questi handle XrSpatialImageTrackingDatabaseEXT quando XrSpatialContextEXT viene distrutto.

La gestione indipendente della durata di XrSpatialContextEXT e XrSpatialImageTrackingDatabaseEXT consente alle applicazioni di riutilizzare gli handle XrSpatialImageTrackingDatabaseEXT creati in precedenza senza dover ripetere la costosa procedura di creazione.

Ad esempio, l'eliminazione di un XrSpatialContextEXT e la successiva ricreazione di un altro XrSpatialContextEXT con lo stesso XrSpatialImageTrackingDatabaseEXT consente di mettere in pausa e riprendere il rilevamento delle immagini senza dover eseguire un'altra procedura di inizializzazione.

Utilizzo valido (implicito)

Thread safety

  • L'accesso a database e a qualsiasi handle secondario deve essere sincronizzato esternamente

Codici di risposta

Operazione riuscita

  • XR_SUCCESS

Errore

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

Supporto dei formati delle immagini di input

Le applicazioni devono chiamare xrEnumerateSpatialReferenceImageFormatsEXT per ottenere l'elenco dei formati delle immagini di riferimento di input supportati.

La funzione xrEnumerateSpatialReferenceImageFormatsEXT è definita come:

XrResult xrEnumerateSpatialReferenceImageFormatsEXT(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    XrSpatialCapabilityEXT                      capability,
    uint32_t                                    formatCapacityInput,
    uint32_t*                                   formatCountOutput,
    XrSpatialReferenceImageFormatEXT*           formats);

Descrizioni dei parametri

  • instance è un handle per un XrInstance .
  • systemId è il XrSystemId di cui verranno enumerati i formati delle immagini di riferimento di input.
  • capability è l'XrSpatialCapabilityEXT per cui verranno enumerati i formati delle immagini di riferimento di input.
  • formatCapacityInput è la capacità dell'array formats o 0 per indicare una richiesta di recupero della capacità richiesta.
  • formatCountOutput è il numero di formati o la capacità richiesta nel caso in cui formatCapacityInput non sia sufficiente.
  • formats è un array di XrSpatialReferenceImageFormatEXT . Può essere NULL se formatCapacityInput è 0.
  • Consulta la sezione Parametri della dimensione del buffer per una descrizione dettagliata del recupero della dimensione formats richiesta.

L'applicazione può enumerare l'elenco dei formati delle immagini di riferimento di input supportati da un determinato XrSystemId per un determinato XrSpatialCapabilityEXT utilizzando xrEnumerateSpatialReferenceImageFormatsEXT .

Il runtime non deve enumerare i formati delle estensioni non abilitate per instance .

Utilizzo valido (implicito)

Codici di risposta

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

Consulta XrSpatialReferenceImageFormatEXT per un elenco completo di tutti i formati delle immagini di riferimento supportati da qualsiasi estensione.

typedef enum XrSpatialReferenceImageFormatEXT {
    XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGBA_8888_EXT = 1,
    XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGB_888_EXT = 2,
    XR_SPATIAL_REFERENCE_IMAGE_FORMAT_YUV_420_888_EXT = 3,
    XR_SPATIAL_REFERENCE_IMAGE_FORMAT_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialReferenceImageFormatEXT;

L'enumerazione XrSpatialReferenceImageFormatEXT identifica i formati delle immagini di riferimento di input che il runtime potrebbe supportare.

Devono essere supportati almeno il valore XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGBA_8888_EXT e il valore XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGB_888_EXT.

Gli enumeranti hanno il seguente significato:

Descrizioni degli enumeranti

  • XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGBA_8888_EXT: un buffer RGBA. Il formato non fornisce alcuna garanzia in merito al layout dei dati dei pixel in memoria. I pixel devono essere accessibili utilizzando i metadati forniti dalle strutture XrSpatialReferenceImagePlaneEXT corrispondenti. Ogni canale di colore dei pixel ha una dimensione di 8 bit, per un totale di 32 bit per pixel.
  • XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGB_888_EXT: un buffer RGB. Il formato non fornisce alcuna garanzia in merito al layout dei dati dei pixel in memoria. I pixel devono essere accessibili utilizzando i metadati forniti dalle strutture XrSpatialReferenceImagePlaneEXT corrispondenti. Ogni canale di colore dei pixel ha una dimensione di 8 bit, il che rende ogni pixel di 24 bit.
  • XR_SPATIAL_REFERENCE_IMAGE_FORMAT_YUV_420_888_EXT: un buffer YUV con sottocampionamento della crominanza con pattern 4:2:0. Il formato non fornisce alcuna garanzia in merito al layout dei dati dei pixel in memoria. I pixel devono essere accessibili utilizzando i metadati forniti dalle strutture XrSpatialReferenceImagePlaneEXT corrispondenti. Ogni canale di colore dei pixel RGB decodificato ha una dimensione di 8 bit, per un totale di 24 bit per pixel.

Impostazioni di tracciamento delle immagini spaziali

Questa estensione fornisce strutture facoltative che l'applicazione può utilizzare per configurare la funzionalità di monitoraggio delle immagini.

Ottimizzazione delle immagini statiche

La struttura XrSpatialImageStaticOptimizationEXT è definita come:

typedef struct XrSpatialImageStaticOptimizationEXT {
    XrStructureType    type;
    const void*        next;
    XrBool32           optimizeForStaticImage;
} XrSpatialImageStaticOptimizationEXT;

Descrizioni dei membri

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture.
  • optimizeForStaticImage è un XrBool32 che indica se le immagini si muovono o meno. Un valore pari a XR_TRUE indica che le immagini non si muovono.

Se XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT viene enumerato da xrEnumerateSpatialCapabilityFeaturesEXT per la funzionalità XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, l'applicazione può concatenare XrSpatialImageStaticOptimizationEXT alla catena XrSpatialImageTrackingDatabaseCreateInfoEXT :: next o XrSpatialReferenceImageEXT :: next .

Se l'applicazione concatena XrSpatialImageStaticOptimizationEXT alla struttura XrSpatialImageTrackingDatabaseCreateInfoEXT, il runtime deve presumere che tutte le immagini di XrSpatialImageTrackingDatabaseEXT siano statiche se optimizeForStaticImage è impostato su XR_TRUE . Di conseguenza, il runtime deve presumere che tutte le immagini di quel XrSpatialImageTrackingDatabaseEXT non siano statiche se optimizeForStaticImage è impostato su XR_FALSE .

Se l'applicazione concatena XrSpatialImageStaticOptimizationEXT alla struttura XrSpatialReferenceImageEXT, il runtime deve presumere che questa immagine di riferimento sia statica se optimizeForStaticImage è impostato su XR_TRUE . Di conseguenza, il runtime deve presumere che questa immagine di riferimento non sia statica se optimizeForStaticImage è impostato su XR_FALSE . Il concatenamento della struttura XrSpatialImageStaticOptimizationEXT alla struttura XrSpatialReferenceImageEXT ha la precedenza sul concatenamento alla struttura XrSpatialImageTrackingDatabaseCreateInfoEXT.

Se XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT non è enumerato da xrEnumerateSpatialCapabilityFeaturesEXT per la funzionalità XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT e l'applicazione concatena una struttura XrSpatialImageStaticOptimizationEXT a una delle catene successive applicabili, il runtime deve restituire XR_ERROR_VALIDATION_FAILURE da xrCreateSpatialImageTrackingDatabaseAsyncEXT .

In questo modo, il runtime potrebbe generare una posa e una dimensione più accurate.

Questo potrebbe consentire al runtime di ridurre il consumo energetico.

Utilizzo valido (implicito)

Larghezza immagine di riferimento

La struttura XrSpatialImageSizeEXT è definita come:

typedef struct XrSpatialImageSizeEXT {
    XrStructureType    type;
    const void*        next;
    float              physicalWidth;
} XrSpatialImageSizeEXT;

Descrizioni dei membri

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture.
  • physicalWidth è un valore float che rappresenta la larghezza fisica in metri da impostare.

Se XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXT viene enumerato da xrEnumerateSpatialCapabilityFeaturesEXT per la funzionalità XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, l'applicazione può concatenare XrSpatialImageSizeEXT a XrSpatialImageTrackingDatabaseCreateInfoEXT :: next o XrSpatialReferenceImageEXT :: next .

Se l'applicazione concatena XrSpatialImageSizeEXT alla struttura XrSpatialImageTrackingDatabaseCreateInfoEXT, il runtime deve presumere che tutte le immagini di XrSpatialImageTrackingDatabaseEXT abbiano una larghezza di physicalWidth metri e un'altezza in base alle proporzioni fornite implicitamente tramite XrSpatialReferenceImageEXT :: width e XrSpatialReferenceImageEXT :: height .

Se l'applicazione concatena XrSpatialImageSizeEXT alla struttura XrSpatialReferenceImageEXT, il runtime deve presumere che questa immagine di riferimento abbia una larghezza di physicalWidth metri e un'altezza in base alle proporzioni fornite implicitamente tramite XrSpatialReferenceImageEXT :: width e XrSpatialReferenceImageEXT :: height . Il concatenamento della struttura XrSpatialImageSizeEXT alla struttura XrSpatialReferenceImageEXT ha la precedenza sul concatenamento alla struttura XrSpatialImageTrackingDatabaseCreateInfoEXT.

In questo modo, il runtime potrebbe restituire una posa e una dimensione più accurate.

Il runtime deve enumerare XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXT o XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT o entrambi.

Se XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT viene enumerato da xrEnumerateSpatialCapabilityFeaturesEXT, il runtime deve fornire automaticamente le dimensioni delle immagini per le immagini per le quali l'applicazione non ha fornito strutture XrSpatialImageSizeEXT come parte di una delle catene successive applicabili.

Affinché il runtime possa generare le dimensioni delle immagini in modo automatico e preciso, potrebbero essere necessarie determinate funzionalità e prerequisiti del dispositivo, ad esempio fotocamere stereo, parametri estrinseci e intrinseci della fotocamera calibrati con precisione.

Se XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT non è enumerato da xrEnumerateSpatialCapabilityFeaturesEXT, l'applicazione deve collegare le strutture XrSpatialImageSizeEXT alle catene successive applicabili in modo che tutte le immagini abbiano una dimensione esplicita, altrimenti il runtime deve restituire XR_ERROR_SPATIAL_IMAGE_SIZE_MISSING_EXT da xrCreateSpatialImageTrackingDatabaseAsyncEXT .

Utilizzo valido (implicito)

La struttura XrSpatialCapabilityConfigurationImageTrackingEXT è definita come:

typedef struct XrSpatialCapabilityConfigurationImageTrackingEXT {
    XrStructureType                             type;
    const void*                                 next;
    XrSpatialCapabilityEXT                      capability;
    uint32_t                                    enabledComponentCount;
    const XrSpatialComponentTypeEXT*            enabledComponents;
    uint32_t                                    imageTrackingDatabaseCount;
    const XrSpatialImageTrackingDatabaseEXT*    imageTrackingDatabases;
} XrSpatialCapabilityConfigurationImageTrackingEXT;

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_IMAGE_TRACKING_EXT .
  • enabledComponentCount è un uint32_t che specifica il numero di elementi in enabledComponents .
  • enabledComponents è un array di XrSpatialComponentTypeEXT che specifica i componenti da attivare per questa funzionalità.
  • imageTrackingDatabaseCount è un unint32_t che specifica il numero di elementi in imageTrackingDatabases .
  • imageTrackingDatabases è un array di handle XrSpatialImageTrackingDatabaseEXT che specifica i database di tracciamento delle immagini da attivare per il contesto spaziale.

Se il rilevamento delle immagini è supportato, il runtime deve attivarlo se viene passata una struttura XrSpatialCapabilityConfigurationImageTrackingEXT in XrSpatialContextCreateInfoEXT :: capabilityConfigs quando viene chiamato xrCreateSpatialContextAsyncEXT .

La struttura XrSpatialCapabilityConfigurationImageTrackingEXT consente all'applicazione di rilevare le immagini di riferimento rappresentate dagli handle XrSpatialImageTrackingDatabaseEXT in imageTrackingDatabases .

Il runtime deve restituire XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT se XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT non è enumerato da xrEnumerateSpatialCapabilitiesEXT .

Utilizzo valido (implicito)

Immagine di riferimento spaziale

La struttura XrSpatialReferenceImagePlaneEXT è definita come:

typedef struct XrSpatialReferenceImagePlaneEXT {
    uint32_t    bufferSize;
    uint8_t*    buffer;
    uint32_t    rowStride;
    uint32_t    pixelStride;
} XrSpatialReferenceImagePlaneEXT;

Descrizioni dei parametri

  • bufferSize è la dimensione dell'array buffer.
  • buffer è un array di dati uint8_t che rappresenta i dati del piano.
  • rowStride è la distanza in byte tra due posizioni iniziali di righe di dati di pixel consecutive.
  • pixelStride è la distanza in byte tra due pixel consecutivi.

Il runtime deve accedere a buffer in base ai pattern forniti dai parametri rowStride e pixelStride.

L'applicazione deve impostare rowStride e pixelStride in modo che il runtime estragga solo i pixel significativi di questo XrSpatialReferenceImagePlaneEXT.

Utilizzo valido (implicito)

  • L'estensione XR_EXT_spatial_image_tracking deve essere attivata prima di utilizzare XrSpatialReferenceImagePlaneEXT
  • buffer deve essere un puntatore a un array di valori bufferSize uint8_t
  • Il parametro bufferSize deve essere maggiore di 0

La struttura XrSpatialReferenceImageEXT è definita come:

typedef struct XrSpatialReferenceImageEXT {
    XrStructureType                           type;
    const void*                               next;
    uint32_t                                  width;
    uint32_t                                  height;
    XrSpatialReferenceImageFormatEXT          format;
    uint32_t                                  planeCount;
    const XrSpatialReferenceImagePlaneEXT*    planes;
} XrSpatialReferenceImageEXT;

Descrizioni dei parametri

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture.
  • width è la larghezza in pixel dell'immagine di riferimento.
  • height è l'altezza in pixel dell'immagine di riferimento.
  • format è un XrSpatialReferenceImageFormatEXT che rappresenta il formato dell'immagine.
  • planeCount è il numero di elementi nell'array planes.
  • planes è un array di strutture XrSpatialReferenceImagePlaneEXT che rappresentano i piani dei dati dell'immagine.

L'applicazione può creare una o più strutture XrSpatialReferenceImageEXT, ciascuna delle quali rappresenta una singola immagine di riferimento di input da passare alla funzione xrCreateSpatialImageTrackingDatabaseAsyncEXT tramite XrSpatialImageTrackingDatabaseCreateInfoEXT :: spatialReferenceImages durante la creazione di un handle XrSpatialImageTrackingDatabaseEXT.

I dati XrSpatialReferenceImagePlaneEXT :: buffer devono essere forniti dall'applicazione in un ordine dei pixel da sinistra a destra e dall'alto verso il basso.

L'applicazione deve fornire una struttura XrSpatialReferenceImagePlaneEXT nell'array XrSpatialReferenceImageEXT :: planes per ogni canale di colore di XrSpatialReferenceImageEXT :: format .

Utilizzo valido (implicito)

Componenti garantiti

Un runtime che supporta XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT deve fornire i seguenti componenti spaziali come componenti garantiti di tutte le entità rilevate da queste funzionalità e deve enumerarli in xrEnumerateSpatialCapabilityComponentTypesEXT :

  • XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT
  • XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT

Componente Immagine 2D

Componente List Struct per eseguire query sui dati

La struttura XrSpatialComponentImage2DListEXT è definita come:

typedef struct XrSpatialComponentImage2DListEXT {
    XrStructureType             type;
    const void*                 next;
    uint32_t                    imageCount;
    XrSpatialImage2DDataEXT*    images;
} XrSpatialComponentImage2DListEXT;

Descrizioni dei parametri

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture.
  • imageCount è il numero di elementi nell'array images.
  • images è un array di XrSpatialImage2DDataEXT .

Il runtime deve restituire XR_ERROR_VALIDATION_FAILURE da xrQuerySpatialComponentDataEXT se XrSpatialComponentImage2DListEXT si trova nella catena XrSpatialComponentDataQueryResultEXT :: next, ma XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT non è incluso in XrSpatialComponentDataQueryConditionEXT :: componentTypes .

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

Utilizzo valido (implicito)

Dati dei componenti

La struttura XrSpatialImage2DDataEXT è definita come:

typedef struct XrSpatialImage2DDataEXT {
    XrSpatialImageTrackingDatabaseEXT    imageTrackingDatabase;
    uint32_t                             referenceImageIndex;
} XrSpatialImage2DDataEXT;

Descrizioni dei parametri

L'applicazione può utilizzare imageTrackingDatabase per identificare quale XrSpatialImageTrackingDatabaseEXT creato in precedenza contiene l'immagine di riferimento di questa struttura XrSpatialImage2DDataEXT. Per questo XrSpatialImageTrackingDatabaseEXT , l'applicazione può utilizzare referenceImageIndex per identificare l'XrSpatialReferenceImageEXT di questa struttura XrSpatialImage2DDataEXT abbinandola all'ordine di input dell'array XrSpatialImageTrackingDatabaseCreateInfoEXT :: spatialReferenceImages.

L'insieme di immagini di riferimento definito dall'insieme di tutti i database attivi non deve includere immagini duplicate. L'inclusione di immagini duplicate potrebbe causare un comportamento di rilevamento o monitoraggio negativo, ad esempio la restituzione di indici incoerenti o multipli.

Utilizzo valido (implicito)

Configurazione

Se XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT è enumerato in XrSpatialCapabilityComponentTypesEXT :: componentTypes per una funzionalità, l'applicazione può attivarla includendo il valore dell'enum nell'elenco XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents. Questo componente non richiede alcuna configurazione speciale per essere incluso nella catena successiva di XrSpatialCapabilityConfigurationBaseHeaderEXT .

Componente 2D delimitato

Il componente 2D delimitato fornisce il centro e le estensioni dell'immagine spaziale rappresentata dall'entità su cui si trova. Per ulteriori dettagli sul componente 2D delimitato, consulta 2D delimitato.

Esempio di codice

Scopri le immagini spaziali ed esegui query sui dati dei componenti

Il seguente codice di esempio mostra come rilevare le entità spaziali per la funzionalità di monitoraggio delle immagini ed eseguire query sui dati dei relativi componenti.

XrInstance instance; // Previously initialized
XrSystemId systemId; // Previously initialized
XrSession session; // Previously initialized

uint32_t capabilityCountOutput = 0;
CHK_XR(xrEnumerateSpatialCapabilitiesEXT(instance, systemId, 0, &capabilityCountOutput, nullptr));
std::vector<XrSpatialCapabilityEXT> capabilities(capabilityCountOutput);
CHK_XR(xrEnumerateSpatialCapabilitiesEXT(instance, systemId, capabilities.size(), &capabilityCountOutput, capabilities.data()));

if (std::find(capabilities.begin(), capabilities.end(), XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT) == capabilities.end()) {
  // Image tracking not supported
}

XrSpatialCapabilityComponentTypesEXT imageTrackingComponents{XR_TYPE_SPATIAL_CAPABILITY_COMPONENT_TYPES_EXT};
CHK_XR(xrEnumerateSpatialCapabilityComponentTypesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, &imageTrackingComponents));
std::vector<XrSpatialComponentTypeEXT> imageTrackingCapabilityComponents(imageTrackingComponents.componentTypeCountOutput);
imageTrackingComponents.componentTypes = imageTrackingCapabilityComponents.data();
CHK_XR(xrEnumerateSpatialCapabilityComponentTypesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, &imageTrackingComponents));

if (std::find(imageTrackingCapabilityComponents.begin(), imageTrackingCapabilityComponents.end(), XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT) == imageTrackingCapabilityComponents.end()) {
  // The image2d component is not supported
}

uint32_t capabilityFeatureCountOutput = 0;
CHK_XR(xrEnumerateSpatialCapabilityFeaturesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, 0, &capabilityFeatureCountOutput, nullptr));
std::vector<XrSpatialCapabilityFeatureEXT> capabilityFeatures(capabilityFeatureCountOutput);
CHK_XR(xrEnumerateSpatialCapabilityFeaturesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, capabilityFeatures.size(), &capabilityFeatureCountOutput, capabilityFeatures.data()));

// Helper function to query optional feature support
const auto supportsFeature = [&capabilityFeatures](XrSpatialCapabilityFeatureEXT feature) {
  return std::find(capabilityFeatures.begin(), capabilityFeatures.end(), feature) != capabilityFeatures.end();
};

// supported state for optional features
const bool supportsAutomaticScaleEstimation = supportsFeature(XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT);
const bool supportsStaticImages = supportsFeature(XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT);
const bool supportsFixedSizeImages = supportsFeature(XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXT);

uint32_t formatCountOutput = 0;
CHK_XR(xrEnumerateSpatialReferenceImageFormatsEXT(instance, systemId, XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, 0, &formatCountOutput, nullptr));
std::vector<XrSpatialReferenceImageFormatEXT> formats(formatCountOutput);
CHK_XR(xrEnumerateSpatialReferenceImageFormatsEXT(instance, systemId, XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, formats.size(), &formatCountOutput, formats.data()));

if (std::find(formats.begin(), formats.end(), XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGBA_8888_EXT) == formats.end()) {
  // The desired format is not supported
}

// Helper function to wait for XrFutureEXT completion
auto waitUntilReady = [&](XrFutureEXT future) {
  XrFuturePollInfoEXT pollInfo{XR_TYPE_FUTURE_POLL_INFO_EXT};
  XrFuturePollResultEXT pollResult{XR_TYPE_FUTURE_POLL_RESULT_EXT};
  pollInfo.future = future;
  do {
    // sleep(1);
    CHK_XR(xrPollFutureEXT(instance, &pollInfo, &pollResult));
  } while (pollResult.state != XR_FUTURE_STATE_READY_EXT);
};

// Data/metadata about reference images (identifiers, 3D models, trigger functions, etc.)
std::vector<std::string> referenceImageIdentifiers;

XrSpatialImageTrackingDatabaseEXT imageTrackingDatabase{};
{
  uint32_t imgSize; // preloaded interleaved RGBA buffer size
  uint8_t* img; // preloaded interleaved RGBA buffer data

  // interleaved RGBA buffer memory layout and buffer positions

  // first row of pixels
  // img[0] | img[1] | img[2] | img[3] | img[0]+pStride | img[1]+pStride | ...
  //  R0    |   G0   |   B0   |   A0   |       R1       |       G1       | ...

  // second row of pixels
  // img[0]+rStride | img[1]+rStride | img[2]+rStride | img[3]+rStride | img[0]+rStride+pStride | ...
  //      R640      |      G640      |      B640      |      A640      |          R641          | ...

  XrSpatialReferenceImagePlaneEXT spatialReferenceImagePlanes[4];

  for (int i = 0; i < 4; ++i) { // for each plane (0=R, 1=G, 2=B, 3=A)
    spatialReferenceImagePlanes[i].buffer = img + i; // set each plane buffer pointer to the first pixel of the plane
    spatialReferenceImagePlanes[i].bufferSize = imgSize - i; // adjust remeinaing buffer size according to offset applied
    spatialReferenceImagePlanes[i].rowStride = 640 * 4; // set byte offset to start of next row for this plane
    spatialReferenceImagePlanes[i].pixelStride = 4; // set byte offset to next pixel for this plane
  }

  XrSpatialReferenceImageEXT spatialReferenceImage{XR_TYPE_SPATIAL_REFERENCE_IMAGE_EXT};
  spatialReferenceImage.width = 640;
  spatialReferenceImage.height = 480;
  spatialReferenceImage.format = XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGBA_8888_EXT;
  spatialReferenceImage.planeCount = 4;
  spatialReferenceImage.planes = spatialReferenceImagePlanes;

  referenceImageIdentifiers.emplace_back("MyReferenceImage");

  // Helper function to append to the next chain
  XrBaseOutStructure* appendTo = reinterpret_cast<XrBaseOutStructure*>(&spatialReferenceImage);
  const auto appendToNextChain = [&appendTo](XrBaseOutStructure* toAppend) {
    appendTo->next = toAppend;
    appendTo = toAppend;
  };

  XrSpatialImageSizeEXT imageSize{XR_TYPE_SPATIAL_IMAGE_SIZE_EXT};
  imageSize.physicalWidth = 0.1f;

  if (!supportsAutomaticScaleEstimation) {
    if (supportsFixedSizeImages) {
      appendToNextChain(reinterpret_cast<XrBaseOutStructure*>(&imageSize));
    }
  }

  XrSpatialImageStaticOptimizationEXT imageStaticOptimization{XR_TYPE_SPATIAL_IMAGE_STATIC_OPTIMIZATION_EXT};
  imageStaticOptimization.optimizeForStaticImage = XR_TRUE;

  if (supportsStaticImages) {
    appendToNextChain(reinterpret_cast<XrBaseOutStructure*>(&imageStaticOptimization));
  }

  XrSpatialImageTrackingDatabaseCreateInfoEXT spatialImageTrackingDatabaseCreateInfo{XR_TYPE_SPATIAL_IMAGE_TRACKING_DATABASE_CREATE_INFO_EXT};
  spatialImageTrackingDatabaseCreateInfo.spatialReferenceImages = &spatialReferenceImage;
  spatialImageTrackingDatabaseCreateInfo.spatialReferenceImageCount = 1;

  XrFutureEXT createImageTrackingDatabaseFuture = XR_NULL_FUTURE_EXT;
  CHK_XR(xrCreateSpatialImageTrackingDatabaseAsyncEXT(session, &spatialImageTrackingDatabaseCreateInfo, &createImageTrackingDatabaseFuture));

  waitUntilReady(createImageTrackingDatabaseFuture);

  XrCreateSpatialImageTrackingDatabaseCompletionEXT imageTrackingCompletion{XR_TYPE_CREATE_SPATIAL_IMAGE_TRACKING_DATABASE_COMPLETION_EXT};
  CHK_XR(xrCreateSpatialImageTrackingDatabaseCompleteEXT(session, createImageTrackingDatabaseFuture, &imageTrackingCompletion));
  if (imageTrackingCompletion.futureResult != XR_SUCCESS) {
    // Error, image tracking database creation failed
  }

  imageTrackingDatabase = imageTrackingCompletion.database;
}

XrSpatialContextEXT spatialContext{};
{
  const std::array<XrSpatialComponentTypeEXT, 2> enabledComponents = {
    XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT,
    XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT
  };

  // Configure the image tracking capability for the spatial context
  XrSpatialCapabilityConfigurationImageTrackingEXT imageTrackingCapabilityConfig{XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_IMAGE_TRACKING_EXT};
  imageTrackingCapabilityConfig.capability = XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT;
  imageTrackingCapabilityConfig.enabledComponentCount = enabledComponents.size();
  imageTrackingCapabilityConfig.enabledComponents = enabledComponents.data();
  imageTrackingCapabilityConfig.imageTrackingDatabaseCount = 1;
  imageTrackingCapabilityConfig.imageTrackingDatabases = &imageTrackingDatabase;

  std::vector<XrSpatialCapabilityConfigurationBaseHeaderEXT*> capabilityConfigs;
  capabilityConfigs.push_back(reinterpret_cast<XrSpatialCapabilityConfigurationBaseHeaderEXT*>(&imageTrackingCapabilityConfig));

  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
  }

  spatialContext = completion.spatialContext;
}

auto discoverSpatialEntities = [&](XrSpatialContextEXT spatialContext, XrTime time) {
  // We want to look for entities that have the following components
  std::array<XrSpatialComponentTypeEXT, 2> snapshotComponents {XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT, XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT};

  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 = localSpace;
  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 the bounded2d component data
    XrSpatialComponentTypeEXT componentsToQuery[] = {XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT, XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT};
    XrSpatialComponentDataQueryConditionEXT queryCond{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT};
    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<XrSpatialBounded2DDataEXT> bounded2d(queryResult.entityIdCountOutput);
    XrSpatialComponentBounded2DListEXT boundsList{XR_TYPE_SPATIAL_COMPONENT_BOUNDED_2D_LIST_EXT};
    boundsList.boundCount = bounded2d.size();
    boundsList.bounds = bounded2d.data();
    queryResult.next = &boundsList;

    std::vector<XrSpatialImage2DDataEXT> image2d(queryResult.entityIdCountOutput);
    XrSpatialComponentImage2DListEXT imagesList{XR_TYPE_SPATIAL_COMPONENT_IMAGE_2D_LIST_EXT};
    imagesList.imageCount = image2d.size();
    imagesList.images = image2d.data();
    queryResult.next = &imagesList;

    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 XrSpatialImage2DDataEXT& currentImage2d = image2d[i];
        const std::string& currentReferenceImageIdentifier = referenceImageIdentifiers[currentImage2d.referenceImageIndex];
        std::cout << currentReferenceImageIdentifier << std::endl; // Outputs the "MyReferenceImage" string the app defined previously; could be any other assocatied data or action.

        // Access bounded2d[i] for image bounds
      }
    }

    CHK_XR(xrDestroySpatialSnapshotEXT(completion.snapshot));
  }
};

while (1) {
  // For every frame in frame loop

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

  // Finish frame loop
}

CHK_XR(xrDestroySpatialContextEXT(spatialContext));

// Unload spatial image tracking resources internally
CHK_XR(xrDestroySpatialImageTrackingDatabaseEXT(imageTrackingDatabase));

Nuovi tipi di oggetti

Nuovi comandi

Nuove strutture

Nuovi enum

Nuove costanti enum

  • XR_EXT_SPATIAL_IMAGE_TRACKING_EXTENSION_NAME
  • XR_EXT_spatial_image_tracking_SPEC_VERSION

  • Estensione di XrObjectType :

    • XR_OBJECT_TYPE_SPATIAL_IMAGE_TRACKING_DATABASE_EXT

  • Estensione di XrResult :

    • XR_ERROR_SPATIAL_IMAGE_FORMAT_UNSUPPORTED_EXT
    • XR_ERROR_SPATIAL_IMAGE_INVALID_EXT
    • XR_ERROR_SPATIAL_IMAGE_SIZE_MISSING_EXT

  • Estensione di XrSpatialCapabilityEXT :

    • XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT

  • Estensione di XrSpatialCapabilityFeatureEXT :

    • XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT
    • XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXT
    • XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT

  • Estensione di XrSpatialComponentTypeEXT :

    • XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT

  • Estensione di XrStructureType :

    • XR_TYPE_CREATE_SPATIAL_IMAGE_TRACKING_DATABASE_COMPLETION_EXT
    • XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_IMAGE_TRACKING_EXT
    • XR_TYPE_SPATIAL_COMPONENT_IMAGE_2D_LIST_EXT
    • XR_TYPE_SPATIAL_IMAGE_SIZE_EXT
    • XR_TYPE_SPATIAL_IMAGE_STATIC_OPTIMIZATION_EXT
    • XR_TYPE_SPATIAL_IMAGE_TRACKING_DATABASE_CREATE_INFO_EXT
    • XR_TYPE_SPATIAL_REFERENCE_IMAGE_EXT

Problemi

Cronologia delle versioni

  • Revisione 1, 22 aprile 2025 (Daniel Guttenberg, Qualcomm)

    • Descrizione iniziale dell'estensione