XR_ANDROID_spatial_annotation_tracking
Cadena de nombre
XR_ANDROID_spatial_annotation_tracking
Tipo de extensión
Extensión de la instancia
Número de extensión registrado
795
Revisión
1
Estado de ratificación
No se ratificó
Dependencias de extensiones y versiones
XR_EXT_spatial_entity
y
XR_EXT_spatial_image_tracking
Fecha de la última modificación
2026-01-12
Estado de la IP
No hay reclamos conocidos por IP.
Colaboradores
Levana Chen, Google
Christopher Feil, Google
Martin Sundermeyer, Google
David Joseph Tan, Google
Jared Finder, Google
Nihav Jain, Google
Descripción general
Esta extensión proporciona la capacidad de seguimiento de anotaciones para la extensión XR_EXT_spatial_entity para hacer un seguimiento de varias anotaciones en la escena. Permite que las aplicaciones superpongan objetos físicos o virtuales definidos por referencias de tiempo de ejecución.
Esta extensión proporciona un tipo de anotación básica "Cuadrado", que es un polígono que tiene exactamente 4 lados, es decir, un cuadrilátero convexo, que representa un cuadro delimitador 2D generalizado dentro de una referencia de tiempo de ejecución. Una anotación de cuadrilátero rastreado se representa como una entidad espacial con los siguientes componentes:
XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID
Por lo general, las aplicaciones pueden usar la extensión de seguimiento de anotaciones espaciales con los siguientes patrones:
- Primero, una aplicación crea un identificador de XrSpatialReferenceCacheANDROID, que comienza a registrar referencias de tiempo de ejecución desde la fuente determinada.
- Luego, la aplicación captura una referencia de tiempo de ejecución de XrSpatialReferenceImageEXT y define una anotación deseada dentro de la referencia durante el período de la caché de referencia.
- Luego, la aplicación crea un identificador XrSpatialContextEXT basado en el XrSpatialReferenceImageEXT proporcionado por XrSpatialCapabilityConfigurationAnnotationTrackingANDROID .
- La aplicación puede destruir el controlador XrSpatialReferenceCacheANDROID para detener el registro de referencias de tiempo de ejecución y reducir el uso de memoria, o bien esperar el evento
XR_TYPE_EVENT_DATA_SPATIAL_ANNOTATION_TRACKING_ANDROIDpara confirmar el resultado de la inicialización. - Luego, la aplicación extrae el evento
XR_TYPE_EVENT_DATA_SPATIAL_ANNOTATION_TRACKING_ANDROIDpara confirmar el resultado de la inicialización de la anotación. - Si la inicialización se realiza correctamente, la aplicación puede extraer el evento
XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXTpara hacer un seguimiento de la anotación. - Si falla la inicialización, la aplicación puede usar el código de error que se devolvió en el evento para determinar el motivo de la falla y destruir el identificador XrSpatialContextEXT existente para iniciar una nueva anotación.
- Independientemente del resultado de la inicialización, la aplicación puede liberar el búfer de imágenes para reducir el uso de memoria después de recibir el evento.
- La aplicación descubre y consulta las anotaciones según los patrones de acceso a entidades espaciales.
- La aplicación puede crear un identificador XrSpatialContextEXT adicional para hacer un seguimiento de las anotaciones dentro de una nueva referencia durante el período de un XrSpatialReferenceCacheANDROID válido .
- La aplicación puede destruir los identificadores de XrSpatialContextEXT para reducir el conjunto de anotaciones detectables y rastreables de forma dinámica durante el tiempo de ejecución.
Asistencia del entorno de ejecución
Un tiempo de ejecución debe anunciar su compatibilidad con la capacidad de seguimiento de anotaciones a través de xrEnumerateSpatialCapabilitiesEXT enumerando la siguiente capacidad:
XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID
Cuando el entorno de ejecución admite la capacidad de seguimiento de anotaciones, ocurre lo siguiente:
- Debe admitir al menos un componente de anotación, para lo cual debe enumerar los componentes de anotación admitidos a través de xrEnumerateSpatialCapabilityComponentTypesEXT .
- Debe admitir al menos uno de los formatos XrSpatialReferenceImageFormatEXT. Para ello , debe enumerar los formatos de referencia admitidos a través de xrEnumerateSpatialReferenceImageFormatsEXT con el parámetro
capabilityestablecido enXR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID. - Debe admitir al menos uno de los XrSpatialAnnotationReferenceSourceANDROID , enumerando las fuentes de referencia admitidas a través de xrEnumerateSpatialAnnotationReferenceSourcesANDROID con
capabilityestablecido enXR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID.
La función xrEnumerateSpatialAnnotationReferenceSourcesANDROID se define de la siguiente manera:
XrResult xrEnumerateSpatialAnnotationReferenceSourcesANDROID(
XrInstance instance,
XrSystemId systemId,
XrSpatialCapabilityEXT capability,
uint32_t sourceCapacityInput,
uint32_t* sourceCountOutput,
XrSpatialAnnotationReferenceSourceANDROID* sources);
Descripciones de los parámetros
instancees un identificador para un XrInstance .systemIdes elXrSystemIdcuyos orígenes de referencia se enumerarán.capabilityes el XrSpatialCapabilityEXT para el que se enumerarán las fuentes de referencia.sourceCapacityInputes la capacidad del arraysourceso 0 para indicar una solicitud para recuperar la capacidad requerida.sourceCountOutputes la cantidad de fuentes o la capacidad requerida en el caso de quesourceCapacityInputsea insuficiente.sourceses un array de XrSpatialAnnotationReferenceSourceANDROID . Puede serNULLsisourceCapacityInputes 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
sourcesrequerido.
La aplicación puede enumerar la lista de fuentes de referencia admitidas por un XrSystemId determinado con xrEnumerateSpatialAnnotationReferenceSourcesANDROID .
El tiempo de ejecución no debe enumerar las fuentes de referencia cuya extensión no esté habilitada para instance .
Uso válido (implícito)
- La extensión
XR_ANDROID_spatial_annotation_trackingdebe habilitarse antes de llamar a xrEnumerateSpatialAnnotationReferenceSourcesANDROID. -
instancedebe ser un identificador de XrInstance válido -
capabilitydebe ser un valor XrSpatialCapabilityEXT válido. -
sourceCountOutputdebe ser un puntero a un valoruint32_t. - Si
sourceCapacityInputno es0,sourcesdebe ser un puntero a un array de valoressourceCapacityInputXrSpatialAnnotationReferenceSourceANDROID.
Códigos de retorno
XR_SUCCESS
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_RUNTIME_FAILUREXR_ERROR_SIZE_INSUFFICIENTXR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXTXR_ERROR_SYSTEM_INVALIDXR_ERROR_VALIDATION_FAILURE
typedef enum XrSpatialAnnotationReferenceSourceANDROID {
XR_SPATIAL_ANNOTATION_REFERENCE_SOURCE_CAMERA_ANDROID = 0,
XR_SPATIAL_ANNOTATION_REFERENCE_SOURCE_MEDIA_PROJECTION_ANDROID = 1,
XR_SPATIAL_ANNOTATION_REFERENCE_SOURCE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSpatialAnnotationReferenceSourceANDROID;
La enumeración XrSpatialAnnotationReferenceSourceANDROID describe la fuente de la referencia que proporciona los metadatos de una anotación.
Los enums tienen los siguientes significados:
Descripción de la enumeración
XR_SPATIAL_ANNOTATION_REFERENCE_SOURCE_CAMERA_ANDROID
La imagen de referencia es una imagen sin recortar que se genera a partir de una API de cámara de Android, p.ej., una imagen de un ImageReader asociado a un CameraDevice de Camera2 o un ImageProxy de un ImageAnalysis asociado a CameraX. Por lo general, es una de las cámaras RGB que apuntan hacia adelante.
XR_SPATIAL_ANNOTATION_REFERENCE_SOURCE_MEDIA_PROJECTION_ANDROID
La imagen de referencia es una imagen sin recortar que se genera a partir de la API de MediaProjection de Android, p.ej., una imagen de un ImageReader asociado a una pantalla virtual de MediaProjection. Puede incluir contenido virtual y real.
La estructura XrSystemSpatialAnnotationPropertiesANDROID se define de la siguiente manera:
typedef struct XrSystemSpatialAnnotationPropertiesANDROID {
XrStructureType type;
void* next;
uint32_t referenceCacheTimespan;
uint32_t maxReferencePixelWidth;
uint32_t maxReferencePixelHeight;
uint32_t maxReferenceCount;
uint32_t maxAnnotationCount;
} XrSystemSpatialAnnotationPropertiesANDROID;
Descripciones de los miembros
typees el XrStructureType de esta estructura.nextesNULLo un puntero a la siguiente estructura en una cadena de estructuras.referenceCacheTimespanindica el período en segundos de un identificador XrSpatialReferenceCacheANDROID válido.maxReferencePixelWidthindica el ancho máximo del borde de las imágenes de referencia en píxeles.maxReferencePixelHeightindica la altura máxima del borde de las imágenes de referencia en píxeles.maxReferenceCountindica la cantidad máxima de imágenes de referencia que se pueden asignar al mismo tiempo.maxAnnotationCountindica la cantidad máxima de anotaciones que se pueden hacer un seguimiento al mismo tiempo.
Cuando el tiempo de ejecución admite la capacidad de seguimiento de anotaciones, una aplicación puede inspeccionar las propiedades del sistema pertinentes encadenando una estructura XrSystemSpatialAnnotationPropertiesANDROID a XrSystemProperties cuando se llama a xrGetSystemProperties .
Si XrSpatialReferenceImageEXT :: width de XrSpatialCapabilityConfigurationAnnotationTrackingANDROID :: reference supera maxReferencePixelWidth , el tiempo de ejecución debe devolver XR_ERROR_VALIDATION_FAILURE cuando se llame a xrCreateSpatialContextAsyncEXT .
Si XrSpatialReferenceImageEXT :: height de XrSpatialCapabilityConfigurationAnnotationTrackingANDROID :: reference supera maxReferencePixelHeight , el tiempo de ejecución debe devolver XR_ERROR_VALIDATION_FAILURE cuando se llame a xrCreateSpatialContextAsyncEXT .
Si XrSpatialCapabilityConfigurationAnnotationTrackingANDROID :: time está fuera del período de XrSpatialReferenceCacheANDROID :: cache , el tiempo de ejecución debe devolver XR_ERROR_TIME_INVALID cuando se llame a xrCreateSpatialContextAsyncEXT . La aplicación puede recrear el identificador de XrSpatialContextEXT con una nueva referencia durante el período de XrSpatialReferenceCacheANDROID .
Si la cantidad de imágenes de referencia asignadas supera maxReferenceCount , el tiempo de ejecución debe devolver XR_ERROR_LIMIT_REACHED y mostrar la falla de inicialización a través de XrEventDataSpatialAnnotationTrackingANDROID :: initializationResult . La aplicación puede destruir el identificador XrSpatialContextEXT y volver a intentarlo después de que se complete la inicialización pendiente.
Si la cantidad de anotaciones activas supera maxAnnotationCount , el tiempo de ejecución debe devolver XR_ERROR_VALIDATION_FAILURE cuando se llame a xrCreateSpatialContextAsyncEXT .
Uso válido (implícito)
- La extensión
XR_ANDROID_spatial_annotation_trackingdebe habilitarse antes de usar XrSystemSpatialAnnotationPropertiesANDROID -
typedebe serXR_TYPE_SYSTEM_SPATIAL_ANNOTATION_PROPERTIES_ANDROID -
nextdebe serNULLo un puntero válido a la siguiente estructura en una cadena de estructuras
Caché de referencia del tiempo de ejecución
XR_DEFINE_HANDLE(XrSpatialReferenceCacheANDROID)
El identificador de XrSpatialReferenceCacheANDROID representa una caché de referencias de tiempo de ejecución registradas desde una fuente determinada.
La función xrCreateSpatialReferenceCacheAsyncANDROID se define de la siguiente manera:
XrResult xrCreateSpatialReferenceCacheAsyncANDROID(
XrSession session,
const XrSpatialReferenceCacheCreateInfoANDROID* createInfo,
XrFutureEXT* future);
Descripciones de los parámetros
sessiones un XrSession en el que la caché de referencia estará activa.createInfoes un puntero a un XrSpatialReferenceCacheCreateInfoANDROID que se usa para especificar los parámetros de la caché de referencia.futurees un puntero al identificador de salida de unXrFutureEXT.
La aplicación puede crear un identificador XrSpatialReferenceCacheANDROID llamando a xrCreateSpatialReferenceCacheAsyncANDROID . El tiempo de ejecución puede tardar un poco en inicializar los servicios de seguimiento. Luego, la aplicación puede llamar a xrCreateSpatialReferenceCacheCompleteANDROID de forma repetida para verificar la finalización de esta operación asíncrona.
El tiempo de ejecución debe devolver XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT si XrSpatialReferenceCacheCreateInfoANDROID :: capability no aparece en la lista de xrEnumerateSpatialCapabilitiesEXT .
El tiempo de ejecución debe devolver XR_ERROR_FEATURE_UNSUPPORTED si XrSpatialReferenceCacheCreateInfoANDROID :: source no aparece en la lista de xrEnumerateSpatialAnnotationReferenceSourcesANDROID para la capacidad determinada.
La aplicación solo puede crear un identificador por fuente para una capacidad determinada. De lo contrario, el tiempo de ejecución debe devolver XR_ERROR_LIMIT_REACHED .
Luego, la aplicación puede capturar referencias de tiempo de ejecución durante el período del identificador XrSpatialReferenceCacheANDROID para configurar un nuevo identificador XrSpatialContextEXT.
Uso válido (implícito)
- La extensión
XR_ANDROID_spatial_annotation_trackingdebe habilitarse antes de llamar a xrCreateSpatialReferenceCacheAsyncANDROID. -
sessiondebe ser un identificador de XrSession válido -
createInfodebe ser un puntero a una estructura XrSpatialReferenceCacheCreateInfoANDROID 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_INSTANCE_LOSTXR_ERROR_LIMIT_REACHEDXR_ERROR_OUT_OF_MEMORYXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXTXR_ERROR_VALIDATION_FAILURE
La estructura XrSpatialReferenceCacheCreateInfoANDROID se define de la siguiente manera:
typedef struct XrSpatialReferenceCacheCreateInfoANDROID {
XrStructureType type;
const void* next;
XrSpatialCapabilityEXT capability;
XrSpatialAnnotationReferenceSourceANDROID source;
} XrSpatialReferenceCacheCreateInfoANDROID;
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.capabilityes un XrSpatialCapabilityEXT que describe para qué capacidad se crea la caché de referencia.sourcees un XrSpatialAnnotationReferenceSourceANDROID que describe la fuente de la caché de referencia.
La estructura XrSpatialReferenceCacheCreateInfoANDROID describe la información para crear un identificador XrSpatialReferenceCacheANDROID.
Uso válido (implícito)
- La extensión
XR_ANDROID_spatial_annotation_trackingdebe habilitarse antes de usar XrSpatialReferenceCacheCreateInfoANDROID -
typedebe serXR_TYPE_SPATIAL_REFERENCE_CACHE_CREATE_INFO_ANDROID -
nextdebe serNULLo un puntero válido a la siguiente estructura en una cadena de estructuras -
capabilitydebe ser un valor XrSpatialCapabilityEXT válido. -
sourcedebe ser un valor de XrSpatialAnnotationReferenceSourceANDROID válido
La función xrCreateSpatialReferenceCacheCompleteANDROID se define de la siguiente manera:
XrResult xrCreateSpatialReferenceCacheCompleteANDROID(
XrSession session,
XrFutureEXT future,
XrCreateSpatialReferenceCacheCompletionANDROID* completion);
Descripciones de los parámetros
sessiones el XrSession que se pasó anteriormente a xrCreateSpatialReferenceCacheAsyncANDROID ::session.futurees elXrFutureEXTque se recibió de xrCreateSpatialReferenceCacheAsyncANDROID ::future.completiones un puntero a un XrCreateSpatialReferenceCacheCompletionANDROID .
La aplicación puede llamar a xrCreateSpatialReferenceCacheCompleteANDROID para esperar a que se complete la operación asíncrona iniciada por xrCreateSpatialReferenceCacheAsyncANDROID .
El tiempo de ejecución debe devolver XR_ERROR_FUTURE_PENDING_EXT si future no está en estado listo. El tiempo de ejecución debe devolver XR_ERROR_FUTURE_INVALID_EXT si future ya se completó o canceló.
Uso válido (implícito)
- La extensión
XR_ANDROID_spatial_annotation_trackingdebe habilitarse antes de llamar a xrCreateSpatialReferenceCacheCompleteANDROID. -
sessiondebe ser un identificador de XrSession válido -
completiondebe ser un puntero a una estructura XrCreateSpatialReferenceCacheCompletionANDROID.
Códigos de retorno
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FEATURE_UNSUPPORTEDXR_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 estructura XrCreateSpatialReferenceCacheCompletionANDROID se define de la siguiente manera:
typedef struct XrCreateSpatialReferenceCacheCompletionANDROID {
XrStructureType type;
void* next;
XrResult futureResult;
XrSpatialReferenceCacheANDROID referenceCache;
} XrCreateSpatialReferenceCacheCompletionANDROID;
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 de creación de la caché de referencia.referenceCachees el identificador de XrSpatialReferenceCacheANDROID si la operación se realiza correctamente.
Códigos de devolución futuros
Valores de futureResult:
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FEATURE_UNSUPPORTEDXR_ERROR_RUNTIME_FAILUREXR_ERROR_INSTANCE_LOSTXR_ERROR_SESSION_LOSTXR_ERROR_OUT_OF_MEMORYXR_ERROR_LIMIT_REACHED
Si futureResult es un código de éxito, el tiempo de ejecución debe devolver un identificador referenceCache válido. Si referenceCache es válido, lo seguirá siendo solo durante la vida útil de xrCreateSpatialReferenceCacheAsyncANDROID :: session o hasta que la aplicación destruya el identificador con xrDestroySpatialReferenceCacheANDROID, lo que suceda primero.
Cuando referenceCache es válido, registra las cachés dentro de XrSystemSpatialAnnotationPropertiesANDROID :: referenceCacheTimespan .
Uso válido (implícito)
- La extensión
XR_ANDROID_spatial_annotation_trackingdebe habilitarse antes de usar XrCreateSpatialReferenceCacheCompletionANDROID -
typedebe serXR_TYPE_CREATE_SPATIAL_REFERENCE_CACHE_COMPLETION_ANDROID -
nextdebe serNULLo un puntero válido a la siguiente estructura en una cadena de estructuras -
futureResultdebe ser un valor XrResult válido -
referenceCachedebe ser un identificador de XrSpatialReferenceCacheANDROID válido
La función xrDestroySpatialReferenceCacheANDROID se define de la siguiente manera:
XrResult xrDestroySpatialReferenceCacheANDROID(
XrSpatialReferenceCacheANDROID cacheHandle);
Descripciones de los parámetros
cacheHandlees un XrSpatialReferenceCacheANDROID creado anteriormente por xrCreateSpatialReferenceCacheAsyncANDROID .
La aplicación puede llamar a la función xrDestroySpatialReferenceCacheANDROID para liberar el identificador cacheHandle y los recursos subyacentes cuando finalice la creación del contexto espacial.
Uso válido (implícito)
- La extensión
XR_ANDROID_spatial_annotation_trackingdebe habilitarse antes de llamar a xrDestroySpatialReferenceCacheANDROID. -
cacheHandledebe ser un identificador de XrSpatialReferenceCacheANDROID válido
Seguridad de subprocesos
- El acceso a
cacheHandley a cualquier identificador secundario debe sincronizarse de forma externa.
Códigos de retorno
XR_SUCCESS
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALID
Configuración
La estructura XrSpatialCapabilityConfigurationAnnotationTrackingANDROID se define de la siguiente manera:
typedef struct XrSpatialCapabilityConfigurationAnnotationTrackingANDROID {
XrStructureType type;
const void* next;
XrSpatialCapabilityEXT capability;
uint32_t enabledComponentCount;
const XrSpatialComponentTypeEXT* enabledComponents;
XrSpatialReferenceCacheANDROID cache;
XrTime time;
XrSpatialReferenceImageEXT reference;
} XrSpatialCapabilityConfigurationAnnotationTrackingANDROID;
Descripciones de los miembros
typees el XrStructureType de esta estructura.nextesNULLo un puntero a la siguiente estructura en una cadena de estructuras.capabilityes un XrSpatialCapabilityEXT y debe serXR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID.enabledComponentCountes unuint32_tque describe el recuento de elementos en el arrayenabledComponents.enabledComponentses un puntero a un array de XrSpatialComponentTypeEXT .cachees un XrSpatialReferenceCacheANDROID creado previamente para registrar referencias de tiempo de ejecución para la configuración dereference.timees elXrTimeen el que se captura elreference.referencees un XrSpatialReferenceImageEXT con anotaciones encadenadas a su siguiente puntero.
Las aplicaciones pueden habilitar la capacidad espacial XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID agregando un puntero a la estructura XrSpatialCapabilityConfigurationAnnotationTrackingANDROID en XrSpatialContextCreateInfoEXT :: capabilityConfigs .
El tiempo de ejecución debe devolver XR_ERROR_VALIDATION_FAILURE si capability no es XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID .
El tiempo de ejecución debe devolver XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT si reference no contiene anotaciones.
El tiempo de ejecución debe devolver XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT si el componente de anotación aparece en enabledComponents, pero no hay anotaciones correspondientes asociadas con reference .
El tiempo de ejecución debe devolver XR_ERROR_VALIDATION_FAILURE si cache no pertenece a la misma XrSession que se pasa a xrCreateSpatialContextAsyncEXT .
El tiempo de ejecución debe devolver XR_ERROR_TIME_INVALID si time está fuera del período de cache .
Uso válido (implícito)
- La extensión
XR_ANDROID_spatial_annotation_trackingdebe habilitarse antes de usar XrSpatialCapabilityConfigurationAnnotationTrackingANDROID -
typedebe serXR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_ANNOTATION_TRACKING_ANDROID -
nextdebe serNULLo un puntero válido a la siguiente estructura en una cadena de estructuras -
capabilitydebe ser un valor XrSpatialCapabilityEXT válido. -
enabledComponentsdebe ser un puntero a un array de valores XrSpatialComponentTypeEXT válidos deenabledComponentCount. -
cachedebe ser un identificador de XrSpatialReferenceCacheANDROID válido -
referencedebe ser una estructura XrSpatialReferenceImageEXT válida. - El parámetro
enabledComponentCountdebe ser mayor que0.
Eventos de seguimiento de anotaciones
La estructura XrEventDataSpatialAnnotationTrackingANDROID se define de la siguiente manera:
typedef struct XrEventDataSpatialAnnotationTrackingANDROID {
XrStructureType type;
const void* next;
XrSpatialContextEXT spatialContext;
uint32_t annotationIndex;
XrResult initializationResult;
} XrEventDataSpatialAnnotationTrackingANDROID;
Descripciones de los miembros
typees el XrStructureType de esta estructura.nextesNULLo un puntero a la siguiente estructura en una cadena de estructuras.spatialContextes el XrSpatialContextEXT para el que se activó el seguimiento de anotaciones.annotationIndexse asigna al índice del array de anotaciones asociado con XrSpatialCapabilityConfigurationAnnotationTrackingANDROID ::reference.initializationResultindica el resultado de la inicialización de la anotación. Si no esXR_SUCCESS, la aplicación puede destruir y volver a crear el identificador XrSpatialContextEXT para reinicializar la anotación o seguir usandospatialContextpara hacer un seguimiento de otras anotaciones.
Uso válido (implícito)
- La extensión
XR_ANDROID_spatial_annotation_trackingdebe habilitarse antes de usar XrEventDataSpatialAnnotationTrackingANDROID -
typedebe serXR_TYPE_EVENT_DATA_SPATIAL_ANNOTATION_TRACKING_ANDROID -
nextdebe serNULLo un puntero válido a la siguiente estructura en una cadena de estructuras
El tiempo de ejecución debe completar el XrEventDataSpatialAnnotationTrackingANDROID para cada anotación y, así, indicar que se completó su inicialización. Independientemente del resultado de la inicialización, la aplicación puede liberar el búfer de imagen para reducir el uso de memoria después de recibir el evento.
El tiempo de ejecución debe completar initializationResult con XR_SUCCESS si la anotación se inicializa correctamente. Luego, la aplicación puede extraer el evento XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT para hacer un seguimiento de la anotación.
De lo contrario, el tiempo de ejecución debe completar initializationResult con un código de error adecuado para indicar el motivo de la falla. La aplicación puede destruir el identificador XrSpatialContextEXT para iniciar una nueva anotación o seguir usando el spatialContext para hacer un seguimiento de otras anotaciones.
Anotación de Quad
Un tiempo de ejecución debe anunciar su compatibilidad con las anotaciones de cuaterniones a través de xrEnumerateSpatialCapabilityComponentTypesEXT enumerando el siguiente tipo de componente:
XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID
Referencia de Quad
La estructura XrSpatialAnnotationQuadReferenceANDROID se define de la siguiente manera:
typedef struct XrSpatialAnnotationQuadReferenceANDROID {
XrStructureType type;
const void* next;
uint32_t quadCount;
const XrSpatialAnnotationQuadANDROID* quads;
} XrSpatialAnnotationQuadReferenceANDROID;
Descripciones de los miembros
typees el XrStructureType de esta estructura.nextesNULLo un puntero a la siguiente estructura en una cadena de estructuras.quadCountes unuint32_tque describe el recuento de elementos en el arrayquads.quadses el puntero a un array de XrSpatialAnnotationQuadANDROID .
Cuando el tiempo de ejecución admite anotaciones de cuadriláteros, una aplicación puede configurar anotaciones encadenando una estructura XrSpatialAnnotationQuadReferenceANDROID a XrSpatialReferenceImageEXT :: next y establecer la referencia en XrSpatialCapabilityConfigurationAnnotationTrackingANDROID :: reference cuando se crea el identificador XrSpatialContextEXT.
El tiempo de ejecución debe devolver XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT desde xrCreateSpatialContextAsyncEXT si quadCount es 0.
Uso válido (implícito)
- La extensión
XR_ANDROID_spatial_annotation_trackingdebe habilitarse antes de usar XrSpatialAnnotationQuadReferenceANDROID -
typedebe serXR_TYPE_SPATIAL_ANNOTATION_QUAD_REFERENCE_ANDROID -
nextdebe serNULLo un puntero válido a la siguiente estructura en una cadena de estructuras -
quadsdebe ser un puntero a un array de estructuras XrSpatialAnnotationQuadANDROID válidas dequadCount - El parámetro
quadCountdebe ser mayor que0.
La estructura XrSpatialAnnotationQuadANDROID se define de la siguiente manera:
typedef struct XrSpatialAnnotationQuadANDROID {
XrSpatialAnnotationQuadAlignmentANDROID alignment;
XrVector2f upperLeft;
XrVector2f upperRight;
XrVector2f lowerRight;
XrVector2f lowerLeft;
} XrSpatialAnnotationQuadANDROID;
Descripciones de los miembros
alignmentes el XrSpatialAnnotationQuadAlignmentANDROID del cuadrilátero.upperLeftes un XrVector2f que describe la coordenada de la esquina superior izquierda del cuadrilátero en relación con el origen.upperRightes un XrVector2f que describe la coordenada de la esquina superior derecha del cuadrilátero relacionada con el origen.lowerRightes un XrVector2f que describe la coordenada de la esquina inferior derecha del cuadrilátero en relación con el origen.lowerLeftes un XrVector2f que describe la coordenada de la esquina inferior izquierda del cuadrilátero en relación con el origen.
Un cuadrilátero en un espacio 2D es un cuadrilátero convexo con orden en el sentido de las agujas del reloj. El valor de las 4 esquinas se relaciona con el origen (0, 0) con el que se asocia el cuadrilátero.
- Cuando se asocia con un XrSpatialReferenceImageEXT, el origen es la esquina superior izquierda de la imagen, donde X se asigna al píxel en el ancho y Y se asigna al píxel en la altura.
- Cuando se asocia con un XrSpatialAnnotationQuadDataANDROID , el origen se indica con XrSpaceLocationData ::
posede XrSpatialAnnotationQuadDataANDROID ::origin.
Uso válido (implícito)
- La extensión
XR_ANDROID_spatial_annotation_trackingdebe habilitarse antes de usar XrSpatialAnnotationQuadANDROID -
alignmentdebe ser un valor XrSpatialAnnotationQuadAlignmentANDROID válido
typedef enum XrSpatialAnnotationQuadAlignmentANDROID {
XR_SPATIAL_ANNOTATION_QUAD_ALIGNMENT_SCREEN_ANDROID = 0,
XR_SPATIAL_ANNOTATION_QUAD_ALIGNMENT_OBJECT_ANDROID = 1,
XR_SPATIAL_ANNOTATION_QUAD_ALIGNMENT_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSpatialAnnotationQuadAlignmentANDROID;
La enumeración XrSpatialAnnotationQuadAlignmentANDROID describe la alineación de la anotación de cuadrilátero.
Los enums tienen los siguientes significados:
Descripción de la enumeración
XR_SPATIAL_ANNOTATION_QUAD_ALIGNMENT_SCREEN_ANDROID
El cuadrilátero de anotación es paralelo al plano de la pantalla, mientras que su rotación en el plano permanece bloqueada a la gravedad mundial. El resultado aparece como un cuadro delimitador vertical normal.
XR_SPATIAL_ANNOTATION_QUAD_ALIGNMENT_OBJECT_ANDROID
El cuadrilátero de anotación se fija directamente al objeto, lo que coincide con la alineación definida en la imagen de referencia. El resultado es un cuadrilátero convexo que ajusta su forma para que coincida con la perspectiva del objeto.
Componentes de Quad
La estructura XrSpatialAnnotationQuadDataANDROID se define de la siguiente manera:
typedef struct XrSpatialAnnotationQuadDataANDROID {
uint32_t annotationIndex;
XrSpaceLocationData origin;
XrSpatialAnnotationQuadANDROID quad;
} XrSpatialAnnotationQuadDataANDROID;
Descripciones de los miembros
annotationIndexes el índice que asigna al array XrSpatialAnnotationQuadReferenceANDROID ::quadsasociado con la referencia que pasa XrSpatialCapabilityConfigurationAnnotationTrackingANDROID ::reference.origines un XrSpaceLocationData que describe el origen de un plano 2D en el que se basa el cuadrilátero. El tiempo de ejecución debe establecer XrSpaceLocationData ::locationFlagspara indicar los bits válidos de la postura de origen.quades un XrSpatialAnnotationQuadANDROID que representa el cuadrilátero en el espacio local. Usaoriginpara transformar el cuadrilátero en espacio de poses.
Uso válido (implícito)
- La extensión
XR_ANDROID_spatial_annotation_trackingdebe habilitarse antes de usar XrSpatialAnnotationQuadDataANDROID -
origindebe ser una estructura XrSpaceLocationData válida -
quaddebe ser una estructura XrSpatialAnnotationQuadANDROID válida
La estructura XrSpatialComponentAnnotationQuadListANDROID se define de la siguiente manera:
typedef struct XrSpatialComponentAnnotationQuadListANDROID {
XrStructureType type;
void* next;
uint32_t quadCount;
XrSpatialAnnotationQuadDataANDROID* quads;
} XrSpatialComponentAnnotationQuadListANDROID;
Descripciones de los miembros
typees el XrStructureType de esta estructura.nextesNULLo un puntero a la siguiente estructura en una cadena de estructuras.quadCountes unuint32_tque describe el recuento de elementos en el arrayquads.quadses un array de XrSpatialAnnotationQuadDataANDROID .
La aplicación puede consultar el componente de anotación de cuadrilátero de las entidades espaciales en un XrSpatialSnapshotEXT agregando XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID en XrSpatialComponentDataQueryConditionEXT :: componentTypes y agregando XrSpatialComponentAnnotationQuadListANDROID a la siguiente cadena de punteros de XrSpatialComponentDataQueryResultEXT .
El tiempo de ejecución debe devolver XR_ERROR_VALIDATION_FAILURE desde xrQuerySpatialComponentDataEXT si XrSpatialComponentAnnotationQuadListANDROID está en la siguiente cadena de XrSpatialComponentDataQueryResultEXT :: next, pero XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID no se incluye en XrSpatialComponentDataQueryConditionEXT :: componentTypes .
El tiempo de ejecución debe devolver XR_ERROR_SIZE_INSUFFICIENT de xrQuerySpatialComponentDataEXT si quadCount es menor que XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .
Uso válido (implícito)
- La extensión
XR_ANDROID_spatial_annotation_trackingdebe habilitarse antes de usar XrSpatialComponentAnnotationQuadListANDROID -
typedebe serXR_TYPE_SPATIAL_COMPONENT_ANNOTATION_QUAD_LIST_ANDROID -
nextdebe serNULLo un puntero válido a la siguiente estructura en una cadena de estructuras -
quadsdebe ser un puntero a un array de estructurasquadCountXrSpatialAnnotationQuadDataANDROID - El parámetro
quadCountdebe ser mayor que0.
Código de ejemplo
Verifica la compatibilidad con el tiempo de ejecución
En el siguiente ejemplo de código, se muestra cómo verificar si el tiempo de ejecución admite la capacidad de seguimiento de anotaciones.
XrInstance instance; // previously initialized
XrSystemId systemId; // previously initialized
XrSession session; // previously initialized
XrSpace localSpace; // previously initialized, e.g. from
// XR_REFERENCE_SPACE_TYPE_LOCAL
PFN_xrEnumerateSpatialCapabilitiesEXT xrEnumerateSpatialCapabilitiesEXT;
PFN_xrEnumerateSpatialAnnotationReferenceSourcesANDROID xrEnumerateSpatialAnnotationReferenceSourcesANDROID;
PFN_xrEnumerateSpatialReferenceImageFormatsEXT xrEnumerateSpatialReferenceImageFormatsEXT;
PFN_xrEnumerateSpatialCapabilityComponentTypesEXT xrEnumerateSpatialCapabilityComponentTypesEXT;
// Check spatial annotation tracking capability
uint32_t capabilityCount;
CHK_XR(xrEnumerateSpatialCapabilitiesEXT(instance, systemId, 0,
&capabilityCount, nullptr));
std::vector<XrSpatialCapabilityEXT> capabilities(capabilityCount);
CHK_XR(xrEnumerateSpatialCapabilitiesEXT(instance, systemId, capabilityCount,
&capabilityCount,
capabilities.data()));
if (std::find(capabilities.begin(), capabilities.end(),
XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID) ==
capabilities.end()) {
// System does not support spatial annotation tracking.
return;
}
// Inspect system properties for annotation tracking variables
XrSystemSpatialAnnotationPropertiesANDROID annotationSystemProperties{
XR_TYPE_SYSTEM_SPATIAL_ANNOTATION_PROPERTIES_ANDROID};
XrSystemProperties systemProperties{.type = XR_TYPE_SYSTEM_PROPERTIES,
.next = &annotationSystemProperties,
.systemId = systemId};
CHK_XR(xrGetSystemProperties(instance, systemId, &systemProperties));
if (annotationSystemProperties.maxAnnotationCount == 0) {
// System does not support any active annotations.
return;
}
// Enumerate supported reference sources
uint32_t sourceCountOutput = 0;
XrSpatialAnnotationReferenceSourceANDROID desiredSource =
XR_SPATIAL_ANNOTATION_REFERENCE_SOURCE_CAMERA_ANDROID;
CHK_XR(xrEnumerateSpatialAnnotationReferenceSourcesANDROID(
instance, systemId, XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID,
0, &sourceCountOutput, nullptr));
std::vector<XrSpatialAnnotationReferenceSourceANDROID> sources(sourceCountOutput);
CHK_XR(xrEnumerateSpatialAnnotationReferenceSourcesANDROID(
instance, systemId, XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID,
sourceCountOutput, &sourceCountOutput, sources.data()));
if (std::find(sources.begin(), sources.end(), desiredSource) == sources.end()) {
// The desired source is not supported.
return;
}
// Enumerate supported reference image formats, provided by XR_EXT_spatial_image_tracking.
uint32_t formatCountOutput = 0;
XrSpatialReferenceImageFormatEXT desiredFormat =
XR_SPATIAL_REFERENCE_IMAGE_FORMAT_YUV_420_888_EXT; // Or XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGBA_8888_EXT for screenshot.
CHK_XR(xrEnumerateSpatialReferenceImageFormatsEXT(
instance, systemId, XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID, 0,
&formatCountOutput, nullptr));
std::vector<XrSpatialReferenceImageFormatEXT> formats(formatCountOutput);
CHK_XR(xrEnumerateSpatialReferenceImageFormatsEXT(
instance, systemId, XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID,
formats.size(), &formatCountOutput, formats.data()));
if (std::find(formats.begin(), formats.end(), desiredFormat) == formats.end()) {
// The desired format is not supported
return;
}
// Enumerate supported components for annotation tracking capability.
XrSpatialCapabilityComponentTypesEXT capabilityComponentTypes{
XR_TYPE_SPATIAL_CAPABILITY_COMPONENT_TYPES_EXT};
CHK_XR(xrEnumerateSpatialCapabilityComponentTypesEXT(
instance, systemId, XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID,
&capabilityComponentTypes));
std::vector<XrSpatialComponentTypeEXT>
annotationTypes(capabilityComponentTypes.componentTypeCountOutput);
capabilityComponentTypes.componentTypeCapacityInput = annotationTypes.size();
capabilityComponentTypes.componentTypes = annotationTypes.data();
CHK_XR(xrEnumerateSpatialCapabilityComponentTypesEXT(
instance, systemId, XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID,
&capabilityComponentTypes));
// Check supported annotation components.
XrSpatialComponentTypeEXT desiredComponent =
XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID;
const auto supportedComponent = [&annotationTypes](
XrSpatialComponentTypeEXT component) {
return std::find(annotationTypes.begin(), annotationTypes.end(), component) !=
annotationTypes.end();
};
if (!supportedComponent(desiredComponent)) {
// The desired annotation is not supported.
return;
}
Configura la anotación de cuadrilátero
En el siguiente ejemplo de código, se muestra cómo configurar la anotación de cuadrilátero.
XrInstance instance; // previously initialized
XrSystemId systemId; // previously initialized
XrSession session; // previously initialized
XrSpace localSpace; // previously initialized, e.g. from
// XR_REFERENCE_SPACE_TYPE_LOCAL
PFN_xrCreateSpatialReferenceCacheAsyncANDROID xrCreateSpatialReferenceCacheAsyncANDROID;
PFN_xrCreateSpatialReferenceCacheCompleteANDROID xrCreateSpatialReferenceCacheCompleteANDROID;
PFN_xrDestroySpatialReferenceCacheANDROID xrDestroySpatialReferenceCacheANDROID;
PFN_xrCreateSpatialContextAsyncEXT xrCreateSpatialContextAsyncEXT;
PFN_xrCreateSpatialContextCompleteEXT xrCreateSpatialContextCompleteEXT;
void (*waitUntilReady)(XrFutureEXT);
XrSpatialReferenceImageFormatEXT desiredFormat;
XrSpatialAnnotationReferenceSourceANDROID desiredSource;
XrSpatialComponentTypeEXT desiredComponent;
// Create and start reference cache to prepare for capturing reference images.
XrSpatialReferenceCacheANDROID referenceCache;
XrSpatialReferenceCacheCreateInfoANDROID cacheCreateInfo{
.type = XR_TYPE_SPATIAL_REFERENCE_CACHE_CREATE_INFO_ANDROID,
.next = nullptr,
.capability = XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID,
.source = desiredSource,
};
XrFutureEXT cacheFuture = XR_NULL_FUTURE_EXT;
CHK_XR(xrCreateSpatialReferenceCacheAsyncANDROID(session, &cacheCreateInfo, &cacheFuture));
waitUntilReady(cacheFuture);
XrCreateSpatialReferenceCacheCompletionANDROID cacheCompletion{
XR_TYPE_CREATE_SPATIAL_REFERENCE_CACHE_COMPLETION_ANDROID};
CHK_XR(xrCreateSpatialReferenceCacheCompleteANDROID(session, cacheFuture,
&cacheCompletion));
if (cacheCompletion.futureResult != XR_SUCCESS) {
// Error, reference cache creation failed
return;
}
referenceCache = cacheCompletion.referenceCache;
// Create the reference image with quad annotations
// YUV 4:2:0 Planar:
// ----------------------
// | Y |Cb |Cr |
// ----------------------
XrSpatialReferenceImagePlaneEXT cameraImagePlanes[3];
// for each plane (0=Y, 1=U(cb), 2=V(Cr)) return by Image#getPlanes().
for (int i = 0; i < 3; ++i) {
cameraImagePlanes[i].buffer; // read from Plane#getBuffer().
cameraImagePlanes[i].bufferSize; // set each buffer size. Y = width * height (bytes); U = Y / 4 (bytes); V = Y / 4 (bytes).
cameraImagePlanes[i].rowStride; // read from Plane#getRowStride().
cameraImagePlanes[i].pixelStride; // read from Plane#getPixelStride().
}
XrSpatialReferenceImageEXT referenceImage{
XR_TYPE_SPATIAL_REFERENCE_IMAGE_EXT};
referenceImage.width = 640;
referenceImage.height = 480;
referenceImage.format = desiredFormat;
referenceImage.planeCount = 3;
referenceImage.planes = cameraImagePlanes;
XrSpatialAnnotationQuadANDROID
quad; // quad coordinates within the reference image.
quad.alignment = XR_SPATIAL_ANNOTATION_QUAD_ALIGNMENT_OBJECT_ANDROID;
// Set unnormalized pixel coordinates of 4 corners.
quad.upperLeft = {0.0, 0.0};
quad.upperRight = {0.0, 100.0};
quad.lowerRight = {100.0, 100.0};
quad.lowerLeft = {0.0, 100.0};
XrSpatialAnnotationQuadReferenceANDROID quadReference{
XR_TYPE_SPATIAL_ANNOTATION_QUAD_REFERENCE_ANDROID};
quadReference.quads = &quad;
quadReference.quadCount = 1;
referenceImage.next = &quadReference;
// Create the spatial context with annotation configuration.
XrSpatialContextEXT spatialContext{};
{
const std::array<XrSpatialComponentTypeEXT, 1> enabledComponents = {
desiredComponent,
};
// Configure annotation tracking
XrSpatialCapabilityConfigurationAnnotationTrackingANDROID annotationConfig{
XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_ANNOTATION_TRACKING_ANDROID};
annotationConfig.capability =
XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID;
annotationConfig.enabledComponentCount = enabledComponents.size();
annotationConfig.enabledComponents = enabledComponents.data();
annotationConfig.cache = referenceCache;
annotationConfig.time; // The time when this reference image is captured.
annotationConfig.reference = referenceImage;
std::vector<XrSpatialCapabilityConfigurationBaseHeaderEXT *>
capabilityConfigs;
capabilityConfigs.push_back(
reinterpret_cast<XrSpatialCapabilityConfigurationBaseHeaderEXT *>(
&annotationConfig));
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
return;
}
spatialContext = completion.spatialContext;
CHK_XR(xrDestroySpatialReferenceCacheANDROID(referenceCache));
}
Descubre las anotaciones activas
En el siguiente ejemplo de código, se muestra cómo descubrir y consultar anotaciones.
XrInstance instance; // previously initialized
XrSession session; // previously initialized
XrSpace localSpace; // previously initialized, e.g. from
// XR_REFERENCE_SPACE_TYPE_LOCAL
XrSpatialContextEXT spatialContext; // previously created
PFN_xrCreateSpatialDiscoverySnapshotAsyncEXT xrCreateSpatialDiscoverySnapshotAsyncEXT;
PFN_xrCreateSpatialDiscoverySnapshotCompleteEXT xrCreateSpatialDiscoverySnapshotCompleteEXT;
PFN_xrQuerySpatialComponentDataEXT xrQuerySpatialComponentDataEXT;
PFN_xrDestroySpatialSnapshotEXT xrDestroySpatialSnapshotEXT;
PFN_xrPollEvent xrPollEvent;
PFN_xrDestroySpatialContextEXT xrDestroySpatialContextEXT;
void (*waitUntilReady)(XrFutureEXT);
XrSpatialComponentTypeEXT desiredComponent; // e.g. XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID
auto discoverAnnotations = [&](XrSpatialContextEXT spatialContext, XrTime time,
XrSpace baseSpace) {
std::array<XrSpatialComponentTypeEXT, 1> snapshotComponents{desiredComponent};
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 = baseSpace;
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 desired annotation data, e.g. quad.
XrSpatialComponentTypeEXT componentsToQuery[] = {
XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID};
XrSpatialComponentDataQueryConditionEXT queryCond{
XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT};
queryCond.componentTypeCount = 1;
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<XrSpatialAnnotationQuadDataANDROID> quads(
queryResult.entityIdCountOutput);
XrSpatialComponentAnnotationQuadListANDROID quadList{
XR_TYPE_SPATIAL_COMPONENT_ANNOTATION_QUAD_LIST_ANDROID};
quadList.quadCount = quads.size();
quadList.quads = quads.data();
queryResult.next = &quadList;
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 XrSpatialAnnotationQuadDataANDROID ¤tQuad = quads[i];
// Rendering quad in the view.
}
}
CHK_XR(xrDestroySpatialSnapshotEXT(completion.snapshot));
}
};
while (1) {
// For every frame in frame loop
XrSpace space; // Application's play space.
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_ANNOTATION_TRACKING_ANDROID: {
const XrEventDataSpatialAnnotationTrackingANDROID &eventdata =
*reinterpret_cast<XrEventDataSpatialAnnotationTrackingANDROID *>(
&event);
if (eventdata.initializationResult != XR_SUCCESS) {
// handle initialization failure.
// e.g. CHK_XR(xrDestroySpatialContextEXT(spatialContext));
}
break;
}
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, space);
break;
}
}
}
// Finish frame loop
}
CHK_XR(xrDestroySpatialContextEXT(spatialContext));
Nuevos tipos de objetos
Comandos nuevos
- xrCreateSpatialReferenceCacheAsyncANDROID
- xrCreateSpatialReferenceCacheCompleteANDROID
- xrDestroySpatialReferenceCacheANDROID
- xrEnumerateSpatialAnnotationReferenceSourcesANDROID
Nuevas estructuras
- XrCreateSpatialReferenceCacheCompletionANDROID
- XrEventDataSpatialAnnotationTrackingANDROID
- XrSpatialAnnotationQuadANDROID
- XrSpatialAnnotationQuadDataANDROID
- XrSpatialCapabilityConfigurationAnnotationTrackingANDROID
- XrSpatialReferenceCacheCreateInfoANDROID
Extiende XrSpatialComponentDataQueryResultEXT :
Extensión de XrSpatialReferenceImageEXT :
Extensión de XrSystemProperties :
Nuevas enumeraciones
Nuevas constantes de enumeración
XR_ANDROID_SPATIAL_ANNOTATION_TRACKING_EXTENSION_NAMEXR_ANDROID_spatial_annotation_tracking_SPEC_VERSIONExtensión de XrObjectType :
XR_OBJECT_TYPE_SPATIAL_REFERENCE_CACHE_ANDROID
Extensión de XrSpatialCapabilityEXT :
XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID
Extensión de XrSpatialComponentTypeEXT :
XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID
Extensión de XrStructureType :
XR_TYPE_CREATE_SPATIAL_REFERENCE_CACHE_COMPLETION_ANDROIDXR_TYPE_EVENT_DATA_SPATIAL_ANNOTATION_TRACKING_ANDROIDXR_TYPE_SPATIAL_ANNOTATION_QUAD_REFERENCE_ANDROIDXR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_ANNOTATION_TRACKING_ANDROIDXR_TYPE_SPATIAL_COMPONENT_ANNOTATION_QUAD_LIST_ANDROIDXR_TYPE_SPATIAL_REFERENCE_CACHE_CREATE_INFO_ANDROIDXR_TYPE_SYSTEM_SPATIAL_ANNOTATION_PROPERTIES_ANDROID
Problemas
Historial de versiones
Revisión 1, 2025-09-17 (Levana Chen)
- Es la descripción inicial de la extensión.