XR_EXT_spatial_entity

Name String

XR_EXT_spatial_entity

Tipo de extensión

Extensión de instancia

Número de extensión registrado

741

Revisión

1

Estado de ratificación

Ratified

Dependencias de extensiones y versiones

XR_EXT_future

Colaboradores

Nihav Jain, Google
Jared Finder, Google
Natalie Fleury, Meta
Yuichi Taguchi, Meta
Ron Bessems, Meta
Yin Li, Microsoft
Karthik Kadappan, Magic Leap
Jimmy Alamparambil, ByteDance
Zhipeng Liu, ByteDance
Jun Yan, ByteDance

Descripción general

Esta extensión presenta los conceptos y fundamentos para la comprensión de escenas y el razonamiento espacial en OpenXR. Esto unifica varias áreas de funcionalidad relacionadas, pero distintas, que se enumeran, configuran y con las que se interactúa de una manera ampliamente uniforme, según lo define esta extensión. Como esta extensión carece de definiciones concretas de cualquiera de estas áreas funcionales, el texto de la especificación formal tiende a ser algo abstracto. Los ejemplos incluidos en este texto de especificación de la extensión se refieren, en ocasiones, a la funcionalidad definida en una extensión relacionada próxima o hipotética con fines ilustrativos, sin limitar o especificar de forma inherente dicha funcionalidad adicional.

Las partes generales de esta extensión son las siguientes:

  • Entidades espaciales : La funcionalidad se centra en las entidades , que proporcionan muy poca funcionalidad por sí solas.
  • Componentes espaciales : Estas entidades tienen componentes asociados que proporcionan datos y comportamientos.
  • Tipos de componentes espaciales : Cada componente espacial es de un tipo de componente específico, y cualquier entidad determinada tiene, como máximo, un solo componente de cualquier tipo de componente determinado.
  • Contexto espacial : Toda la interacción de las entidades espaciales se produce en un contexto después de una fase de inicialización y configuración.
  • Funciones espaciales : Las funciones proporcionan ampliamente la manipulación de entidades espaciales. Una capacidad es una unidad de funcionalidad, por ejemplo (sin limitarse a ello), anclajes definidos por la aplicación, detección de planos o seguimiento de imágenes. Cada capacidad suele definirse en una extensión independiente (que se habilita en la creación de la instancia, como de costumbre) y se habilita para un contexto específico en el momento de la creación.
  • Cada capacidad está asociada con un conjunto de tipos de componentes para los que hay componentes presentes en cada entidad expuesta por esa capacidad . La extensión que define una capacidad especifica qué tipos de componentes son obligatorios para la capacidad ("garantizados"), mientras que esa misma extensión o algunas otras pueden especificar tipos de componentes opcionales proporcionados por algunas implementaciones potenciales. Cualquier cantidad de capacidades puede proporcionar entidades con componentes de un tipo de componente determinado, que se pueden usar de manera uniforme sin importar la capacidad que lo produjo.
  • Atributos de capacidades espaciales : Además, algunas capacidades requieren configuración y, por lo tanto, se parametrizan con atributos de capacidades .

Esta extensión proporciona un mecanismo para enumerar los componentes que proporciona cada capacidad admitida en el sistema actual, tanto los obligatorios como los opcionales.

Como algunas implementaciones pueden requerir diferentes grados de parametrización para las capacidades , esta extensión proporciona un mecanismo para enumerar las funciones de capacidad admitidas asociadas con una capacidad determinada en el sistema actual.

Esta extensión también define varios componentes comunes que se espera que se usen en una amplia gama de capacidades .

Entidad espacial

Las entidades espaciales son entidades que existen en algún espacio y que tienen varios datos asociados organizados en componentes. Pueden ser cualquiera de los siguientes:

  • Físicos (p.ej., superficies planas como paredes y pisos, objetos como sillas y estanterías, etc.)
  • Virtual (p.ej., contenido que coloca y comparte otra aplicación o usuario)
  • Definido por la app (p.ej., la aplicación marca un área como "sala de estar" o "cocina", o marca un punto como la ubicación para colocar la TV, etc.)

Los elementos que se exponen a través del sistema de acciones, como los controles o la mirada, no están diseñados para modelarse como entidades espaciales.

Las entidades espaciales en OpenXR se modelan como un sistema de componentes de entidad . Cada entidad espacial tiene un conjunto de componentes, y cada componente proporciona un conjunto único de datos y comportamientos para esa entidad.

Las entidades espaciales se representan con un átomo XrSpatialEntityIdEXT o un controlador XrSpatialEntityEXT, cuyos detalles se proporcionan en la sección Representaciones de entidades espaciales.

Tipos de componentes espaciales

Una entidad espacial tiene uno o más componentes que proporcionan datos o comportamientos para esa entidad. Consulta Componentes comunes para ver algunos componentes comunes definidos por esta extensión.

