XR_ANDROID_trackables_image

Cadena de nombre

XR_ANDROID_trackables_image

Tipo de extensión

Extensión de la instancia

Número de extensión registrado

710

Revisión

1

Estado de ratificación

No se ratificó

Dependencias de extensiones y versiones

XR_EXT_future
y
XR_ANDROID_trackables

Fecha de la última modificación

2025-04-08

Estado de la IP

No hay reclamos conocidos por IP.

Colaboradores

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

Descripción general

Esta extensión permite hacer un seguimiento de imágenes planas según lo especificado por conjuntos de imágenes de referencia de entrada.

Permisos

Las aplicaciones para Android deben tener el permiso android.permission.SCENE_UNDERSTANDING_COARSE en su manifiesto, ya que esta extensión depende de XR_ANDROID_trackables y expone la geometría del entorno. El permiso android.permission.SCENE_UNDERSTANDING_COARSE se considera un permiso peligroso.

(nivel de protección: peligroso)

Inspecciona la capacidad del sistema

La estructura XrSystemImageTrackingPropertiesANDROID se define de la siguiente manera:

typedef struct XrSystemImageTrackingPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsImageTracking;
    XrBool32           supportsPhysicalSizeEstimation;
    uint32_t           maxTrackedImageCount;
    uint32_t           maxLoadedImageCount;
} XrSystemImageTrackingPropertiesANDROID;

Descripciones de los miembros

  • type es el XrStructureType de esta estructura.
  • next es NULL o un puntero a la siguiente estructura en una cadena de estructuras. No se definen tales estructuras en OpenXR principal ni en esta extensión. Para obtener más detalles sobre la cadena de estructura, consulta la estructura que se extiende ( XrSystemProperties ).
  • supportsImageTracking es un XrBool32 que indica si el sistema actual proporciona capacidad de seguimiento de imágenes.
  • supportsPhysicalSizeEstimation es un XrBool32 que indica si el sistema actual proporciona una estimación del tamaño de la imagen.
  • maxTrackedImageCount es la cantidad máxima total de imágenes que se pueden rastrear al mismo tiempo.
  • maxLoadedImageCount es la cantidad máxima total de imágenes de referencia que se pueden cargar en todas las bases de datos.

Una aplicación puede inspeccionar si el sistema es capaz de realizar el seguimiento de imágenes extendiendo XrSystemProperties con la estructura XrSystemImageTrackingPropertiesANDROID cuando llama a xrGetSystemProperties . El tiempo de ejecución debe devolver XR_ERROR_FEATURE_UNSUPPORTED para la creación del objeto de seguimiento de imágenes si y solo si supportsImageTracking es XR_FALSE .

Si un entorno de ejecución admite el seguimiento de imágenes, debe admitir maxTrackedImageCount imágenes rastreadas en cualquier momento.

Si un tiempo de ejecución admite el seguimiento de imágenes, debe admitir imágenes cargadas de maxLoadedImageCount en cualquier momento.

Si un tiempo de ejecución admite la estimación del tamaño de la imagen, la aplicación puede establecer XrTrackableImageDatabaseEntryANDROID :: physicalWidth 0 para indicar el uso de la estimación del tamaño. De lo contrario, la aplicación debe establecer XrTrackableImageDatabaseEntryANDROID :: physicalWidth en un valor positivo, o se devolverá XR_ERROR_VALIDATION_FAILURE.

Uso válido (implícito)

Creación de bases de datos

La aplicación puede crear un identificador XrTrackableImageDatabaseANDROID creando una o más estructuras XrTrackableImageDatabaseEntryANDROID y pasándolas a la función xrCreateTrackableImageDatabaseAsyncANDROID a través de una estructura XrTrackableImageDatabaseCreateInfoANDROID.

La aplicación debe proporcionar al menos una XrTrackableImageDatabaseEntryANDROID cuando se crea un identificador de XrTrackableImageDatabaseANDROID.

Un objeto XrTrackableImageDatabaseANDROID es un identificador que representa un conjunto de imágenes de referencia procesadas que se pueden descubrir y hacerles un seguimiento en el entorno.

XR_DEFINE_HANDLE(XrTrackableImageDatabaseANDROID)

La estructura XrTrackableImageDatabaseEntryANDROID se define de la siguiente manera:

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;

