XR_EXT_spatial_image_tracking

Name String

XR_EXT_spatial_image_tracking

Tipo de extensión

Extensión de instancia

Número de extensión registrado

783

Revisión

1

Estado de ratificación

No ratificado

Dependencias de extensiones y versiones

XR_EXT_spatial_entity

Colaboradores

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

Descripción general

Esta extensión proporciona la capacidad de seguimiento de imágenes para la extensión XR_EXT_spatial_entity. Permite que las aplicaciones detecten y hagan un seguimiento de imágenes planas específicas, según lo que se indique en los conjuntos de imágenes de referencia de entrada.

Una imagen con seguimiento se representa como una entidad espacial con los siguientes componentes:

  • XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT
  • XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT

Por lo general, las aplicaciones usan la extensión de seguimiento de imágenes espaciales con el siguiente patrón:

  • Primero, una aplicación crea uno o varios controladores XrSpatialImageTrackingDatabaseEXT basados en conjuntos de datos de imágenes de referencia precargados.
  • Luego, la aplicación crea un controlador XrSpatialContextEXT basado en los controladores XrSpatialImageTrackingDatabaseEXT creados anteriormente.
  • Luego, la aplicación libera los datos de la imagen de referencia para reducir su consumo de memoria.
  • La aplicación descubre y consulta imágenes según los patrones de acceso de la entidad espacial.
  • La aplicación puede cargar conjuntos adicionales de imágenes de referencia y crear XrSpatialImageTrackingDatabaseEXT adicionales y, posteriormente, XrSpatialContextEXT a partir de ellos para extender el conjunto de imágenes detectables y rastreables de forma dinámica durante el tiempo de ejecución.
  • La aplicación puede destruir los controladores XrSpatialImageTrackingDatabaseEXT para reducir el conjunto de imágenes detectables y rastreables de forma dinámica durante el tiempo de ejecución.
  • La aplicación puede destruir los controladores XrSpatialContextEXT para reducir el conjunto de imágenes detectables y rastreables de forma dinámica durante el tiempo de ejecución.

Asistencia del entorno de ejecución

Un entorno de ejecución debe anunciar su compatibilidad con la función de seguimiento de imágenes usando xrEnumerateSpatialCapabilitiesEXT y enumerando la siguiente función:

  • XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT

Configuración

Para habilitar la detección y el seguimiento de imágenes planas, la aplicación puede pasar estructuras XrSpatialCapabilityConfigurationImageTrackingEXT en XrSpatialContextCreateInfoEXT :: capabilityConfigs cuando se llama a la función xrCreateSpatialContextAsyncEXT y se pasan arrays de estructuras< XrSpatialImageTrackingDatabaseEXT en cada XrSpatialCapabilityConfigurationImageTrackingEXT :: imageTrackingDatabases .

Creación de conjuntos de imágenes de entrada

Para especificar las imágenes de referencia que se detectarán y seguirán, la aplicación debe crear al menos un conjunto de imágenes de referencia de entrada. Un conjunto de imágenes de referencia de entrada se representa con un controlador XrSpatialImageTrackingDatabaseEXT y contiene al menos una imagen.

XR_DEFINE_HANDLE(XrSpatialImageTrackingDatabaseEXT)

El controlador XrSpatialImageTrackingDatabaseEXT representa los recursos para descubrir y actualizar una cantidad de imágenes espaciales en el entorno del usuario. Las aplicaciones pueden usar este controlador para descubrir y actualizar imágenes espaciales con otras funciones de esta extensión.

Crea la base de datos de seguimiento de imágenes espaciales

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

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

Descripciones de los parámetros

  • session es una XrSession en la que estará activa la base de datos de seguimiento de imágenes espaciales.
  • createInfo es el XrSpatialImageTrackingDatabaseCreateInfoEXT que se usa para especificar los parámetros de la base de datos de seguimiento de imágenes espaciales.
  • future es un puntero a un XrFutureEXT .

Una aplicación puede crear un controlador XrSpatialImageTrackingDatabaseEXT con la función xrCreateSpatialImageTrackingDatabaseAsyncEXT y configurar los conjuntos de imágenes de referencia de entrada de la base de datos de seguimiento de imágenes con createInfo .