typedef enum XrSpatialComponentTypeEXT {
    XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT = 1,
    XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT = 2,
    XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT = 3,
    XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT = 4,
    XR_SPATIAL_COMPONENT_TYPE_PLANE_ALIGNMENT_EXT = 1000741000,
    XR_SPATIAL_COMPONENT_TYPE_MESH_2D_EXT = 1000741001,
    XR_SPATIAL_COMPONENT_TYPE_POLYGON_2D_EXT = 1000741002,
    XR_SPATIAL_COMPONENT_TYPE_PLANE_SEMANTIC_LABEL_EXT = 1000741003,
    XR_SPATIAL_COMPONENT_TYPE_MARKER_EXT = 1000743000,
    XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_EXT = 1000744000,
    XR_SPATIAL_COMPONENT_TYPE_KEYBOARD_SEMANTIC_LABEL_EXT = 1000744001,
    XR_SPATIAL_COMPONENT_TYPE_MOUSE_SEMANTIC_LABEL_EXT = 1000744002,
    XR_SPATIAL_COMPONENT_TYPE_ANCHOR_EXT = 1000762000,
    XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_EXT = 1000763000,
    XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT = 1000782000,
    XR_SPATIAL_COMPONENT_TYPE_MESH_3D_NORMALS_EXT = 1000783000,
    XR_SPATIAL_COMPONENT_TYPE_MESH_3D_VERTEX_SEMANTIC_LABELS_EXT = 1000783001,
    XR_SPATIAL_COMPONENT_TYPE_MESH_3D_TRIANGLE_SEMANTIC_LABELS_EXT = 1000783002,
    XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_ANDROID = 1000785000,
    XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID = 1000786000,
    XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID = 1000791000,
    XR_SPATIAL_COMPONENT_TYPE_ROOM_ANDROIDSYS = 1000792002,
    XR_SPATIAL_COMPONENT_TYPE_MATERIAL_TYPE_ANDROIDSYS = 1000792003,
    XR_SPATIAL_COMPONENT_TYPE_CONFIDENCE_ANDROIDSYS = 1000792004,
    XR_SPATIAL_COMPONENT_TYPE_ROOM_EMPTINESS_ANDROIDSYS = 1000792005,
    XR_SPATIAL_COMPONENT_TYPE_OCCUPANCY_GRID_ANDROIDX1 = 1000793000,
    XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID = 1000794000,
    XR_SPATIAL_COMPONENT_TYPE_STREETSCAPE_GEOMETRY_METADATA_ANDROIDX2 = 1000798000,
    XR_SPATIAL_COMPONENT_TYPE_GEOMETRY_POINT_ANDROID = 1000803000,
    XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_SCOPES_ANDROIDX1 = 1000808000,
    XR_SPATIAL_COMPONENT_TYPE_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialComponentTypeEXT;

La enumeración XrSpatialComponentTypeEXT identifica los diferentes tipos de componentes que el entorno de ejecución puede admitir.

Esta extensión no proporciona por sí sola todos los tipos de componentes que se indican: algunos requieren que se habiliten extensiones adicionales en el momento de la creación de la instancia, como se documenta.

Los enumeradores tienen los siguientes valores:

Descripción de enum

XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT

Es el componente que proporciona los límites en 2D para una entidad espacial. La estructura de lista correspondiente es XrSpatialComponentBounded2DListEXT; la estructura de datos correspondiente es XrSpatialBounded2DDataEXT

XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT

Es el componente que proporciona los límites en 3D para una entidad espacial. La estructura de lista correspondiente es XrSpatialComponentBounded3DListEXT; la estructura de datos correspondiente es XrBoxf

XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT

Es el componente que proporciona el XrSpatialEntityIdEXT del elemento superior para una entidad espacial. La estructura de lista correspondiente es XrSpatialComponentParentListEXT; la estructura de datos correspondiente es XrSpatialEntityIdEXT

XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT

Es un componente que proporciona una malla 3D para una entidad espacial. La estructura de lista correspondiente es XrSpatialComponentMesh3DListEXT; la estructura de datos correspondiente es XrSpatialMeshDataEXT

XR_SPATIAL_COMPONENT_TYPE_PLANE_ALIGNMENT_EXT

Es el componente que proporciona la enumeración de alineación del plano para una entidad espacial. La estructura de lista correspondiente es XrSpatialComponentPlaneAlignmentListEXT. La estructura de datos correspondiente es XrSpatialPlaneAlignmentEXT (agregada por la extensión XR_EXT_spatial_plane_tracking).

XR_SPATIAL_COMPONENT_TYPE_MESH_2D_EXT

Es un componente que proporciona una malla 2D para una entidad espacial. La estructura de lista correspondiente es XrSpatialComponentMesh2DListEXT; la estructura de datos correspondiente es XrSpatialMeshDataEXT (agregada por la extensión XR_EXT_spatial_plane_tracking).

XR_SPATIAL_COMPONENT_TYPE_POLYGON_2D_EXT

Componente que proporciona un polígono de límite en 2D para una entidad espacial. La estructura de lista correspondiente es XrSpatialComponentPolygon2DListEXT; la estructura de datos correspondiente es XrSpatialPolygon2DDataEXT (agregada por la extensión XR_EXT_spatial_plane_tracking).

XR_SPATIAL_COMPONENT_TYPE_PLANE_SEMANTIC_LABEL_EXT

Componente que proporciona una etiqueta semántica para un plano. La estructura de lista correspondiente es XrSpatialComponentPlaneSemanticLabelListEXT. La estructura de datos correspondiente es XrSpatialPlaneSemanticLabelEXT (agregada por la extensión XR_EXT_spatial_plane_tracking).

XR_SPATIAL_COMPONENT_TYPE_MARKER_EXT

Es un componente que describe el tipo, el ID y la ubicación del marcador. La estructura de lista correspondiente es XrSpatialComponentMarkerListEXT; la estructura de datos correspondiente es XrSpatialMarkerDataEXT (agregada por la extensión XR_EXT_spatial_marker_tracking).

XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_EXT

Es el componente que proporciona una etiqueta semántica para una escena. La estructura de lista correspondiente es XrSpatialComponentObjectSemanticLabelListEXT. La estructura de datos correspondiente es XrSpatialObjectSemanticLabelEXT . (Agregado por la extensión XR_EXT_spatial_object_tracking)

XR_SPATIAL_COMPONENT_TYPE_KEYBOARD_SEMANTIC_LABEL_EXT

Es el componente que proporciona una etiqueta semántica para un teclado. La estructura de lista correspondiente es XrSpatialComponentKeyboardSemanticLabelListEXT. La estructura de datos correspondiente es XrSpatialKeyboardSemanticLabelEXT (agregada por la extensión XR_EXT_spatial_object_tracking).

XR_SPATIAL_COMPONENT_TYPE_MOUSE_SEMANTIC_LABEL_EXT

Es el componente que proporciona una etiqueta semántica para un mouse. La estructura de lista correspondiente es XrSpatialComponentMouseSemanticLabelListEXT. La estructura de datos correspondiente es XrSpatialMouseSemanticLabelEXT (agregada por la extensión XR_EXT_spatial_object_tracking).

XR_SPATIAL_COMPONENT_TYPE_ANCHOR_EXT

Es el componente que proporciona la ubicación de un ancla. La estructura de lista correspondiente es XrSpatialComponentAnchorListEXT; la estructura de datos correspondiente es XrPosef (agregada por la extensión XR_EXT_spatial_anchor).

XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_EXT

Es el componente que proporciona el UUID persistente para una entidad espacial. La estructura de lista correspondiente es XrSpatialComponentPersistenceListEXT. La estructura de datos correspondiente es XrSpatialPersistenceDataEXT (agregada por la extensión XR_EXT_spatial_persistence).

XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT

Es un componente que describe el tipo de imagen planar. La estructura de lista correspondiente es XrSpatialComponentImage2DListEXT; la estructura de datos correspondiente es XrSpatialImageSizeEXT . (Agregado por la extensión XR_EXT_spatial_image_tracking)

XR_SPATIAL_COMPONENT_TYPE_MESH_3D_NORMALS_EXT

Es el componente que proporciona las normales para la malla 3D de una entidad espacial. La estructura de lista correspondiente es XrSpatialComponentMesh3DNormalsListEXT. La estructura de datos correspondiente es XrSpatialBufferEXT (agregada por la extensión XR_EXT_spatial_mesh_tracking).

XR_SPATIAL_COMPONENT_TYPE_MESH_3D_VERTEX_SEMANTIC_LABELS_EXT

Componente que proporciona las etiquetas semánticas por vértice para la malla 3D de una entidad espacial. La estructura de lista correspondiente es XrSpatialComponentMesh3DVertexSemanticLabelsListEXT. La estructura de datos correspondiente es XrSpatialBufferEXT. Los datos dentro del búfer se asignan a XrSpatialMeshSemanticLabelEXT (agregado por la extensión XR_EXT_spatial_mesh_tracking).

XR_SPATIAL_COMPONENT_TYPE_MESH_3D_TRIANGLE_SEMANTIC_LABELS_EXT

Es el componente que proporciona las etiquetas semánticas por cara de triángulo para la malla 3D de una entidad espacial. La estructura de lista correspondiente es XrSpatialComponentMesh3DTriangleSemanticLabelsListEXT. La estructura de datos correspondiente es XrSpatialBufferEXT. Los datos dentro del búfer se asignan a XrSpatialMeshSemanticLabelEXT (agregado por la extensión XR_EXT_spatial_mesh_tracking).

XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_ANDROID

Es el componente que proporciona una etiqueta semántica para un objeto. La estructura de lista correspondiente es XrSpatialComponentObjectSemanticLabelListANDROID. La estructura de datos correspondiente es XrSpatialObjectSemanticLabelANDROID (agregada por la extensión XR_ANDROID_spatial_object_tracking).

XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID

Es el componente que proporciona la pose de un impacto de raycast en una entidad. La estructura de lista correspondiente es XrSpatialComponentRaycastResultListANDROID; la estructura de datos correspondiente es XrSpatialRaycastResultDataANDROID (agregada por la extensión XR_ANDROID_spatial_discovery_raycast).

XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID

Componente que proporciona el ID de la entidad que subsume la entidad adjunta. La estructura de lista correspondiente es XrSpatialComponentSubsumedByListANDROID; la estructura de datos correspondiente es XrSpatialEntityIdEXT (agregada por la extensión XR_ANDROID_spatial_component_subsumed_by)

XR_SPATIAL_COMPONENT_TYPE_ROOM_ANDROIDSYS

Componente que proporciona las dimensiones y el tipo de habitación de una caja de zapatos. La estructura de lista correspondiente es XrSpatialComponentRoomListANDROIDSYS. La estructura de datos correspondiente es XrSpatialRoomDataANDROIDSYS (agregada por la extensión XR_ANDROIDSYS_spatial_room_tracking).

XR_SPATIAL_COMPONENT_TYPE_MATERIAL_TYPE_ANDROIDSYS

Es el componente que proporciona el tipo de material de una superficie límite. La estructura de lista correspondiente es XrSpatialComponentMaterialTypeListANDROIDSYS. La estructura de datos correspondiente es XrSpatialMaterialTypeANDROIDSYS (agregada por la extensión XR_ANDROIDSYS_spatial_room_tracking).

XR_SPATIAL_COMPONENT_TYPE_CONFIDENCE_ANDROIDSYS

Es el componente que proporciona la confianza de un elemento rastreable. La estructura de lista correspondiente es XrSpatialComponentConfidenceListANDROIDSYS. La estructura de datos correspondiente es float (agregada por la extensión XR_ANDROIDSYS_spatial_room_tracking).

XR_SPATIAL_COMPONENT_TYPE_ROOM_EMPTINESS_ANDROIDSYS

Es el componente que proporciona el vacío de una habitación. La estructura de lista correspondiente es XrSpatialComponentRoomEmptinessListANDROIDSYS. La estructura de datos correspondiente es float (agregada por la extensión XR_ANDROIDSYS_spatial_room_tracking).

XR_SPATIAL_COMPONENT_TYPE_OCCUPANCY_GRID_ANDROIDX1

Es el componente que proporciona información de la cuadrícula de ocupación en la entidad adjunta. La estructura de lista correspondiente es XrSpatialComponentOccupancyGridListANDROIDX1; la estructura de datos correspondiente es XrSpatialOccupancyGridDataANDROIDX1 (agregada por la extensión XR_ANDROIDX1_spatial_occupancy_grid).

XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID

Es un componente que describe una anotación de cuadrilátero. La estructura de lista correspondiente es XrSpatialComponentAnnotationQuadListANDROID. La estructura de datos correspondiente es XrSpatialAnnotationQuadDataANDROID (agregada por la extensión XR_ANDROID_spatial_annotation_tracking).

XR_SPATIAL_COMPONENT_TYPE_STREETSCAPE_GEOMETRY_METADATA_ANDROIDX2

Es el componente que proporciona los metadatos para una geometría de paisaje urbano. La estructura de lista correspondiente es XrSpatialComponentStreetscapeGeometryMetadataListANDROIDX2. La estructura de datos correspondiente es XrSpatialStreetscapeGeometryMetadataANDROIDX2 (agregada por la extensión XR_ANDROIDX2_geospatial_streetscape).

XR_SPATIAL_COMPONENT_TYPE_GEOMETRY_POINT_ANDROID

Es el componente que identifica una entidad como un punto de geometría. No hay una lista ni una estructura de datos correspondientes para este tipo de componente. La presencia de este componente solo indica la capacidad de una entidad para adjuntarse a un ancla. (Agregado por la extensión XR_ANDROID_spatial_geometry_point)

XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_SCOPES_ANDROIDX1

Es un componente que describe los permisos de persistencia en los que se conserva la entidad. Si el entorno de ejecución admite XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_EXT, debe admitir también este componente. La estructura de datos correspondiente es XrSpatialBufferEXT . La estructura de la lista correspondiente es XrSpatialComponentPersistenceScopeDataListANDROIDX1 . (Agregado por la extensión XR_ANDROIDX1_spatial_anchor_cloud_sharing)

Funciones y configuración de Spatial

Las capacidades espaciales definen las habilidades de un entorno de ejecución para descubrir entidades que tienen un conjunto garantizado de componentes en ellas. Las aplicaciones habilitan los componentes de una capacidad espacial cuando crean el XrSpatialContextEXT y, a su vez, el entorno de ejecución debe proporcionar solo los componentes habilitados en las entidades descubiertas. Por ejemplo, si un entorno de ejecución informa que uno de los componentes de una capacidad determinada es "etiquetas semánticas", significa que la aplicación puede habilitar las etiquetas semánticas a través de la configuración de esa capacidad, y el entorno de ejecución debe proporcionar solo el componente de etiqueta semántica si está configurado.

typedef enum XrSpatialCapabilityEXT {
    XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT = 1000741000,
    XR_SPATIAL_CAPABILITY_MARKER_TRACKING_QR_CODE_EXT = 1000743000,
    XR_SPATIAL_CAPABILITY_MARKER_TRACKING_MICRO_QR_CODE_EXT = 1000743001,
    XR_SPATIAL_CAPABILITY_MARKER_TRACKING_ARUCO_MARKER_EXT = 1000743002,
    XR_SPATIAL_CAPABILITY_MARKER_TRACKING_APRIL_TAG_EXT = 1000743003,
    XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT = 1000744000,
    XR_SPATIAL_CAPABILITY_ANCHOR_EXT = 1000762000,
    XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT = 1000782000,
    XR_SPATIAL_CAPABILITY_MESH_TRACKING_EXT = 1000783000,
    XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_ANDROID = 1000785000,
    XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID = 1000786000,
    XR_SPATIAL_CAPABILITY_ROOM_TRACKING_ANDROIDSYS = 1000792000,
    XR_SPATIAL_CAPABILITY_ROOM_BOUNDARY_TRACKING_ANDROIDSYS = 1000792001,
    XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID = 1000794000,
    XR_SPATIAL_CAPABILITY_STREETSCAPE_GEOMETRY_ANDROIDX2 = 1000798000,
    XR_SPATIAL_CAPABILITY_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialCapabilityEXT;

La enumeración XrSpatialCapabilityEXT identifica los diferentes tipos de capacidades que el entorno de ejecución puede admitir.

Los enumeradores tienen los siguientes valores:

Descripción de enum

XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT

Seguimiento de planos (agregado por la extensión XR_EXT_spatial_plane_tracking)

XR_SPATIAL_CAPABILITY_MARKER_TRACKING_QR_CODE_EXT

Capacidad para detectar y hacer un seguimiento de los códigos QR. (Agregado por la extensión XR_EXT_spatial_marker_tracking)

XR_SPATIAL_CAPABILITY_MARKER_TRACKING_MICRO_QR_CODE_EXT

Capacidad para detectar y hacer un seguimiento de códigos Micro QR. (Agregado por la extensión XR_EXT_spatial_marker_tracking)

XR_SPATIAL_CAPABILITY_MARKER_TRACKING_ARUCO_MARKER_EXT

Capacidad para detectar y hacer un seguimiento de los marcadores de ArUco (Agregado por la extensión XR_EXT_spatial_marker_tracking)

XR_SPATIAL_CAPABILITY_MARKER_TRACKING_APRIL_TAG_EXT

Capacidad de detectar y hacer un seguimiento de las AprilTags. (Agregado por la extensión XR_EXT_spatial_marker_tracking)

XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT

Seguimiento de objetos (agregado por la extensión XR_EXT_spatial_object_tracking)

XR_SPATIAL_CAPABILITY_ANCHOR_EXT

Capacidad para crear anclajes espaciales (agregada por la extensión XR_EXT_spatial_anchor)

XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT

Capacidad para detectar y hacer un seguimiento de las imágenes de referencia planas. (Agregado por la extensión XR_EXT_spatial_image_tracking)

XR_SPATIAL_CAPABILITY_MESH_TRACKING_EXT

Capacidad de hacer un seguimiento de la malla de un entorno. (Agregado por la extensión XR_EXT_spatial_mesh_tracking)

XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_ANDROID

Seguimiento de objetos (agregado por la extensión XR_ANDROID_spatial_object_tracking)

XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID

Raycast contra el búfer de profundidad (agregado por la extensión XR_ANDROID_spatial_discovery_raycast)

XR_SPATIAL_CAPABILITY_ROOM_TRACKING_ANDROIDSYS

Capacidad para hacer un seguimiento de una sala (agregada por la extensión XR_ANDROIDSYS_spatial_room_tracking)

XR_SPATIAL_CAPABILITY_ROOM_BOUNDARY_TRACKING_ANDROIDSYS

Capacidad para hacer un seguimiento de los límites de una habitación (agregada por la extensión XR_ANDROIDSYS_spatial_room_tracking)

XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID

Seguimiento de anotaciones (agregado por la extensión XR_ANDROID_spatial_annotation_tracking)

XR_SPATIAL_CAPABILITY_STREETSCAPE_GEOMETRY_ANDROIDX2

Geometría del paisaje urbano (agregada por la extensión XR_ANDROIDX2_geospatial_streetscape)

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

XrResult xrEnumerateSpatialCapabilitiesEXT(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    uint32_t                                    capabilityCapacityInput,
    uint32_t*                                   capabilityCountOutput,
    XrSpatialCapabilityEXT*                     capabilities);

Descripciones de los parámetros

  • instance es un controlador de un XrInstance .
  • systemId es el XrSystemId cuyas capacidades espaciales se enumerarán.
  • capabilityCapacityInput es la capacidad del array capabilities, o 0 para indicar una solicitud de recuperación de la capacidad requerida.
  • capabilityCountOutput es la cantidad de capacidades o la capacidad requerida en caso de que capabilityCapacityInput no sea suficiente.
  • capabilities es un array de XrSpatialCapabilityEXT . Puede ser NULL si capabilityCapacityInput 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 capabilities requerido.

La aplicación puede enumerar la lista de capacidades espaciales que admite un XrSystemId determinado con xrEnumerateSpatialCapabilitiesEXT .

El entorno de ejecución no debe enumerar las capacidades espaciales cuya extensión no esté habilitada para instance .

Uso válido (implícito)

  • La extensión XR_EXT_spatial_entity debe estar habilitada antes de llamar a xrEnumerateSpatialCapabilitiesEXT.
  • instance debe ser un controlador XrInstance válido.
  • capabilityCountOutput debe ser un puntero a un valor uint32_t
  • Si capabilityCapacityInput no es 0 , capabilities debe ser un puntero a un array de valores capabilityCapacityInput XrSpatialCapabilityEXT

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_SYSTEM_INVALID
  • XR_ERROR_VALIDATION_FAILURE

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

XrResult xrEnumerateSpatialCapabilityComponentTypesEXT(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    XrSpatialCapabilityEXT                      capability,
    XrSpatialCapabilityComponentTypesEXT*       capabilityComponents);

Descripciones de los parámetros

  • instance es un controlador de un XrInstance .
  • systemId es el XrSystemId cuyos componentes de capacidad espacial se enumerarán.
  • capability es el XrSpatialCapabilityEXT para el que se enumerarán los componentes.
  • capabilityComponents es un puntero a un XrSpatialCapabilityComponentTypesEXT , que es una estructura de entrada/salida en la que se propaga un array asignado por la aplicación.

Esta función enumera los tipos de componentes que la capacidad dada proporciona en sus entidades en el sistema según la configuración.

La aplicación puede usar los tipos de componentes enumerados en XrSpatialCapabilityComponentTypesEXT :: componentTypes para comprender el conjunto completo de componentes que admite systemId para capability y puede usar esta lista para determinar cuál es una configuración válida para capability cuando se crea un XrSpatialContextEXT para él.

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

El entorno de ejecución no debe enumerar los tipos de componentes espaciales cuya extensión no esté habilitada 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

La estructura XrSpatialCapabilityComponentTypesEXT se define de la siguiente manera:

typedef struct XrSpatialCapabilityComponentTypesEXT {
    XrStructureType               type;
    void*                         next;
    uint32_t                      componentTypeCapacityInput;
    uint32_t                      componentTypeCountOutput;
    XrSpatialComponentTypeEXT*    componentTypes;
} XrSpatialCapabilityComponentTypesEXT;

Descripciones de los miembros

  • type es el XrStructureType de esta estructura.
  • next es NULL o un puntero a la siguiente estructura en una cadena de estructuras. No se definen tales estructuras en OpenXR principal ni en esta extensión.
  • componentTypeCapacityInput es la capacidad del array o 0 para indicar una solicitud de recuperación de la capacidad requerida.
  • componentTypeCountOutput es la cantidad de tipos de componentes o la capacidad requerida en caso de que componentTypeCapacityInput no sea suficiente.
  • componentTypes es un array de XrSpatialComponentTypeEXT . Puede ser NULL si componentTypeCapacityInput 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 componentTypes requerido.

Uso válido (implícito)

Funciones de capacidad espacial

typedef enum XrSpatialCapabilityFeatureEXT {
    XR_SPATIAL_CAPABILITY_FEATURE_MARKER_TRACKING_FIXED_SIZE_MARKERS_EXT = 1000743000,
    XR_SPATIAL_CAPABILITY_FEATURE_MARKER_TRACKING_STATIC_MARKERS_EXT = 1000743001,
    XR_SPATIAL_CAPABILITY_FEATURE_OBJECT_SEMANTIC_LABEL_SUBSET_EXT = 1000744000,
    XR_SPATIAL_CAPABILITY_FEATURE_SPHERE_BOUNDS_FILTER_ANDROID = 1000761000,
    XR_SPATIAL_CAPABILITY_FEATURE_BOX_BOUNDS_FILTER_ANDROID = 1000761001,
    XR_SPATIAL_CAPABILITY_FEATURE_FRUSTUM_BOUNDS_FILTER_ANDROID = 1000761002,
    XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT = 1000782000,
    XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT = 1000782001,
    XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXT = 1000782002,
    XR_SPATIAL_CAPABILITY_FEATURE_TRACK_WATERTIGHT_MESH_EXT = 1000783000,
    XR_SPATIAL_CAPABILITY_FEATURE_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialCapabilityFeatureEXT;

Algunas capacidades tienen parámetros expuestos a la aplicación para configurar cómo el entorno de ejecución calcula los datos del componente. Estas dimensiones de parametrización o configurabilidad se conocen como funciones de capacidad. Por ejemplo, para una función de seguimiento de imágenes, un entorno de ejecución puede admitir una función para que la aplicación especifique si las imágenes de las que se hace un seguimiento son estáticas o no.

Proporcionar esta información al entorno de ejecución a través de una estructura de configuración no debe cambiar el conjunto de tipos de componentes presentes en las entidades asociadas, p.ej., en la imagen de la que se hace un seguimiento. Sin embargo, el entorno de ejecución puede optimizar, por ejemplo, las habilidades de seguimiento de la función de seguimiento de imágenes y proporcionar una mejor experiencia a la aplicación.

Estas funciones se representan con XrSpatialCapabilityFeatureEXT, y la aplicación las enumera con xrEnumerateSpatialCapabilityFeaturesEXT .

Cada función de capacidad tiene una estructura de configuración correspondiente para habilitarla. Estas estructuras de configuración deben encadenarse a XrSpatialCapabilityConfigurationBaseHeaderEXT :: next de la capability correspondiente.

Los enumeradores tienen los siguientes valores:

Descripción de enum

XR_SPATIAL_CAPABILITY_FEATURE_MARKER_TRACKING_FIXED_SIZE_MARKERS_EXT

Función de capacidad para permitir que las aplicaciones especifiquen el tamaño de los marcadores. La estructura de configuración correspondiente es XrSpatialMarkerSizeEXT (agregada por la extensión XR_EXT_spatial_marker_tracking).

XR_SPATIAL_CAPABILITY_FEATURE_MARKER_TRACKING_STATIC_MARKERS_EXT

Se agregó una función de capacidad para permitir que las aplicaciones especifiquen si los marcadores son estáticos. La estructura de configuración correspondiente es XrSpatialMarkerStaticOptimizationEXT (agregada por la extensión XR_EXT_spatial_marker_tracking).

XR_SPATIAL_CAPABILITY_FEATURE_OBJECT_SEMANTIC_LABEL_SUBSET_EXT

Es una función espacial que permite que las aplicaciones especifiquen un subconjunto de etiquetas de XrSpatialObjectSemanticLabelEXT para que el entorno de ejecución realice un seguimiento. La estructura de configuración correspondiente es XrSpatialFeatureObjectSemanticLabelSubsetEXT . (Agregado por la extensión XR_EXT_spatial_object_tracking)

XR_SPATIAL_CAPABILITY_FEATURE_SPHERE_BOUNDS_FILTER_ANDROID

El entorno de ejecución admite el filtro XrSpatialBoundsSpherefANDROID para XrSpatialDiscoverySnapshotCreateInfoEXT. Esto no requiere que se incluya ninguna estructura de configuración durante la creación del contexto espacial. (Agregado por la extensión XR_ANDROID_spatial_discovery_bounds)

XR_SPATIAL_CAPABILITY_FEATURE_BOX_BOUNDS_FILTER_ANDROID

El entorno de ejecución admite el filtro XrSpatialBoundsBoxfANDROID para XrSpatialDiscoverySnapshotCreateInfoEXT. Esto no requiere que se incluya ninguna estructura de configuración durante la creación del contexto espacial. (Agregado por la extensión XR_ANDROID_spatial_discovery_bounds)

XR_SPATIAL_CAPABILITY_FEATURE_FRUSTUM_BOUNDS_FILTER_ANDROID

El entorno de ejecución admite el filtro XrSpatialBoundsFrustumfANDROID para XrSpatialDiscoverySnapshotCreateInfoEXT. Esto no requiere que se incluya ninguna estructura de configuración durante la creación del contexto espacial. (Agregado por la extensión XR_ANDROID_spatial_discovery_bounds)

XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT

El entorno de ejecución admite la deducción automática del tamaño físico de las imágenes detectadas y con seguimiento. La estructura de configuración correspondiente es XrSpatialImageSizeEXT (agregada por la extensión XR_EXT_spatial_image_tracking).

XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT

El entorno de ejecución admite XrSpatialImageStaticOptimizationEXT . La estructura de configuración correspondiente es XrSpatialImageStaticOptimizationEXT . (Agregado por la extensión XR_EXT_spatial_image_tracking)

XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXT

El entorno de ejecución admite XrSpatialImageSizeEXT . La estructura de configuración correspondiente es XrSpatialImageSizeEXT (agregada por la extensión XR_EXT_spatial_image_tracking).

XR_SPATIAL_CAPABILITY_FEATURE_TRACK_WATERTIGHT_MESH_EXT

Función de capacidad para hacer un seguimiento de una malla hermética del entorno. La estructura de configuración correspondiente es XrSpatialFeatureTrackWatertightMeshEXT . (Agregado por la extensión XR_EXT_spatial_mesh_tracking)

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

XrResult xrEnumerateSpatialCapabilityFeaturesEXT(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    XrSpatialCapabilityEXT                      capability,
    uint32_t                                    capabilityFeatureCapacityInput,
    uint32_t*                                   capabilityFeatureCountOutput,
    XrSpatialCapabilityFeatureEXT*              capabilityFeatures);

Descripciones de los parámetros

  • instance es un controlador de un XrInstance .
  • systemId es el XrSystemId cuyas funciones de capacidad espacial se enumerarán.
  • capability es el XrSpatialCapabilityEXT para el que se enumerarán las funciones.
  • capabilityFeatureCapacityInput es la capacidad del array o 0 para indicar una solicitud de recuperación de la capacidad requerida.
  • capabilityFeatureCountOutput es la cantidad de funciones o la capacidad requerida en caso de que capabilityFeatureCapacityInput no sea suficiente.
  • capabilityFeatures es un array de XrSpatialCapabilityFeatureEXT . Puede ser NULL si capabilityFeatureCapacityInput 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 capabilityFeatures requerido.

La aplicación descubre las funciones que admite un sistema determinado para un XrSpatialCapabilityEXT con xrEnumerateSpatialCapabilityFeaturesEXT .

En el caso de las capacidades que tienen funciones expuestas, la aplicación selecciona la función o las funciones que se habilitarán y proporciona la estructura de configuración correspondiente en la siguiente cadena de las estructuras de configuración de capacidades en XrSpatialContextCreateInfoEXT :: capabilityConfigs .

Si capability no es una capacidad enumerada por xrEnumerateSpatialCapabilitiesEXT , el entorno de ejecución debe devolver XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT .

El entorno de ejecución no debe enumerar las funciones de capacidad espacial cuya extensión no esté habilitada 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

Contexto espacial

Crea un contexto espacial

XR_DEFINE_HANDLE(XrSpatialContextEXT)

El controlador XrSpatialContextEXT representa los recursos para descubrir y actualizar una cantidad de entidades espaciales en el entorno del usuario. La aplicación puede usar este controlador para descubrir y actualizar entidades espaciales con otras funciones de esta extensión.

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

XrResult xrCreateSpatialContextAsyncEXT(
    XrSession                                   session,
    const XrSpatialContextCreateInfoEXT*        createInfo,
    XrFutureEXT*                                future);

Descripciones de los parámetros

  • session es una XrSession en la que el contexto espacial estará activo.
  • createInfo es el XrSpatialContextCreateInfoEXT que se usa para especificar los parámetros de contexto espacial.
  • future es un puntero a un XrFutureEXT .

La aplicación puede crear un controlador XrSpatialContextEXT de la siguiente manera:

El entorno de ejecución debe devolver XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT si XrSpatialContextCreateInfoEXT ::capabilityConfigCount es 0. Un controlador de contexto espacial necesita al menos una capacidad.

El entorno de ejecución debe devolver XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT si xrEnumerateSpatialCapabilitiesEXT no enumera ninguna capacidad del array XrSpatialContextCreateInfoEXT :: capabilityConfigs.

El entorno de ejecución debe mostrar XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT si algún XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponentCount en XrSpatialContextCreateInfoEXT :: capabilityConfigs es 0. La configuración de una capacidad está incompleta si no se incluye una lista de tipos de componentes que se deben habilitar para esa capacidad.

El entorno de ejecución debe devolver XR_ERROR_SPATIAL_COMPONENT_UNSUPPORTED_FOR_CAPABILITY_EXT si algún tipo de componente que aparece en XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents no se enumera para XrSpatialCapabilityConfigurationBaseHeaderEXT :: capability en xrEnumerateSpatialCapabilityComponentTypesEXT .

Si alguna de las estructuras de la siguiente cadena de XrSpatialContextCreateInfoEXT :: capabilityConfigs corresponde a un XrSpatialCapabilityFeatureEXT que no se enumera para esa capacidad en xrEnumerateSpatialCapabilityFeaturesEXT , el entorno de ejecución debe ignorar esa estructura XrSpatialCapabilityFeatureEXT.

El entorno de ejecución debe devolver XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT si XrSpatialContextCreateInfoEXT :: capabilityConfigs contiene varias estructuras con el mismo XrSpatialCapabilityConfigurationBaseHeaderEXT :: capability .

Para garantizar el uso óptimo de los recursos del sistema, el entorno de ejecución puede usar los parámetros de configuración proporcionados en el array XrSpatialContextCreateInfoEXT para prepararse para las solicitudes espaciales que se reciban. Por ejemplo, un entorno de ejecución que admita la capacidad de seguimiento de planos puede comenzar su canalización de seguimiento de planos solo si la aplicación crea un controlador de contexto espacial que contenga la capacidad de seguimiento de planos. Si las capacidades configuradas tienen un tiempo de preparación largo, las llamadas a xrCreateSpatialDiscoverySnapshotAsyncEXT pueden dar como resultado una instantánea vacía. La aplicación puede esperar a XrEventDataSpatialDiscoveryRecommendedEXT antes de usar xrCreateSpatialDiscoverySnapshotAsyncEXT para asegurarse de que los servicios de seguimiento subyacentes se hayan iniciado.

Si un entorno de ejecución aplica un sistema de permisos para controlar el acceso de la aplicación a las funciones espaciales que se configuran para el XrSpatialContextEXT , 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 xrCreateSpatialContextCompleteEXT , 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 XrCreateSpatialContextCompletionEXT .

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_CAPABILITY_CONFIGURATION_INVALID_EXT
  • XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT
  • XR_ERROR_SPATIAL_COMPONENT_UNSUPPORTED_FOR_CAPABILITY_EXT
  • XR_ERROR_VALIDATION_FAILURE
  • XR_ERROR_TIME_INVALID (si XR_ANDROID_spatial_annotation_tracking está habilitado)

La estructura XrSpatialContextCreateInfoEXT se define de la siguiente manera:

typedef struct XrSpatialContextCreateInfoEXT {
    XrStructureType                                                type;
    const void*                                                    next;
    uint32_t                                                       capabilityConfigCount;
    const XrSpatialCapabilityConfigurationBaseHeaderEXT* const*    capabilityConfigs;
} XrSpatialContextCreateInfoEXT;

Descripciones de los miembros

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

La estructura XrSpatialContextCreateInfoEXT describe la información para crear un controlador XrSpatialContextEXT.

Uso válido (implícito)

La estructura XrSpatialCapabilityConfigurationBaseHeaderEXT se define de la siguiente manera:

typedef struct XrSpatialCapabilityConfigurationBaseHeaderEXT {
    XrStructureType                     type;
    const void*                         next;
    XrSpatialCapabilityEXT              capability;
    uint32_t                            enabledComponentCount;
    const XrSpatialComponentTypeEXT*    enabledComponents;
} XrSpatialCapabilityConfigurationBaseHeaderEXT;

Esta estructura no se usa directamente en la API, sino que sus estructuras secundarias se pueden usar con XrSpatialContextCreateInfoEXT para configurar las capacidades espaciales.

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 .
  • enabledComponentCount es un uint32_t que describe el recuento de elementos en el array enabledComponents.
  • enabledComponents es un puntero a un array de XrSpatialComponentTypeEXT .

El entorno de ejecución debe devolver XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT si xrEnumerateSpatialCapabilitiesEXT no enumera capability. El entorno de ejecución debe devolver XR_ERROR_SPATIAL_COMPONENT_UNSUPPORTED_FOR_CAPABILITY_EXT si algún tipo de componente que aparece en enabledComponents no se enumera para capability en xrEnumerateSpatialCapabilityComponentTypesEXT .

Uso válido (implícito)

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

XrResult xrCreateSpatialContextCompleteEXT(
    XrSession                                   session,
    XrFutureEXT                                 future,
    XrCreateSpatialContextCompletionEXT*        completion);

Descripciones de los parámetros

xrCreateSpatialContextCompleteEXT completa la operación asíncrona que inició xrCreateSpatialContextAsyncEXT . 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 XrCreateSpatialContextCompletionEXT se define de la siguiente manera:

typedef struct XrCreateSpatialContextCompletionEXT {
    XrStructureType        type;
    void*                  next;
    XrResult               futureResult;
    XrSpatialContextEXT    spatialContext;
} XrCreateSpatialContextCompletionEXT;

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_CAPABILITY_CONFIGURATION_INVALID_EXT

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

Uso válido (implícito)

Destruye el contexto espacial

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

XrResult xrDestroySpatialContextEXT(
    XrSpatialContextEXT                         spatialContext);

Descripciones de los parámetros

La aplicación puede llamar a la función xrDestroySpatialContextEXT para liberar el controlador spatialContext y los recursos subyacentes cuando finalicen las tareas de descubrimiento y actualización de entidades espaciales. Si no hay ningún otro XrSpatialContextEXT válido que se haya creado con las mismas capacidades espaciales que spatialContext , esta llamada sirve como sugerencia para que el entorno de ejecución inhabilite los servicios de seguimiento necesarios para esas capacidades con el objetivo de ahorrar recursos del sistema.

Uso válido (implícito)

Seguridad de subprocesos

  • El acceso a spatialContext 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

Representaciones de entidades espaciales

ID de la entidad espacial

XR_DEFINE_ATOM(XrSpatialEntityIdEXT)

XrSpatialEntityIdEXT se usa para representar cualquier tipo de entidad que el entorno de ejecución descubra en el entorno espacial del usuario. Un XrSpatialEntityIdEXT es válido para el XrSpatialContextEXT en el que se descubre, y el entorno de ejecución no debe volver a usar el mismo XrSpatialEntityIdEXT para diferentes entidades dentro del mismo XrSpatialContextEXT . Además, el entorno de ejecución no debe volver a usar el mismo XrSpatialEntityIdEXT en varios XrSpatialContextEXT dentro de la misma XrSession, independientemente de si representa la misma entidad o una diferente.

#define XR_NULL_SPATIAL_ENTITY_ID_EXT 0

XR_NULL_SPATIAL_ENTITY_ID_EXT es un valor reservado que representa un XrSpatialEntityIdEXT no válido. Puede pasarse a las funciones de la API y devolverse desde ellas solo cuando se permita específicamente.

Identificador de entidad espacial

XR_DEFINE_HANDLE(XrSpatialEntityEXT)

El controlador XrSpatialEntityEXT representa una entidad espacial. Una aplicación puede crear un identificador de este tipo para expresar su interés en una entidad específica para el entorno de ejecución.

Cómo crear un controlador de entidad espacial a partir de un ID

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

XrResult xrCreateSpatialEntityFromIdEXT(
    XrSpatialContextEXT                         spatialContext,
    const XrSpatialEntityFromIdCreateInfoEXT*   createInfo,
    XrSpatialEntityEXT*                         spatialEntity);

Descripciones de los parámetros

La aplicación puede usar xrCreateSpatialEntityFromIdEXT para crear un controlador XrSpatialEntityEXT, que es una referencia a una entidad que existe en el entorno del usuario.

El entorno de ejecución debe devolver XR_ERROR_SPATIAL_ENTITY_ID_INVALID_EXT si XrSpatialEntityFromIdCreateInfoEXT :: entityId no es un ID válido para spatialContext .

Uso válido (implícito)

Códigos de retorno

Listo

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falla

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_ENTITY_ID_INVALID_EXT
  • XR_ERROR_VALIDATION_FAILURE

La estructura XrSpatialEntityFromIdCreateInfoEXT se define de la siguiente manera:

typedef struct XrSpatialEntityFromIdCreateInfoEXT {
    XrStructureType         type;
    const void*             next;
    XrSpatialEntityIdEXT    entityId;
} XrSpatialEntityFromIdCreateInfoEXT;

Descripciones de los miembros

  • type es el XrStructureType de esta estructura.
  • next es NULL o un puntero a la siguiente estructura en una cadena de estructuras. No se definen tales estructuras en OpenXR principal ni en esta extensión.
  • entityId es el XrSpatialEntityIdEXT de la entidad para la que la aplicación desea crear un identificador.

Uso válido (implícito)

Destruye el controlador de la entidad espacial

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

XrResult xrDestroySpatialEntityEXT(
    XrSpatialEntityEXT                          spatialEntity);

Descripciones de los parámetros

La aplicación puede usar xrDestroySpatialEntityEXT para liberar el controlador spatialEntity cuando ya no le interese la entidad a la que hace referencia este controlador.

Uso válido (implícito)

Seguridad de subprocesos

  • El acceso a spatialEntity 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

Instantánea espacial

XR_DEFINE_HANDLE(XrSpatialSnapshotEXT)

La aplicación puede crear instantáneas espaciales con el propósito de descubrir entidades espaciales o actualizar su información sobre entidades espaciales conocidas. El controlador XrSpatialSnapshotEXT representa los datos inmutables de las entidades espaciales descubiertas o actualizadas, y un subconjunto de sus componentes según lo seleccionado por la aplicación. La instantánea espacial representa una vista coherente de las entidades y los datos de sus componentes. Una vez que se crea una instantánea, sus datos deben permanecer constantes mientras la instantánea sea válida.

La aplicación puede crear cualquier cantidad de instantáneas que desee, pero debe tener en cuenta la memoria que se asigna para cada instantánea nueva y debe destruir las instantáneas una vez que ya no las necesite.

Crea una instantánea de descubrimiento

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

XrResult xrCreateSpatialDiscoverySnapshotAsyncEXT(
    XrSpatialContextEXT                         spatialContext,
    const XrSpatialDiscoverySnapshotCreateInfoEXT* createInfo,
    XrFutureEXT*                                future);

Descripciones de los parámetros

La aplicación puede descubrir entidades espaciales creando una instantánea de descubrimiento con xrCreateSpatialDiscoverySnapshotAsyncEXT .

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 xrCreateSpatialDiscoverySnapshotCompleteEXT , 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 XrCreateSpatialDiscoverySnapshotCompletionEXT .

La aplicación puede enviar varias solicitudes de creación de instantáneas de descubrimiento sin necesidad de esperar a que se complete la anterior. El entorno de ejecución puede procesar y completar la creación de instantáneas en cualquier orden. El entorno de ejecución puede retrasar la finalización de la creación de la instantánea de descubrimiento para limitar la aplicación si necesita reducir el uso de recursos del sistema debido a políticas de energía, térmicas o de otro tipo del dispositivo.

La aplicación puede usar XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes para filtrar la lista de entidades y los componentes cuyos datos el entorno de ejecución debe incluir en la instantánea. Si la aplicación proporciona una lista válida de tipos de componentes espaciales en XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes , el entorno de ejecución debe incluir solo entidades espaciales en la instantánea que tengan al menos uno de los componentes proporcionados en XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes . Además, el entorno de ejecución debe incluir solo los datos de los componentes de la instantánea.

El entorno de ejecución debe devolver XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT si alguno de los XrSpatialComponentTypeEXT en XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes no está habilitado para las capacidades espaciales que se pasaron a XrSpatialContextCreateInfoEXT :: capabilityConfigs cuando se creó spatialContext .

Si la aplicación no proporciona una lista de tipos de componentes espaciales en XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes , el entorno de ejecución debe incluir todas las entidades espaciales en la instantánea que tengan el conjunto de componentes que se enumeran en XrSpatialCapabilityConfigurationBaseHeaderEXT ::enabledComponents para las capacidades configuradas para spatialContext . El entorno de ejecución debe incluir los datos de todos los componentes habilitados de las capacidades configuradas para spatialContext .

Si XrEventDataReferenceSpaceChangePending se pone en cola antes de que se complete future y XrEventDataReferenceSpaceChangePending :: poseValid es falso, el entorno de ejecución puede crear un XrSpatialSnapshotEXT que no tenga entidades o establecer el XrSpatialEntityTrackingStateEXT de las entidades que ya no se pueden ubicar en XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: baseSpace en XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: time como XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT o XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT . El entorno de ejecución no debe establecer XrCreateSpatialContextCompletionEXT :: futureResult en un código de error debido a XrEventDataReferenceSpaceChangePending .

Uso válido (implícito)

Códigos de retorno

Listo

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falla

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT
  • XR_ERROR_VALIDATION_FAILURE

La estructura XrSpatialDiscoverySnapshotCreateInfoEXT se define de la siguiente manera:

typedef struct XrSpatialDiscoverySnapshotCreateInfoEXT {
    XrStructureType                     type;
    const void*                         next;
    uint32_t                            componentTypeCount;
    const XrSpatialComponentTypeEXT*    componentTypes;
} XrSpatialDiscoverySnapshotCreateInfoEXT;

Descripciones de los miembros

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

La estructura XrSpatialDiscoverySnapshotCreateInfoEXT describe la información para crear un controlador XrSpatialSnapshotEXT cuando se descubren entidades espaciales.

Uso válido (implícito)

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

XrResult xrCreateSpatialDiscoverySnapshotCompleteEXT(
    XrSpatialContextEXT                         spatialContext,
    const XrCreateSpatialDiscoverySnapshotCompletionInfoEXT* createSnapshotCompletionInfo,
    XrCreateSpatialDiscoverySnapshotCompletionEXT* completion);

Descripciones de los parámetros

xrCreateSpatialDiscoverySnapshotCompleteEXT completa la operación asíncrona que inició xrCreateSpatialDiscoverySnapshotAsyncEXT . El entorno de ejecución debe devolver XR_ERROR_FUTURE_PENDING_EXT si XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: future no está en estado listo. El entorno de ejecución debe devolver XR_ERROR_FUTURE_INVALID_EXT si XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: 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_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

La estructura XrCreateSpatialDiscoverySnapshotCompletionInfoEXT se define de la siguiente manera:

typedef struct XrCreateSpatialDiscoverySnapshotCompletionInfoEXT {
    XrStructureType    type;
    const void*        next;
    XrSpace            baseSpace;
    XrTime             time;
    XrFutureEXT        future;
} XrCreateSpatialDiscoverySnapshotCompletionInfoEXT;

Descripciones de los miembros

Las ubicaciones en los diversos datos de componentes incluidos en la instantánea creada se representarán en baseSpace , ubicado en time .

Uso válido (implícito)

La estructura XrCreateSpatialDiscoverySnapshotCompletionEXT se define de la siguiente manera:

typedef struct XrCreateSpatialDiscoverySnapshotCompletionEXT {
    XrStructureType         type;
    void*                   next;
    XrResult                futureResult;
    XrSpatialSnapshotEXT    snapshot;
} XrCreateSpatialDiscoverySnapshotCompletionEXT;

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.
  • futureResult es el XrResult de la operación de creación de instantáneas de descubrimiento espacial.
  • snapshot es un XrSpatialSnapshotEXT que se puede usar para consultar los datos de los componentes de las entidades espaciales descubiertas.

Códigos de devolución futuros

Valores de futureResult:

Listo

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falla

  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_LIMIT_REACHED

Uso válido (implícito)

Evento de recomendación de descubrimiento

La estructura XrEventDataSpatialDiscoveryRecommendedEXT se define de la siguiente manera:

typedef struct XrEventDataSpatialDiscoveryRecommendedEXT {
    XrStructureType        type;
    const void*            next;
    XrSpatialContextEXT    spatialContext;
} XrEventDataSpatialDiscoveryRecommendedEXT;

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.
  • spatialContext es el XrSpatialContextEXT para el que el entorno de ejecución recomienda el descubrimiento.

La aplicación puede recuperar este evento con xrPollEvent . La aplicación puede evitar llamadas excesivas a xrCreateSpatialDiscoverySnapshotAsyncEXT para descubrir entidades espaciales esperando este evento. Si la aplicación crea varias instantáneas de descubrimiento con el mismo XrSpatialDiscoverySnapshotCreateInfoEXT entre dos eventos XrEventDataSpatialDiscoveryRecommendedEXT, las instantáneas resultantes pueden contener las mismas entidades y, por lo tanto, la creación de instantáneas y las consultas de datos serían un desperdicio.

Esperar a que este evento cree una nueva instantánea de descubrimiento garantiza que la aplicación no sobrecargue el sistema con solicitudes de descubrimiento para las que el entorno de ejecución puede no devolver datos nuevos y ayuda a evitar el riesgo de usar en exceso los recursos del sistema y de que se limite debido a las políticas de energía o térmicas del dispositivo. Esto también ayuda a crear paridad entre los entornos de ejecución que descubren entidades espaciales sobre la marcha con el seguimiento en vivo y los entornos de ejecución que proporcionan entidades espaciales a partir de un estado registrado previamente (en el que el entorno de ejecución puede poner en cola el evento de recomendación de descubrimiento solo una vez para cada XrSpatialContextEXT).

El entorno de ejecución no debe poner en cola este evento para notificar a la aplicación sobre los cambios o ajustes realizados en los datos de los componentes de las entidades espaciales existentes. La aplicación puede usar xrCreateSpatialUpdateSnapshotEXT para hacer un seguimiento de las actualizaciones de datos de componentes de las entidades espaciales que le interesan.

Un entorno de ejecución puede poner en cola un evento de recomendación de descubrimiento sin esperar a que la aplicación llame primero a xrCreateSpatialDiscoverySnapshotAsyncEXT . Por ejemplo, un entorno de ejecución puede basar la decisión de poner en cola el evento de recomendación de descubrimiento en la configuración de XrSpatialContextEXT, su propia comprensión del entorno que rodea al usuario (descubrimiento de entidades nuevas o pérdida de las existentes) o para sugerir una cadencia de solicitud de descubrimiento adecuada a la aplicación para no sobrecargar los recursos del sistema. El entorno de ejecución puede optar por nunca poner en cola este evento para un XrSpatialContextEXT si no se encuentran entidades en el entorno del usuario durante la vida útil de ese XrSpatialContextEXT .

El entorno de ejecución no debe poner en cola este evento para un spatialContext determinado hasta que la aplicación complete su creación con xrCreateSpatialContextCompleteEXT .

Después de que la aplicación llama a xrDestroySpatialContextEXT , el entorno de ejecución no debe poner en cola más eventos de recomendación de descubrimiento para ese contexto espacial ni devolver esos eventos para ese contexto desde xrPollEvent .

Uso válido (implícito)

Datos de componentes de consulta

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

XrResult xrQuerySpatialComponentDataEXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialComponentDataQueryConditionEXT* queryCondition,
    XrSpatialComponentDataQueryResultEXT*       queryResult);

Descripciones de los parámetros

La aplicación puede usar xrQuerySpatialComponentDataEXT para consultar los datos de los componentes de las entidades en la instantánea adjuntando una estructura de lista a XrSpatialComponentDataQueryResultEXT :: next correspondiente a cada XrSpatialComponentTypeEXT en XrSpatialComponentDataQueryConditionEXT :: componentTypes .

Si la aplicación adjunta una estructura de lista a XrSpatialComponentDataQueryResultEXT :: next que no corresponde a ninguno de los componentes que se indican en XrSpatialComponentDataQueryConditionEXT :: componentTypes , el entorno de ejecución debe devolver XR_ERROR_VALIDATION_FAILURE .

La aplicación puede optar por adjuntar las estructuras de lista correspondientes solo a un subconjunto de componentes enumerados en XrSpatialComponentDataQueryConditionEXT :: componentTypes . La aplicación puede omitir las estructuras de lista por completo si solo desea conocer los IDs y el estado de seguimiento de las entidades espaciales que satisfacen el queryCondition . El entorno de ejecución no debe tratar la ausencia de estructuras de lista de la cadena XrSpatialComponentDataQueryResultEXT :: next como una falla.

Si XrEventDataReferenceSpaceChangePending está en cola y XrEventDataReferenceSpaceChangePending :: changeTime transcurrió mientras la aplicación consulta datos de componentes de un XrSpatialSnapshotEXT , la aplicación puede usar los datos del evento para ajustar las poses según corresponda.

El entorno de ejecución debe propagar XrSpatialComponentDataQueryResultEXT :: entityIds solo con entidades que tengan todos los componentes especificados en XrSpatialComponentDataQueryConditionEXT :: componentTypes . Si XrSpatialComponentDataQueryConditionEXT :: componentTypeCount es 0, el entorno de ejecución debe propagar queryResult con todas las entidades (y sus estados de seguimiento) que se encuentran en la instantánea. Si se agregan condiciones de consulta adicionales a XrSpatialComponentDataQueryConditionEXT :: next, el entorno de ejecución debe tratarlas como un "AND" con la disponibilidad de los tipos de componentes, es decir, el entorno de ejecución debe propagar XrSpatialComponentDataQueryResultEXT ::entityIds solo con entidades que cumplan con todas las condiciones proporcionadas. El entorno de ejecución debe propagar los datos de los componentes en las estructuras de lista en el mismo orden que las entidades en XrSpatialComponentDataQueryResultEXT :: entityIds, es decir, los datos de los componentes en un índice determinado del array de estructura de lista deben corresponder a la entidad en el mismo índice.

Si el estado de seguimiento de una entidad no es XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT , el entorno de ejecución no debe cambiar los datos en el índice correspondiente a esa entidad en el array contenido en las estructuras de lista adjuntas a XrSpatialComponentDataQueryResultEXT .

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_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_VALIDATION_FAILURE

Por ejemplo, la aplicación crea un XrSpatialSnapshotEXT que contiene 5 entidades, donde:

  • Las entidades 1 y 2 tienen los componentes XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT y XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT
  • Las entidades 3 y 4 tienen los componentes XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT y XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT
  • La entidad 5 tiene los componentes XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT y XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT .

XrSpatialEntityIdEXT

XrSpatialEntityIdEXT

1

1

2

2

3

3

4

4

5

5

Bounded2D

Bounded2D

Sí

Sí

Sí

Sí

No

No

No

No

Sí

Sí

Padre

Padre

Sí

Sí

Sí

Sí

No

No

No

No

No

No

Mesh3D

Mesh3D

No

No

No

No

Sí

Sí

Sí

Sí

Sí

Sí

Bounded3D

Bounded3D

No

No

No

No

Sí

Sí

Sí

Sí

No

No Text is not SVG - cannot display

Figura 20. Instantánea de ejemplo

xrQuerySpatialComponentDataEXT en la instantánea anterior con XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT que aparece en la condición de consulta dará como resultado que se devuelvan las entidades n.º 1, n.º 2 y n.º 5 a la aplicación, y la aplicación puede adjuntar un array de XrSpatialBounded2DDataEXT como parte de la estructura XrSpatialComponentBounded2DListEXT a la siguiente cadena de XrSpatialComponentDataQueryResultEXT para obtener los datos de bounded2D.

XrSpatialEntityIdEXT

XrSpatialEntityIdEXT

1

1

2

2

5

5

Bounded2D

Bounded2D

Datos para entityId #1

Datos de entid...

Datos para el entityId n° 2

Datos de entid...

Datos para entityId n° 5

Datos de entid...

entityIds

entityIds

siguiente

siguiente

XrSpatialComponent
DataQueryResultEXT

XrSpatialComponent
Dat...

bounds

bounds

XrSpatialComponent
Bounded2DListEXT

XrSpatialComponent
Bou... El texto no es SVG, por lo que no se puede mostrar

Figura 21. Resultado de la consulta de ejemplo

xrQuerySpatialComponentDataEXT en la instantánea anterior con los componentes XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT y XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT que se indican en la condición de la consulta dará como resultado que se devuelvan las entidades n.º 3 y n.º 4 a la aplicación, y la aplicación puede adjuntar arrays de XrBoxf y XrSpatialMeshDataEXT como parte de las estructuras XrSpatialComponentBounded3DListEXT y XrSpatialComponentMesh3DListEXT, respectivamente, a la siguiente cadena de XrSpatialComponentDataQueryResultEXT para obtener los datos del componente.

XrSpatialEntityIdEXT

XrSpatialEntityIdEXT

3

3

4

4

Bounded3D

Bounded3D

Datos para entityId #3

Datos de la ent...

Datos para entityId 4

Datos de entid...

Mesh3D

Mesh3D

Datos de entityId #3

Datos de la ent...

Datos para entityId 4

Datos de la entid...

entityIds

entityIds

siguiente

siguiente

XrSpatialComponent
DataQueryResultEXT

XrSpatialComponent
Da...

bounds

bounds

siguiente

siguiente

XrSpatialComponent
Bounded3DListEXT

XrSpatialComponent
Bo...

XrSpatialComponent
Mesh3DListEXT

XrSpatialComponent
Me...

mallas

mallas Text is not SVG - cannot display

Figura 22. Resultado de la consulta de ejemplo

La estructura XrSpatialComponentDataQueryConditionEXT se define de la siguiente manera:

typedef struct XrSpatialComponentDataQueryConditionEXT {
    XrStructureType                     type;
    const void*                         next;
    uint32_t                            componentTypeCount;
    const XrSpatialComponentTypeEXT*    componentTypes;
} XrSpatialComponentDataQueryConditionEXT;

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.
  • componentTypeCount es un uint32_t que describe el recuento de elementos en el array componentTypes.
  • componentTypes es un array de XrSpatialComponentTypeEXT del que se obtendrán los datos de la instantánea.

Uso válido (implícito)

La estructura XrSpatialComponentDataQueryResultEXT se define de la siguiente manera:

typedef struct XrSpatialComponentDataQueryResultEXT {
    XrStructureType                     type;
    void*                               next;
    uint32_t                            entityIdCapacityInput;
    uint32_t                            entityIdCountOutput;
    XrSpatialEntityIdEXT*               entityIds;
    uint32_t                            entityStateCapacityInput;
    uint32_t                            entityStateCountOutput;
    XrSpatialEntityTrackingStateEXT*    entityStates;
} XrSpatialComponentDataQueryResultEXT;

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.
  • entityIdCapacityInput es la capacidad del array entityIds, o 0 para indicar una solicitud de recuperación de la capacidad requerida.
  • entityIdCountOutput es la cantidad de XrSpatialEntityIdEXT en entityIds o la capacidad requerida en caso de que entityIdCapacityInput sea insuficiente.
  • entityIds es un array de XrSpatialEntityIdEXT . Puede ser NULL si entityIdCapacityInput es 0.
  • entityStateCapacityInput es la capacidad del array entityStates, o 0 para indicar una solicitud de recuperación de la capacidad requerida.
  • entityStateCountOutput es la cantidad de XrSpatialEntityTrackingStateEXT en entityStates o la capacidad requerida en caso de que entityStateCapacityInput sea insuficiente. Este valor debe ser siempre el mismo que entityIdCountOutput .
  • entityStates es un array de XrSpatialEntityTrackingStateEXT . Puede ser NULL si entityStateCapacityInput 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 entityIds requerido.

Una aplicación puede usar el entityIds con xrCreateSpatialEntityFromIdEXT para crear controladores XrSpatialEntityEXT para las entidades de las que le interesa recibir actualizaciones periódicas. Luego, la aplicación puede usar estos controladores XrSpatialEntityEXT con xrCreateSpatialUpdateSnapshotEXT para crear una instantánea de actualización que tenga los datos conocidos más recientes del entorno de ejecución de los componentes para las entidades proporcionadas.

Uso válido (implícito)

typedef enum XrSpatialEntityTrackingStateEXT {
    XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT = 1,
    XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT = 2,
    XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT = 3,
    XR_SPATIAL_ENTITY_TRACKING_STATE_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialEntityTrackingStateEXT;

XrSpatialEntityTrackingStateEXT enumera los posibles estados de seguimiento de entidades espaciales:

Las enumeraciones tienen los siguientes significados:

Descripción de enum

XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT

El entorno de ejecución dejó de hacer un seguimiento de esta entidad y nunca lo reanudará.

XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT

El entorno de ejecución detuvo el seguimiento de esta entidad, pero puede reanudarlo en el futuro.

XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT

El entorno de ejecución está haciendo un seguimiento de esta entidad y los datos de sus componentes son válidos.

SEGUIMIENTO

DETENIDA

DETENIDO

Figura 23. XrSpatialEntityTrackingStateEXT

  • El entorno de ejecución puede cambiar el estado de la entidad espacial de XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT a XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT si suspende el seguimiento de esa entidad espacial, pero tiene la posibilidad de reanudarlo en el futuro. Algunos ejemplos de cuándo el entorno de ejecución puede hacer esto incluyen (entre otros) si la aplicación pierde el foco de entrada, si la entidad espacial determinada está demasiado lejos del usuario como para que se realice un seguimiento preciso o si se realiza un seguimiento de demasiadas entidades y el entorno de ejecución quiere reducir el costo del seguimiento. XrSpatialEntityTrackingStateEXT ayuda a la aplicación a aislarse de las diferentes políticas de seguimiento de cada entorno de ejecución.
  • El entorno de ejecución puede cambiar el estado de una entidad de XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT a XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT o XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT .
  • El entorno de ejecución debe cambiar el estado de la entidad espacial de XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT o XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT a XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT si se pierde la entidad espacial y nunca se recuperará ni reanudará su seguimiento. Un ejemplo de este caso sería si el dispositivo pierde el seguimiento, reinicia su sesión de seguimiento, pero no puede volver a localizarse en su entorno y, por lo tanto, trata las entidades descubiertas de esta sesión de seguimiento como entidades nuevas.
  • Una vez que el estado de seguimiento de una entidad se establece en XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT , el entorno de ejecución no debe cambiarlo a ningún otro estado.
  • Cuando se consultan los datos de componentes de una entidad espacial con xrQuerySpatialComponentDataEXT , el entorno de ejecución debe establecer datos válidos en el contenido de los búferes que proporciona la aplicación en la siguiente cadena de XrSpatialComponentDataQueryResultEXT si el estado de la entidad es XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT . Si el estado de la entidad es XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT o XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT , el entorno de ejecución no debe cambiar el contenido de los búferes.

Lenguaje de dos llamadas para datos de componentes

La estructura XrSpatialBufferEXT se define de la siguiente manera:

typedef struct XrSpatialBufferEXT {
    XrSpatialBufferIdEXT      bufferId;
    XrSpatialBufferTypeEXT    bufferType;
} XrSpatialBufferEXT;

Descripciones de los miembros

  • bufferId: Es el XrSpatialBufferIdEXT de los datos del búfer.
  • bufferType es el XrSpatialBufferTypeEXT para indicar el tipo de datos en bufferId . La aplicación puede usar bufferType para determinar qué función usar para recuperar los datos reales del búfer.

Algunos componentes espaciales tienen datos de tamaño variable y, por lo tanto, requieren el uso del lenguaje de dos llamadas para recuperar sus datos. En esos casos, la estructura de datos del componente espacial proporciona un XrSpatialBufferEXT para cada búfer de tamaño variable que se necesita en los datos de ese componente.

Para el mismo bufferId , el entorno de ejecución debe proporcionar los mismos datos de una consulta de datos de componentes a otra, incluso de una instantánea a otra. Un bufferId diferente entre las llamadas de consulta de datos de componentes indica a la aplicación que los datos de ese componente pueden haber cambiado.

Uso válido (implícito)

XR_DEFINE_ATOM(XrSpatialBufferIdEXT)

XrSpatialBufferIdEXT se usa para representar cualquier tipo de datos de tamaño variable para un componente espacial.

El entorno de ejecución debe mantener el XrSpatialBufferIdEXT y sus datos en la memoria durante, al menos, el ciclo de vida del XrSpatialSnapshotEXT que lo contiene. El entorno de ejecución puede mantener el XrSpatialBufferIdEXT y sus datos en la memoria durante más tiempo que el ciclo de vida de XrSpatialSnapshotEXT para devolver el mismo ID como parte de las instantáneas que la aplicación cree más adelante. Para el mismo XrSpatialBufferIdEXT , el entorno de ejecución debe siempre devolver los mismos datos a través de la función xrGetSpatialBuffer* adecuada.

typedef enum XrSpatialBufferTypeEXT {
    XR_SPATIAL_BUFFER_TYPE_UNKNOWN_EXT = 0,
    XR_SPATIAL_BUFFER_TYPE_STRING_EXT = 1,
    XR_SPATIAL_BUFFER_TYPE_UINT8_EXT = 2,
    XR_SPATIAL_BUFFER_TYPE_UINT16_EXT = 3,
    XR_SPATIAL_BUFFER_TYPE_UINT32_EXT = 4,
    XR_SPATIAL_BUFFER_TYPE_FLOAT_EXT = 5,
    XR_SPATIAL_BUFFER_TYPE_VECTOR2F_EXT = 6,
    XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT = 7,
    XR_SPATIAL_BUFFER_TYPE_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialBufferTypeEXT;

La enumeración XrSpatialBufferTypeEXT identifica los diferentes tipos de datos del búfer representado XrSpatialBufferIdEXT .

Descripciones de enumerantes

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

XrResult xrGetSpatialBufferStringEXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialBufferGetInfoEXT*            info,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    char*                                       buffer);

Descripciones de los parámetros

  • snapshot es un controlador de un XrSpatialSnapshotEXT .
  • info contiene la información sobre el búfer que se consultará.
  • bufferCapacityInput es la capacidad del array o 0 para indicar una solicitud de recuperación de la capacidad requerida.
  • bufferCountOutput es la cantidad de caracteres o la capacidad requerida en caso de que bufferCapacityInput no sea suficiente.
  • buffer es un array de char . Puede ser NULL si bufferCapacityInput 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 buffer requerido.

La aplicación puede obtener los datos de un XrSpatialBufferEXT proporcionado por un componente, donde XrSpatialBufferEXT :: bufferType es XR_SPATIAL_BUFFER_TYPE_STRING_EXT con xrGetSpatialBufferStringEXT .

El entorno de ejecución debe devolver XR_ERROR_VALIDATION_FAILURE si el XrSpatialBufferTypeEXT para XrSpatialBufferGetInfoEXT :: bufferId no es XR_SPATIAL_BUFFER_TYPE_STRING_EXT .

El entorno de ejecución debe devolver XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT si XrSpatialBufferGetInfoEXT :: bufferId no pertenece a snapshot .

buffer completado por el entorno de ejecución debe ser una cadena UTF-8 terminada en nulo.

Uso válido (implícito)

  • La extensión XR_EXT_spatial_entity debe estar habilitada antes de llamar a xrGetSpatialBufferStringEXT.
  • snapshot debe ser un controlador XrSpatialSnapshotEXT válido
  • info debe ser un puntero a una estructura XrSpatialBufferGetInfoEXT válida.
  • bufferCountOutput debe ser un puntero a un valor uint32_t
  • Si bufferCapacityInput no es 0 , buffer debe ser un puntero a un array de valores char de bufferCapacityInput

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_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT
  • XR_ERROR_VALIDATION_FAILURE

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

XrResult xrGetSpatialBufferUint8EXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialBufferGetInfoEXT*            info,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    uint8_t*                                    buffer);

Descripciones de los parámetros

  • snapshot es un controlador de un XrSpatialSnapshotEXT .
  • info contiene la información sobre el búfer que se consultará.
  • bufferCapacityInput es la capacidad del array o 0 para indicar una solicitud de recuperación de la capacidad requerida.
  • bufferCountOutput es la cantidad de elementos en el array buffer o la capacidad requerida en caso de que bufferCapacityInput sea insuficiente.
  • buffer es un array de uint8_t . Puede ser NULL si bufferCapacityInput 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 buffer requerido.

La aplicación puede obtener los datos de un XrSpatialBufferEXT proporcionado por un componente, donde XrSpatialBufferEXT :: bufferType es XR_SPATIAL_BUFFER_TYPE_UINT8_EXT con xrGetSpatialBufferUint8EXT .

El entorno de ejecución debe devolver XR_ERROR_VALIDATION_FAILURE si el XrSpatialBufferTypeEXT para XrSpatialBufferGetInfoEXT :: bufferId no es XR_SPATIAL_BUFFER_TYPE_UINT8_EXT .

El entorno de ejecución debe devolver XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT si XrSpatialBufferGetInfoEXT :: bufferId no pertenece a snapshot .

Uso válido (implícito)

  • La extensión XR_EXT_spatial_entity debe estar habilitada antes de llamar a xrGetSpatialBufferUint8EXT.
  • snapshot debe ser un controlador XrSpatialSnapshotEXT válido
  • info debe ser un puntero a una estructura XrSpatialBufferGetInfoEXT válida.
  • bufferCountOutput debe ser un puntero a un valor uint32_t
  • Si bufferCapacityInput no es 0 , buffer debe ser un puntero a un array de valores bufferCapacityInput uint8_t

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_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT
  • XR_ERROR_VALIDATION_FAILURE

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

XrResult xrGetSpatialBufferUint16EXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialBufferGetInfoEXT*            info,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    uint16_t*                                   buffer);

Descripciones de los parámetros

  • snapshot es un controlador de un XrSpatialSnapshotEXT .
  • info contiene la información sobre el búfer que se consultará.
  • bufferCapacityInput es la capacidad del array o 0 para indicar una solicitud de recuperación de la capacidad requerida.
  • bufferCountOutput es la cantidad de elementos en el array buffer o la capacidad requerida en caso de que bufferCapacityInput sea insuficiente.
  • buffer es un array de uint16_t . Puede ser NULL si bufferCapacityInput 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 buffer requerido.

La aplicación puede obtener los datos de un XrSpatialBufferEXT proporcionado por un componente, donde XrSpatialBufferEXT :: bufferType es XR_SPATIAL_BUFFER_TYPE_UINT16_EXT con xrGetSpatialBufferUint16EXT .

El entorno de ejecución debe devolver XR_ERROR_VALIDATION_FAILURE si el XrSpatialBufferTypeEXT para XrSpatialBufferGetInfoEXT :: bufferId no es XR_SPATIAL_BUFFER_TYPE_UINT16_EXT .

El entorno de ejecución debe devolver XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT si XrSpatialBufferGetInfoEXT :: bufferId no pertenece a snapshot .

Uso válido (implícito)

  • La extensión XR_EXT_spatial_entity debe estar habilitada antes de llamar a xrGetSpatialBufferUint16EXT.
  • snapshot debe ser un controlador XrSpatialSnapshotEXT válido
  • info debe ser un puntero a una estructura XrSpatialBufferGetInfoEXT válida.
  • bufferCountOutput debe ser un puntero a un valor uint32_t
  • Si bufferCapacityInput no es 0 , buffer debe ser un puntero a un array de valores bufferCapacityInput uint16_t

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_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT
  • XR_ERROR_VALIDATION_FAILURE

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

XrResult xrGetSpatialBufferUint32EXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialBufferGetInfoEXT*            info,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    uint32_t*                                   buffer);