Descripciones de los miembros

  • type es el XrStructureType de esta estructura.
  • next es NULL o un puntero a la siguiente estructura en una cadena de estructuras. No se definen tales estructuras en OpenXR principal ni en esta extensión.
  • trackingMode es un XrTrackableImageTrackingModeANDROID que indica el modo deseado para el seguimiento.
  • physicalWidth indica el ancho de la imagen en metros. Si es cero, el tamaño de la imagen se estimará en línea.
  • imageWidth indica el ancho de la imagen en píxeles.
  • imageHeight indica la altura de la imagen en píxeles.
  • format es un XrTrackableImageFormatANDROID que indica el formato de los datos de la imagen en buffer .
  • bufferSize indica la longitud en bytes de buffer .
  • buffer es el búfer uint8_t que contiene los datos de píxeles de imagen de la imagen de referencia. El contenido de buffer debe ser válido durante la operación asíncrona de creación de la base de datos, que se inicia con xrCreateTrackableImageDatabaseAsyncANDROID y se completa con xrCreateTrackableImageDatabaseCompleteANDROID.

La aplicación puede establecer physicalWidth en 0 para solicitar la estimación del tamaño en línea si XrSystemImageTrackingPropertiesANDROID :: supportsPhysicalSizeEstimation es XR_TRUE .

El tiempo de ejecución puede devolver XR_ERROR_VALIDATION_FAILURE desde xrCreateTrackableImageDatabaseAsyncANDROID si bufferSize no coincide con el tamaño esperado según los campos imageWidth , imageHeight y format de la entrada .

Uso válido (implícito)

La estructura XrTrackableImageDatabaseCreateInfoANDROID se define de la siguiente manera:

typedef struct XrTrackableImageDatabaseCreateInfoANDROID {
    XrStructureType                                type;
    const void*                                    next;
    uint32_t                                       entryCount;
    const XrTrackableImageDatabaseEntryANDROID*    entries;
} XrTrackableImageDatabaseCreateInfoANDROID;

Descripciones de los miembros

  • type es el XrStructureType de esta estructura.
  • next es NULL o un puntero a la siguiente estructura en una cadena de estructuras. No se definen tales estructuras en OpenXR principal ni en esta extensión.
  • entryCount es un uint32_t que especifica el recuento de elementos en el array entries.
  • entries es un array de estructuras XrTrackableImageDatabaseEntryANDROID.

Uso válido (implícito)

La estructura XrCreateTrackableImageDatabaseCompletionANDROID se define de la siguiente manera:

typedef struct XrCreateTrackableImageDatabaseCompletionANDROID {
    XrStructureType                    type;
    void*                              next;
    XrResult                           futureResult;
    XrTrackableImageDatabaseANDROID    database;
} XrCreateTrackableImageDatabaseCompletionANDROID;

Descripciones de los miembros

  • type es el XrStructureType de esta estructura.
  • next es NULL o un puntero a la siguiente estructura en una cadena de estructuras. No se definen tales estructuras en OpenXR principal ni en esta extensión.
  • futureResult es el XrResult de la operación asíncrona.
  • database es el identificador XrTrackableImageDatabaseANDROID creado.

Códigos de devolución futuros

Valores de futureResult:

Listo

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falla

  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_LIMIT_REACHED

Uso válido (implícito)

La función xrCreateTrackableImageDatabaseAsyncANDROID se define de la siguiente manera:

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

Descripciones de los parámetros

Uso válido (implícito)

Códigos de retorno

Listo

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falla

  • 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 función xrCreateTrackableImageDatabaseCompleteANDROID se define de la siguiente manera:

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

Descripciones de los parámetros

Uso válido (implícito)

Códigos de retorno

Listo

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falla

  • 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 función xrDestroyTrackableImageDatabaseANDROID se define de la siguiente manera:

XrResult xrDestroyTrackableImageDatabaseANDROID(
    XrTrackableImageDatabaseANDROID             database);

Descripciones de los parámetros

Uso válido (implícito)

Seguridad de subprocesos

  • El acceso a database y a cualquier identificador secundario debe sincronizarse de forma externa.

Códigos de retorno

Listo

  • XR_SUCCESS

Falla

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

Imágenes de seguimiento

Esta extensión agrega XR_TRACKABLE_TYPE_IMAGE_ANDROID a XrTrackableTypeANDROID .

La aplicación puede crear un XrTrackableTrackerANDROID llamando a xrCreateTrackableTrackerANDROID y especificando XR_TRACKABLE_TYPE_IMAGE_ANDROID como el tipo de objeto rastreable en XrTrackableTrackerCreateInfoANDROID :: trackableType para rastrear imágenes.

