XR_ANDROID_trackables_image
Stringa del nome
XR_ANDROID_trackables_image
Tipo di estensione
Estensione dell'istanza
Numero di interno registrato
710
Revisione
1
Stato di ratifica
Non ratificato
Dipendenze da estensioni e versioni
XR_EXT_future
e
XR_ANDROID_trackables
Data ultima modifica
2025-04-08
Stato IP
Nessuna rivendicazione di proprietà intellettuale nota.
Collaboratori
Christopher Doer, Google
Levana Chen, Google
Jared Finder, Google
Spencer Quin, Google
Nihav Jain, Google
Diego Tipaldi, Google
Daniel Guttenberg, Qualcomm
Mark Vadasi, Qualcomm
Markus Birkner, Qualcomm
Maximilian Mayer, Qualcomm
Panoramica
Questa estensione consente il monitoraggio delle immagini planari specificate da set di immagini di riferimento di input.
Autorizzazioni
Le applicazioni Android devono disporre dell'autorizzazione android.permission.SCENE_UNDERSTANDING_COARSE elencata nel loro manifest, in quanto questa estensione dipende da XR_ANDROID_trackables ed espone la geometria dell'ambiente. L'autorizzazione android.permission.SCENE_UNDERSTANDING_COARSE è considerata pericolosa.
(livello di protezione: pericoloso)
Ispeziona la funzionalità del sistema
La struttura XrSystemImageTrackingPropertiesANDROID è definita come:
typedef struct XrSystemImageTrackingPropertiesANDROID {
XrStructureType type;
void* next;
XrBool32 supportsImageTracking;
XrBool32 supportsPhysicalSizeEstimation;
uint32_t maxTrackedImageCount;
uint32_t maxLoadedImageCount;
} XrSystemImageTrackingPropertiesANDROID;
Descrizioni dei membri
typeè l'XrStructureType di questa struttura.nextèNULLo un puntatore alla struttura successiva in una catena di strutture. Queste strutture non sono definite in OpenXR di base o in questa estensione. Per maggiori dettagli sulla catena di strutture, consulta la struttura in fase di estensione ( XrSystemProperties).supportsImageTrackingè unXrBool32che indica se il sistema attuale fornisce la funzionalità di monitoraggio delle immagini.supportsPhysicalSizeEstimationè unXrBool32che indica se il sistema attuale fornisce la stima delle dimensioni dell'immagine.maxTrackedImageCountè il numero massimo totale di immagini che possono essere monitorate contemporaneamente.maxLoadedImageCountè il numero massimo totale di immagini di riferimento che possono essere caricate in tutti i database.
Un'applicazione può verificare se il sistema è in grado di tracciare le immagini estendendo XrSystemProperties con la struttura XrSystemImageTrackingPropertiesANDROID quando chiama xrGetSystemProperties . Il runtime deve restituire XR_ERROR_FEATURE_UNSUPPORTED per la creazione del tracker delle immagini se e solo se supportsImageTracking è XR_FALSE .
Se un runtime supporta il monitoraggio delle immagini, deve supportare maxTrackedImageCount immagini monitorate in un determinato momento.
Se un runtime supporta il monitoraggio delle immagini, deve supportare maxLoadedImageCount immagini caricate in un determinato momento.
Se un runtime supporta la stima delle dimensioni dell'immagine, l'applicazione può impostare XrTrackableImageDatabaseEntryANDROID :: physicalWidth 0 per indicare l'utilizzo della stima delle dimensioni. In caso contrario, l'applicazione deve impostare XrTrackableImageDatabaseEntryANDROID :: physicalWidth su un valore positivo o verrà restituito XR_ERROR_VALIDATION_FAILURE.
Utilizzo valido (implicito)
- L'estensione
XR_ANDROID_trackables_imagedeve essere attivata prima di utilizzare XrSystemImageTrackingPropertiesANDROID -
typedeve essereXR_TYPE_SYSTEM_IMAGE_TRACKING_PROPERTIES_ANDROID -
nextdeve essereNULLo un puntatore valido alla struttura successiva in una catena di strutture
Creazione di database
L'applicazione può creare un handle XrTrackableImageDatabaseANDROID creando una o più strutture XrTrackableImageDatabaseEntryANDROID e passandole alla funzione xrCreateTrackableImageDatabaseAsyncANDROID tramite una struttura XrTrackableImageDatabaseCreateInfoANDROID.
L'applicazione deve fornire almeno una XrTrackableImageDatabaseEntryANDROID durante la creazione di un handle XrTrackableImageDatabaseANDROID.
Un XrTrackableImageDatabaseANDROID è un handle che rappresenta un insieme di immagini di riferimento elaborate che possono essere rilevate e monitorate nell'ambiente.
XR_DEFINE_HANDLE(XrTrackableImageDatabaseANDROID)
La struttura XrTrackableImageDatabaseEntryANDROID è definita come:
typedef struct XrTrackableImageDatabaseEntryANDROID {
XrStructureType type;
const void* next;
XrTrackableImageTrackingModeANDROID trackingMode;
float physicalWidth;
uint32_t imageWidth;
uint32_t imageHeight;
XrTrackableImageFormatANDROID format;
uint32_t bufferSize;
const uint8_t* buffer;
} XrTrackableImageDatabaseEntryANDROID;
Descrizioni dei membri
typeè l'XrStructureType di questa struttura.nextèNULLo un puntatore alla struttura successiva in una catena di strutture. Queste strutture non sono definite in OpenXR di base o in questa estensione.trackingModeè un XrTrackableImageTrackingModeANDROID che indica la modalità di monitoraggio desiderata.physicalWidthindica la larghezza dell'immagine in metri. Se è zero, le dimensioni dell'immagine verranno stimate online.imageWidthindica la larghezza dell'immagine in pixel.imageHeightindica l'altezza dell'immagine in pixel.formatè un XrTrackableImageFormatANDROID che indica il formato dei dati immagine inbuffer.bufferSizeindica la lunghezza in byte dibuffer.bufferè il bufferuint8_tcontenente i dati dei pixel dell'immagine di riferimento. I contenuti dibufferdevono essere validi per la durata dell'operazione asincrona di creazione del database, che viene avviata da xrCreateTrackableImageDatabaseAsyncANDROID e completata da xrCreateTrackableImageDatabaseCompleteANDROID .
L'applicazione potrebbe impostare physicalWidth su 0 per richiedere la stima delle dimensioni online se XrSystemImageTrackingPropertiesANDROID :: supportsPhysicalSizeEstimation è XR_TRUE .
Il runtime potrebbe restituire XR_ERROR_VALIDATION_FAILURE da xrCreateTrackableImageDatabaseAsyncANDROID se bufferSize non corrisponde alle dimensioni previste in base a imageWidth , imageHeight e format della voce .
Utilizzo valido (implicito)
- L'estensione
XR_ANDROID_trackables_imagedeve essere abilitata prima di utilizzare XrTrackableImageDatabaseEntryANDROID -
typedeve essereXR_TYPE_TRACKABLE_IMAGE_DATABASE_ENTRY_ANDROID -
nextdeve essereNULLo un puntatore valido alla struttura successiva in una catena di strutture -
trackingModedeve essere un valore XrTrackableImageTrackingModeANDROID valido -
formatdeve essere un valore XrTrackableImageFormatANDROID valido -
bufferdeve essere un puntatore a un array di valoribufferSizeuint8_t - Il parametro
bufferSizedeve essere maggiore di0
La struttura XrTrackableImageDatabaseCreateInfoANDROID è definita come:
typedef struct XrTrackableImageDatabaseCreateInfoANDROID {
XrStructureType type;
const void* next;
uint32_t entryCount;
const XrTrackableImageDatabaseEntryANDROID* entries;
} XrTrackableImageDatabaseCreateInfoANDROID;
Descrizioni dei membri
typeè l'XrStructureType di questa struttura.nextèNULLo un puntatore alla struttura successiva in una catena di strutture. Queste strutture non sono definite in OpenXR di base o in questa estensione.entryCountè unuint32_tche specifica il conteggio degli elementi nell'arrayentries.entriesè un array di strutture XrTrackableImageDatabaseEntryANDROID.
Utilizzo valido (implicito)
- L'estensione
XR_ANDROID_trackables_imagedeve essere abilitata prima di utilizzare XrTrackableImageDatabaseCreateInfoANDROID -
typedeve essereXR_TYPE_TRACKABLE_IMAGE_DATABASE_CREATE_INFO_ANDROID -
nextdeve essereNULLo un puntatore valido alla struttura successiva in una catena di strutture -
entriesmust be a pointer to an array ofentryCountvalid XrTrackableImageDatabaseEntryANDROID structures - Il parametro
entryCountdeve essere maggiore di0
La struttura XrCreateTrackableImageDatabaseCompletionANDROID è definita come:
typedef struct XrCreateTrackableImageDatabaseCompletionANDROID {
XrStructureType type;
void* next;
XrResult futureResult;
XrTrackableImageDatabaseANDROID database;
} XrCreateTrackableImageDatabaseCompletionANDROID;
Descrizioni dei membri
typeè l'XrStructureType di questa struttura.nextèNULLo un puntatore alla struttura successiva in una catena di strutture. Queste strutture non sono definite in OpenXR di base o in questa estensione.futureResultè l'XrResult dell'operazione asincrona.databaseè l'handle XrTrackableImageDatabaseANDROID creato.
Codici di reso futuri
Valori futureResult:
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_RUNTIME_FAILUREXR_ERROR_INSTANCE_LOSTXR_ERROR_SESSION_LOSTXR_ERROR_OUT_OF_MEMORYXR_ERROR_LIMIT_REACHED
Utilizzo valido (implicito)
- L'estensione
XR_ANDROID_trackables_imagedeve essere attivata prima di utilizzare XrCreateTrackableImageDatabaseCompletionANDROID -
typedeve essereXR_TYPE_CREATE_TRACKABLE_IMAGE_DATABASE_COMPLETION_ANDROID -
nextdeve essereNULLo un puntatore valido alla struttura successiva in una catena di strutture -
futureResultdeve essere un valore XrResult valido -
databasedeve essere un handle XrTrackableImageDatabaseANDROID valido
La funzione xrCreateTrackableImageDatabaseAsyncANDROID è definita come:
XrResult xrCreateTrackableImageDatabaseAsyncANDROID(
XrSession session,
const XrTrackableImageDatabaseCreateInfoANDROID* createInfo,
XrFutureEXT* future);
Descrizioni dei parametri
sessionè un handle per un XrSession creato in precedenza con xrCreateSession .createInfoè un puntatore a una struttura XrTrackableImageDatabaseCreateInfoANDROID.futureè un puntatore all'oggettoXrFutureEXTcreato .
Utilizzo valido (implicito)
- L'estensione
XR_ANDROID_trackables_imagedeve essere attivata prima di chiamare xrCreateTrackableImageDatabaseAsyncANDROID -
sessiondeve essere un handle XrSession valido -
createInfodeve essere un puntatore a una struttura XrTrackableImageDatabaseCreateInfoANDROID valida -
futuredeve essere un puntatore a un valoreXrFutureEXT
Codici di ritorno
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FEATURE_UNSUPPORTEDXR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_IMAGE_FORMAT_UNSUPPORTED_ANDROIDXR_ERROR_INSTANCE_LOSTXR_ERROR_LIMIT_REACHEDXR_ERROR_OUT_OF_MEMORYXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_VALIDATION_FAILURE
La funzione xrCreateTrackableImageDatabaseCompleteANDROID è definita come:
XrResult xrCreateTrackableImageDatabaseCompleteANDROID(
XrSession session,
XrFutureEXT future,
XrCreateTrackableImageDatabaseCompletionANDROID* completion);
Descrizioni dei parametri
sessionè un handle per un XrSession creato in precedenza con xrCreateSession .futureè laXrFutureEXTdel futuro da completare.completionè un puntatore a una struttura XrCreateTrackableImageDatabaseCompletionANDROID contenente il risultato dell'operazione.
Utilizzo valido (implicito)
- L'estensione
XR_ANDROID_trackables_imagedeve essere abilitata prima di chiamare xrCreateTrackableImageDatabaseCompleteANDROID -
sessiondeve essere un handle XrSession valido -
completiondeve essere un puntatore a una struttura XrCreateTrackableImageDatabaseCompletionANDROID
Codici di ritorno
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_FUTURE_INVALID_EXTXR_ERROR_FUTURE_PENDING_EXTXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_LIMIT_REACHEDXR_ERROR_OUT_OF_MEMORYXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_VALIDATION_FAILURE
La funzione xrDestroyTrackableImageDatabaseANDROID è definita come:
XrResult xrDestroyTrackableImageDatabaseANDROID(
XrTrackableImageDatabaseANDROID database);
Descrizioni dei parametri
databaseè l'handle XrTrackableImageDatabaseANDROID da eliminare.
Utilizzo valido (implicito)
- L'estensione
XR_ANDROID_trackables_imagedeve essere abilitata prima di chiamare xrDestroyTrackableImageDatabaseANDROID -
databasedeve essere un handle XrTrackableImageDatabaseANDROID valido
Thread Safety
- L'accesso a
databasee a tutti gli handle secondari deve essere sincronizzato esternamente
Codici di ritorno
XR_SUCCESS
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_RUNTIME_FAILURE
Immagini di monitoraggio
Questa estensione aggiunge XR_TRACKABLE_TYPE_IMAGE_ANDROID a XrTrackableTypeANDROID .
L'applicazione può creare un XrTrackableTrackerANDROID chiamando xrCreateTrackableTrackerANDROID e specificando XR_TRACKABLE_TYPE_IMAGE_ANDROID come tipo tracciabile in XrTrackableTrackerCreateInfoANDROID :: trackableType per monitorare le immagini.
Il runtime deve restituire XR_ERROR_FEATURE_UNSUPPORTED se XrTrackableTrackerCreateInfoANDROID :: trackableType è XR_TRACKABLE_TYPE_IMAGE_ANDROID e XrSystemImageTrackingPropertiesANDROID :: supportsImageTracking restituisce XR_FALSE tramite xrGetSystemProperties .
La struttura XrTrackableImageConfigurationANDROID è definita come:
typedef struct XrTrackableImageConfigurationANDROID {
XrStructureType type;
const void* next;
uint32_t databaseCount;
const XrTrackableImageDatabaseANDROID* databases;
} XrTrackableImageConfigurationANDROID;
Descrizioni dei membri
typeè l'XrStructureType di questa struttura.nextèNULLo un puntatore alla struttura successiva in una catena di strutture. Queste strutture non sono definite in OpenXR di base o in questa estensione.databaseCountè unuint32_tche specifica il numero di elementi indatabasesdatabasesè un array di XrTrackableImageDatabaseANDROID che specifica i database con cui creare il tracker.
L'applicazione deve impostare una configurazione valida aggiungendo un XrTrackableImageConfigurationANDROID alla catena next di XrTrackableTrackerCreateInfoANDROID . In caso contrario, il runtime deve restituire XR_ERROR_VALIDATION_FAILURE .
L'applicazione deve fornire almeno una struttura XrTrackableImageDatabaseANDROID per creare il tracker.
Utilizzo valido (implicito)
- L'estensione
XR_ANDROID_trackables_imagedeve essere abilitata prima di utilizzare XrTrackableImageConfigurationANDROID -
typedeve essereXR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID -
nextdeve essereNULLo un puntatore valido alla struttura successiva in una catena di strutture -
databasesdeve essere un puntatore a un array didatabaseCounthandle XrTrackableImageDatabaseANDROID validi - Il parametro
databaseCountdeve essere maggiore di0
L'enumerazione XrTrackableImageTrackingModeANDROID descrive le modalità di monitoraggio delle immagini supportate.
typedef enum XrTrackableImageTrackingModeANDROID {
XR_TRACKABLE_IMAGE_TRACKING_MODE_DYNAMIC_ANDROID = 1,
XR_TRACKABLE_IMAGE_TRACKING_MODE_STATIC_ANDROID = 2,
XR_TRACKABLE_IMAGE_TRACKING_MODE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrTrackableImageTrackingModeANDROID;
Descrizioni dell'enumerante
XR_TRACKABLE_IMAGE_TRACKING_MODE_DYNAMIC_ANDROID: questa modalità ha la massima accuratezza e consente il rilevamento a bassa latenza delle immagini in movimento. Inoltre, ha il consumo energetico più elevato.XR_TRACKABLE_IMAGE_TRACKING_MODE_STATIC_ANDROID: questa modalità deve essere utilizzata per le immagini statiche o semi-statiche. Questa modalità comporta un consumo energetico inferiore rispetto alla modalità dinamica. Se viene spostata un'immagine statica, questa verrà aggiornata con una latenza molto più elevata rispetto all'utilizzo della modalità dinamica.
L'enumerazione XrTrackableImageFormatANDROID descrive i formati supportati delle immagini.
typedef enum XrTrackableImageFormatANDROID {
XR_TRACKABLE_IMAGE_FORMAT_R8G8B8A8_ANDROID = 1,
XR_TRACKABLE_IMAGE_FORMAT_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrTrackableImageFormatANDROID;
Descrizioni dell'enumerante
XR_TRACKABLE_IMAGE_FORMAT_R8G8B8A8_ANDROID: formato immagine RGBA con dati di colore e trasparenza a 8 bit per canale.
La funzione xrAddTrackableImageDatabaseANDROID è definita come:
XrResult xrAddTrackableImageDatabaseANDROID(
XrTrackableTrackerANDROID tracker,
XrTrackableImageDatabaseANDROID database);
Descrizioni dei parametri
trackerè l'handle XrTrackableTrackerANDROID a cui aggiungeredatabase.databaseè l'handle XrTrackableImageDatabaseANDROID da aggiungere atracker.
Quando a un tracker viene aggiunto un XrTrackableImageDatabaseANDROID, le immagini di riferimento di questo database devono essere prese in considerazione per il rilevamento e il monitoraggio, oltre a qualsiasi altro database aggiunto in precedenza con xrAddTrackableImageDatabaseANDROID o tramite la struttura XrTrackableImageConfigurationANDROID durante la creazione iniziale del tracker.
Utilizzo valido (implicito)
- L'estensione
XR_ANDROID_trackables_imagedeve essere attivata prima di chiamare xrAddTrackableImageDatabaseANDROID -
trackerdeve essere un handle XrTrackableTrackerANDROID valido -
databasedeve essere un handle XrTrackableImageDatabaseANDROID valido - Sia
databasechetrackerdevono essere stati creati, allocati o recuperati dalla stessa XrSession
Codici di ritorno
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_LIMIT_REACHEDXR_ERROR_OUT_OF_MEMORYXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_VALIDATION_FAILURE
La funzione xrRemoveTrackableImageDatabaseANDROID è definita come:
XrResult xrRemoveTrackableImageDatabaseANDROID(
XrTrackableTrackerANDROID tracker,
XrTrackableImageDatabaseANDROID database);
Descrizioni dei parametri
trackerè l'handle XrTrackableTrackerANDROID da cui rimuoveredatabase.databaseè l'handle XrTrackableImageDatabaseANDROID da rimuovere datracker.
Quando un XrTrackableImageDatabaseANDROID viene rimosso da un XrTrackableTrackerANDROID , le strutture XrTrackableImageDatabaseEntryANDROID di quel database non devono più essere prese in considerazione per il rilevamento e il monitoraggio. Tutte le voci monitorate attivamente di quel database non devono più essere segnalate. L'handle XrTrackableImageDatabaseANDROID rimosso non deve essere distrutto implicitamente nell'ambito di questa operazione.
Utilizzo valido (implicito)
- L'estensione
XR_ANDROID_trackables_imagedeve essere attivata prima di chiamare xrRemoveTrackableImageDatabaseANDROID -
trackerdeve essere un handle XrTrackableTrackerANDROID valido -
databasedeve essere un handle XrTrackableImageDatabaseANDROID valido - Sia
databasechetrackerdevono essere stati creati, allocati o recuperati dalla stessa XrSession
Codici di ritorno
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_VALIDATION_FAILURE
Recupero delle immagini…
La funzione xrGetTrackableImageANDROID è definita come:
XrResult xrGetTrackableImageANDROID(
XrTrackableTrackerANDROID tracker,
const XrTrackableGetInfoANDROID* getInfo,
XrTrackableImageANDROID* trackable);
Descrizioni dei parametri
trackerè l'XrTrackableTrackerANDROID su cui eseguire la query.getInfoè XrTrackableGetInfoANDROID con le informazioni utilizzate per ottenere il codice QR tracciabile.trackableè un puntatore alla struttura XrTrackableImageANDROID in cui viene restituita l'immagine tracciabile.
Il runtime deve restituire XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID se il tipo tracciabile di XrTrackableANDROID non è XR_TRACKABLE_TYPE_IMAGE_ANDROID o se il tipo tracciabile di XrTrackableTrackerANDROID non è XR_TRACKABLE_TYPE_IMAGE_ANDROID .
Utilizzo valido (implicito)
- L'estensione
XR_ANDROID_trackables_imagedeve essere attivata prima di chiamare xrGetTrackableImageANDROID -
trackerdeve essere un handle XrTrackableTrackerANDROID valido -
getInfodeve essere un puntatore a una struttura XrTrackableGetInfoANDROID valida -
trackabledeve essere un puntatore a una struttura XrTrackableImageANDROID
Codici di ritorno
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROIDXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_TIME_INVALIDXR_ERROR_VALIDATION_FAILURE
La struttura XrTrackableImageANDROID è definita come:
typedef struct XrTrackableImageANDROID {
XrStructureType type;
const void* next;
XrTrackingStateANDROID trackingState;
XrTime lastUpdatedTime;
XrTrackableImageDatabaseANDROID database;
uint32_t databaseEntryIndex;
XrPosef centerPose;
XrExtent2Df extents;
} XrTrackableImageANDROID;
Descrizioni dei membri
typeè l'XrStructureType di questa struttura.nextèNULLo un puntatore alla struttura successiva in una catena di strutture. Queste strutture non sono definite in OpenXR di base o in questa estensione.trackingStateè XrTrackingStateANDROID dell'immagine.lastUpdatedTimeè ilXrTimedell'ultimo aggiornamento dell'immagine.databaseè l'handle XrTrackableImageDatabaseANDROID da cui è stata monitorata questa immagine.databaseEntryIndexè l'indice che mappa l'arrayentriesdidatabasein XrTrackableImageDatabaseCreateInfoANDROID .centerPoseè l'XrPosef dell'immagine che si trova in XrTrackableGetInfoANDROID ::baseSpace. L'immagine si trova nel piano XZ, con X che punta a destra dell'immagine e Z che punta in basso.extentssono le dimensioni XrExtent2Df dell'immagine. Il confine del riquadro di delimitazione si trova nei punti:centerPose+/- (extents/ 2).
Utilizzo valido (implicito)
- L'estensione
XR_ANDROID_trackables_imagedeve essere abilitata prima di utilizzare XrTrackableImageANDROID -
typedeve essereXR_TYPE_TRACKABLE_IMAGE_ANDROID -
nextdeve essereNULLo un puntatore valido alla struttura successiva in una catena di strutture -
trackingStatedeve essere un valore XrTrackingStateANDROID valido -
databasedeve essere un handle XrTrackableImageDatabaseANDROID valido
Gestione degli errori
L'applicazione deve eseguire il polling dell'evento XrEventDataImageTrackingLostANDROID utilizzando xrPollEvent e non deve ignorarlo.
La struttura XrEventDataImageTrackingLostANDROID è definita come:
typedef struct XrEventDataImageTrackingLostANDROID {
XrStructureType type;
const void* next;
XrTime time;
} XrEventDataImageTrackingLostANDROID;
Descrizioni dei membri
typeè l'XrStructureType di questa struttura.nextèNULLo un puntatore alla struttura successiva in una catena di strutture. Queste strutture non sono definite in OpenXR di base o in questa estensione.timeXrTime
La ricezione dell'evento XrEventDataImageTrackingLostANDROID indica che il monitoraggio delle immagini ha subito un errore interno che ha invalidato le risorse esistenti. L'applicazione deve eliminare tutti gli handle XrTrackableImageDatabaseANDROID e ricrearli se vuole continuare il rilevamento delle immagini. L'applicazione deve anche eliminare tutti gli handle XrTrackableTrackerANDROID correlati al monitoraggio delle immagini e ricrearli se vuole continuare a monitorare le immagini.
Utilizzo valido (implicito)
- L'estensione
XR_ANDROID_trackables_imagedeve essere attivata prima di utilizzare XrEventDataImageTrackingLostANDROID -
typedeve essereXR_TYPE_EVENT_DATA_IMAGE_TRACKING_LOST_ANDROID -
nextdeve essereNULLo un puntatore valido alla struttura successiva in una catena di strutture
Codice di esempio per ottenere immagini monitorabili
Il seguente codice di esempio mostra come ottenere immagini tracciabili.
XrInstance instance; // Previously initialized.
XrSession session; // Previously initialized.
XrSystemId systemId; // Previously initialized.
// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrGetSystemProperties xrGetSystemProperties; // Previously initialized.
PFN_xrPollFutureEXT xrPollFutureEXT; // Previously initialized.
PFN_xrCreateTrackableTrackerANDROID xrCreateTrackableTrackerANDROID; // Previously initialized.
PFN_xrGetAllTrackablesANDROID xrGetAllTrackablesANDROID; // Previously initialized.
PFN_xrDestroyTrackableTrackerANDROID xrDestroyTrackableTrackerANDROID; // Previously initialized.
PFN_xrGetTrackableImageANDROID xrGetTrackableImageANDROID; // Previously initialized.
PFN_xrCreateTrackableImageDatabaseAsyncANDROID xrCreateTrackableImageDatabaseAsyncANDROID; // Previously initialized.
PFN_xrCreateTrackableImageDatabaseCompleteANDROID xrCreateTrackableImageDatabaseCompleteANDROID; // Previously initialized.
PFN_xrDestroyTrackableImageDatabaseANDROID xrDestroyTrackableImageDatabaseANDROID; // Previously initialized.
PFN_xrAddTrackableImageDatabaseANDROID xrAddTrackableImageDatabaseANDROID; // Previously initialized.
PFN_xrRemoveTrackableImageDatabaseANDROID xrRemoveTrackableImageDatabaseANDROID; // Previously initialized.
XrTime updateTime; // Time used for the current frame's simulation update.
XrSpace appSpace; // Space created for XR_REFERENCE_SPACE_TYPE_LOCAL.
// Inspect system capability
XrSystemImageTrackingPropertiesANDROID imageProperty {
.type = XR_TYPE_SYSTEM_IMAGE_TRACKING_PROPERTIES_ANDROID,
.next = nullptr,
};
XrSystemProperties systemProperties {
.type = XR_TYPE_SYSTEM_PROPERTIES,
.next = &imageProperty,
};
CHK_XR(xrGetSystemProperties(instance, systemId, &systemProperties));
if (!imageProperty.supportsImageTracking) {
// image tracking is not supported.
return;
}
uint8_t* imageBuffer; // Load the image buffer.
uint32_t imageBufferSize; // Get the image buffer size.
XrTrackableImageDatabaseEntryANDROID imageDatabaseEntries[1] = {
{
.type = XR_TYPE_TRACKABLE_IMAGE_DATABASE_ENTRY_ANDROID,
.next = nullptr,
.trackingMode = XR_TRACKABLE_IMAGE_TRACKING_MODE_STATIC_ANDROID,
.physicalWidth = 0.1f, // The width of the image in meters.
.imageWidth = 640,
.imageHeight = 480,
.format = XR_TRACKABLE_IMAGE_FORMAT_R8G8B8A8_ANDROID,
.bufferSize = imageBufferSize, // RGBA buffer size in bytes.
.buffer = imageBuffer, // RGBA data.
}
};
XrTrackableImageDatabaseCreateInfoANDROID imageDatabaseCreateInfo {
.type = XR_TYPE_TRACKABLE_IMAGE_DATABASE_CREATE_INFO_ANDROID,
.next = nullptr,
.entryCount = 1,
.entries = imageDatabaseEntries
};
XrFutureEXT imageDatabaseFuture;
CHK_XR(xrCreateTrackableImageDatabaseAsyncANDROID(session, &imageDatabaseCreateInfo, &imageDatabaseFuture));
bool keepLooping = true;
bool futureReady = false;
while (keepLooping) {
XrFuturePollInfoEXT pollInfo{
.type = XR_TYPE_FUTURE_POLL_INFO_EXT,
.future = imageDatabaseFuture,
};
XrFuturePollResultEXT pollResult{
.type = XR_TYPE_FUTURE_POLL_RESULT_EXT,
};
CHK_XR(xrPollFutureEXT(instance, &pollInfo, &pollResult));
if (pollResult.state == XR_FUTURE_STATE_READY_EXT) {
futureReady = true;
keepLooping = false;
} else {
// Throttle the loop to not fully expend this CPU core.
std::this_thread::yield();
}
}
XrTrackableImageDatabaseANDROID imageDatabase;
if (futureReady) {
XrCreateTrackableImageDatabaseCompletionANDROID imageDatabaseCompletion {
.type = XR_TYPE_CREATE_TRACKABLE_IMAGE_DATABASE_COMPLETION_ANDROID,
.next = nullptr,
};
CHK_XR(xrCreateTrackableImageDatabaseCompleteANDROID(session, imageDatabaseFuture, &imageDatabaseCompletion));
CHK_XR(imageDatabaseCompletion.futureResult);
imageDatabase = imageDatabaseCompletion.database;
}
XrTrackableImageConfigurationANDROID imageConfig {
.type = XR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID,
.next = nullptr,
.databaseCount = 1,
.databases = &imageDatabase
};
XrTrackableTrackerCreateInfoANDROID createInfo {
.type = XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID,
.next = &imageConfig,
.trackableType = XR_TRACKABLE_TYPE_IMAGE_ANDROID
};
XrTrackableTrackerANDROID imageTrackableTracker;
CHK_XR(xrCreateTrackableTrackerANDROID(session, &createInfo, &imageTrackableTracker));
XrTrackableImageDatabaseANDROID anotherImageDatabase; // Load another database.
// ... dynamically add it to the existing tracker
CHK_XR(xrAddTrackableImageDatabaseANDROID(imageTrackableTracker, anotherImageDatabase));
while (1) {
uint32_t trackableCountOutput = 0;
CHK_XR(xrGetAllTrackablesANDROID(imageTrackableTracker, 0, &trackableCountOutput, nullptr));
std::vector<XrTrackableANDROID> allImageTrackables;
allImageTrackables.resize(trackableCountOutput);
CHK_XR(xrGetAllTrackablesANDROID(imageTrackableTracker, 0, &trackableCountOutput, allImageTrackables.data()));
for (XrTrackableANDROID trackable : allImageTrackables) {
XrTrackableGetInfoANDROID imageGetInfo {
.type = XR_TYPE_TRACKABLE_GET_INFO_ANDROID,
.next = nullptr,
.trackable = trackable,
.baseSpace = appSpace,
.time = updateTime
};
XrTrackableImageANDROID trackableImage{
.type = XR_TYPE_TRACKABLE_IMAGE_ANDROID,
};
CHK_XR(xrGetTrackableImageANDROID(imageTrackableTracker, &imageGetInfo, &trackableImage));
// Use XrTrackableImageANDROID data.
(void)trackableImage.trackingState;
(void)trackableImage.lastUpdatedTime;
(void)trackableImage.centerPose;
(void)trackableImage.extents;
if (trackableImage.database == imageDatabase && trackableImage.databaseEntryIndex == 0) {
// Knowing which image the index of 0 maps to, use the specific image database
// entry (e.g. rendering A for image A).
}
// indices 1+N comparisons for another specific image database entry.
}
// Throttle the loop to not fully expend this CPU core.
std::this_thread::yield();
}
// Remove image database from an existing tracker to stop tracking the images
// of that specific database. To resume tracking of those images re-add the
// database at a later point.
CHK_XR(xrRemoveTrackableImageDatabaseANDROID(imageTrackableTracker, anotherImageDatabase));
// Destroy the image tracker to stop image tracking completely. Re-creating the
// image tracker with existing image databases will restart image tracking.
CHK_XR(xrDestroyTrackableTrackerANDROID(imageTrackableTracker));
// Destroy image databases to unload the associated resources. Re-creatingd
// databases requires going through the asynchronous creation procedure again.
CHK_XR(xrDestroyTrackableImageDatabaseANDROID(anotherImageDatabase));
CHK_XR(xrDestroyTrackableImageDatabaseANDROID(imageDatabase));
Codice di esempio per la gestione dei database di immagini in fase di runtime
Il seguente codice di esempio mostra come modificare l'insieme di immagini monitorate.
XrSession session; // Previously initialized.
// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrCreateTrackableTrackerANDROID xrCreateTrackableTrackerANDROID; // Previously initialized.
PFN_xrDestroyTrackableTrackerANDROID xrDestroyTrackableTrackerANDROID; // Previously initialized.
PFN_xrDestroyTrackableImageDatabaseANDROID xrDestroyTrackableImageDatabaseANDROID; // Previously initialized.
PFN_xrAddTrackableImageDatabaseANDROID xrAddTrackableImageDatabaseANDROID; // Previously initialized.
PFN_xrRemoveTrackableImageDatabaseANDROID xrRemoveTrackableImageDatabaseANDROID; // Previously initialized.
// See previous C++ sample for database and tracker initialization.
XrTrackableImageDatabaseANDROID imageDatabases[2]; // Previously initialized.
XrTrackableImageDatabaseANDROID anotherImageDatabase; // Previously initialized.
// Create the image tracker config with two input databases to track.
XrTrackableImageConfigurationANDROID imageConfig {
.type = XR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID,
.next = nullptr,
.databaseCount = 2,
.databases = imageDatabases
};
XrTrackableTrackerCreateInfoANDROID createInfo {
.type = XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID,
.next = &imageConfig,
.trackableType = XR_TRACKABLE_TYPE_IMAGE_ANDROID
};
XrTrackableTrackerANDROID imageTrackableTracker;
CHK_XR(xrCreateTrackableTrackerANDROID(session, &createInfo, &imageTrackableTracker));
// The tracker currently tracks the images of the two databases 'imageDatabases[0]' and
// 'imageDatabases[1]' supplied through 'imageConfig'.
CHK_XR(xrRemoveTrackableImageDatabaseANDROID(imageTrackableTracker, imageDatabases[1]));
// The tracker currently tracks 'imageDatabases[0]', but no longer tracks
// 'imageDatabases[1]'.
// The 'imageDatabases[1]' database handle is still valid.
CHK_XR(xrAddTrackableImageDatabaseANDROID(imageTrackableTracker, imageDatabases[1]));
// The tracker currently tracks 'imageDatabases[0]' and 'imageDatabases[1]'.
CHK_XR(xrDestroyTrackableImageDatabaseANDROID(imageDatabases[1]));
// The tracker currently tracks 'imageDatabases[0]', but no longer tracks
// 'imageDatabases[1]'.
// The 'imageDatabases[1]' database handle is no longer valid and the corresponding
// resources have been released internally. The database needs to be re-initialized
// and re-added to resume tracking of 'imageDatabases[0]'.
CHK_XR(xrAddTrackableImageDatabaseANDROID(imageTrackableTracker, anotherImageDatabase));
// The tracker currently tracks 'imageDatabases[0]' and 'anotherImageDatabase'.
CHK_XR(xrDestroyTrackableTrackerANDROID(imageTrackableTracker));
// The 'imageTrackableTracker' tracker handle is invalid and image tracking has been
// stopped.
// The 'imageDatabases[0]' and 'anotherImageDatabase' database handles are still valid.
// Create another the image tracker config to re-create the image tracker.
XrTrackableImageConfigurationANDROID anotherImageConfig {
.type = XR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID,
.next = nullptr,
.databaseCount = 1,
.databases = &anotherImageDatabase
};
XrTrackableTrackerCreateInfoANDROID anotherCreateInfo {
.type = XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID,
.next = &anotherImageConfig,
.trackableType = XR_TRACKABLE_TYPE_IMAGE_ANDROID
};
CHK_XR(xrCreateTrackableTrackerANDROID(session, &anotherCreateInfo, &imageTrackableTracker));
// The tracker handle has been re-initialized and image tracking has been started again.
// The tracker currently tracks 'anotherImageDatabase'.
// The 'imageDatabases[0]' database handle is still valid, but not currently tracked.
Codice di esempio per reagire agli errori di monitoraggio delle immagini
Il seguente codice di esempio mostra come gestire l'errore eseguendo il polling dell'evento XrEventDataImageTrackingLostANDROID.
XrInstance instance; // Previously initialized.
XrSession session; // Previously initialized.
// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrPollFutureEXT xrPollFutureEXT; // Previously initialized.
PFN_xrCreateTrackableTrackerANDROID xrCreateTrackableTrackerANDROID; // Previously initialized.
PFN_xrDestroyTrackableTrackerANDROID xrDestroyTrackableTrackerANDROID; // Previously initialized.
PFN_xrCreateTrackableImageDatabaseAsyncANDROID xrCreateTrackableImageDatabaseAsyncANDROID; // Previously initialized.
PFN_xrCreateTrackableImageDatabaseCompleteANDROID xrCreateTrackableImageDatabaseCompleteANDROID; // Previously initialized.
PFN_xrDestroyTrackableImageDatabaseANDROID xrDestroyTrackableImageDatabaseANDROID; // Previously initialized.
XrTrackableImageDatabaseEntryANDROID imageDatabaseEntries[1]; // Previously initialized.
XrTrackableImageDatabaseANDROID imageDatabase; // Previously initialized.
XrTrackableTrackerANDROID imageTrackableTracker; // Previously initialized.
// Initialize an event buffer to hold the output.
XrEventDataBuffer event = {
.type = XR_TYPE_EVENT_DATA_BUFFER,
};
XrResult result = xrPollEvent(instance, &event);
if (result == XR_SUCCESS) {
switch (event.type) {
case XR_TYPE_EVENT_DATA_IMAGE_TRACKING_LOST_ANDROID: {
const XrEventDataImageTrackingLostANDROID& eventdata =
*reinterpret_cast<XrEventDataImageTrackingLostANDROID*>(&event);
// All existing databases and trackers need to be destroyed.
CHK_XR(xrDestroyTrackableTrackerANDROID(imageTrackableTracker));
CHK_XR(xrDestroyTrackableImageDatabaseANDROID(imageDatabase));
// To resume image tracking, the database(s) and the tracker need to be re-created.
XrTrackableImageDatabaseCreateInfoANDROID imageDatabaseCreateInfo {
.type = XR_TYPE_TRACKABLE_IMAGE_DATABASE_CREATE_INFO_ANDROID,
.next = nullptr,
.entryCount = 1,
.entries = imageDatabaseEntries
};
XrFutureEXT imageDatabaseFuture;
CHK_XR(xrCreateTrackableImageDatabaseAsyncANDROID(session, &imageDatabaseCreateInfo, &imageDatabaseFuture));
while (true) {
XrFuturePollInfoEXT pollInfo{
.type = XR_TYPE_FUTURE_POLL_INFO_EXT,
.future = imageDatabaseFuture,
};
XrFuturePollResultEXT pollResult{
.type = XR_TYPE_FUTURE_POLL_RESULT_EXT,
};
CHK_XR(xrPollFutureEXT(instance, &pollInfo, &pollResult));
if (pollResult.state == XR_FUTURE_STATE_READY_EXT) {
break;
} else {
// Throttle the loop to not fully expend this CPU core.
std::this_thread::yield();
}
}
XrCreateTrackableImageDatabaseCompletionANDROID imageDatabaseCompletion {
.type = XR_TYPE_CREATE_TRACKABLE_IMAGE_DATABASE_COMPLETION_ANDROID,
.next = nullptr,
};
CHK_XR(xrCreateTrackableImageDatabaseCompleteANDROID(session, imageDatabaseFuture, &imageDatabaseCompletion));
CHK_XR(imageDatabaseCompletion.futureResult);
imageDatabase = imageDatabaseCompletion.database;
XrTrackableImageConfigurationANDROID imageConfig {
.type = XR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID,
.next = nullptr,
.databaseCount = 1,
.databases = &imageDatabase
};
XrTrackableTrackerCreateInfoANDROID createInfo {
.type = XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID,
.next = &imageConfig,
.trackableType = XR_TRACKABLE_TYPE_IMAGE_ANDROID
};
XrTrackableTrackerANDROID imageTrackableTracker;
CHK_XR(xrCreateTrackableTrackerANDROID(session, &createInfo, &imageTrackableTracker));
break;
}
}
}
Nuovi tipi di oggetti
Nuovi comandi
- xrAddTrackableImageDatabaseANDROID
- xrCreateTrackableImageDatabaseAsyncANDROID
- xrCreateTrackableImageDatabaseCompleteANDROID
- xrDestroyTrackableImageDatabaseANDROID
- xrGetTrackableImageANDROID
- xrRemoveTrackableImageDatabaseANDROID
Nuove strutture
- XrCreateTrackableImageDatabaseCompletionANDROID
- XrEventDataImageTrackingLostANDROID
- XrTrackableImageANDROID
- XrTrackableImageConfigurationANDROID
- XrTrackableImageDatabaseCreateInfoANDROID
- XrTrackableImageDatabaseEntryANDROID
Estensione di XrSystemProperties :
Nuovi enum
Nuove costanti enum
XR_ANDROID_TRACKABLES_IMAGE_EXTENSION_NAMEXR_ANDROID_trackables_image_SPEC_VERSIONEstensione di XrObjectType :
XR_OBJECT_TYPE_TRACKABLE_IMAGE_DATABASE_ANDROID
Estensione di XrResult :
XR_ERROR_IMAGE_FORMAT_UNSUPPORTED_ANDROID
Estensione di XrStructureType :
XR_TYPE_CREATE_TRACKABLE_IMAGE_DATABASE_COMPLETION_ANDROIDXR_TYPE_EVENT_DATA_IMAGE_TRACKING_LOST_ANDROIDXR_TYPE_SYSTEM_IMAGE_TRACKING_PROPERTIES_ANDROIDXR_TYPE_TRACKABLE_IMAGE_ANDROIDXR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROIDXR_TYPE_TRACKABLE_IMAGE_DATABASE_CREATE_INFO_ANDROIDXR_TYPE_TRACKABLE_IMAGE_DATABASE_ENTRY_ANDROID
Estensione di XrTrackableTypeANDROID :
XR_TRACKABLE_TYPE_IMAGE_ANDROID
Problemi
Cronologia delle versioni
Revisione 1, 8/04/2025 (Daniel Guttenberg)
- Descrizione iniziale dell'estensione.