Descripciones de los parámetros

  • snapshot es un controlador de un XrSpatialSnapshotEXT .
  • info contiene la información sobre el búfer que se consultará.
  • bufferCapacityInput es la capacidad del array o 0 para indicar una solicitud de recuperación de la capacidad requerida.
  • bufferCountOutput es la cantidad de elementos en el array buffer o la capacidad requerida en caso de que bufferCapacityInput sea insuficiente.
  • buffer es un array de uint32_t . Puede ser NULL si bufferCapacityInput 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 buffer requerido.

La aplicación puede obtener los datos de un XrSpatialBufferEXT proporcionado por un componente, donde XrSpatialBufferEXT :: bufferType es XR_SPATIAL_BUFFER_TYPE_UINT32_EXT con xrGetSpatialBufferUint32EXT .

El entorno de ejecución debe devolver XR_ERROR_VALIDATION_FAILURE si el XrSpatialBufferTypeEXT para XrSpatialBufferGetInfoEXT :: bufferId no es XR_SPATIAL_BUFFER_TYPE_UINT32_EXT .

El entorno de ejecución debe devolver XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT si XrSpatialBufferGetInfoEXT :: bufferId no pertenece a snapshot .

Uso válido (implícito)

  • La extensión XR_EXT_spatial_entity debe estar habilitada antes de llamar a xrGetSpatialBufferUint32EXT
  • snapshot debe ser un controlador XrSpatialSnapshotEXT válido
  • info debe ser un puntero a una estructura XrSpatialBufferGetInfoEXT válida.
  • bufferCountOutput debe ser un puntero a un valor uint32_t
  • Si bufferCapacityInput no es 0 , buffer debe ser un puntero a un array de valores bufferCapacityInput uint32_t

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_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT
  • XR_ERROR_VALIDATION_FAILURE

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

XrResult xrGetSpatialBufferFloatEXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialBufferGetInfoEXT*            info,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    float*                                      buffer);

Descripciones de los parámetros

  • snapshot es un controlador de un XrSpatialSnapshotEXT .
  • info contiene la información sobre el búfer que se consultará.
  • bufferCapacityInput es la capacidad del array o 0 para indicar una solicitud de recuperación de la capacidad requerida.
  • bufferCountOutput es la cantidad de elementos en el array buffer o la capacidad requerida en caso de que bufferCapacityInput sea insuficiente.
  • buffer es un array de float . Puede ser NULL si bufferCapacityInput 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 buffer requerido.

La aplicación puede obtener los datos de un XrSpatialBufferEXT proporcionado por un componente, donde XrSpatialBufferEXT :: bufferType es XR_SPATIAL_BUFFER_TYPE_FLOAT_EXT con xrGetSpatialBufferFloatEXT .

El entorno de ejecución debe devolver XR_ERROR_VALIDATION_FAILURE si el XrSpatialBufferTypeEXT para XrSpatialBufferGetInfoEXT :: bufferId no es XR_SPATIAL_BUFFER_TYPE_FLOAT_EXT .

El entorno de ejecución debe devolver XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT si XrSpatialBufferGetInfoEXT :: bufferId no pertenece a snapshot .