El tiempo de ejecución debe devolver XR_ERROR_FEATURE_UNSUPPORTED si XrTrackableTrackerCreateInfoANDROID :: trackableType es XR_TRACKABLE_TYPE_IMAGE_ANDROID y XrSystemImageTrackingPropertiesANDROID :: supportsImageTracking devuelve XR_FALSE a través de xrGetSystemProperties .

La estructura XrTrackableImageConfigurationANDROID se define de la siguiente manera:

typedef struct XrTrackableImageConfigurationANDROID {
    XrStructureType                           type;
    const void*                               next;
    uint32_t                                  databaseCount;
    const XrTrackableImageDatabaseANDROID*    databases;
} XrTrackableImageConfigurationANDROID;

Descripciones de los miembros

  • type es el XrStructureType de esta estructura.
  • next es NULL o un puntero a la siguiente estructura en una cadena de estructuras. No se definen tales estructuras en OpenXR principal ni en esta extensión.
  • databaseCount es un uint32_t que especifica la cantidad de elementos en databases.
  • databases es un array de XrTrackableImageDatabaseANDROID que especifica las bases de datos con las que se creará el objeto de seguimiento.

La aplicación debe establecer una configuración válida agregando un XrTrackableImageConfigurationANDROID a la cadena next de XrTrackableTrackerCreateInfoANDROID . De lo contrario, el tiempo de ejecución debe devolver XR_ERROR_VALIDATION_FAILURE .

La aplicación debe proporcionar al menos una estructura XrTrackableImageDatabaseANDROID para crear el objeto de seguimiento.

Uso válido (implícito)

La enumeración XrTrackableImageTrackingModeANDROID describe los modos de seguimiento de imágenes admitidos.

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;

Descripciones de los enumerantes

  • XR_TRACKABLE_IMAGE_TRACKING_MODE_DYNAMIC_ANDROID: Este modo tiene la mayor precisión y permite el seguimiento de imágenes en movimiento con baja latencia. También tiene el mayor consumo de energía.
  • XR_TRACKABLE_IMAGE_TRACKING_MODE_STATIC_ANDROID: Este modo se debe usar para imágenes que se sabe que son estáticas o semiestáticas. Este modo genera un menor consumo de energía en comparación con el modo dinámico. Si se mueve una imagen estática, se actualizará con una latencia mucho mayor que si se usa el modo dinámico.

La enumeración XrTrackableImageFormatANDROID describe los formatos de imágenes compatibles.

