XR_ANDROID_trackables_image
Name String
XR_ANDROID_trackables_image
Tipo de extensión
Extensión de instancia
Número de extensión registrado
710
Revisión
1
Estado de ratificación
No ratificado
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 de IP conocidos.
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 las imágenes planas, según lo especificado por los 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
typees el XrStructureType de esta estructura.nextesNULLo 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 estructuras, consulta la estructura que se extiende ( XrSystemProperties).supportsImageTrackinges unXrBool32que indica si el sistema actual proporciona la capacidad de seguimiento de imágenes.supportsPhysicalSizeEstimationes unXrBool32que indica si el sistema actual proporciona una estimación del tamaño de la imagen.maxTrackedImageCountes la cantidad máxima total de imágenes de las que se puede hacer un seguimiento al mismo tiempo.maxLoadedImageCountes 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 un seguimiento de imágenes extendiendo XrSystemProperties con la estructura XrSystemImageTrackingPropertiesANDROID cuando se llama a xrGetSystemProperties . El entorno de ejecución debe mostrar XR_ERROR_FEATURE_UNSUPPORTED para la creación del 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 con seguimiento en cualquier momento.
Si un entorno de ejecución admite el seguimiento de imágenes, debe admitir maxLoadedImageCount imágenes cargadas en cualquier momento.
Si un entorno 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)
- La extensión
XR_ANDROID_trackables_imagedebe estar habilitada antes de usar XrSystemImageTrackingPropertiesANDROID -
typedebe serXR_TYPE_SYSTEM_IMAGE_TRACKING_PROPERTIES_ANDROID -
nextdebe serNULLo un puntero válido a la siguiente estructura en una cadena de estructuras
Crea bases de datos
La aplicación puede crear un controlador 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 un XrTrackableImageDatabaseEntryANDROID cuando se crea un controlador XrTrackableImageDatabaseANDROID.
Un XrTrackableImageDatabaseANDROID es un controlador que representa un conjunto de imágenes de referencia procesadas que se pueden descubrir y seguir 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
typees el XrStructureType de esta estructura.nextesNULLo un puntero a la siguiente estructura en una cadena de estructuras. No se definen tales estructuras en OpenXR principal ni en esta extensión.trackingModees un XrTrackableImageTrackingModeANDROID que indica el modo deseado para el seguimiento.physicalWidthindica el ancho de la imagen en metros. Si es cero, el tamaño de la imagen se estimará en línea.imageWidthindica el ancho de la imagen en píxeles.imageHeightindica la altura de la imagen en píxeles.formates un XrTrackableImageFormatANDROID que indica el formato de los datos de la imagen enbuffer.bufferSizeindica la longitud en bytes debuffer.bufferes el búferuint8_tque contiene los datos de píxeles de la imagen de referencia. El contenido debufferdebe ser válido durante la operación asíncrona de creación de la base de datos, que inicia xrCreateTrackableImageDatabaseAsyncANDROID y completa xrCreateTrackableImageDatabaseCompleteANDROID .
La aplicación puede establecer physicalWidth en 0 para solicitar una estimación del tamaño en línea si XrSystemImageTrackingPropertiesANDROID :: supportsPhysicalSizeEstimation es XR_TRUE .
El entorno de ejecución puede devolver XR_ERROR_VALIDATION_FAILURE de xrCreateTrackableImageDatabaseAsyncANDROID si bufferSize no coincide con el tamaño esperado según los valores imageWidth , imageHeight y format de la entrada.
Uso válido (implícito)
- La extensión
XR_ANDROID_trackables_imagedebe estar habilitada antes de usar XrTrackableImageDatabaseEntryANDROID. -
typedebe serXR_TYPE_TRACKABLE_IMAGE_DATABASE_ENTRY_ANDROID -
nextdebe serNULLo un puntero válido a la siguiente estructura en una cadena de estructuras -
trackingModedebe ser un valor XrTrackableImageTrackingModeANDROID válido. -
formatdebe ser un valor XrTrackableImageFormatANDROID válido. -
bufferdebe ser un puntero a un array de valoresbufferSizeuint8_t - El parámetro
bufferSizedebe ser mayor que0.
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
typees el XrStructureType de esta estructura.nextesNULLo un puntero a la siguiente estructura en una cadena de estructuras. No se definen tales estructuras en OpenXR principal ni en esta extensión.entryCountes unuint32_tque especifica el recuento de elementos en el arrayentries.entrieses un array de estructuras XrTrackableImageDatabaseEntryANDROID.
Uso válido (implícito)
- La extensión
XR_ANDROID_trackables_imagedebe estar habilitada antes de usar XrTrackableImageDatabaseCreateInfoANDROID. -
typedebe serXR_TYPE_TRACKABLE_IMAGE_DATABASE_CREATE_INFO_ANDROID -
nextdebe serNULLo un puntero válido a la siguiente estructura en una cadena de estructuras -
entriesdebe ser un puntero a un array de estructurasentryCountXrTrackableImageDatabaseEntryANDROID válidas - El parámetro
entryCountdebe ser mayor que0.
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
typees el XrStructureType de esta estructura.nextesNULLo un puntero a la siguiente estructura en una cadena de estructuras. No se definen tales estructuras en OpenXR principal ni en esta extensión.futureResultes el XrResult de la operación asíncrona.databasees el controlador XrTrackableImageDatabaseANDROID creado.
Códigos de devolución futuros
Valores de futureResult:
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_RUNTIME_FAILUREXR_ERROR_INSTANCE_LOSTXR_ERROR_SESSION_LOSTXR_ERROR_OUT_OF_MEMORYXR_ERROR_LIMIT_REACHED
Uso válido (implícito)
- La extensión
XR_ANDROID_trackables_imagedebe estar habilitada antes de usar XrCreateTrackableImageDatabaseCompletionANDROID. -
typedebe serXR_TYPE_CREATE_TRACKABLE_IMAGE_DATABASE_COMPLETION_ANDROID -
nextdebe serNULLo un puntero válido a la siguiente estructura en una cadena de estructuras -
futureResultdebe ser un valor XrResult válido. -
databasedebe ser un controlador XrTrackableImageDatabaseANDROID válido.
La función xrCreateTrackableImageDatabaseAsyncANDROID se define de la siguiente manera:
XrResult xrCreateTrackableImageDatabaseAsyncANDROID(
XrSession session,
const XrTrackableImageDatabaseCreateInfoANDROID* createInfo,
XrFutureEXT* future);
Descripciones de los parámetros
sessiones un controlador para un XrSession creado anteriormente con xrCreateSession .createInfoes un puntero a una estructura XrTrackableImageDatabaseCreateInfoANDROID.futurees un puntero alXrFutureEXTcreado.
Uso válido (implícito)
- La extensión
XR_ANDROID_trackables_imagedebe estar habilitada antes de llamar a xrCreateTrackableImageDatabaseAsyncANDROID. -
sessiondebe ser un controlador XrSession válido -
createInfodebe ser un puntero a una estructura XrTrackableImageDatabaseCreateInfoANDROID válida. -
futuredebe ser un puntero a un valorXrFutureEXT
Códigos de retorno
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 función xrCreateTrackableImageDatabaseCompleteANDROID se define de la siguiente manera:
XrResult xrCreateTrackableImageDatabaseCompleteANDROID(
XrSession session,
XrFutureEXT future,
XrCreateTrackableImageDatabaseCompletionANDROID* completion);
Descripciones de los parámetros
sessiones un controlador para un XrSession creado anteriormente con xrCreateSession .futurees elXrFutureEXTdel futuro que se debe completar.completiones un puntero a una estructura XrCreateTrackableImageDatabaseCompletionANDROID que contiene el resultado de la operación.
Uso válido (implícito)
- La extensión
XR_ANDROID_trackables_imagedebe estar habilitada antes de llamar a xrCreateTrackableImageDatabaseCompleteANDROID. -
sessiondebe ser un controlador XrSession válido -
completiondebe ser un puntero a una estructura XrCreateTrackableImageDatabaseCompletionANDROID.
Códigos de retorno
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 función xrDestroyTrackableImageDatabaseANDROID se define de la siguiente manera:
XrResult xrDestroyTrackableImageDatabaseANDROID(
XrTrackableImageDatabaseANDROID database);
Descripciones de los parámetros
databasees el controlador XrTrackableImageDatabaseANDROID que se destruirá.
Uso válido (implícito)
- La extensión
XR_ANDROID_trackables_imagedebe estar habilitada antes de llamar a xrDestroyTrackableImageDatabaseANDROID. -
databasedebe ser un controlador XrTrackableImageDatabaseANDROID válido.
Seguridad de subprocesos
- El acceso a
databasey a cualquier controlador secundario debe sincronizarse de forma externa.
Códigos de retorno
XR_SUCCESS
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_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 elemento rastreable en XrTrackableTrackerCreateInfoANDROID :: trackableType para hacer un seguimiento de las imágenes.
El entorno 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
typees el XrStructureType de esta estructura.nextesNULLo un puntero a la siguiente estructura en una cadena de estructuras. No se definen tales estructuras en OpenXR principal ni en esta extensión.databaseCountes unuint32_tque especifica la cantidad de elementos endatabases.databaseses un array de XrTrackableImageDatabaseANDROID que especifica las bases de datos con las que se creará el rastreador.
La aplicación debe establecer una configuración válida agregando un XrTrackableImageConfigurationANDROID a la cadena next de XrTrackableTrackerCreateInfoANDROID . De lo contrario, el entorno de ejecución debe devolver XR_ERROR_VALIDATION_FAILURE .
La aplicación debe proporcionar al menos una estructura XrTrackableImageDatabaseANDROID para crear el rastreador.
Uso válido (implícito)
- La extensión
XR_ANDROID_trackables_imagedebe estar habilitada antes de usar XrTrackableImageConfigurationANDROID. -
typedebe serXR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID -
nextdebe serNULLo un puntero válido a la siguiente estructura en una cadena de estructuras -
databasesdebe ser un puntero a un array de controladoresdatabaseCountválidos de XrTrackableImageDatabaseANDROID. - El parámetro
databaseCountdebe ser mayor que0.
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 enumerantes
XR_TRACKABLE_IMAGE_TRACKING_MODE_DYNAMIC_ANDROID: Este modo tiene la mayor precisión y permite el seguimiento de baja latencia de imágenes en movimiento. También tiene el consumo de energía más alto.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 usara 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 enumerantes
XR_TRACKABLE_IMAGE_FORMAT_R8G8B8A8_ANDROID: Es el formato de imagen RGBA con 8 bits por canal de datos de color y transparencia.
La función xrAddTrackableImageDatabaseANDROID se define de la siguiente manera:
XrResult xrAddTrackableImageDatabaseANDROID(
XrTrackableTrackerANDROID tracker,
XrTrackableImageDatabaseANDROID database);
Descripciones de los parámetros
trackeres el controlador XrTrackableTrackerANDROID al que se agregarádatabase.databasees el controlador XrTrackableImageDatabaseANDROID que se agregará atracker.
Cuando se agrega un XrTrackableImageDatabaseANDROID a un rastreador, 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ó inicialmente el rastreador.
Uso válido (implícito)
- La extensión
XR_ANDROID_trackables_imagedebe estar habilitada antes de llamar a xrAddTrackableImageDatabaseANDROID. -
trackerdebe ser un controlador XrTrackableTrackerANDROID válido. -
databasedebe ser un controlador XrTrackableImageDatabaseANDROID válido. - Tanto
databasecomotrackerdeben haberse creado, asignado o recuperado de la misma XrSession.
Códigos de retorno
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 función xrRemoveTrackableImageDatabaseANDROID se define de la siguiente manera:
XrResult xrRemoveTrackableImageDatabaseANDROID(
XrTrackableTrackerANDROID tracker,
XrTrackableImageDatabaseANDROID database);
Descripciones de los parámetros
trackeres el controlador XrTrackableTrackerANDROID del que se quitará eldatabase.databasees el controlador XrTrackableImageDatabaseANDROID que se quitará detracker.
Cuando se quita un XrTrackableImageDatabaseANDROID de un XrTrackableTrackerANDROID , las estructuras XrTrackableImageDatabaseEntryANDROID de esa base de datos ya no deben tenerse en cuenta para la detección y el seguimiento. No se deben informar las entradas de esa base de datos de las que se hace un seguimiento activo. El controlador XrTrackableImageDatabaseANDROID que se quitó no debe destruirse de forma implícita como parte de esta operación.
Uso válido (implícito)
- La extensión
XR_ANDROID_trackables_imagedebe estar habilitada antes de llamar a xrRemoveTrackableImageDatabaseANDROID. -
trackerdebe ser un controlador XrTrackableTrackerANDROID válido. -
databasedebe ser un controlador XrTrackableImageDatabaseANDROID válido. - Tanto
databasecomotrackerdeben haberse creado, asignado o recuperado de la misma XrSession.
Códigos de retorno
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_VALIDATION_FAILURE
Obteniendo 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
trackeres el XrTrackableTrackerANDROID que se consulta.getInfoes el XrTrackableGetInfoANDROID con la información que se usa para obtener el código QR rastreable.trackablees un puntero a la estructura XrTrackableImageANDROID en la que se devuelve la imagen que se puede seguir.
El entorno de ejecución debe devolver XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID si el tipo de elemento rastreable de XrTrackableANDROID no es XR_TRACKABLE_TYPE_IMAGE_ANDROID o si el tipo de elemento rastreable de XrTrackableTrackerANDROID no es XR_TRACKABLE_TYPE_IMAGE_ANDROID .
Uso válido (implícito)
- La extensión
XR_ANDROID_trackables_imagedebe estar habilitada antes de llamar a xrGetTrackableImageANDROID. -
trackerdebe ser un controlador XrTrackableTrackerANDROID válido. -
getInfodebe ser un puntero a una estructura XrTrackableGetInfoANDROID válida. -
trackabledebe ser un puntero a una estructura XrTrackableImageANDROID.
Códigos de retorno
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 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
typees el XrStructureType de esta estructura.nextesNULLo un puntero a la siguiente estructura en una cadena de estructuras. No se definen tales estructuras en OpenXR principal ni en esta extensión.trackingStatees el XrTrackingStateANDROID de la imagen.lastUpdatedTimees laXrTimede la última actualización de la imagen.databasees el controlador XrTrackableImageDatabaseANDROID desde el que se hizo un seguimiento de esta imagen.databaseEntryIndexes el índice que se asigna al arrayentriesdedatabasede XrTrackableImageDatabaseCreateInfoANDROID :: .centerPosees el XrPosef de la imagen ubicada en XrTrackableGetInfoANDROID ::baseSpace. La imagen se encuentra en el plano XZ, con X apuntando a la derecha de la imagen y Z apuntando a la parte inferior.extentsson las dimensiones XrExtent2Df de la imagen. El límite del cuadro delimitador se encuentra en los puntos:centerPose+/- (extents/ 2).
Uso válido (implícito)
- La extensión
XR_ANDROID_trackables_imagedebe estar habilitada antes de usar XrTrackableImageANDROID. -
typedebe serXR_TYPE_TRACKABLE_IMAGE_ANDROID -
nextdebe serNULLo un puntero válido a la siguiente estructura en una cadena de estructuras -
trackingStatedebe ser un valor XrTrackingStateANDROID válido. -
databasedebe ser un controlador XrTrackableImageDatabaseANDROID válido.
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
typees el XrStructureType de esta estructura.nextesNULLo un puntero a la siguiente estructura en una cadena de estructuras. No se definen tales estructuras en OpenXR principal ni en esta extensión.timeXrTime
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 controladores XrTrackableImageDatabaseANDROID y volver a crearlos si desea continuar con el seguimiento de imágenes. La aplicación también debe destruir todos los controladores 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)
- La extensión
XR_ANDROID_trackables_imagedebe estar habilitada antes de usar XrEventDataImageTrackingLostANDROID. -
typedebe serXR_TYPE_EVENT_DATA_IMAGE_TRACKING_LOST_ANDROID -
nextdebe serNULLo un puntero válido a la siguiente estructura en una cadena de estructuras
Código de ejemplo para obtener imágenes rastreables
En el siguiente código de ejemplo, se muestra cómo obtener imágenes que se pueden seguir.
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));
Código de ejemplo para administrar bases de datos de imágenes durante el tiempo de ejecución
En el siguiente código de ejemplo, se muestra cómo modificar el conjunto de imágenes de las que se hace un seguimiento.
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.
Código de ejemplo para reaccionar a las fallas de seguimiento de imágenes
En el siguiente ejemplo de código, 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
- xrAddTrackableImageDatabaseANDROID
- xrCreateTrackableImageDatabaseAsyncANDROID
- xrCreateTrackableImageDatabaseCompleteANDROID
- xrDestroyTrackableImageDatabaseANDROID
- xrGetTrackableImageANDROID
- xrRemoveTrackableImageDatabaseANDROID
Estructuras nuevas
- XrCreateTrackableImageDatabaseCompletionANDROID
- XrEventDataImageTrackingLostANDROID
- XrTrackableImageANDROID
- XrTrackableImageConfigurationANDROID
- XrTrackableImageDatabaseCreateInfoANDROID
- XrTrackableImageDatabaseEntryANDROID
Extiende XrSystemProperties :
Enums nuevas
Nuevas constantes de enum
XR_ANDROID_TRACKABLES_IMAGE_EXTENSION_NAMEXR_ANDROID_trackables_image_SPEC_VERSIONExtiende XrObjectType :
XR_OBJECT_TYPE_TRACKABLE_IMAGE_DATABASE_ANDROID
Extiende XrResult :
XR_ERROR_IMAGE_FORMAT_UNSUPPORTED_ANDROID
Extiende 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
Extiende XrTrackableTypeANDROID :
XR_TRACKABLE_TYPE_IMAGE_ANDROID
Problemas
Historial de versiones
Revisión 1, 8 de abril de 2025 (Daniel Guttenberg)
- Descripción inicial de la extensión.