Uso válido (implícito)

  • La extensión XR_EXT_spatial_entity debe estar habilitada antes de llamar a xrGetSpatialBufferFloatEXT.
  • snapshot debe ser un controlador XrSpatialSnapshotEXT válido
  • info debe ser un puntero a una estructura XrSpatialBufferGetInfoEXT válida.
  • bufferCountOutput debe ser un puntero a un valor uint32_t
  • Si bufferCapacityInput no es 0 , buffer debe ser un puntero a un array de valores bufferCapacityInput float

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_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT
  • XR_ERROR_VALIDATION_FAILURE

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

XrResult xrGetSpatialBufferVector2fEXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialBufferGetInfoEXT*            info,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    XrVector2f*                                 buffer);

Descripciones de los parámetros

  • snapshot es un controlador de un XrSpatialSnapshotEXT .
  • info contiene la información sobre el búfer que se consultará.
  • bufferCapacityInput es la capacidad del array o 0 para indicar una solicitud de recuperación de la capacidad requerida.
  • bufferCountOutput es la cantidad de elementos en el array buffer o la capacidad requerida en caso de que bufferCapacityInput sea insuficiente.
  • buffer es un array de XrVector2f . Puede ser NULL si bufferCapacityInput 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 buffer requerido.

La aplicación puede obtener los datos de un XrSpatialBufferEXT que proporciona un componente, donde XrSpatialBufferEXT :: bufferType es XR_SPATIAL_BUFFER_TYPE_VECTOR2F_EXT con xrGetSpatialBufferVector2fEXT .