El entorno de ejecución debe mostrar XR_ERROR_SPATIAL_IMAGE_FORMAT_UNSUPPORTED_EXT si xrEnumerateSpatialReferenceImageFormatsEXT no enumera el format de XrSpatialReferenceImageEXT de ninguna de las imágenes de referencia de entrada.

El entorno de ejecución debe devolver XR_ERROR_SPATIAL_IMAGE_INVALID_EXT si el array XrSpatialReferenceImageEXT :: planes de cualquiera de las imágenes de referencia de entrada no se puede evaluar según los metadatos de la imagen de referencia de XrSpatialReferenceImageEXT .

El entorno de ejecución debe devolver XR_ERROR_SPATIAL_IMAGE_INVALID_EXT si el array XrSpatialReferenceImageEXT :: planes de cualquiera de las imágenes de referencia de entrada no proporciona exactamente la misma cantidad de planos que los canales de color que tiene XrSpatialReferenceImageEXT :: format.

Si un entorno de ejecución aplica un sistema de permisos para controlar el acceso de la aplicación a la función de seguimiento de imágenes, el entorno de ejecución debe devolver XR_ERROR_PERMISSION_INSUFFICIENT si no se otorgaron esos permisos a esta aplicación.

Esta función inicia una operación asíncrona y crea un XrFutureEXT correspondiente, que se puede usar con xrPollFutureEXT y funciones relacionadas. El valor que se muestra de esta función solo indica si los parámetros eran aceptables para programar la operación asíncrona. La función de finalización correspondiente es xrCreateSpatialImageTrackingDatabaseCompleteEXT , que se puede usar cuando un futuro de esta función está en el estado READY, con los resultados propagados por esa función en la estructura de finalización XrCreateSpatialImageTrackingDatabaseCompletionEXT .

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_PERMISSION_INSUFFICIENT
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_IMAGE_FORMAT_UNSUPPORTED_EXT
  • XR_ERROR_SPATIAL_IMAGE_INVALID_EXT
  • XR_ERROR_SPATIAL_IMAGE_SIZE_MISSING_EXT
  • XR_ERROR_VALIDATION_FAILURE

La estructura XrSpatialImageTrackingDatabaseCreateInfoEXT se define de la siguiente manera:

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

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.
  • spatialReferenceImageCount es la cantidad de elementos en el array spatialReferenceImages.
  • spatialReferenceImages es un array de XrSpatialReferenceImageEXT .

La estructura XrSpatialImageTrackingDatabaseCreateInfoEXT describe la información para crear un controlador XrSpatialImageTrackingDatabaseEXT.

Cada XrSpatialImageTrackingDatabaseEXT debe crearse con al menos un XrSpatialReferenceImageEXT en el array XrSpatialImageTrackingDatabaseCreateInfoEXT :: spatialReferenceImages.

Uso válido (implícito)

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

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

Descripciones de los parámetros

xrCreateSpatialImageTrackingDatabaseCompleteEXT completa la operación asíncrona que inició xrCreateSpatialImageTrackingDatabaseAsyncEXT .

El entorno de ejecución no debe acceder a ningún puntero XrSpatialReferenceImagePlaneEXT :: buffer que haya proporcionado el array de entrada XrSpatialImageTrackingDatabaseCreateInfoEXT :: spatialReferenceImages para esta llamada a xrCreateSpatialImageTrackingDatabaseAsyncEXT después de que se haya completado. La aplicación puede liberar cualquier dato de XrSpatialReferenceImagePlaneEXT :: buffer después de que se haya completado xrCreateSpatialImageTrackingDatabaseAsyncEXT para reducir su espacio en memoria.

El entorno de ejecución debe mostrar XR_ERROR_FUTURE_PENDING_EXT si future no está en estado listo. El entorno de ejecución debe devolver XR_ERROR_FUTURE_INVALID_EXT si future ya se completó o canceló.

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

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

Descripciones de los miembros

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
  • XR_ERROR_SPATIAL_IMAGE_FORMAT_UNSUPPORTED_EXT
  • XR_ERROR_SPATIAL_IMAGE_INVALID_EXT

Si futureResult es un código de éxito, database debe ser un controlador válido. Si database es válido, solo lo será dentro del ciclo de vida de xrCreateSpatialImageTrackingDatabaseAsyncEXT :: session o hasta que la aplicación destruya el database con xrDestroySpatialImageTrackingDatabaseEXT , lo que ocurra primero.

