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 è NULL o 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 è un XrBool32 che indica se il sistema attuale fornisce la funzionalità di monitoraggio delle immagini.
  • supportsPhysicalSizeEstimation è un XrBool32 che 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)

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 è NULL o 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.
  • physicalWidth indica la larghezza dell'immagine in metri. Se è zero, le dimensioni dell'immagine verranno stimate online.
  • imageWidth indica la larghezza dell'immagine in pixel.
  • imageHeight indica l'altezza dell'immagine in pixel.
  • format è un XrTrackableImageFormatANDROID che indica il formato dei dati immagine in buffer .
  • bufferSize indica la lunghezza in byte di buffer .
  • buffer è il buffer uint8_t contenente i dati dei pixel dell'immagine di riferimento. I contenuti di buffer devono 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)

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 è NULL o un puntatore alla struttura successiva in una catena di strutture. Queste strutture non sono definite in OpenXR di base o in questa estensione.
  • entryCount è un uint32_t che specifica il conteggio degli elementi nell'array entries.
  • entries è un array di strutture XrTrackableImageDatabaseEntryANDROID.

Utilizzo valido (implicito)

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 è NULL o 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:

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

Utilizzo valido (implicito)

La funzione xrCreateTrackableImageDatabaseAsyncANDROID è definita come:

XrResult xrCreateTrackableImageDatabaseAsyncANDROID(
    XrSession                                   session,
    const XrTrackableImageDatabaseCreateInfoANDROID* createInfo,
    XrFutureEXT*                                future);

Descrizioni dei parametri

Utilizzo valido (implicito)

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_IMAGE_FORMAT_UNSUPPORTED_ANDROID
  • 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 funzione xrCreateTrackableImageDatabaseCompleteANDROID è definita come:

XrResult xrCreateTrackableImageDatabaseCompleteANDROID(
    XrSession                                   session,
    XrFutureEXT                                 future,
    XrCreateTrackableImageDatabaseCompletionANDROID* completion);

Descrizioni dei parametri

Utilizzo valido (implicito)

Codici di ritorno

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 funzione xrDestroyTrackableImageDatabaseANDROID è definita come:

XrResult xrDestroyTrackableImageDatabaseANDROID(
    XrTrackableImageDatabaseANDROID             database);

Descrizioni dei parametri

Utilizzo valido (implicito)

Thread Safety

  • L'accesso a database 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
  • XR_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 è NULL o un puntatore alla struttura successiva in una catena di strutture. Queste strutture non sono definite in OpenXR di base o in questa estensione.
  • databaseCount è un uint32_t che specifica il numero di elementi in databases
  • databases è 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'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

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)

Codici di ritorno

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_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

La funzione xrRemoveTrackableImageDatabaseANDROID è definita come:

XrResult xrRemoveTrackableImageDatabaseANDROID(
    XrTrackableTrackerANDROID                   tracker,
    XrTrackableImageDatabaseANDROID             database);

Descrizioni dei parametri

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)

Codici di ritorno

Operazione riuscita

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Errore

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

Recupero delle immagini…

La funzione xrGetTrackableImageANDROID è definita come:

XrResult xrGetTrackableImageANDROID(
    XrTrackableTrackerANDROID                   tracker,
    const XrTrackableGetInfoANDROID*            getInfo,
    XrTrackableImageANDROID*                    trackable);

Descrizioni dei parametri

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)

Codici di ritorno

Operazione riuscita

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Errore

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_TIME_INVALID
  • XR_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 è NULL o 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 è il XrTime dell'ultimo aggiornamento dell'immagine.
  • database è l'handle XrTrackableImageDatabaseANDROID da cui è stata monitorata questa immagine.
  • databaseEntryIndex è l'indice che mappa l'array entries di database in 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.
  • extents sono le dimensioni XrExtent2Df dell'immagine. Il confine del riquadro di delimitazione si trova nei punti: centerPose +/- ( extents / 2).

Utilizzo valido (implicito)

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 è NULL o un puntatore alla struttura successiva in una catena di strutture. Queste strutture non sono definite in OpenXR di base o in questa estensione.
  • time XrTime

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)

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

Nuove strutture

Nuovi enum

Nuove costanti enum

  • XR_ANDROID_TRACKABLES_IMAGE_EXTENSION_NAME
  • XR_ANDROID_trackables_image_SPEC_VERSION
  • Estensione 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_ANDROID
    • XR_TYPE_EVENT_DATA_IMAGE_TRACKING_LOST_ANDROID
    • XR_TYPE_SYSTEM_IMAGE_TRACKING_PROPERTIES_ANDROID
    • XR_TYPE_TRACKABLE_IMAGE_ANDROID
    • XR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID
    • XR_TYPE_TRACKABLE_IMAGE_DATABASE_CREATE_INFO_ANDROID
    • XR_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.