El entorno de ejecución debe devolver XR_ERROR_VALIDATION_FAILURE si el XrSpatialBufferTypeEXT para XrSpatialBufferGetInfoEXT :: bufferId no es XR_SPATIAL_BUFFER_TYPE_VECTOR2F_EXT .

El entorno de ejecución debe devolver XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT si XrSpatialBufferGetInfoEXT :: bufferId no pertenece a snapshot .

Uso válido (implícito)

  • La extensión XR_EXT_spatial_entity debe estar habilitada antes de llamar a xrGetSpatialBufferVector2fEXT.
  • snapshot debe ser un controlador XrSpatialSnapshotEXT válido
  • info debe ser un puntero a una estructura XrSpatialBufferGetInfoEXT válida.
  • bufferCountOutput debe ser un puntero a un valor uint32_t
  • Si bufferCapacityInput no es 0 , buffer debe ser un puntero a un array de estructuras bufferCapacityInput XrVector2f.

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_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT
  • XR_ERROR_VALIDATION_FAILURE

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

XrResult xrGetSpatialBufferVector3fEXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialBufferGetInfoEXT*            info,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    XrVector3f*                                 buffer);

Descripciones de los parámetros

  • snapshot es un controlador de un XrSpatialSnapshotEXT .
  • info contiene la información sobre el búfer que se consultará.
  • bufferCapacityInput es la capacidad del array o 0 para indicar una solicitud de recuperación de la capacidad requerida.
  • bufferCountOutput es la cantidad de elementos en el array buffer o la capacidad requerida en caso de que bufferCapacityInput sea insuficiente.
  • buffer es un array de XrVector3f . Puede ser NULL si bufferCapacityInput 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 buffer requerido.

La aplicación puede obtener los datos de un XrSpatialBufferEXT que proporciona un componente, donde XrSpatialBufferEXT :: bufferType es XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT con xrGetSpatialBufferVector3fEXT .

El entorno de ejecución debe devolver XR_ERROR_VALIDATION_FAILURE si el XrSpatialBufferTypeEXT para XrSpatialBufferGetInfoEXT :: bufferId no es XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT .

El entorno de ejecución debe devolver XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT si XrSpatialBufferGetInfoEXT :: bufferId no pertenece a snapshot .

Uso válido (implícito)

  • La extensión XR_EXT_spatial_entity debe estar habilitada antes de llamar a xrGetSpatialBufferVector3fEXT.
  • snapshot debe ser un controlador XrSpatialSnapshotEXT válido
  • info debe ser un puntero a una estructura XrSpatialBufferGetInfoEXT válida.
  • bufferCountOutput debe ser un puntero a un valor uint32_t
  • Si bufferCapacityInput no es 0 , buffer debe ser un puntero a un array de estructuras bufferCapacityInput XrVector3f.

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_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT
  • XR_ERROR_VALIDATION_FAILURE

La estructura XrSpatialBufferGetInfoEXT se define de la siguiente manera:

typedef struct XrSpatialBufferGetInfoEXT {
    XrStructureType         type;
    const void*             next;
    XrSpatialBufferIdEXT    bufferId;
} XrSpatialBufferGetInfoEXT;

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.
  • bufferId un XrSpatialBufferIdEXT para el búfer cuyos datos se recuperarán.

Uso válido (implícito)

#define XR_NULL_SPATIAL_BUFFER_ID_EXT 0

XR_NULL_SPATIAL_BUFFER_ID_EXT es un valor reservado que representa un XrSpatialBufferIdEXT no válido. Puede pasarse a las funciones de la API y devolverse desde ellas solo cuando se permita específicamente.

Crea una instantánea de actualización

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

XrResult xrCreateSpatialUpdateSnapshotEXT(
    XrSpatialContextEXT                         spatialContext,
    const XrSpatialUpdateSnapshotCreateInfoEXT* createInfo,
    XrSpatialSnapshotEXT*                       snapshot);

Descripciones de los parámetros

La aplicación puede usar xrCreateSpatialUpdateSnapshotEXT para crear una instantánea y obtener los datos de componentes más recientes de entidades específicas, según lo que sepa el entorno de ejecución. Las aplicaciones pueden proporcionar los controladores XrSpatialEntityEXT y los tipos de componentes que les interesan cuando crean la instantánea.

La aplicación puede usar XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes para filtrar la lista de componentes cuyos datos deben incluirse en la instantánea. Si la aplicación proporciona una lista válida de tipos de componentes espaciales en XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes , el entorno de ejecución debe incluir solo entidades espaciales en la instantánea que tengan al menos uno de los componentes proporcionados en XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes . Además, el entorno de ejecución debe incluir solo los datos de esos componentes en la instantánea.

El entorno de ejecución debe devolver XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT si alguno de los XrSpatialComponentTypeEXT en XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes no está habilitado para las capacidades espaciales que se pasaron a XrSpatialContextCreateInfoEXT :: capabilityConfigs cuando se creó spatialContext .

Si la aplicación no proporciona una lista de tipos de componentes espaciales en XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes , el entorno de ejecución debe incluir todas las entidades espaciales que se indican en XrSpatialUpdateSnapshotCreateInfoEXT :: entities en la instantánea y debe incluir los datos de todos los componentes habilitados de las capacidades configuradas para spatialContext .

El entorno de ejecución no debe incluir entidades espaciales que no se incluyan en XrSpatialUpdateSnapshotCreateInfoEXT :: entities en snapshot .

La aplicación puede crear cualquier cantidad de instantáneas que desee, pero debe tener en cuenta la memoria que se asigna para cada instantánea nueva y debe destruir las instantáneas una vez que ya no las necesite.

Uso válido (implícito)

Códigos de retorno

Listo

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falla

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

La estructura XrSpatialUpdateSnapshotCreateInfoEXT se define de la siguiente manera:

typedef struct XrSpatialUpdateSnapshotCreateInfoEXT {
    XrStructureType                     type;
    const void*                         next;
    uint32_t                            entityCount;
    const XrSpatialEntityEXT*           entities;
    uint32_t                            componentTypeCount;
    const XrSpatialComponentTypeEXT*    componentTypes;
    XrSpace                             baseSpace;
    XrTime                              time;
} XrSpatialUpdateSnapshotCreateInfoEXT;

Descripciones de los miembros

  • type es el XrStructureType de esta estructura.
  • next es NULL o un puntero a la siguiente estructura en una cadena de estructuras. No se definen tales estructuras en OpenXR principal ni en esta extensión.
  • entityCount es un uint32_t que describe el recuento de elementos en el array entities.
  • entities es un array de XrSpatialEntityEXT para el que el entorno de ejecución debe incluir los datos del componente en la instantánea.
  • componentTypeCount es un uint32_t que describe el recuento de elementos en el array componentTypes.
  • componentTypes es un array de XrSpatialComponentTypeEXT para el que el entorno de ejecución debe incluir los datos en la instantánea.
  • baseSpace es el XrSpace en relación con el que se ubicarán todas las ubicaciones de la actualización XrSpatialSnapshotEXT.
  • time es el XrTime en el que se ubicarán todas las ubicaciones de la actualización XrSpatialSnapshotEXT.