Uso válido (implícito)

Destruye la base de datos de seguimiento de imágenes espaciales

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

XrResult xrDestroySpatialImageTrackingDatabaseEXT(
    XrSpatialImageTrackingDatabaseEXT           database);

Descripciones de los parámetros

La aplicación puede llamar a la función xrDestroySpatialImageTrackingDatabaseEXT para liberar el controlador database y los recursos subyacentes cuando finalicen las tareas de descubrimiento y actualización de imágenes espaciales.

La aplicación puede llamar a la función xrDestroySpatialImageTrackingDatabaseEXT antes de llamar a xrDestroySpatialContextEXT . El entorno de ejecución no debe informar más imágenes administradas por este XrSpatialImageTrackingDatabaseEXT destruido. El entorno de ejecución debe seguir informando las imágenes administradas por otras bases de datos.

El entorno de ejecución debe garantizar que las instantáneas de descubrimiento que muestra xrCreateSpatialDiscoverySnapshotCompleteEXT no contengan imágenes que pertenezcan a controladores XrSpatialImageTrackingDatabaseEXT destruidos o no válidos, incluso si el controlador se destruyó después de que la aplicación llamó a xrCreateSpatialDiscoverySnapshotAsyncEXT . Dado que los datos de una instantánea espacial son inmutables, la aplicación debería destruir cualquier controlador XrSpatialSnapshotEXT que se haya creado antes de destruir database. De lo contrario, la aplicación podría recibir controladores XrSpatialImageTrackingDatabaseEXT no válidos cuando se use xrQuerySpatialComponentDataEXT.

La aplicación puede llamar a la función xrDestroySpatialContextEXT para liberar el controlador XrSpatialContextEXT antes de destruir cualquiera de los controladores XrSpatialImageTrackingDatabaseEXT con los que se creó XrSpatialContextEXT. El entorno de ejecución no debe destruir de forma implícita estos controladores XrSpatialImageTrackingDatabaseEXT cuando se destruye el XrSpatialContextEXT.

Administrar el ciclo de vida de XrSpatialContextEXT y XrSpatialImageTrackingDatabaseEXT de forma independiente permite que las aplicaciones reutilicen los controladores de XrSpatialImageTrackingDatabaseEXT creados anteriormente sin necesidad de volver a realizar el costoso procedimiento de creación.

Por ejemplo, destruir un XrSpatialContextEXT y, luego, volver a crear otro XrSpatialContextEXT con el mismo XrSpatialImageTrackingDatabaseEXT permite pausar y reanudar el seguimiento de imágenes sin necesidad de realizar otro procedimiento de inicialización.

Uso válido (implícito)

Seguridad de subprocesos

  • El acceso a database y a cualquier controlador 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

Compatibilidad con formatos de imagen de entrada

Las aplicaciones deben llamar a xrEnumerateSpatialReferenceImageFormatsEXT para obtener la lista de formatos de imagen de referencia de entrada admitidos.

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

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

Descripciones de los parámetros

  • instance es un controlador de un XrInstance .
  • systemId es el XrSystemId cuyos formatos de imagen de referencia de entrada se enumerarán.
  • capability es el XrSpatialCapabilityEXT para el que se enumerarán los formatos de imagen de referencia de entrada.
  • formatCapacityInput es la capacidad del array formats, o 0 para indicar una solicitud de recuperación de la capacidad requerida.
  • formatCountOutput es la cantidad de formatos o la capacidad requerida en caso de que formatCapacityInput sea insuficiente.
  • formats es un array de XrSpatialReferenceImageFormatEXT . Puede ser NULL si formatCapacityInput es 0.
  • Consulta la sección Parámetros de tamaño del búfer para obtener una descripción detallada de cómo recuperar el tamaño de formats requerido.

La aplicación puede enumerar la lista de formatos de imagen de referencia de entrada que admite un XrSystemId determinado para un XrSpatialCapabilityEXT determinado con xrEnumerateSpatialReferenceImageFormatsEXT .

El entorno de ejecución no debe enumerar los formatos de las extensiones que no están habilitadas para instance .

Uso válido (implícito)