typedef enum XrTrackableImageFormatANDROID {
    XR_TRACKABLE_IMAGE_FORMAT_R8G8B8A8_ANDROID = 1,
    XR_TRACKABLE_IMAGE_FORMAT_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrTrackableImageFormatANDROID;

Descripciones de los enumerantes

  • XR_TRACKABLE_IMAGE_FORMAT_R8G8B8A8_ANDROID: Formato de imagen RGBA con datos de transparencia y color de 8 bits por canal.

La función xrAddTrackableImageDatabaseANDROID se define de la siguiente manera:

XrResult xrAddTrackableImageDatabaseANDROID(
    XrTrackableTrackerANDROID                   tracker,
    XrTrackableImageDatabaseANDROID             database);

Descripciones de los parámetros

Cuando se agrega una XrTrackableImageDatabaseANDROID a un objeto de seguimiento, las imágenes de referencia de esa base de datos deben tenerse en cuenta para la detección y el seguimiento, además de cualquier otra base de datos que se haya agregado anteriormente con xrAddTrackableImageDatabaseANDROID o a través de la estructura XrTrackableImageConfigurationANDROID cuando se creó el objeto de seguimiento inicialmente.

Uso válido (implícito)

Códigos de retorno

Listo

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falla

  • 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 función xrRemoveTrackableImageDatabaseANDROID se define de la siguiente manera:

XrResult xrRemoveTrackableImageDatabaseANDROID(
    XrTrackableTrackerANDROID                   tracker,
    XrTrackableImageDatabaseANDROID             database);

Descripciones de los parámetros

Cuando se quita un XrTrackableImageDatabaseANDROID de un XrTrackableTrackerANDROID , las estructuras XrTrackableImageDatabaseEntryANDROID de esa base de datos ya no se deben tener en cuenta para la detección y el seguimiento. Ya no se deben informar las entradas de esa base de datos que se rastrean de forma activa. El identificador XrTrackableImageDatabaseANDROID quitado no debe destruirse de forma implícita como parte de esta operación.

Uso válido (implícito)

Códigos de retorno

Listo

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falla

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

Cómo obtener imágenes

La función xrGetTrackableImageANDROID se define de la siguiente manera:

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

Descripciones de los parámetros

El tiempo de ejecución debe devolver XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID si el tipo de objeto rastreable de XrTrackableANDROID no es XR_TRACKABLE_TYPE_IMAGE_ANDROID o si el tipo de objeto rastreable de XrTrackableTrackerANDROID no es XR_TRACKABLE_TYPE_IMAGE_ANDROID .

Uso válido (implícito)

Códigos de retorno

Listo

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falla

  • 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 estructura XrTrackableImageANDROID se define de la siguiente manera:

typedef struct XrTrackableImageANDROID {
    XrStructureType                    type;
    const void*                        next;
    XrTrackingStateANDROID             trackingState;
    XrTime                             lastUpdatedTime;
    XrTrackableImageDatabaseANDROID    database;
    uint32_t                           databaseEntryIndex;
    XrPosef                            centerPose;
    XrExtent2Df                        extents;
} XrTrackableImageANDROID;

Descripciones de los miembros

  • type es el XrStructureType de esta estructura.
  • next es NULL o un puntero a la siguiente estructura en una cadena de estructuras. No se definen tales estructuras en OpenXR principal ni en esta extensión.
  • trackingState es el XrTrackingStateANDROID de la imagen.
  • lastUpdatedTime es el XrTime de la última actualización de la imagen.
  • database es el identificador de XrTrackableImageDatabaseANDROID desde el que se hizo el seguimiento de esta imagen.
  • databaseEntryIndex es el índice que se asigna al array XrTrackableImageDatabaseCreateInfoANDROID :: entries de database .
  • centerPose es el XrPosef de la imagen ubicada en XrTrackableGetInfoANDROID :: baseSpace . La imagen se encuentra en el plano XZ, con X apuntando hacia la derecha de la imagen y Z apuntando hacia su parte inferior.
  • extents son las dimensiones de XrExtent2Df de la imagen. El límite del cuadro delimitador se encuentra en los puntos: centerPose +/- ( extents / 2).

Uso válido (implícito)

Manejo de fallas

La aplicación debe sondear el evento XrEventDataImageTrackingLostANDROID con xrPollEvent y no debe ignorarlo.

La estructura XrEventDataImageTrackingLostANDROID se define de la siguiente manera:

typedef struct XrEventDataImageTrackingLostANDROID {
    XrStructureType    type;
    const void*        next;
    XrTime             time;
} XrEventDataImageTrackingLostANDROID;

Descripciones de los miembros

  • type es el XrStructureType de esta estructura.
  • next es NULL o un puntero a la siguiente estructura en una cadena de estructuras. No se definen tales estructuras en OpenXR principal ni en esta extensión.
  • time XrTime

Recibir el evento XrEventDataImageTrackingLostANDROID indica que el seguimiento de imágenes sufrió una falla interna que provocó que se invalidaran los recursos existentes. La aplicación debe destruir todos los identificadores de XrTrackableImageDatabaseANDROID y volver a crearlos si desea continuar con el seguimiento de imágenes. La aplicación también debe destruir todos los identificadores de XrTrackableTrackerANDROID relacionados con el seguimiento de imágenes y volver a crearlos si desea continuar con el seguimiento de imágenes.

Uso válido (implícito)

Ejemplo de código para obtener imágenes rastreables

En el siguiente ejemplo de código, se muestra cómo obtener imágenes rastreables.

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

Ejemplo de código para administrar bases de datos de imágenes durante el tiempo de ejecución

En el siguiente ejemplo de código, se muestra cómo modificar el conjunto de imágenes que se rastrean.

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.

Ejemplo de código para reaccionar ante errores de seguimiento de imágenes

En el siguiente código de ejemplo, se muestra cómo controlar las fallas sondeando el 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;
    }
  }
}

Nuevos tipos de objetos

Comandos nuevos

Nuevas estructuras

Enums nuevos

Nuevas constantes de enumeración

  • XR_ANDROID_TRACKABLES_IMAGE_EXTENSION_NAME
  • XR_ANDROID_trackables_image_SPEC_VERSION
  • Extensión de XrObjectType :

    • XR_OBJECT_TYPE_TRACKABLE_IMAGE_DATABASE_ANDROID
  • Extensión de XrResult :

    • XR_ERROR_IMAGE_FORMAT_UNSUPPORTED_ANDROID
  • Extensión de 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
  • Extiende XrTrackableTypeANDROID :

    • XR_TRACKABLE_TYPE_IMAGE_ANDROID

Problemas

Historial de versiones

  • Revisión 1, 2025-04-08 (Daniel Guttenberg)

    • Es la descripción inicial de la extensión.