Uso válido (implícito)

  • La extensión XR_EXT_spatial_entity debe estar habilitada antes de usar XrSpatialUpdateSnapshotCreateInfoEXT.
  • type debe ser XR_TYPE_SPATIAL_UPDATE_SNAPSHOT_CREATE_INFO_EXT
  • next debe ser NULL o un puntero válido a la siguiente estructura en una cadena de estructuras
  • entities debe ser un puntero a un array de controladores XrSpatialEntityEXT válidos de entityCount
  • Si componentTypeCount no es 0 , componentTypes debe ser un puntero a un array de valores XrSpatialComponentTypeEXT válidos de componentTypeCount.
  • baseSpace debe ser un controlador XrSpace válido.
  • El parámetro entityCount debe ser mayor que 0.
  • Tanto baseSpace como los elementos de entities deben haberse creado, asignado o recuperado de la misma XrSession.

Destruir instantánea

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

XrResult xrDestroySpatialSnapshotEXT(
    XrSpatialSnapshotEXT                        snapshot);

Descripciones de los parámetros

La aplicación puede llamar a xrDestroySpatialSnapshotEXT para destruir el controlador XrSpatialSnapshotEXT y los recursos asociados a él.

Uso válido (implícito)

Seguridad de subprocesos

  • El acceso a snapshot 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

Componentes comunes

2D delimitado

Datos de componentes

La estructura XrSpatialBounded2DDataEXT se define de la siguiente manera:

typedef struct XrSpatialBounded2DDataEXT {
    XrPosef        center;
    XrExtent2Df    extents;
} XrSpatialBounded2DDataEXT;

Descripciones de los miembros

  • center es un XrPosef que define el centro geométrico del componente 2D delimitado.
  • extents es la extensión del componente 2D delimitado a lo largo del eje X (extents.width) y el eje Y (extents.height), centrado en center .

El extents del XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT hace referencia al tamaño de la entidad en el plano x-y del sistema de coordenadas del plano. Un plano con una posición de {0, 0, 0}, una rotación de {0, 0, 0, 1} (sin rotación) y una extensión de {1, 1} se refiere a un plano de 1 metro x 1 metro centrado en {0, 0, 0} con su vector normal de cara frontal apuntando hacia la dirección +Z en el espacio del componente.

X X Y Y Z Z Altura Altura Y Y Z Z X X Plano vertical Plano vertical Plano horizontal Plano horizontal Ancho Ancho Ancho Ancho Altura Altura

Figura 24. Sistema de coordenadas de componentes de Bounded2D

Nota

OpenXR usa un plano X-Y con +Z como la normal del plano, pero otras APIs pueden usar un plano X-Z con +Y como la normal del plano. El plano X-Y puede convertirse en un plano X-Z rotando -π/2 radianes alrededor del eje +X.

Uso válido (implícito)

Estructura de la lista de componentes para consultar datos

La estructura XrSpatialComponentBounded2DListEXT se define de la siguiente manera:

typedef struct XrSpatialComponentBounded2DListEXT {
    XrStructureType               type;
    void*                         next;
    uint32_t                      boundCount;
    XrSpatialBounded2DDataEXT*    bounds;
} XrSpatialComponentBounded2DListEXT;

Descripciones de los miembros

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

El entorno de ejecución debe devolver XR_ERROR_VALIDATION_FAILURE de xrQuerySpatialComponentDataEXT si XrSpatialComponentBounded2DListEXT está en la siguiente cadena de XrSpatialComponentDataQueryResultEXT :: next, pero XrSpatialComponentDataQueryConditionEXT ::componentTypeCount no es cero y XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT no se incluye en XrSpatialComponentDataQueryConditionEXT :: componentTypes .

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

Si xrQuerySpatialComponentDataEXT :: snapshot se creó a partir de xrCreateSpatialDiscoverySnapshotCompleteEXT , el entorno de ejecución debe proporcionar XrSpatialBounded2DDataEXT :: center en XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: baseSpace y XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: time .

Si xrQuerySpatialComponentDataEXT :: snapshot se creó a partir de xrCreateSpatialUpdateSnapshotEXT , el entorno de ejecución debe proporcionar XrSpatialBounded2DDataEXT :: center en XrSpatialUpdateSnapshotCreateInfoEXT :: baseSpace y XrSpatialUpdateSnapshotCreateInfoEXT :: time .

Uso válido (implícito)

Configuración

Si XR_SPATIAL_COMPONENT_TYPE_BOUNDED_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 .

3D delimitado

Datos de componentes

XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT usa XrBoxf para sus datos.

Estructura de la lista de componentes para consultar datos

La estructura XrSpatialComponentBounded3DListEXT se define de la siguiente manera:

typedef struct XrSpatialComponentBounded3DListEXT {
    XrStructureType    type;
    void*              next;
    uint32_t           boundCount;
    XrBoxf*            bounds;
} XrSpatialComponentBounded3DListEXT;

Descripciones de los miembros

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

El entorno de ejecución debe devolver XR_ERROR_VALIDATION_FAILURE de xrQuerySpatialComponentDataEXT si XrSpatialComponentBounded3DListEXT está en la siguiente cadena de XrSpatialComponentDataQueryResultEXT :: next, pero XrSpatialComponentDataQueryConditionEXT ::componentTypeCount no es cero y XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT no se incluye en XrSpatialComponentDataQueryConditionEXT :: componentTypes .

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

Si se creó xrQuerySpatialComponentDataEXT :: snapshot a partir de xrCreateSpatialDiscoverySnapshotCompleteEXT , el entorno de ejecución debe proporcionar XrBoxf :: center en XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: baseSpace en XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: time .

Si xrQuerySpatialComponentDataEXT :: snapshot se creó a partir de xrCreateSpatialUpdateSnapshotEXT , el entorno de ejecución debe proporcionar XrBoxf :: center en XrSpatialUpdateSnapshotCreateInfoEXT :: baseSpace en XrSpatialUpdateSnapshotCreateInfoEXT :: time .

Uso válido (implícito)

Configuración

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

Padre

Datos de componentes

XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT usa XrSpatialEntityIdEXT para sus datos.

Estructura de la lista de componentes para consultar datos

La estructura XrSpatialComponentParentListEXT se define de la siguiente manera:

typedef struct XrSpatialComponentParentListEXT {
    XrStructureType          type;
    void*                    next;
    uint32_t                 parentCount;
    XrSpatialEntityIdEXT*    parents;
} XrSpatialComponentParentListEXT;

Descripciones de los miembros

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

El entorno de ejecución debe devolver XR_ERROR_VALIDATION_FAILURE de xrQuerySpatialComponentDataEXT si XrSpatialComponentParentListEXT está en la siguiente cadena de XrSpatialComponentDataQueryResultEXT :: next, pero XrSpatialComponentDataQueryConditionEXT ::componentTypeCount no es cero y XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT no se incluye en XrSpatialComponentDataQueryConditionEXT :: componentTypes .

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

Uso válido (implícito)

Configuración

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

Malla 3D

Datos de componentes

La estructura XrSpatialMeshDataEXT se define de la siguiente manera:

typedef struct XrSpatialMeshDataEXT {
    XrPosef               origin;
    XrSpatialBufferEXT    vertexBuffer;
    XrSpatialBufferEXT    indexBuffer;
} XrSpatialMeshDataEXT;

Descripciones de los miembros

  • origin es un XrPosef que define el origen de la malla. Todos los vértices de la malla deben ser relativos a este origen.
  • vertexBuffer es un XrSpatialBufferEXT que proporciona el ID de un búfer que representa el búfer de vértices de la entidad en la que se encuentra este componente. La posición de los vértices debe ser relativa a origin .
  • indexBuffer es un XrSpatialBufferEXT que proporciona el ID de un búfer que representa un array de índices de triángulos, que especifica los índices de los vértices de la malla en el vertexBuffer . Los índices de triángulos deben mostrarse en el sentido contrario a las manecillas del reloj, y tres índices denotan un triángulo.

El tipo de componente que usa XrSpatialMeshDataEXT debe especificar el XrSpatialBufferTypeEXT de vertexBuffer y indexBuffer .

Uso válido (implícito)

Estructura de la lista de componentes para consultar datos

La estructura XrSpatialComponentMesh3DListEXT se define de la siguiente manera:

typedef struct XrSpatialComponentMesh3DListEXT {
    XrStructureType          type;
    void*                    next;
    uint32_t                 meshCount;
    XrSpatialMeshDataEXT*    meshes;
} XrSpatialComponentMesh3DListEXT;

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.
  • meshCount es un uint32_t que describe el recuento de elementos en el array meshes.
  • meshes es un array de XrSpatialMeshDataEXT .

La aplicación puede consultar el componente de malla 3D de las entidades espaciales en un XrSpatialSnapshotEXT agregando XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT en XrSpatialComponentDataQueryConditionEXT :: componentTypes y agregando XrSpatialComponentMesh3DListEXT a la siguiente cadena de punteros de XrSpatialComponentDataQueryResultEXT .

El entorno de ejecución debe devolver XR_ERROR_VALIDATION_FAILURE de xrQuerySpatialComponentDataEXT si XrSpatialComponentMesh3DListEXT está en la siguiente cadena de XrSpatialComponentDataQueryResultEXT :: next, pero XrSpatialComponentDataQueryConditionEXT ::componentTypeCount no es cero y XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT no se incluye en XrSpatialComponentDataQueryConditionEXT :: componentTypes .

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

Para el XrSpatialMeshDataEXT que completa el entorno de ejecución en el array meshes, el XrSpatialBufferEXT :: bufferType para XrSpatialMeshDataEXT :: vertexBuffer debe ser XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT y XrSpatialBufferEXT :: bufferType para XrSpatialMeshDataEXT :: indexBuffer debe ser XR_SPATIAL_BUFFER_TYPE_UINT32_EXT .

Uso válido (implícito)

Configuración

Si XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT se enumera en XrSpatialCapabilityComponentTypesEXT :: componentTypes para alguna capacidad, la aplicación puede habilitarla incluyendo la enumeración en la lista XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents de la estructura derivada XrSpatialCapabilityConfigurationBaseHeaderEXT de la capacidad que admite este componente.

Este componente no requiere ninguna configuración especial para incluirse en la siguiente cadena de XrSpatialCapabilityConfigurationBaseHeaderEXT .

Filtros de estado de seguimiento

La estructura XrSpatialFilterTrackingStateEXT se define de la siguiente manera:

typedef struct XrSpatialFilterTrackingStateEXT {
    XrStructureType                    type;
    const void*                        next;
    XrSpatialEntityTrackingStateEXT    trackingState;
} XrSpatialFilterTrackingStateEXT;

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.
  • trackingState es el XrSpatialEntityTrackingStateEXT para el que la aplicación quiere aplicar el filtro.

La aplicación puede usar XrSpatialFilterTrackingStateEXT en la siguiente cadena de XrSpatialDiscoverySnapshotCreateInfoEXT para limitar el descubrimiento solo a aquellas entidades cuyo estado de seguimiento sea trackingState .

La aplicación puede usar XrSpatialFilterTrackingStateEXT en la siguiente cadena de XrSpatialComponentDataQueryConditionEXT para limitar la consulta de datos de componentes de una instantánea solo a las entidades cuyo estado de seguimiento sea trackingState .

Uso válido (implícito)

Ejemplo de código

Uso de la aplicación

Por lo general, las aplicaciones usan la extensión de entidad espacial con el siguiente patrón:

Descubre entidades espaciales y consulta datos de componentes

En el siguiente código de ejemplo, se muestra cómo descubrir entidades espaciales para la capacidad "Foo" y consultar sus datos de componentes.

/****************************/
/* Capability definition    */
/****************************/
// Foo capability has the following components -
// - XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT
#define XR_SPATIAL_CAPABILITY_FOO ((XrSpatialCapabilityEXT)1000740000U)

#define XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_FOO_EXT ((XrStructureType)1000740000U)
// Derives from XrSpatialCapabilityConfigurationBaseHeaderEXT
typedef struct XrSpatialCapabilityConfigurationFooEXT {
  XrStructureType                     type;
  const void* XR_MAY_ALIAS            next;
  XrSpatialCapabilityEXT              capability;
  uint32_t                            enabledComponentCount;
  const XrSpatialComponentTypeEXT*    enabledComponents;
} XrSpatialCapabilityConfigurationFooEXT;

/******************************/
/* End capability definition  */
/******************************/

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

// Create a spatial spatial context
XrSpatialContextEXT spatialContext{};
{
  const std::array<XrSpatialComponentTypeEXT, 1> enabledComponents = {
    XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT,
  };

  // Configure Foo capability for the spatial context
  XrSpatialCapabilityConfigurationFooEXT fooConfig{XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_FOO_EXT};
  fooConfig.capability = XR_SPATIAL_CAPABILITY_FOO;
  fooConfig.enabledComponentCount = enabledComponents.size();
  fooConfig.enabledComponents = enabledComponents.data();

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

  XrSpatialContextCreateInfoEXT spatialContextCreateInfo{XR_TYPE_SPATIAL_CONTEXT_CREATE_INFO_EXT};
  spatialContextCreateInfo.capabilityConfigCount = capabilityConfigs.size();
  spatialContextCreateInfo.capabilityConfigs = capabilityConfigs.data();
  XrFutureEXT createContextFuture;
  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) {
    return;
  }

  spatialContext = completion.spatialContext;
}

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

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

  waitUntilReady(future);

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

  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 componentToQuery = XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT;
    XrSpatialComponentDataQueryConditionEXT queryCond{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT};
    queryCond.componentTypes = &componentToQuery;

    XrSpatialComponentDataQueryResultEXT queryResult{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_RESULT_EXT};
    queryResult.entityIdCapacityInput = 0;
    queryResult.entityIds = nullptr;
    queryResult.entityStateCapacityInput = 0;
    queryResult.entityStates = nullptr;
    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;

    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) {
        // 2D extents for entity entityIds[i] is bounded2d[i].extents.
      }
    }

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

Consulta datos del búfer

En el siguiente código de ejemplo, se muestra cómo obtener los datos de un componente que proporciona un XrSpatialBufferEXT .

/****************************/
/* Component definition     */
/****************************/
// Foo component that provides an XrVector3f buffer
#define XR_SPATIAL_COMPONENT_TYPE_FOO_EXT ((XrSpatialComponentTypeEXT)1000740000U)

#define XR_TYPE_SPATIAL_COMPONENT_FOO_LIST_EXT ((XrStructureType)1000740000U)