Códigos de retorno

Listo

  • XR_SUCCESS

Falla

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT
  • XR_ERROR_SYSTEM_INVALID
  • XR_ERROR_VALIDATION_FAILURE

Consulta XrSpatialReferenceImageFormatEXT para obtener una lista completa de todos los formatos de imagen de referencia que admite cualquier extensión.

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

La enumeración XrSpatialReferenceImageFormatEXT identifica los formatos de imagen de referencia de entrada que el entorno de ejecución puede admitir.

Se deben admitir, como mínimo, los valores XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGBA_8888_EXT y XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGB_888_EXT.

Los enumerantes tienen el siguiente significado:

Descripciones de enumerantes

  • XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGBA_8888_EXT: Es un búfer RGBA. El formato no garantiza el diseño de los datos de píxeles en la memoria. Se debe acceder a los píxeles con los metadatos que proporcionan las estructuras XrSpatialReferenceImagePlaneEXT correspondientes. Cada canal de color de píxel tiene un tamaño de 8 bits, lo que hace que cada píxel tenga un tamaño de 32 bits.
  • XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGB_888_EXT: Es un búfer RGB. El formato no garantiza el diseño de los datos de píxeles en la memoria. Se debe acceder a los píxeles con los metadatos que proporcionan las estructuras XrSpatialReferenceImagePlaneEXT correspondientes. Cada canal de color de píxel tiene un tamaño de 8 bits, lo que hace que cada píxel tenga un tamaño de 24 bits.
  • XR_SPATIAL_REFERENCE_IMAGE_FORMAT_YUV_420_888_EXT: Es un búfer YUV con submuestreo de crominancia de patrón 4:2:0. El formato no garantiza el diseño de los datos de píxeles en la memoria. Se debe acceder a los píxeles con los metadatos que proporcionan las estructuras XrSpatialReferenceImagePlaneEXT correspondientes. Cada canal de color de píxel RGB decodificado tiene un tamaño de 8 bits, lo que hace que cada píxel tenga un tamaño de 24 bits.

Configuración del seguimiento de imágenes espaciales

Esta extensión proporciona estructuras opcionales que la aplicación puede usar para configurar la capacidad de seguimiento de imágenes.

Optimización de imágenes estáticas

La estructura XrSpatialImageStaticOptimizationEXT se define de la siguiente manera:

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

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.
  • optimizeForStaticImage es un XrBool32 que indica si las imágenes se mueven o no. Un valor de XR_TRUE indica que las imágenes no se mueven.

Si XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT se enumera con xrEnumerateSpatialCapabilityFeaturesEXT para la capacidad XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, la aplicación puede encadenar XrSpatialImageStaticOptimizationEXT a la cadena XrSpatialImageTrackingDatabaseCreateInfoEXT :: next o XrSpatialReferenceImageEXT :: next .

Si la aplicación encadena XrSpatialImageStaticOptimizationEXT a la estructura XrSpatialImageTrackingDatabaseCreateInfoEXT, el entorno de ejecución debe suponer que todas las imágenes de ese XrSpatialImageTrackingDatabaseEXT son estáticas si optimizeForStaticImage se establece en XR_TRUE . En consecuencia, el entorno de ejecución debe suponer que todas las imágenes de ese XrSpatialImageTrackingDatabaseEXT no son estáticas si optimizeForStaticImage se establece en XR_FALSE .

Si la aplicación encadena XrSpatialImageStaticOptimizationEXT a la estructura XrSpatialReferenceImageEXT, el entorno de ejecución debe suponer que esta imagen de referencia es estática si optimizeForStaticImage se establece en XR_TRUE . En consecuencia, el entorno de ejecución debe suponer que esta imagen de referencia no es estática si optimizeForStaticImage se establece en XR_FALSE . Encadenar la estructura XrSpatialImageStaticOptimizationEXT a la estructura XrSpatialReferenceImageEXT tiene prioridad sobre encadenarla a la estructura XrSpatialImageTrackingDatabaseCreateInfoEXT.

Si xrEnumerateSpatialCapabilityFeaturesEXT no enumera XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT para la capacidad XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT y la aplicación encadena una estructura XrSpatialImageStaticOptimizationEXT a cualquiera de las siguientes cadenas aplicables, el entorno de ejecución debe devolver XR_ERROR_VALIDATION_FAILURE de xrCreateSpatialImageTrackingDatabaseAsyncEXT .

Esto puede permitir que el entorno de ejecución genere una pose y un tamaño más precisos.

Esto puede permitir que el entorno de ejecución reduzca el consumo de energía.

Uso válido (implícito)

Ancho de la imagen de referencia

La estructura XrSpatialImageSizeEXT se define de la siguiente manera:

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

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.
  • physicalWidth es un valor float que representa el ancho físico en metros que se establecerá.

Si xrEnumerateSpatialCapabilityFeaturesEXT enumera XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXT para la capacidad XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, la aplicación puede encadenar XrSpatialImageSizeEXT a XrSpatialImageTrackingDatabaseCreateInfoEXT :: next o XrSpatialReferenceImageEXT :: next .

Si la aplicación encadena XrSpatialImageSizeEXT a la estructura XrSpatialImageTrackingDatabaseCreateInfoEXT, el entorno de ejecución debe suponer que todas las imágenes de esa XrSpatialImageTrackingDatabaseEXT tienen un ancho de physicalWidth metros y una altura según la relación de aspecto que se proporciona de forma implícita a través de XrSpatialReferenceImageEXT :: width y XrSpatialReferenceImageEXT :: height .

Si la aplicación encadena XrSpatialImageSizeEXT a la estructura XrSpatialReferenceImageEXT, el entorno de ejecución debe suponer que esta imagen de referencia tiene un ancho de physicalWidth metros y una altura según la relación de aspecto que se proporciona de forma implícita a través de XrSpatialReferenceImageEXT :: width y XrSpatialReferenceImageEXT :: height . Encadenar la estructura XrSpatialImageSizeEXT a la estructura XrSpatialReferenceImageEXT tiene prioridad sobre encadenarla a la estructura XrSpatialImageTrackingDatabaseCreateInfoEXT.

Esto puede permitir que el entorno de ejecución devuelva una pose y un tamaño más precisos.

El entorno de ejecución debe enumerar XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXT o XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT, o ambos.

Si XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT se enumera con xrEnumerateSpatialCapabilityFeaturesEXT, el entorno de ejecución debe proporcionar tamaños de imagen automáticamente para las imágenes para las que la aplicación no proporcionó ninguna estructura XrSpatialImageSizeEXT como parte de ninguna de las cadenas siguientes aplicables.

Para que el entorno de ejecución pueda generar tamaños de imágenes de forma automática y precisa, es posible que se requieran ciertas capacidades del dispositivo y requisitos previos, como cámaras estéreo y parámetros extrínsecos e intrínsecos de la cámara calibrados con precisión.

Si xrEnumerateSpatialCapabilityFeaturesEXT no enumera XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT, la aplicación debe vincular las estructuras XrSpatialImageSizeEXT a las siguientes cadenas aplicables de modo que todas las imágenes tengan un tamaño explícito proporcionado para ellas; de lo contrario, el entorno de ejecución debe devolver XR_ERROR_SPATIAL_IMAGE_SIZE_MISSING_EXT desde xrCreateSpatialImageTrackingDatabaseAsyncEXT .

Uso válido (implícito)

La estructura XrSpatialCapabilityConfigurationImageTrackingEXT se define de la siguiente manera:

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

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.
  • capability es un XrSpatialCapabilityEXT y debe ser XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT .
  • enabledComponentCount es un uint32_t que especifica la cantidad de elementos en enabledComponents .
  • enabledComponents es un array de XrSpatialComponentTypeEXT que especifica los componentes que se habilitarán para esta capacidad.
  • imageTrackingDatabaseCount es un unint32_t que especifica la cantidad de elementos en imageTrackingDatabases .
  • imageTrackingDatabases es un array de controladores XrSpatialImageTrackingDatabaseEXT que especifica las bases de datos de seguimiento de imágenes que se habilitarán para el contexto espacial.

Si se admite el seguimiento de imágenes, el entorno de ejecución debe habilitarlo si se pasa una estructura XrSpatialCapabilityConfigurationImageTrackingEXT en XrSpatialContextCreateInfoEXT :: capabilityConfigs cuando se llama a xrCreateSpatialContextAsyncEXT .