// XrSpatialComponentFooListEXT extends XrSpatialComponentDataQueryResultEXT
typedef struct XrSpatialComponentFooListEXT {
    XrStructureType                   type;
    void* XR_MAY_ALIAS                next;
    uint32_t                          fooCount;
    XrSpatialBufferEXT*               foo;
} XrSpatialComponentFooListEXT;

/******************************/
/* End Component definition  */
/******************************/

// Query for the foo component data
XrSpatialComponentTypeEXT componentToQuery = XR_SPATIAL_COMPONENT_TYPE_FOO_EXT;
XrSpatialComponentDataQueryConditionEXT queryCond{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT};
queryCond.componentTypeCount = 1;
queryCond.componentTypes = &componentToQuery;

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

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

std::vector<XrSpatialBufferEXT> fooBuffers(queryResult.entityIdCountOutput);
XrSpatialComponentFooListEXT fooList{XR_TYPE_SPATIAL_COMPONENT_FOO_LIST_EXT};
fooList.fooCount = fooBuffers.size();
fooList.foo = fooBuffers.data();
queryResult.next = &fooList;

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

for (int32_t i = 0; i < queryResult.entityIdCountOutput; ++i) {
  // foo component data for entity entityIds[i]
  if (fooBuffers[i].bufferType == XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT) {
    XrSpatialBufferGetInfoEXT getInfo{XR_TYPE_SPATIAL_BUFFER_GET_INFO_EXT};
    getInfo.bufferId = fooBuffers[i].bufferId;
    uint32_t bufferCountOutput;
    CHK_XR(xrGetSpatialBufferVector3fEXT(snapshot, &getInfo, 0, &bufferCountOutput, nullptr));
    std::vector<XrVector3f> vertexBuffer(bufferCountOutput);
    CHK_XR(xrGetSpatialBufferVector3fEXT(snapshot, &getInfo, bufferCountOutput, &bufferCountOutput, vertexBuffer.data()));

    // XrVertex3f buffer for entity entityIds[i] is now available in vertexBuffer vector.
  }
}

Lineamientos de extensiones

  • Si una extensión define un nuevo XrSpatialComponentTypeEXT que proporciona datos adicionales sobre una entidad espacial,

  • Las extensiones pueden definir estructuras que extiendan XrSpatialDiscoverySnapshotCreateInfoEXT para proporcionar filtros adicionales para el descubrimiento. Los filtros para crear la instantánea no deben afectar la configuración del contexto espacial, sino que se deben usar para proporcionar sugerencias al entorno de ejecución sobre qué entidades y datos se deben incluir en la instantánea, según lo que se registre en la configuración actual del contexto espacial (y, por lo tanto, la configuración actual de los servicios subyacentes).

  • Si una extensión define un nuevo XrSpatialCapabilityEXT ,

  • Si una extensión define un nuevo XrSpatialCapabilityFeatureEXT, debe definir también una estructura de configuración correspondiente que pueda encadenarse al siguiente puntero de XrSpatialCapabilityConfigurationBaseHeaderEXT , que la aplicación pueda usar para habilitar la función cuando se cree un XrSpatialContextEXT .

  • Una extensión que defina un nuevo XrSpatialCapabilityEXT debería seguir esta plantilla para la especificación:

    • Descripción general
    • Asistencia del entorno de ejecución
    • Configuración
    • Componentes garantizados
    • Código de ejemplo

  • Una extensión que defina un nuevo XrSpatialComponentTypeEXT debería seguir esta plantilla para la especificación:

    • Datos de componentes
    • Estructura de la lista de componentes para consultar datos
    • Configuración

  • Cuando se escribe una API que proporciona a la aplicación un XrSpatialBufferIdEXT, debe ir acompañada de un XrSpatialBufferTypeEXT para informar a la aplicación cuál es el tipo de datos del búfer, y la aplicación puede usar una función xrGetSpatialBuffer* adecuada para recuperar el contenido real del búfer.

Lineamientos de diseño y extensión de etiquetas semánticas

Si bien esta extensión no define ningún componente para transmitir la información de la etiqueta semántica de una entidad, establece las reglas y los lineamientos de diseño para cualquier extensión que defina ese componente. En el siguiente texto, "debería " y "debe " restringen a los autores de esa funcionalidad, en lugar de restringir una implementación del entorno de ejecución o una aplicación que use la API.

  • Si una extensión define etiquetas semánticas para cualquier XrSpatialCapabilityEXT, debe hacerlo definiendo un nuevo XrSpatialComponentTypeEXT, así como una nueva enumeración con un conjunto de etiquetas (un "conjunto de etiquetas semánticas") para que sean los datos de ese componente.
  • Una enumeración que representa un conjunto de etiquetas semánticas debe tener un valor para indicar que la entidad no está categorizada en ninguna de las etiquetas de este conjunto. El nombre de este enumerante debe incluir "UNCATEGORIZED", p.ej., XR_SPATIAL_PLANE_SEMANTIC_LABEL_UNCATEGORIZED_EXT . Este valor indica a las aplicaciones que el entorno de ejecución reconoce esta entidad, pero que hay otros conjuntos de etiquetas semánticas en los que se categoriza esta entidad.
  • La enumeración de este XrSpatialComponentTypeEXT recién definido en xrEnumerateSpatialCapabilityComponentTypesEXT implica que el entorno de ejecución admite el conjunto de etiquetas semánticas (y, por lo tanto, las etiquetas definidas en el conjunto) correspondiente a ese tipo de componente.
  • Las aplicaciones expresan su deseo de descubrir entidades que tengan etiquetas que pertenezcan a este conjunto de etiquetas semánticas incluyendo el XrSpatialComponentTypeEXT correspondiente en el array XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents de la estructura de configuración de la capacidad para la que se enumera el tipo de componente.
  • Es posible que una sola entidad espacial tenga varios componentes, cada uno de los cuales le proporciona una etiqueta de su propio conjunto de etiquetas semánticas. Considera el siguiente ejemplo con algunos conjuntos de etiquetas semánticas hipotéticas: XrSpatialObjectSemanticLabel , que podrían tener valores como silla, sofá, mesa, etcétera. XrSpatialSofaBrand , que podría tener valores como IKEA, Wayfair, etc., y XrSpatialIkeaSofa , que podría tener nombres de modelos de sofás específicos de IKEA. En este caso, la misma entidad de sofá tiene los 3 componentes (etiquetas de los 3 conjuntos de etiquetas semánticas), y cada uno proporciona un nivel de detalle diferente de información sobre la entidad.
  • Si una extensión define un nuevo XrSpatialComponentTypeEXT que proporciona un nuevo conjunto de etiquetas semánticas que contiene varias etiquetas además de la etiqueta UNCATEGORIZED, la extensión debería considerar definir un XrSpatialCapabilityFeatureEXT que permita que las aplicaciones activen solo un subconjunto de las etiquetas definidas en el conjunto de etiquetas semánticas correspondiente a ese tipo de componente. Este subconjunto, que se proporciona en la siguiente cadena de la configuración de capacidades, actúa como una sugerencia para que los entornos de ejecución optimicen sus canalizaciones de seguimiento y solo realicen un seguimiento del subconjunto proporcionado. A continuación, se proporciona un ejemplo de una estructura de atributos de este tipo.
  • Las extensiones no deben agregar etiquetas a la enumeración de conjuntos de etiquetas semánticas existentes. En su lugar, deben definir una enumeración nueva que contenga enumerantes equivalentes con semántica idéntica y con valores iguales a los del otro conjunto, además de los enumerantes recién agregados. La especificación del conjunto de etiquetas semánticas recién definido también debe establecer la asignación entre el conjunto de etiquetas anterior y el nuevo. Consulta el ejemplo que se incluye más abajo .
Ejemplo de definición de un componente espacial para un subconjunto de etiquetas semánticas
// New example semantic label set.
typedef enum XrSpatialExampleSemanticLabelEXT {
  // ... label values
} XrSpatialExampleSemanticLabelEXT;

/*
typedef enum XrSpatialCapabilityFeatureEXT {
  // .. existing values

  // new spatial feature value
  XR_SPATIAL_CAPABILITY_FEATURE_EXAMPLE_SEMANTIC_LABEL_SUBSET_EXT

  // .. existing values
} XrSpatialCapabilityFeatureEXT;
*/

// New spatial feaure configuration structure
typedef struct XrSpatialFeatureExampleSemanticLabelSubsetEXT {
    XrStructureType                             type;
    const void* XR_MAY_ALIAS                    next;
    uint32_t                                    semanticLabelCount;
    const XrSpatialExampleSemanticLabelEXT*     semanticLabels;
} XrSpatialFeatureExampleSemanticLabelSubsetEXT;
Ejemplo de extensión de etiqueta semántica espacial
typedef enum XrSpatialExamplePlaneSemanticLabelExtensionEXT {
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_UNCATEGORIZED_EXT = 1,
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_FLOOR_EXT = 2,
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_WALL_EXT = 3,
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_CEILING_EXT = 4,
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_TABLE_EXT = 5,
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_DOOR_EXT = 6,
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_WINDOW_EXT = 7,
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialExamplePlaneSemanticLabelExtensionEXT;

Considera el ejemplo anterior, en el que una extensión define una enumeración XrSpatialExamplePlaneSemanticLabelExtensionEXT para extender el XrSpatialPlaneSemanticLabelEXT existente con valores que representen puertas y ventanas. La especificación de la nueva enumeración debe incluir texto para el siguiente formulario:

For all non-UNCATEGORIZED label enumerants in elink:XrSpatialPlaneSemanticLabelEXT,
the runtime must: return that enumerant if and only if it returns the corresponding
label enumerant from elink:XrSpatialExamplePlaneSemanticLabelExtensionEXT with the same value
i.e.
the ename:XR_SPATIAL_COMPONENT_TYPE_PLANE_SEMANTIC_LABEL_EXT value for that entity must:
correspond with the ename:XR_SPATIAL_COMPONENT_TYPE_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_EXT values
according to the following table -

[width="100%",options="header"]
|====
| XrSpatialExamplePlaneSemanticLabelExtensionEXT                | XrSpatialPlaneSemanticLabelEXT
| XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_FLOOR_EXT   | XR_SPATIAL_PLANE_SEMANTIC_LABEL_FLOOR_EXT
| XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_WALL_EXT    | XR_SPATIAL_PLANE_SEMANTIC_LABEL_WALL_EXT
| XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_CEILING_EXT | XR_SPATIAL_PLANE_SEMANTIC_LABEL_CEILING_EXT
| XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_TABLE_EXT   | XR_SPATIAL_PLANE_SEMANTIC_LABEL_TABLE_EXT
| XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_DOOR_EXT    | XR_SPATIAL_PLANE_SEMANTIC_LABEL_UNCATEGORIZED_EXT
| XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_WINDOW_EXT  | XR_SPATIAL_PLANE_SEMANTIC_LABEL_UNCATEGORIZED_EXT
|====

Macros nuevas

Nuevos tipos de bases

  • XrSpatialBufferIdEXT
  • XrSpatialEntityIdEXT

Nuevos tipos de objetos

Comandos nuevos

Estructuras nuevas

Enums nuevas

Nuevas constantes de enum

  • XR_EXT_SPATIAL_ENTITY_EXTENSION_NAME
  • XR_EXT_spatial_entity_SPEC_VERSION

  • Extiende XrObjectType :

    • XR_OBJECT_TYPE_SPATIAL_CONTEXT_EXT
    • XR_OBJECT_TYPE_SPATIAL_ENTITY_EXT
    • XR_OBJECT_TYPE_SPATIAL_SNAPSHOT_EXT

  • Extiende XrResult :

    • XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT
    • XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT
    • XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT
    • XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT
    • XR_ERROR_SPATIAL_COMPONENT_UNSUPPORTED_FOR_CAPABILITY_EXT
    • XR_ERROR_SPATIAL_ENTITY_ID_INVALID_EXT

  • Extiende XrStructureType :

    • XR_TYPE_CREATE_SPATIAL_CONTEXT_COMPLETION_EXT
    • XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_EXT
    • XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_INFO_EXT
    • XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT
    • XR_TYPE_SPATIAL_BUFFER_GET_INFO_EXT
    • XR_TYPE_SPATIAL_CAPABILITY_COMPONENT_TYPES_EXT
    • XR_TYPE_SPATIAL_COMPONENT_BOUNDED_2D_LIST_EXT
    • XR_TYPE_SPATIAL_COMPONENT_BOUNDED_3D_LIST_EXT
    • XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT
    • XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_RESULT_EXT
    • XR_TYPE_SPATIAL_COMPONENT_MESH_3D_LIST_EXT
    • XR_TYPE_SPATIAL_COMPONENT_PARENT_LIST_EXT
    • XR_TYPE_SPATIAL_CONTEXT_CREATE_INFO_EXT
    • XR_TYPE_SPATIAL_DISCOVERY_SNAPSHOT_CREATE_INFO_EXT
    • XR_TYPE_SPATIAL_ENTITY_FROM_ID_CREATE_INFO_EXT
    • XR_TYPE_SPATIAL_FILTER_TRACKING_STATE_EXT
    • XR_TYPE_SPATIAL_UPDATE_SNAPSHOT_CREATE_INFO_EXT

Problemas

  • ¿Una sola entidad siempre deriva de un solo componente?

    • Resuelto
    • Respuesta: No. Depende completamente del entorno de ejecución en función de sus propias capacidades de seguimiento y de cómo quiera representar una entidad detectada. La especificación no prescribe ninguna representación particular de la entidad espacial, excepto los componentes garantizados de una capacidad determinada para establecer una expectativa mínima. Un entorno de ejecución puede combinar entidades detectadas por capacidades independientes y representarlas como una sola entidad con los componentes garantizados de todas las capacidades que ayudaron a identificarla. Un ejemplo de esto podría ser que las mesas se puedan detectar con una función de seguimiento de planos y una función de seguimiento de objetos, en la que el seguimiento de planos proporcione el componente XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT en la entidad y el seguimiento de objetos proporcione XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT . Un entorno de ejecución determinado puede proporcionar la tabla como 2 entidades independientes, cada una con su propio conjunto de componentes garantizados, mientras que otros entornos de ejecución pueden proporcionar solo 1 entidad para representar la tabla y tener XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT y XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT en la misma entidad. Lo importante aquí es que una entidad espacial determinada puede tener, como máximo, un solo componente de cualquier tipo de componente determinado. Por lo tanto, si los datos de los componentes producidos por las diferentes capacidades entran en conflicto para una entidad determinada, el entorno de ejecución debe representarlos como 2 entidades independientes.

Historial de versiones

  • Revisión 1, 12 de abril de 2024 (Nihav Jain, Google)

    • Descripción inicial de la extensión