La estructura XrSpatialCapabilityConfigurationImageTrackingEXT permite que la aplicación descubra las imágenes de referencia representadas por los controladores XrSpatialImageTrackingDatabaseEXT en imageTrackingDatabases .

El entorno de ejecución debe devolver XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT si xrEnumerateSpatialCapabilitiesEXT no enumera XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT.

Uso válido (implícito)

Imagen de referencia espacial

La estructura XrSpatialReferenceImagePlaneEXT se define de la siguiente manera:

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

Descripciones de los parámetros

  • bufferSize es el tamaño del array buffer.
  • buffer es un array de datos uint8_t que representa los datos del plano.
  • rowStride es la distancia en bytes entre dos posiciones iniciales de filas de datos de píxeles consecutivas.
  • pixelStride es la distancia en bytes entre dos píxeles consecutivos.

El entorno de ejecución debe acceder a buffer según los patrones que proporcionan los parámetros rowStride y pixelStride.

La aplicación debe establecer rowStride y pixelStride de modo que el entorno de ejecución solo extraiga los píxeles significativos de este XrSpatialReferenceImagePlaneEXT.

Uso válido (implícito)

  • La extensión XR_EXT_spatial_image_tracking debe estar habilitada antes de usar XrSpatialReferenceImagePlaneEXT.
  • buffer debe ser un puntero a un array de valores bufferSize uint8_t
  • El parámetro bufferSize debe ser mayor que 0.

La estructura XrSpatialReferenceImageEXT se define de la siguiente manera:

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

Descripciones de los parámetros

  • type es el XrStructureType de esta estructura.
  • next es NULL o un puntero a la siguiente estructura en una cadena de estructuras.
  • width es el ancho en píxeles de la imagen de referencia.
  • height es la altura en píxeles de la imagen de referencia.
  • format es un XrSpatialReferenceImageFormatEXT que representa el formato de la imagen.
  • planeCount es la cantidad de elementos en el array planes.
  • planes es un array de estructuras XrSpatialReferenceImagePlaneEXT que representan los planos de los datos de la imagen.

La aplicación puede crear una o más estructuras XrSpatialReferenceImageEXT, cada una de las cuales representa una sola imagen de referencia de entrada que se pasará a la función xrCreateSpatialImageTrackingDatabaseAsyncEXT a través de XrSpatialImageTrackingDatabaseCreateInfoEXT :: spatialReferenceImages cuando se cree un controlador XrSpatialImageTrackingDatabaseEXT.

La aplicación debe proporcionar los datos de XrSpatialReferenceImagePlaneEXT :: buffer en un orden de píxeles de izquierda a derecha y de arriba abajo.

La aplicación debe proporcionar una estructura XrSpatialReferenceImagePlaneEXT en el array XrSpatialReferenceImageEXT :: planes para cada canal de color de XrSpatialReferenceImageEXT :: format .

Uso válido (implícito)

Componentes garantizados

Un entorno de ejecución que admita XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT debe proporcionar los siguientes componentes espaciales como componentes garantizados de todas las entidades descubiertas por esas capacidades y debe enumerarlos en xrEnumerateSpatialCapabilityComponentTypesEXT :

  • XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT
  • XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT

Componente de imagen 2D

Struct de lista de componentes para consultar datos

La estructura XrSpatialComponentImage2DListEXT se define de la siguiente manera:

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

Descripciones de los parámetros

  • type es el XrStructureType de esta estructura.
  • next es NULL o un puntero a la siguiente estructura en una cadena de estructuras.
  • imageCount es la cantidad de elementos en el array images.
  • images es un array de XrSpatialImage2DDataEXT .

El entorno de ejecución debe devolver XR_ERROR_VALIDATION_FAILURE de xrQuerySpatialComponentDataEXT si XrSpatialComponentImage2DListEXT está en la cadena XrSpatialComponentDataQueryResultEXT :: next, pero XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT no se incluye en XrSpatialComponentDataQueryConditionEXT :: componentTypes .

El entorno de ejecución debe devolver XR_ERROR_SIZE_INSUFFICIENT de xrQuerySpatialComponentDataEXT si imageCount es menor que XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .

Uso válido (implícito)

Datos de componentes

La estructura XrSpatialImage2DDataEXT se define de la siguiente manera:

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

Descripciones de los parámetros

La aplicación puede usar imageTrackingDatabase para identificar qué XrSpatialImageTrackingDatabaseEXT creado anteriormente contiene la imagen de referencia de esta estructura XrSpatialImage2DDataEXT. Para ese XrSpatialImageTrackingDatabaseEXT , la aplicación puede usar referenceImageIndex para identificar el XrSpatialReferenceImageEXT de esta estructura XrSpatialImage2DDataEXT haciéndolo coincidir con el orden de entrada del array XrSpatialImageTrackingDatabaseCreateInfoEXT :: spatialReferenceImages.

El conjunto de imágenes de referencia definido por el conjunto de todas las bases de datos activas no debería incluir imágenes duplicadas. Incluir imágenes duplicadas puede causar un comportamiento adverso de descubrimiento o seguimiento, es decir, que se devuelvan índices incoherentes o múltiples.

Uso válido (implícito)

Configuración

Si XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT se enumera en XrSpatialCapabilityComponentTypesEXT :: componentTypes para alguna capacidad, la aplicación puede habilitarla incluyendo el valor de enumeración en la lista XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents. Este componente no requiere ninguna configuración especial para incluirse en la siguiente cadena de XrSpatialCapabilityConfigurationBaseHeaderEXT .

Componente 2D delimitado

El componente 2D delimitado proporciona el centro y las extensiones de la imagen espacial representada por la entidad en la que se encuentra. Consulta Bounded 2D para obtener más detalles sobre el componente Bounded 2D.

Código de ejemplo

Descubre imágenes espaciales y consulta datos de componentes

En el siguiente ejemplo de código, se muestra cómo descubrir entidades espaciales para la función de seguimiento de imágenes y consultar los datos de sus componentes.

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

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

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

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

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

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

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

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

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

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

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

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

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

  // interleaved RGBA buffer memory layout and buffer positions

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

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

  XrSpatialReferenceImagePlaneEXT spatialReferenceImagePlanes[4];

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

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

  referenceImageIdentifiers.emplace_back("MyReferenceImage");

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

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

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

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

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

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

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

  waitUntilReady(createImageTrackingDatabaseFuture);

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

  imageTrackingDatabase = imageTrackingCompletion.database;
}

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

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

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

  XrSpatialContextCreateInfoEXT spatialContextCreateInfo{XR_TYPE_SPATIAL_CONTEXT_CREATE_INFO_EXT};
  spatialContextCreateInfo.capabilityConfigCount = capabilityConfigs.size();
  spatialContextCreateInfo.capabilityConfigs = capabilityConfigs.data();

  XrFutureEXT createContextFuture = XR_NULL_FUTURE_EXT;
  CHK_XR(xrCreateSpatialContextAsyncEXT(session, &spatialContextCreateInfo, &createContextFuture));

  waitUntilReady(createContextFuture);

  XrCreateSpatialContextCompletionEXT completion{XR_TYPE_CREATE_SPATIAL_CONTEXT_COMPLETION_EXT};
  CHK_XR(xrCreateSpatialContextCompleteEXT(session, createContextFuture, &completion));
  if (completion.futureResult != XR_SUCCESS) {
    // Error, spatial context creation failed
  }

  spatialContext = completion.spatialContext;
}

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

  XrSpatialDiscoverySnapshotCreateInfoEXT snapshotCreateInfo{XR_TYPE_SPATIAL_DISCOVERY_SNAPSHOT_CREATE_INFO_EXT};
  snapshotCreateInfo.componentTypeCount = snapshotComponents.size();
  snapshotCreateInfo.componentTypes = snapshotComponents.data();
  XrFutureEXT discoveryFuture = XR_NULL_FUTURE_EXT;
  CHK_XR(xrCreateSpatialDiscoverySnapshotAsyncEXT(spatialContext, &snapshotCreateInfo, &discoveryFuture));

  waitUntilReady(discoveryFuture);

  XrCreateSpatialDiscoverySnapshotCompletionInfoEXT completionInfo{XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_INFO_EXT};
  completionInfo.baseSpace = localSpace;
  completionInfo.time = time;
  completionInfo.future = discoveryFuture;

  XrCreateSpatialDiscoverySnapshotCompletionEXT completion{XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_EXT};
  CHK_XR(xrCreateSpatialDiscoverySnapshotCompleteEXT(spatialContext, &completionInfo, &completion));
  if (completion.futureResult == XR_SUCCESS) {
    // Query for the bounded2d component data
    XrSpatialComponentTypeEXT componentsToQuery[] = {XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT, XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT};
    XrSpatialComponentDataQueryConditionEXT queryCond{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT};
    queryCond.componentTypes = componentsToQuery;

    XrSpatialComponentDataQueryResultEXT queryResult{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_RESULT_EXT};
    CHK_XR(xrQuerySpatialComponentDataEXT(completion.snapshot, &queryCond, &queryResult));

    std::vector<XrSpatialEntityIdEXT> entityIds(queryResult.entityIdCountOutput);
    std::vector<XrSpatialEntityTrackingStateEXT> entityStates(queryResult.entityStateCountOutput);
    queryResult.entityIdCapacityInput = entityIds.size();
    queryResult.entityIds = entityIds.data();
    queryResult.entityStateCapacityInput = entityStates.size();
    queryResult.entityStates = entityStates.data();

    std::vector<XrSpatialBounded2DDataEXT> bounded2d(queryResult.entityIdCountOutput);
    XrSpatialComponentBounded2DListEXT boundsList{XR_TYPE_SPATIAL_COMPONENT_BOUNDED_2D_LIST_EXT};
    boundsList.boundCount = bounded2d.size();
    boundsList.bounds = bounded2d.data();
    queryResult.next = &boundsList;

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

    CHK_XR(xrQuerySpatialComponentDataEXT(completion.snapshot, &queryCond, &queryResult));

    for (int32_t i = 0; i < queryResult.entityIdCountOutput; ++i) {
      if (entityStates[i] == XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT) {
        const XrSpatialImage2DDataEXT& currentImage2d = image2d[i];
        const std::string& currentReferenceImageIdentifier = referenceImageIdentifiers[currentImage2d.referenceImageIndex];
        std::cout << currentReferenceImageIdentifier << std::endl; // Outputs the "MyReferenceImage" string the app defined previously; could be any other assocatied data or action.

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

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

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

  XrFrameState frameState;  // Previously returned from xrWaitFrame
  const XrTime time = frameState.predictedDisplayTime;

  // Poll for the XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT event
  XrEventDataBuffer event = {XR_TYPE_EVENT_DATA_BUFFER};
  XrResult result = xrPollEvent(instance, &event);
  if (result == XR_SUCCESS) {
      switch (event.type) {
          case XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT: {
              const XrEventDataSpatialDiscoveryRecommendedEXT& eventdata = *reinterpret_cast<XrEventDataSpatialDiscoveryRecommendedEXT*>(&event);
              // Discover spatial entities for the context that we received the "discovery
              // recommended" event for
              discoverSpatialEntities(eventdata.spatialContext, time);
              break;
          }
      }
  }

  // Finish frame loop
}

CHK_XR(xrDestroySpatialContextEXT(spatialContext));

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

Nuevos tipos de objetos

Comandos nuevos

Estructuras nuevas

Enums nuevas

Nuevas constantes de enum

  • XR_EXT_SPATIAL_IMAGE_TRACKING_EXTENSION_NAME
  • XR_EXT_spatial_image_tracking_SPEC_VERSION

  • Extiende XrObjectType :

    • XR_OBJECT_TYPE_SPATIAL_IMAGE_TRACKING_DATABASE_EXT

  • Extiende XrResult :

    • XR_ERROR_SPATIAL_IMAGE_FORMAT_UNSUPPORTED_EXT
    • XR_ERROR_SPATIAL_IMAGE_INVALID_EXT
    • XR_ERROR_SPATIAL_IMAGE_SIZE_MISSING_EXT

  • Extiende XrSpatialCapabilityEXT :

    • XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT

  • Extensión de XrSpatialCapabilityFeatureEXT :

    • XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT
    • XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXT
    • XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT

  • Extiende XrSpatialComponentTypeEXT :

    • XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT

  • Extiende XrStructureType :

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

Problemas

Historial de versiones

  • Revisión 1, 22 de abril de 2025 (Daniel Guttenberg, Qualcomm)

    • Descripción inicial de la extensión