Android XR for OpenXR | Android Developers

The Android XR SDK has reached Developer Preview 4, and we want your feedback! Try things out, and visit our support page to reach out.

XR_EXT_spatial_entity

Name String

XR_EXT_spatial_entity

Extension Type

Instance extension

Registered Extension Number

741

Revision

Ratification Status

Ratified

Extension and Version Dependencies

XR_EXT_future

Contributors

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

Overview

This extension introduces the concepts and foundations for scene understanding and spatial reasoning in OpenXR. This unifies several related but distinct areas of functionality, which are enumerated, configured, and interacted with in a broadly uniform way as defined by this extension. As this extension lacks concrete definitions of any one of these functional areas, the formal specification text tends to be somewhat abstract. Examples included in this extension specification text refers at times to functionality defined in a forthcoming or hypothetical related extension for the purpose of illustration, without inherently limiting or specifying such additional functionality.

The broad pieces of this extension are the following:

Spatial entities : The functionality is centered around entities , which provide very little functionality on their own.
Spatial components : These entities have components associated with them that provide data and behaviors.
Spatial component types : Each spatial component is of a specific component type , and any given entity has at most a single component of any given component type .
Spatial context : All spatial entity interaction occurs in a context after an initialization and configuration phase.
Spatial capabilities : Spatial entity manipulation is broadly provided by capabilities . A capability is some unit of functionality, for example (without limitation) application-defined anchors, plane detection, or image tracking. Each capability is typically defined in a separate extension (enabled at instance creation as usual) and is enabled for a specific context at the time of creation.
Each capability is associated with a set of component types for which components are present on every entity exposed by that capability . The extension defining a capability specifies which component types are mandatory for the capability ("guaranteed"), while that same extension or others may specify optional component types provided by some potential implementations. Any number of capabilities might provide entities with components of a given component type , which are uniformly usable no matter the capability that produced it.
Spatial capability features : Further, some capabilities require configuration, and thus are parameterized by capability features .

This extension provides a mechanism for enumerating the components provided by each capability supported on the current system, both the mandatory and any optional components .

As some implementations may require different degrees of parameterization for capabilities , this extension provides a mechanism for enumerating the supported capability features associated with a given capability in the current system.

This extension also defines several common components expected to be used across a wide range of capabilities .

Spatial Entity

Spatial entities are entities that exist in some space, that have various associated data organized into components. They may be any of the following:

Physical (e.g. planar surfaces like walls and floors, objects like chairs and bookcases, etc.)
Virtual (e.g. content placed and shared by another application or user),
App-defined (e.g. application marking an area as the "living room" or "kitchen", or marking a point as the location to place the TV etc.)

Things which are exposed via the action system, like controllers or eye gaze, are not intended to be modeled as spatial entities.

Spatial entities in OpenXR are modeled as an Entity-Component system . Each spatial entity has a set of components, and each component provides a unique set of data and behaviors for that entity.

Spatial entities are represented by either an XrSpatialEntityIdEXT atom or an XrSpatialEntityEXT handle, details of which are provided in the Spatial Entity Representations section.

Spatial Component Types

A spatial entity has one or more components which provide data or behaviors for that entity. See Common Components for some common components defined by this extension.

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_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialComponentTypeEXT;

The XrSpatialComponentTypeEXT enumeration identifies the different types of components that the runtime may support.

Not all component types listed are provided by this extension on its own: some require additional extensions to be enabled at instance creation time, as documented.

The enumerants have the following values:

Enum Description

XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT

Component that provides the 2D bounds for a spatial entity. Corresponding list structure is XrSpatialComponentBounded2DListEXT ; Corresponding data structure is XrSpatialBounded2DDataEXT

XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT

Component that provides the 3D bounds for a spatial entity. Corresponding list structure is XrSpatialComponentBounded3DListEXT ; Corresponding data structure is XrBoxf

XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT

Component that provides the XrSpatialEntityIdEXT of the parent for a spatial entity. Corresponding list structure is XrSpatialComponentParentListEXT ; Corresponding data structure is XrSpatialEntityIdEXT

XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT

Component that provides a 3D mesh for a spatial entity. Corresponding list structure is XrSpatialComponentMesh3DListEXT ; Corresponding data structure is XrSpatialMeshDataEXT

XR_SPATIAL_COMPONENT_TYPE_PLANE_ALIGNMENT_EXT

Component that provides the plane alignment enum for a spatial entity. Corresponding list structure is XrSpatialComponentPlaneAlignmentListEXT ; Corresponding data structure is XrSpatialPlaneAlignmentEXT (Added by the XR_EXT_spatial_plane_tracking extension)

XR_SPATIAL_COMPONENT_TYPE_MESH_2D_EXT

Component that provides a 2D mesh for a spatial entity. Corresponding list structure is XrSpatialComponentMesh2DListEXT ; Corresponding data structure is XrSpatialMeshDataEXT (Added by the XR_EXT_spatial_plane_tracking extension)

XR_SPATIAL_COMPONENT_TYPE_POLYGON_2D_EXT

Component that provides a 2D boundary polygon for a spatial entity. Corresponding list structure is XrSpatialComponentPolygon2DListEXT ; Corresponding data structure is XrSpatialPolygon2DDataEXT (Added by the XR_EXT_spatial_plane_tracking extension)

XR_SPATIAL_COMPONENT_TYPE_PLANE_SEMANTIC_LABEL_EXT

Component that provides a semantic label for a plane. Corresponding list structure is XrSpatialComponentPlaneSemanticLabelListEXT ; Corresponding data structure is XrSpatialPlaneSemanticLabelEXT (Added by the XR_EXT_spatial_plane_tracking extension)

XR_SPATIAL_COMPONENT_TYPE_MARKER_EXT

A component describing the marker type, id and location. Corresponding list structure is XrSpatialComponentMarkerListEXT ; Corresponding data structure is XrSpatialMarkerDataEXT (Added by the XR_EXT_spatial_marker_tracking extension)

XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_EXT

Component that provides a semantic label for a scene; Corresponding list structure is XrSpatialComponentObjectSemanticLabelListEXT . Corresponding data structure is XrSpatialObjectSemanticLabelEXT . (Added by the XR_EXT_spatial_object_tracking extension)

XR_SPATIAL_COMPONENT_TYPE_KEYBOARD_SEMANTIC_LABEL_EXT

Component that provides a semantic label for a keyboard; Corresponding list structure is XrSpatialComponentKeyboardSemanticLabelListEXT . Corresponding data structure is XrSpatialKeyboardSemanticLabelEXT (Added by the XR_EXT_spatial_object_tracking extension)

XR_SPATIAL_COMPONENT_TYPE_MOUSE_SEMANTIC_LABEL_EXT

Component that provides a semantic label for a mouse; Corresponding list structure is XrSpatialComponentMouseSemanticLabelListEXT . Corresponding data structure is XrSpatialMouseSemanticLabelEXT (Added by the XR_EXT_spatial_object_tracking extension)

XR_SPATIAL_COMPONENT_TYPE_ANCHOR_EXT

Component that provides the location for an anchor. Corresponding list structure is XrSpatialComponentAnchorListEXT ; Corresponding data structure is XrPosef (Added by the XR_EXT_spatial_anchor extension)

XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_EXT

Component that provides the persisted UUID for a spatial entity. Corresponding list structure is XrSpatialComponentPersistenceListEXT ; Corresponding data structure is XrSpatialPersistenceDataEXT (Added by the XR_EXT_spatial_persistence extension)

XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT

A component describing the planar image type. Corresponding list structure is XrSpatialComponentImage2DListEXT ; Corresponding data structure is XrSpatialImageSizeEXT . (Added by the XR_EXT_spatial_image_tracking extension)

XR_SPATIAL_COMPONENT_TYPE_MESH_3D_NORMALS_EXT

Component that provides the normals for the 3D mesh of a spatial entity. Corresponding list structure is XrSpatialComponentMesh3DNormalsListEXT ; Corresponding data structure is XrSpatialBufferEXT (Added by the XR_EXT_spatial_mesh_tracking extension)

XR_SPATIAL_COMPONENT_TYPE_MESH_3D_VERTEX_SEMANTIC_LABELS_EXT

Component that provides the per-vertex semantic labels for the 3D mesh of a spatial entity. Corresponding list structure is XrSpatialComponentMesh3DVertexSemanticLabelsListEXT ; Corresponding data structure is XrSpatialBufferEXT ; Data within the buffer maps to XrSpatialMeshSemanticLabelEXT (Added by the XR_EXT_spatial_mesh_tracking extension)

XR_SPATIAL_COMPONENT_TYPE_MESH_3D_TRIANGLE_SEMANTIC_LABELS_EXT

Component that provides the per-triangle-face semantic labels for the 3D mesh of a spatial entity. Corresponding list structure is XrSpatialComponentMesh3DTriangleSemanticLabelsListEXT ; Corresponding data structure is XrSpatialBufferEXT ; Data within the buffer maps to XrSpatialMeshSemanticLabelEXT (Added by the XR_EXT_spatial_mesh_tracking extension)

XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_ANDROID

Component that provides a semantic label for a object; Corresponding list structure is XrSpatialComponentObjectSemanticLabelListANDROID ; Corresponding data structure is XrSpatialObjectSemanticLabelANDROID (Added by the XR_ANDROID_spatial_object_tracking extension)

XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID

Component that provides the pose of a raycast hit on an entity. Corresponding list structure is XrSpatialComponentRaycastResultListANDROID ; Corresponding data structure is XrSpatialRaycastResultDataANDROID (Added by the XR_ANDROID_spatial_discovery_raycast extension)

XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID

Component that provides entity ID of the entity subsuming the attached entity. Corresponding list structure is XrSpatialComponentSubsumedByListANDROID ; Corresponding data structure is XrSpatialEntityIdEXT (Added by the XR_ANDROID_spatial_component_subsumed_by extension)

XR_SPATIAL_COMPONENT_TYPE_ROOM_ANDROIDSYS

Component that provides the dimensions and the room type of a shoebox; Corresponding list structure is XrSpatialComponentRoomListANDROIDSYS ; Corresponding data structure is XrSpatialRoomDataANDROIDSYS (Added by the XR_ANDROIDSYS_spatial_room_tracking extension)

XR_SPATIAL_COMPONENT_TYPE_MATERIAL_TYPE_ANDROIDSYS

Component that provides the material type of a boudary surface; Corresponding list structure is XrSpatialComponentMaterialTypeListANDROIDSYS ; Corresponding data structure is XrSpatialMaterialTypeANDROIDSYS (Added by the XR_ANDROIDSYS_spatial_room_tracking extension)

XR_SPATIAL_COMPONENT_TYPE_CONFIDENCE_ANDROIDSYS

Component that provides the confidence of a trackable; Corresponding list structure is XrSpatialComponentConfidenceListANDROIDSYS ; Corresponding data structure is float (Added by the XR_ANDROIDSYS_spatial_room_tracking extension)

XR_SPATIAL_COMPONENT_TYPE_ROOM_EMPTINESS_ANDROIDSYS

Component that provides the emptiness of a room; Corresponding list structure is XrSpatialComponentRoomEmptinessListANDROIDSYS ; Corresponding data structure is float (Added by the XR_ANDROIDSYS_spatial_room_tracking extension)

XR_SPATIAL_COMPONENT_TYPE_OCCUPANCY_GRID_ANDROIDX1

Component that provides information of occupancy grid on the attached entity. Corresponding list structure is XrSpatialComponentOccupancyGridListANDROIDX1 ; Corresponding data structure is XrSpatialOccupancyGridDataANDROIDX1 (Added by the XR_ANDROIDX1_spatial_occupancy_grid extension)

XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID

A component describing a quad annotation. Corresponding list structure is XrSpatialComponentAnnotationQuadListANDROID ; Corresponding data structure is XrSpatialAnnotationQuadDataANDROID (Added by the XR_ANDROID_spatial_annotation_tracking extension)

XR_SPATIAL_COMPONENT_TYPE_STREETSCAPE_GEOMETRY_METADATA_ANDROIDX2

Component that provides the metadata for a streetscape geometry; Corresponding list structure is XrSpatialComponentStreetscapeGeometryMetadataListANDROIDX2 ; Corresponding data structure is XrSpatialStreetscapeGeometryMetadataANDROIDX2 (Added by the XR_ANDROIDX2_geospatial_streetscape extension)

Spatial Capabilities and Setup

Spatial capabilities define a runtime’s abilities to discover entities that have a guaranteed set of components on them. Applications enable the components of a spatial capability when creating the XrSpatialContextEXT , and the runtime in turn must provide only the enabled components on discovered entities. e.g. If a runtime reports that one of the components for a given capability is "semantic labels", it means the application can enable semantic labels via the configuration for that capability and the runtime must only provide the semantic label component if it is configured.

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;

The XrSpatialCapabilityEXT enumeration identifies the different types of capabilities that the runtime may support.

The enumerants have the following values:

Enum Description

XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT

Plane tracking (Added by the XR_EXT_spatial_plane_tracking extension)

XR_SPATIAL_CAPABILITY_MARKER_TRACKING_QR_CODE_EXT

Capability to be able to detect and track QR codes. (Added by the XR_EXT_spatial_marker_tracking extension)

XR_SPATIAL_CAPABILITY_MARKER_TRACKING_MICRO_QR_CODE_EXT

Capability to be able to detect and track Micro QR codes. (Added by the XR_EXT_spatial_marker_tracking extension)

XR_SPATIAL_CAPABILITY_MARKER_TRACKING_ARUCO_MARKER_EXT

Capability to be able to detect and track Aruco Markers. (Added by the XR_EXT_spatial_marker_tracking extension)

XR_SPATIAL_CAPABILITY_MARKER_TRACKING_APRIL_TAG_EXT

Capability to be able to detect and track AprilTags. (Added by the XR_EXT_spatial_marker_tracking extension)

XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT

Object tracking (Added by the XR_EXT_spatial_object_tracking extension)

XR_SPATIAL_CAPABILITY_ANCHOR_EXT

Capability to be able to create spatial anchors (Added by the XR_EXT_spatial_anchor extension)

XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT

Capability to be able to detect and track planar reference images. (Added by the XR_EXT_spatial_image_tracking extension)

XR_SPATIAL_CAPABILITY_MESH_TRACKING_EXT

Capability to track the mesh of an environment. (Added by the XR_EXT_spatial_mesh_tracking extension)

XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_ANDROID

Object tracking (Added by the XR_ANDROID_spatial_object_tracking extension)

XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID

Raycast against depth buffer (Added by the XR_ANDROID_spatial_discovery_raycast extension)

XR_SPATIAL_CAPABILITY_ROOM_TRACKING_ANDROIDSYS

Capability to track a room (Added by the XR_ANDROIDSYS_spatial_room_tracking extension)

XR_SPATIAL_CAPABILITY_ROOM_BOUNDARY_TRACKING_ANDROIDSYS

Capability to track a room boundary (Added by the XR_ANDROIDSYS_spatial_room_tracking extension)

XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID

Annotation tracking (Added by the XR_ANDROID_spatial_annotation_tracking extension)

XR_SPATIAL_CAPABILITY_STREETSCAPE_GEOMETRY_ANDROIDX2

Streetscape geometry (Added by the XR_ANDROIDX2_geospatial_streetscape extension)

The xrEnumerateSpatialCapabilitiesEXT function is defined as:

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

Parameter Descriptions

instance is a handle to an XrInstance .
systemId is the XrSystemId whose spatial capabilities will be enumerated.
capabilityCapacityInput is the capacity of the capabilities array, or 0 to indicate a request to retrieve the required capacity.
capabilityCountOutput is the number of capabilities, or the required capacity in the case that capabilityCapacityInput is insufficient.
capabilities is an array of XrSpatialCapabilityEXT . It can be NULL if capabilityCapacityInput is 0.
See the Buffer Size Parameters section for a detailed description of retrieving the required capabilities size.

The application can enumerate the list of spatial capabilities supported by a given XrSystemId using xrEnumerateSpatialCapabilitiesEXT .

The runtime must not enumerate the spatial capabilities whose extension is not enabled for instance .

Valid Usage (Implicit)

The XR_EXT_spatial_entity extension must be enabled prior to calling xrEnumerateSpatialCapabilitiesEXT
instance must be a valid XrInstance handle
capabilityCountOutput must be a pointer to a uint32_t value
If capabilityCapacityInput is not 0 , capabilities must be a pointer to an array of capabilityCapacityInput XrSpatialCapabilityEXT values

Return Codes

Success

XR_SUCCESS

Failure

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

The xrEnumerateSpatialCapabilityComponentTypesEXT function is defined as:

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

Parameter Descriptions

instance is a handle to an XrInstance .
systemId is the XrSystemId whose spatial capability components will be enumerated.
capability is the XrSpatialCapabilityEXT for which the components will be enumerated.
capabilityComponents is a pointer to an XrSpatialCapabilityComponentTypesEXT , which is an input/output structure in which an application-allocated array is populated.

This function enumerates the component types that the given capability provides on its entities in the system as configured.

The application can use the component types enumerated in XrSpatialCapabilityComponentTypesEXT :: componentTypes to understand the full set of components that the systemId supports for capability and can use this list to determine what a valid configuration for capability is when creating an XrSpatialContextEXT for it.

The runtime must return XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT if capability is not enumerated by xrEnumerateSpatialCapabilitiesEXT .

The runtime must not enumerate the spatial component types whose extension is not enabled for instance .

Valid Usage (Implicit)

The XR_EXT_spatial_entity extension must be enabled prior to calling xrEnumerateSpatialCapabilityComponentTypesEXT
instance must be a valid XrInstance handle
capability must be a valid XrSpatialCapabilityEXT value
capabilityComponents must be a pointer to an XrSpatialCapabilityComponentTypesEXT structure

Return Codes

Success

XR_SUCCESS

Failure

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

The XrSpatialCapabilityComponentTypesEXT structure is defined as:

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

Member Descriptions

type is the XrStructureType of this structure.
next is NULL or a pointer to the next structure in a structure chain. No such structures are defined in core OpenXR or this extension.
componentTypeCapacityInput is the capacity of the array, or 0 to indicate a request to retrieve the required capacity.
componentTypeCountOutput is the number of component types, or the required capacity in the case that componentTypeCapacityInput is insufficient.
componentTypes is an array of XrSpatialComponentTypeEXT . It can be NULL if componentTypeCapacityInput is 0.
See the Buffer Size Parameters section for a detailed description of retrieving the required componentTypes size.

Valid Usage (Implicit)

The XR_EXT_spatial_entity extension must be enabled prior to using XrSpatialCapabilityComponentTypesEXT
type must be XR_TYPE_SPATIAL_CAPABILITY_COMPONENT_TYPES_EXT
next must be NULL or a valid pointer to the next structure in a structure chain
If componentTypeCapacityInput is not 0 , componentTypes must be a pointer to an array of componentTypeCapacityInput XrSpatialComponentTypeEXT values

Spatial capability features

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;

Some capabilities have parameters exposed to the application to configure how the component data is computed by the runtime. These dimensions of parameterization/configurability are known as capability features. E.g. for an image tracking capability, a runtime may support a feature for the application to specify whether the tracked images are stationary or not.

Providing this information to the runtime via a configuration structure must not change the set of component types present on the associated entities, e.g. on the tracked image. However, the runtime may be able to optimize e.g. the tracking abilities of the image tracking capability and provide a better experience to the application.

Such features are represented by XrSpatialCapabilityFeatureEXT and the application enumerates them by using xrEnumerateSpatialCapabilityFeaturesEXT .

Each capability feature has a corresponding configuration structure to enable it. Such configuration structures must be chained to XrSpatialCapabilityConfigurationBaseHeaderEXT :: next of the corresponding capability.

The enumerants have the following values:

Enum Description

XR_SPATIAL_CAPABILITY_FEATURE_MARKER_TRACKING_FIXED_SIZE_MARKERS_EXT

Capability feature to allow applications to specify the size for the markers. Corresponding config structure is XrSpatialMarkerSizeEXT (Added by the XR_EXT_spatial_marker_tracking extension)

XR_SPATIAL_CAPABILITY_FEATURE_MARKER_TRACKING_STATIC_MARKERS_EXT

Capability feature to allow applications to specify if markers are static. Corresponding config structure is XrSpatialMarkerStaticOptimizationEXT (Added by the XR_EXT_spatial_marker_tracking extension)

XR_SPATIAL_CAPABILITY_FEATURE_OBJECT_SEMANTIC_LABEL_SUBSET_EXT

Spatial feature allowing applications to specify a subset of labels from XrSpatialObjectSemanticLabelEXT for the runtime to track. Corresponding config structure is XrSpatialFeatureObjectSemanticLabelSubsetEXT . (Added by the XR_EXT_spatial_object_tracking extension)

XR_SPATIAL_CAPABILITY_FEATURE_SPHERE_BOUNDS_FILTER_ANDROID

The runtime supports XrSpatialBoundsSpherefANDROID filter for XrSpatialDiscoverySnapshotCreateInfoEXT ; This does not require any configuration structure to be included during spatial context creation. (Added by the XR_ANDROID_spatial_discovery_bounds extension)

XR_SPATIAL_CAPABILITY_FEATURE_BOX_BOUNDS_FILTER_ANDROID

The runtime supports XrSpatialBoundsBoxfANDROID filter for XrSpatialDiscoverySnapshotCreateInfoEXT ; This does not require any configuration structure to be included during spatial context creation. (Added by the XR_ANDROID_spatial_discovery_bounds extension)

XR_SPATIAL_CAPABILITY_FEATURE_FRUSTUM_BOUNDS_FILTER_ANDROID

The runtime supports XrSpatialBoundsFrustumfANDROID filter for XrSpatialDiscoverySnapshotCreateInfoEXT ; This does not require any configuration structure to be included during spatial context creation. (Added by the XR_ANDROID_spatial_discovery_bounds extension)

XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT

The runtime supports automatically deducing the physical size of detected and tracked images. Corresponding config structure is XrSpatialImageSizeEXT (Added by the XR_EXT_spatial_image_tracking extension)

XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT

The runtime supports XrSpatialImageStaticOptimizationEXT . Corresponding config structure is XrSpatialImageStaticOptimizationEXT . (Added by the XR_EXT_spatial_image_tracking extension)

XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXT

The runtime supports XrSpatialImageSizeEXT . Corresponding config structure is XrSpatialImageSizeEXT (Added by the XR_EXT_spatial_image_tracking extension)

XR_SPATIAL_CAPABILITY_FEATURE_TRACK_WATERTIGHT_MESH_EXT

Capability feature to track a watertight mesh of the environment. Corresponding config structure is XrSpatialFeatureTrackWatertightMeshEXT . (Added by the XR_EXT_spatial_mesh_tracking extension)

The xrEnumerateSpatialCapabilityFeaturesEXT function is defines as:

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

Parameter Descriptions

instance is a handle to an XrInstance .
systemId is the XrSystemId whose spatial capability features will be enumerated.
capability is the XrSpatialCapabilityEXT for which the features will be enumerated.
capabilityFeatureCapacityInput is the capacity of the array, or 0 to indicate a request to retrieve the required capacity.
capabilityFeatureCountOutput is the number of features, or the required capacity in the case that capabilityFeatureCapacityInput is insufficient.
capabilityFeatures is an array of XrSpatialCapabilityFeatureEXT . It can be NULL if capabilityFeatureCapacityInput is 0.
See the Buffer Size Parameters section for a detailed description of retrieving the required capabilityFeatures size.

The application discovers the features supported by a given system for a XrSpatialCapabilityEXT by using xrEnumerateSpatialCapabilityFeaturesEXT .

For capabilities that have features exposed, the application selects the feature or features to enable and provides the corresponding configuration structure in the next chain of the capability configuration structures in XrSpatialContextCreateInfoEXT :: capabilityConfigs .

If capability is not a capability enumerated by xrEnumerateSpatialCapabilitiesEXT , the runtime must return XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT .

The runtime must not enumerate the spatial capability features whose extension is not enabled for instance .

Valid Usage (Implicit)

The XR_EXT_spatial_entity extension must be enabled prior to calling xrEnumerateSpatialCapabilityFeaturesEXT
instance must be a valid XrInstance handle
capability must be a valid XrSpatialCapabilityEXT value
capabilityFeatureCountOutput must be a pointer to a uint32_t value
If capabilityFeatureCapacityInput is not 0 , capabilityFeatures must be a pointer to an array of capabilityFeatureCapacityInput XrSpatialCapabilityFeatureEXT values

Return Codes

Success

XR_SUCCESS

Failure

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

Spatial Context

Create a spatial context

XR_DEFINE_HANDLE(XrSpatialContextEXT)

The XrSpatialContextEXT handle represents the resources for discovering and updating some number of spatial entities in the environment of the user. Application can use this handle to discover and update spatial entities using other functions in this extension.

The xrCreateSpatialContextAsyncEXT function is defined as:

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

Parameter Descriptions

session is an XrSession in which the spatial context will be active.
createInfo is the XrSpatialContextCreateInfoEXT used to specify the spatial context parameters.
future is a pointer to an XrFutureEXT .

The application can create an XrSpatialContextEXT handle by:

Providing XrSpatialCapabilityConfigurationBaseHeaderEXT derived structures in XrSpatialContextCreateInfoEXT :: capabilityConfigs to enable capabilities and enable components for that capability.
Configuring the capabilities themselves with the corresponding configuration structures of its XrSpatialCapabilityFeatureEXT .

The runtime must return XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT if XrSpatialContextCreateInfoEXT ::capabilityConfigCount is 0. A spatial context handle needs at least one capability.

The runtime must return XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT if any capability in the XrSpatialContextCreateInfoEXT :: capabilityConfigs array is not enumerated by xrEnumerateSpatialCapabilitiesEXT .

The runtime must return XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT if any XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponentCount in XrSpatialContextCreateInfoEXT :: capabilityConfigs is 0. A capability configuration is incomplete without a list of component types to enable for that capability.

The runtime must return XR_ERROR_SPATIAL_COMPONENT_UNSUPPORTED_FOR_CAPABILITY_EXT if any component type listed in XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents is not enumerated for XrSpatialCapabilityConfigurationBaseHeaderEXT :: capability in xrEnumerateSpatialCapabilityComponentTypesEXT .

If any of the structures in the next chain of XrSpatialContextCreateInfoEXT :: capabilityConfigs corresponds to an XrSpatialCapabilityFeatureEXT that is not enumerated for that capability in xrEnumerateSpatialCapabilityFeaturesEXT , the runtime must ignore that XrSpatialCapabilityFeatureEXT structure.

The runtime must return XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT if XrSpatialContextCreateInfoEXT :: capabilityConfigs contains multiple structures with the same XrSpatialCapabilityConfigurationBaseHeaderEXT :: capability .

To ensure optimal use of system resources, the runtime may use the configurations provided in XrSpatialContextCreateInfoEXT array to prepare itself for spatial requests to come in. For example, a runtime that supports plane tracking capability may only begin its plane tracking pipeline if a spatial context handle containing the plane tracking capability is created by the application. If the configured capabilities have a long warm-up time, calls to xrCreateSpatialDiscoverySnapshotAsyncEXT may result in an empty snapshot. Application can wait for XrEventDataSpatialDiscoveryRecommendedEXT before using xrCreateSpatialDiscoverySnapshotAsyncEXT to be sure that the underlying tracking services have warmed up.

If a runtime enforces a permission system to control application access to the spatial capabilities being configured for the XrSpatialContextEXT , then the runtime must return XR_ERROR_PERMISSION_INSUFFICIENT if those permissions have not been granted to this application.

This function starts an asynchronous operation and creates a corresponding XrFutureEXT , usable with xrPollFutureEXT and related functions. The return value of this function only indicates whether the parameters were acceptable to schedule the asynchronous operation. The corresponding completion function is xrCreateSpatialContextCompleteEXT , usable when a future from this function is in the READY state, with outputs populated by that function in the completion structure XrCreateSpatialContextCompletionEXT .

Valid Usage (Implicit)

The XR_EXT_spatial_entity extension must be enabled prior to calling xrCreateSpatialContextAsyncEXT
session must be a valid XrSession handle
createInfo must be a pointer to a valid XrSpatialContextCreateInfoEXT structure
future must be a pointer to an XrFutureEXT value

Return Codes

Success

XR_SUCCESS
XR_SESSION_LOSS_PENDING

Failure

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

The XrSpatialContextCreateInfoEXT structure is defined as:

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

Member Descriptions

type is the XrStructureType of this structure.
next is NULL or a pointer to the next structure in a structure chain. No such structures are defined in core OpenXR or this extension.
capabilityConfigCount is a uint32_t describing the count of elements in the capabilityConfigs array.
capabilityConfigs is a pointer to an array of XrSpatialCapabilityConfigurationBaseHeaderEXT pointers.

The XrSpatialContextCreateInfoEXT structure describes the information to create an XrSpatialContextEXT handle.

Valid Usage (Implicit)

The XR_EXT_spatial_entity extension must be enabled prior to using XrSpatialContextCreateInfoEXT
type must be XR_TYPE_SPATIAL_CONTEXT_CREATE_INFO_EXT
next must be NULL or a valid pointer to the next structure in a structure chain . See also: XrSpatialContextPersistenceConfigEXT
capabilityConfigs must be a pointer to an array of capabilityConfigCount valid XrSpatialCapabilityConfigurationBaseHeaderEXT -based structures. See also: XrSpatialCapabilityConfigurationAnchorEXT , XrSpatialCapabilityConfigurationAprilTagEXT , XrSpatialCapabilityConfigurationArucoMarkerEXT , XrSpatialCapabilityConfigurationDepthRaycastANDROID , XrSpatialCapabilityConfigurationImageTrackingEXT , XrSpatialCapabilityConfigurationMeshTrackingEXT , XrSpatialCapabilityConfigurationMicroQrCodeEXT , XrSpatialCapabilityConfigurationObjectTrackingANDROID , XrSpatialCapabilityConfigurationObjectTrackingEXT , XrSpatialCapabilityConfigurationPlaneTrackingEXT , XrSpatialCapabilityConfigurationQrCodeEXT , XrSpatialCapabilityConfigurationRoomBoundaryTrackingANDROIDSYS , XrSpatialCapabilityConfigurationRoomTrackingANDROIDSYS , XrSpatialCapabilityConfigurationStreetscapeGeometryANDROIDX2
The capabilityConfigCount parameter must be greater than 0

The XrSpatialCapabilityConfigurationBaseHeaderEXT structure is defined as:

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

This structure is not directly used in the API but instead its child structures can be used with XrSpatialContextCreateInfoEXT to configure spatial capabilities.

Member Descriptions

type is the XrStructureType of this structure.
next is NULL or a pointer to the next structure in a structure chain.
capability is an XrSpatialCapabilityEXT .
enabledComponentCount is a uint32_t describing the count of elements in the enabledComponents array.
enabledComponents is a pointer to an array of XrSpatialComponentTypeEXT .

The runtime must return XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT if capability is not enumerated by xrEnumerateSpatialCapabilitiesEXT . The runtime must return XR_ERROR_SPATIAL_COMPONENT_UNSUPPORTED_FOR_CAPABILITY_EXT if any component type listed in enabledComponents is not enumerated for capability in xrEnumerateSpatialCapabilityComponentTypesEXT .

Valid Usage (Implicit)

The XR_EXT_spatial_entity extension must be enabled prior to using XrSpatialCapabilityConfigurationBaseHeaderEXT
next must be NULL or a valid pointer to the next structure in a structure chain
capability must be a valid XrSpatialCapabilityEXT value
enabledComponents must be a pointer to an array of enabledComponentCount valid XrSpatialComponentTypeEXT values
The enabledComponentCount parameter must be greater than 0

The xrCreateSpatialContextCompleteEXT function is defined as:

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

Parameter Descriptions

session is the XrSession previously passed to xrCreateSpatialContextAsyncEXT :: session .
future is the XrFutureEXT received from xrCreateSpatialContextAsyncEXT .
completion is a pointer to an XrCreateSpatialContextCompletionEXT .

xrCreateSpatialContextCompleteEXT completes the asynchronous operation started by xrCreateSpatialContextAsyncEXT . The runtime must return XR_ERROR_FUTURE_PENDING_EXT if future is not in ready state. The runtime must return XR_ERROR_FUTURE_INVALID_EXT if future has already been completed or cancelled.

Valid Usage (Implicit)

The XR_EXT_spatial_entity extension must be enabled prior to calling xrCreateSpatialContextCompleteEXT
session must be a valid XrSession handle
completion must be a pointer to an XrCreateSpatialContextCompletionEXT structure

Return Codes

Success

XR_SUCCESS
XR_SESSION_LOSS_PENDING

Failure

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

The XrCreateSpatialContextCompletionEXT structure is defined as:

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

Member Descriptions

type is the XrStructureType of this structure.
next is NULL or a pointer to the next structure in a structure chain.
futureResult is the XrResult of the spatial context creation operation.
spatialContext is an XrSpatialContextEXT created using the data and configuration in xrCreateSpatialContextAsyncEXT :: createInfo .

Future Return Codes

futureResult values:

Success

XR_SUCCESS
XR_SESSION_LOSS_PENDING

Failure

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

If futureResult is a success code, spatialContext must be valid. If spatialContext is valid, it remains so only within the lifecycle of xrCreateSpatialContextAsyncEXT :: session or until the application destroys the spatialContext with xrDestroySpatialContextEXT , whichever comes first.

Valid Usage (Implicit)

The XR_EXT_spatial_entity extension must be enabled prior to using XrCreateSpatialContextCompletionEXT
type must be XR_TYPE_CREATE_SPATIAL_CONTEXT_COMPLETION_EXT
next must be NULL or a valid pointer to the next structure in a structure chain
futureResult must be a valid XrResult value
If spatialContext is not XR_NULL_HANDLE , spatialContext must be a valid XrSpatialContextEXT handle

Destroy the spatial context

The xrDestroySpatialContextEXT function is defined as:

XrResult xrDestroySpatialContextEXT(
    XrSpatialContextEXT                         spatialContext);

Parameter Descriptions

spatialContext is an XrSpatialContextEXT previously created by xrCreateSpatialContextAsyncEXT .

The application can call xrDestroySpatialContextEXT function to release the spatialContext handle and the underlying resources when finished with spatial entity discovery and update tasks. If there is no other valid XrSpatialContextEXT that was created with the same spatial capabilities as spatialContext , this call serves as a suggestion to the runtime to disable the tracking services required for those capabilities to save system resources.

Valid Usage (Implicit)

The XR_EXT_spatial_entity extension must be enabled prior to calling xrDestroySpatialContextEXT
spatialContext must be a valid XrSpatialContextEXT handle

Thread Safety

Access to spatialContext , and any child handles, must be externally synchronized

Return Codes

Success

XR_SUCCESS

Failure

XR_ERROR_FUNCTION_UNSUPPORTED
XR_ERROR_HANDLE_INVALID
XR_ERROR_RUNTIME_FAILURE

Spatial Entity Representations

Spatial Entity ID

XR_DEFINE_ATOM(XrSpatialEntityIdEXT)

XrSpatialEntityIdEXT is used to represent any kind of entity discovered by the runtime in the spatial environment of the user. An XrSpatialEntityIdEXT is valid for the XrSpatialContextEXT in which it is discovered, and the runtime must not reuse the same XrSpatialEntityIdEXT for different entities within the same XrSpatialContextEXT . Also, the runtime must not reuse the same XrSpatialEntityIdEXT across multiple XrSpatialContextEXT within the same XrSession regardless of whether it represents the same entity or different ones.

#define XR_NULL_SPATIAL_ENTITY_ID_EXT 0

XR_NULL_SPATIAL_ENTITY_ID_EXT is a reserved value representing an invalid XrSpatialEntityIdEXT . It may be passed to and returned from API functions only when specifically allowed.

Spatial Entity Handle

XR_DEFINE_HANDLE(XrSpatialEntityEXT)

The XrSpatialEntityEXT handle represents a spatial entity. An application can create such a handle to express its interest in a specific entity to the runtime.

Create Spatial Entity Handle from ID

The xrCreateSpatialEntityFromIdEXT function is defined as:

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

Parameter Descriptions

spatialContext is an XrSpatialContextEXT previously created using xrCreateSpatialContextAsyncEXT .
createInfo is a pointer to XrSpatialEntityFromIdCreateInfoEXT structure.
spatialEntity is the returned XrSpatialEntityEXT handle.

The application can use xrCreateSpatialEntityFromIdEXT to create an XrSpatialEntityEXT handle which is a reference to an entity that exists in the user’s environment.

The runtime must return XR_ERROR_SPATIAL_ENTITY_ID_INVALID_EXT if XrSpatialEntityFromIdCreateInfoEXT :: entityId is not a valid ID for spatialContext .

Valid Usage (Implicit)

The XR_EXT_spatial_entity extension must be enabled prior to calling xrCreateSpatialEntityFromIdEXT
spatialContext must be a valid XrSpatialContextEXT handle
createInfo must be a pointer to a valid XrSpatialEntityFromIdCreateInfoEXT structure
spatialEntity must be a pointer to an XrSpatialEntityEXT handle

Return Codes

Success

XR_SUCCESS
XR_SESSION_LOSS_PENDING

Failure

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

The XrSpatialEntityFromIdCreateInfoEXT structure is defined as:

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

Member Descriptions

type is the XrStructureType of this structure.
next is NULL or a pointer to the next structure in a structure chain. No such structures are defined in core OpenXR or this extension.
entityId is the XrSpatialEntityIdEXT of the entity that the application wants to create a handle for.

Valid Usage (Implicit)

The XR_EXT_spatial_entity extension must be enabled prior to using XrSpatialEntityFromIdCreateInfoEXT
type must be XR_TYPE_SPATIAL_ENTITY_FROM_ID_CREATE_INFO_EXT
next must be NULL or a valid pointer to the next structure in a structure chain

Destroy Spatial Entity Handle

The xrDestroySpatialEntityEXT function is defined as:

XrResult xrDestroySpatialEntityEXT(
    XrSpatialEntityEXT                          spatialEntity);

Parameter Descriptions

spatialEntity is a handle to an XrSpatialEntityEXT previously created by a function such as xrCreateSpatialEntityFromIdEXT .

The application can use xrDestroySpatialEntityEXT to release the spatialEntity handle when it is no longer interested in the entity referenced by this handle.

Valid Usage (Implicit)

The XR_EXT_spatial_entity extension must be enabled prior to calling xrDestroySpatialEntityEXT
spatialEntity must be a valid XrSpatialEntityEXT handle

Thread Safety

Access to spatialEntity , and any child handles, must be externally synchronized

Return Codes

Success

XR_SUCCESS

Failure

XR_ERROR_FUNCTION_UNSUPPORTED
XR_ERROR_HANDLE_INVALID
XR_ERROR_RUNTIME_FAILURE

Spatial Snapshot

XR_DEFINE_HANDLE(XrSpatialSnapshotEXT)

The application can create spatial snapshots for the purpose of discovering spatial entities or for updating its information about known spatial entities. The XrSpatialSnapshotEXT handle represents the immutable data for the discovered or updated spatial entities and a subset of their components as selected by the application. The spatial snapshot represents a coherent view of the entities and their component data. Once a snapshot is created, the snapshot’s data must remain constant while the snapshot is valid.

The application can create any number of snapshots it wants but must be mindful of the memory being allocated for each new snapshot and must destroy the snapshots once it no longer needs them.

Create discovery snapshot

The xrCreateSpatialDiscoverySnapshotAsyncEXT function is defined as:

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

Parameter Descriptions

spatialContext is an XrSpatialContextEXT previously created by using xrCreateSpatialContextAsyncEXT .
createInfo is a pointer to an XrSpatialDiscoverySnapshotCreateInfoEXT .
future is a pointer to an XrFutureEXT .

The application can discover spatial entities by creating a discovery snapshot by using xrCreateSpatialDiscoverySnapshotAsyncEXT .

This function starts an asynchronous operation and creates a corresponding XrFutureEXT , usable with xrPollFutureEXT and related functions. The return value of this function only indicates whether the parameters were acceptable to schedule the asynchronous operation. The corresponding completion function is xrCreateSpatialDiscoverySnapshotCompleteEXT , usable when a future from this function is in the READY state, with outputs populated by that function in the completion structure XrCreateSpatialDiscoverySnapshotCompletionEXT .

The application can submit multiple discovery snapshot creation requests without needing to wait for the previous one to be completed. The runtime may process and complete the snapshot creation in any order. The runtime may delay the completion of the discovery snapshot creation to throttle the application if it needs to reduce the use of system resources due to power, thermal or other policies of the device.

The application can use XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes to filter the list of entities and the components whose data the runtime must include in the snapshot. If the application provides a valid list of spatial component types in XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes , then the runtime must only include spatial entities in the snapshot that have at least one of the components provided in XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes . Also, the runtime must only include data for only those components in the snapshot.

The runtime must return XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT if any of the XrSpatialComponentTypeEXT in XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes are not enabled for the spatial capabilities passed to XrSpatialContextCreateInfoEXT :: capabilityConfigs when creating spatialContext .

If the application does not provide a list of spatial component types in XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes , the runtime must include all the spatial entities in the snapshot that have the set of components which are enumerated in XrSpatialCapabilityConfigurationBaseHeaderEXT ::enabledComponents for the capabilities configured for spatialContext . The runtime must include the data for all the enabled components of the capabilities configured for spatialContext .

If XrEventDataReferenceSpaceChangePending is queued before the completion of future , and XrEventDataReferenceSpaceChangePending :: poseValid is false, then the runtime may either create an XrSpatialSnapshotEXT that has no entities in it or set the XrSpatialEntityTrackingStateEXT of the entities that are no longer locatable in XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: baseSpace at XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: time to XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT or XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT . The runtime must not set XrCreateSpatialContextCompletionEXT :: futureResult to an error code because of XrEventDataReferenceSpaceChangePending .

Valid Usage (Implicit)

The XR_EXT_spatial_entity extension must be enabled prior to calling xrCreateSpatialDiscoverySnapshotAsyncEXT
spatialContext must be a valid XrSpatialContextEXT handle
createInfo must be a pointer to a valid XrSpatialDiscoverySnapshotCreateInfoEXT structure
future must be a pointer to an XrFutureEXT value

Return Codes

Success

XR_SUCCESS
XR_SESSION_LOSS_PENDING

Failure

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

The XrSpatialDiscoverySnapshotCreateInfoEXT structure is defined as:

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

Member Descriptions

type is the XrStructureType of this structure.
next is NULL or a pointer to the next structure in a structure chain. No such structures are defined in core OpenXR or this extension.
componentTypeCount is a uint32_t describing the count of elements in the componentTypes array.
componentTypes is an array of XrSpatialComponentTypeEXT .

The XrSpatialDiscoverySnapshotCreateInfoEXT structure describes the information to create an XrSpatialSnapshotEXT handle when discovering spatial entities.

Valid Usage (Implicit)

The XR_EXT_spatial_entity extension must be enabled prior to using XrSpatialDiscoverySnapshotCreateInfoEXT
type must be XR_TYPE_SPATIAL_DISCOVERY_SNAPSHOT_CREATE_INFO_EXT
next must be NULL or a valid pointer to the next structure in a structure chain . See also: XrSpatialBoundsBoxfANDROID , XrSpatialBoundsFrustumfANDROID , XrSpatialBoundsSpherefANDROID , XrSpatialDiscoveryPersistenceUuidFilterEXT , XrSpatialDiscoveryRoomBoundaryFilterANDROIDSYS , XrSpatialDiscoveryUniqueEntitiesFilterANDROID , XrSpatialFilterTrackingStateEXT , XrSpatialRaycastInfoANDROID
If componentTypeCount is not 0 , componentTypes must be a pointer to an array of componentTypeCount valid XrSpatialComponentTypeEXT values

The xrCreateSpatialDiscoverySnapshotCompleteEXT function is defined as:

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

Parameter Descriptions

spatialContext is the XrSpatialContextEXT previously passed to xrCreateSpatialDiscoverySnapshotAsyncEXT :: spatialContext .
createSnapshotCompletionInfo is a pointer to an XrCreateSpatialDiscoverySnapshotCompletionInfoEXT which provides info about the discovery snapshot creation request completion.
completion is a pointer to an XrCreateSpatialDiscoverySnapshotCompletionEXT .

xrCreateSpatialDiscoverySnapshotCompleteEXT completes the asynchronous operation started by xrCreateSpatialDiscoverySnapshotAsyncEXT . The runtime must return XR_ERROR_FUTURE_PENDING_EXT if XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: future is not in ready state. The runtime must return XR_ERROR_FUTURE_INVALID_EXT if XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: future has already been completed or cancelled.

Valid Usage (Implicit)

The XR_EXT_spatial_entity extension must be enabled prior to calling xrCreateSpatialDiscoverySnapshotCompleteEXT
spatialContext must be a valid XrSpatialContextEXT handle
createSnapshotCompletionInfo must be a pointer to a valid XrCreateSpatialDiscoverySnapshotCompletionInfoEXT structure
completion must be a pointer to an XrCreateSpatialDiscoverySnapshotCompletionEXT structure

Return Codes

Success

XR_SUCCESS
XR_SESSION_LOSS_PENDING

Failure

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

The XrCreateSpatialDiscoverySnapshotCompletionInfoEXT structure is defined as:

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

Member Descriptions

type is the XrStructureType of this structure.
next is NULL or a pointer to the next structure in a structure chain.
baseSpace is the XrSpace in which all the locations of the discovery XrSpatialSnapshotEXT will be located.
time is the XrTime at which all the locations of the discovery XrSpatialSnapshotEXT will be located.
future is the XrFutureEXT received from xrCreateSpatialDiscoverySnapshotAsyncEXT

The locations in the various component data included in the created snapshot will be represented in baseSpace , located at time .

Valid Usage (Implicit)

The XR_EXT_spatial_entity extension must be enabled prior to using XrCreateSpatialDiscoverySnapshotCompletionInfoEXT
type must be XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_INFO_EXT
next must be NULL or a valid pointer to the next structure in a structure chain
baseSpace must be a valid XrSpace handle

The XrCreateSpatialDiscoverySnapshotCompletionEXT structure is defined as:

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

Member Descriptions

type is the XrStructureType of this structure.
next is NULL or a pointer to the next structure in a structure chain.
futureResult is the XrResult of the spatial discovery snapshot creation operation.
snapshot is an XrSpatialSnapshotEXT which can be used to query the component data of the discovered spatial entities.

Future Return Codes

futureResult values:

Success

XR_SUCCESS
XR_SESSION_LOSS_PENDING

Failure

XR_ERROR_RUNTIME_FAILURE
XR_ERROR_INSTANCE_LOST
XR_ERROR_SESSION_LOST
XR_ERROR_OUT_OF_MEMORY
XR_ERROR_LIMIT_REACHED

Valid Usage (Implicit)

The XR_EXT_spatial_entity extension must be enabled prior to using XrCreateSpatialDiscoverySnapshotCompletionEXT
type must be XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_EXT
next must be NULL or a valid pointer to the next structure in a structure chain
futureResult must be a valid XrResult value
If snapshot is not XR_NULL_HANDLE , snapshot must be a valid XrSpatialSnapshotEXT handle

Discovery Recommendation Event

The XrEventDataSpatialDiscoveryRecommendedEXT structure is defined as:

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

Member Descriptions

type is the XrStructureType of this structure.
next is NULL or a pointer to the next structure in a structure chain.
spatialContext is the XrSpatialContextEXT for which discovery is being recommended by the runtime.

The application can retrieve this event by using xrPollEvent . The application can avoid excessive calls to xrCreateSpatialDiscoverySnapshotAsyncEXT to discover spatial entities by waiting for this event. If the application creates multiple discovery snapshots with the same XrSpatialDiscoverySnapshotCreateInfoEXT between two XrEventDataSpatialDiscoveryRecommendedEXT events, the resultant snapshots may contain the same entities and therefore the snapshot creation and data queries would be wasteful.

Waiting for this event to create a new discovery snapshot ensures that the application is not overloading the system with discovery requests for which the runtime may not return any new data and helps avoid the risk of overusing the system resources, and getting throttled due to power or thermal policies of the device. This also helps create parity between runtimes that are discovering spatial entities on the fly with live tracking and runtimes which are providing spatial entities off of a previously recorded state (where the runtime may queue the discovery recommendation event only once for each XrSpatialContextEXT ).

The runtime must not queue this event for notifying the application about changes or adjustments made to the component data of existing spatial entities. The application can use the xrCreateSpatialUpdateSnapshotEXT to keep track of component data updates for the spatial entities it is interested in.

A runtime may queue a discovery recommendation event without waiting for the application to first call xrCreateSpatialDiscoverySnapshotAsyncEXT . For example, a runtime may base the decision of queueing the discovery recommendation event on the configuration of the XrSpatialContextEXT , its own understanding of the environment around the user (discovery of new entities or loss of existing ones), or for hinting an appropriate discovery request cadence to the application so as not to overload the system resources. The runtime may choose to never queue this event for an XrSpatialContextEXT if no entities are found in the user’s environment throughout the lifetime of that XrSpatialContextEXT .

The runtime must not queue this event for a given spatialContext until the application completes its creation by using xrCreateSpatialContextCompleteEXT .

After the application calls xrDestroySpatialContextEXT , the runtime must not queue any more discovery recommendation events for that spatial context nor return any such events for that context from xrPollEvent .

Valid Usage (Implicit)

The XR_EXT_spatial_entity extension must be enabled prior to using XrEventDataSpatialDiscoveryRecommendedEXT
type must be XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT
next must be NULL or a valid pointer to the next structure in a structure chain

Query Component Data

The xrQuerySpatialComponentDataEXT function is defined as:

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

Parameter Descriptions

snapshot is an XrSpatialSnapshotEXT previously provided by xrCreateSpatialDiscoverySnapshotCompleteEXT or xrCreateSpatialUpdateSnapshotEXT .
queryCondition is a pointer to an XrSpatialComponentDataQueryConditionEXT structure.
queryResult is a pointer to an XrSpatialComponentDataQueryResultEXT structure.

The application can use xrQuerySpatialComponentDataEXT to query the component data of the entities in the snapshot by attaching a list structure to XrSpatialComponentDataQueryResultEXT :: next corresponding to each XrSpatialComponentTypeEXT in XrSpatialComponentDataQueryConditionEXT :: componentTypes .

If the application attaches a list structure to XrSpatialComponentDataQueryResultEXT :: next that does not correspond to any of the components listed in XrSpatialComponentDataQueryConditionEXT :: componentTypes , the runtime must return XR_ERROR_VALIDATION_FAILURE .

The application can choose to attach the list structures corresponding to only a subset of components listed in XrSpatialComponentDataQueryConditionEXT :: componentTypes . The application can choose to omit the list structures altogether if it only wishes to know the ids and tracking state of the spatial entities that satisfy the queryCondition . The runtime must not treat the absence of list structures from the XrSpatialComponentDataQueryResultEXT :: next chain as a failure.

If XrEventDataReferenceSpaceChangePending is queued and XrEventDataReferenceSpaceChangePending :: changeTime elapsed while the application is querying component data from an XrSpatialSnapshotEXT , the application may use the event data to adjust the poses accordingly.

The runtime must populate XrSpatialComponentDataQueryResultEXT :: entityIds only with entities that have all the components specified in XrSpatialComponentDataQueryConditionEXT :: componentTypes . If XrSpatialComponentDataQueryConditionEXT :: componentTypeCount is 0, the runtime must populate queryResult with all the entities (and their tracking states) that are in the snapshot. If additional query conditions are added to XrSpatialComponentDataQueryConditionEXT :: next , the runtime must treat those as an "AND" with the component types availability i.e. the runtime must populate XrSpatialComponentDataQueryResultEXT ::entityIds only with entities that satisfy all of the provided conditions. The runtime must populate the component data in the list structures in the same order as the entities in XrSpatialComponentDataQueryResultEXT :: entityIds i.e. the component data at a given index in the list structure array must correspond to the entity at the same index.

If the tracking state for an entity is not XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT , the runtime must not change the data at the index corresponding to that entity in the array contained in the list structures attached to XrSpatialComponentDataQueryResultEXT .

Valid Usage (Implicit)

The XR_EXT_spatial_entity extension must be enabled prior to calling xrQuerySpatialComponentDataEXT
snapshot must be a valid XrSpatialSnapshotEXT handle
queryCondition must be a pointer to a valid XrSpatialComponentDataQueryConditionEXT structure
queryResult must be a pointer to an XrSpatialComponentDataQueryResultEXT structure

Return Codes

Success

XR_SUCCESS
XR_SESSION_LOSS_PENDING

Failure

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

As an example the application creates an XrSpatialSnapshotEXT which contains 5 entities, where -

Entity 1 and 2 have components XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT and XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT
Entity 3 and 4 have components XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT and XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT
Entity 5 has components XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT and XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT .

XrSpatialEntityIdEXT

Bounded2D

Yes

Parent

Yes

Mesh3D

Yes

Bounded3D

Yes

No Text is not SVG - cannot display

Figure 20. Example snapshot

xrQuerySpatialComponentDataEXT on the above snapshot with XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT listed in the query condition will result in entity #1, #2, and #5 being returned to the application and the application can attach an array of XrSpatialBounded2DDataEXT as part of the XrSpatialComponentBounded2DListEXT structure to the next chain of XrSpatialComponentDataQueryResultEXT to get the bounded2D data.

XrSpatialEntityIdEXT

Bounded2D

Data for entityId #1

Data for entit...

Data for entityId #2

Data for entit...

Data for entityId #5

Data for entit...

entityIds

XrSpatialComponent DataQueryResultEXT

XrSpatialComponent Dat...

bounds

XrSpatialComponent Bounded2DListEXT

XrSpatialComponent Bou... Text is not SVG - cannot display

Figure 21. Example query result

xrQuerySpatialComponentDataEXT on the above snapshot with XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT and XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT components listed in the query condition will result in entity #3 and #4 being returned to the application and the application can attach arrays of XrBoxf and XrSpatialMeshDataEXT as part of the XrSpatialComponentBounded3DListEXT and XrSpatialComponentMesh3DListEXT structures respectively to the next chain of XrSpatialComponentDataQueryResultEXT to get the component data.

XrSpatialEntityIdEXT

Bounded3D

Data for entityId #3

Data for entit...

Data for entityId #4

Data for entit...

Mesh3D

Data for entityId #3

Data for entit...

Data for entityId #4

Data for entit...

entityIds

XrSpatialComponent DataQueryResultEXT

XrSpatialComponent Da...

bounds

XrSpatialComponent Bounded3DListEXT

XrSpatialComponent Bo...

XrSpatialComponent Mesh3DListEXT

XrSpatialComponent Me...

meshes

meshes Text is not SVG - cannot display

Figure 22. Example query result

The XrSpatialComponentDataQueryConditionEXT structure is defined as:

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

Member Descriptions

type is the XrStructureType of this structure.
next is NULL or a pointer to the next structure in a structure chain.
componentTypeCount is a uint32_t describing the count of elements in the componentTypes array.
componentTypes is an array of XrSpatialComponentTypeEXT for which to get the data from the snapshot.

Valid Usage (Implicit)

The XR_EXT_spatial_entity extension must be enabled prior to using XrSpatialComponentDataQueryConditionEXT
type must be XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT
next must be NULL or a valid pointer to the next structure in a structure chain . See also: XrSpatialDiscoveryPersistenceUuidFilterEXT , XrSpatialFilterArchetypeEXT , XrSpatialFilterTrackingStateEXT
If componentTypeCount is not 0 , componentTypes must be a pointer to an array of componentTypeCount valid XrSpatialComponentTypeEXT values

The XrSpatialComponentDataQueryResultEXT structure is defined as:

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

Member Descriptions

type is the XrStructureType of this structure.
next is NULL or a pointer to the next structure in a structure chain.
entityIdCapacityInput is the capacity of the entityIds array, or 0 to indicate a request to retrieve the required capacity.
entityIdCountOutput is the number of XrSpatialEntityIdEXT in entityIds , or the required capacity in the case that entityIdCapacityInput is insufficient.
entityIds is an array of XrSpatialEntityIdEXT . It can be NULL if entityIdCapacityInput is 0.
entityStateCapacityInput is the capacity of the entityStates array, or 0 to indicate a request to retrieve the required capacity.
entityStateCountOutput is the number of XrSpatialEntityTrackingStateEXT in entityStates , or the required capacity in the case that entityStateCapacityInput is insufficient. This must always be the same as entityIdCountOutput .
entityStates is an array of XrSpatialEntityTrackingStateEXT . It can be NULL if entityStateCapacityInput is 0.
See the Buffer Size Parameters section for a detailed description of retrieving the required entityIds size.

An application can use the entityIds with xrCreateSpatialEntityFromIdEXT to create XrSpatialEntityEXT handles for the entities it is interested in getting regular updates for. The application can then use these XrSpatialEntityEXT handles with xrCreateSpatialUpdateSnapshotEXT to create an update snapshot that has the runtime’s latest known data of the components for the provided entities.

Valid Usage (Implicit)

The XR_EXT_spatial_entity extension must be enabled prior to using XrSpatialComponentDataQueryResultEXT
type must be XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_RESULT_EXT
next must be NULL or a valid pointer to the next structure in a structure chain . See also: XrSpatialComponentAnchorListEXT , XrSpatialComponentAnnotationQuadListANDROID , XrSpatialComponentBounded2DListEXT , XrSpatialComponentBounded3DListEXT , XrSpatialComponentConfidenceListANDROIDSYS , XrSpatialComponentImage2DListEXT , XrSpatialComponentKeyboardSemanticLabelListEXT , XrSpatialComponentMarkerListEXT , XrSpatialComponentMaterialTypeListANDROIDSYS , XrSpatialComponentMesh2DListEXT , XrSpatialComponentMesh3DListEXT , XrSpatialComponentMesh3DNormalsListEXT , XrSpatialComponentMesh3DTriangleSemanticLabelsListEXT , XrSpatialComponentMesh3DVertexSemanticLabelsListEXT , XrSpatialComponentMouseSemanticLabelListEXT , XrSpatialComponentObjectSemanticLabelListANDROID , XrSpatialComponentObjectSemanticLabelListEXT , XrSpatialComponentOccupancyGridListANDROIDX1 , XrSpatialComponentParentListEXT , XrSpatialComponentPersistenceListEXT , XrSpatialComponentPlaneAlignmentListEXT , XrSpatialComponentPlaneSemanticLabelListEXT , XrSpatialComponentPolygon2DListEXT , XrSpatialComponentRaycastResultListANDROID , XrSpatialComponentRoomEmptinessListANDROIDSYS , XrSpatialComponentRoomListANDROIDSYS , XrSpatialComponentStreetscapeGeometryMetadataListANDROIDX2 , XrSpatialComponentSubsumedByListANDROID
If entityIdCapacityInput is not 0 , entityIds must be a pointer to an array of entityIdCapacityInput XrSpatialEntityIdEXT values
If entityStateCapacityInput is not 0 , entityStates must be a pointer to an array of entityStateCapacityInput XrSpatialEntityTrackingStateEXT values

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;

The XrSpatialEntityTrackingStateEXT enumerates the possible spatial entity tracking states:

The enums have the following meanings:

Enum Description

XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT

The runtime has stopped tracking this entity and will never resume tracking it.

XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT

The runtime has paused tracking this entity but may resume tracking it in the future.

XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT

The runtime is currently tracking this entity and its component data is valid.

TRACKING

PAUSED

STOPPED

Figure 23. XrSpatialEntityTrackingStateEXT

The runtime may change the state of the spatial entity from XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT to XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT if it suspends the tracking of that spatial entity but has the possibility of resuming its tracking in the future. Some examples of when the runtime may do this include (but not limited to) if the application loses input focus; or if the given spatial entity is too far from the user to be accurately tracked; or if there are too many entities being tracked and the runtime wants to reduce the cost of tracking. XrSpatialEntityTrackingStateEXT helps the application insulate itself from the different tracking policies of each runtime.
The runtime may change the state of an entity from XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT to XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT or XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT .
The runtime must change the state of the spatial entity from XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT or XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT to XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT if the spatial entity is lost and its tracking will never be recovered or resumed. An example of such a case would be if the device loses tracking, restarts its tracking session but is unable to relocalize in its environment, and therefore treats discovered entities of this tracking session as new entities.
Once the tracking state of an entity is set to XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT , the runtime must never change it any other state.
When querying the component data of a spatial entity using xrQuerySpatialComponentDataEXT , the runtime must set valid data in the contents of the buffers provided by the application in the next chain of XrSpatialComponentDataQueryResultEXT if the entity state is XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT . If the entity state is XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT or XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT , the runtime must not change the content of the buffers.

Two-call idiom for component data

The XrSpatialBufferEXT structure is defined as:

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

Member Descriptions

bufferId the XrSpatialBufferIdEXT of the buffer data.
bufferType is the XrSpatialBufferTypeEXT to indicate the type of data in bufferId . The application can use bufferType to determine which function to use to retrieve the actual data of the buffer.

Some spatial components have variable-sized data and therefore require using the two-call idiom to retrieve their data. In such cases, the spatial component data structure provides an XrSpatialBufferEXT for each variable sized buffer needed in that component’s data.

For the same bufferId , the runtime must provide the same data from one component data query to another, even across one snapshot to another. A different bufferId between component data query calls indicates to the application that the data for that component may have changed.

Valid Usage (Implicit)

The XR_EXT_spatial_entity extension must be enabled prior to using XrSpatialBufferEXT
bufferType must be a valid XrSpatialBufferTypeEXT value

XR_DEFINE_ATOM(XrSpatialBufferIdEXT)

XrSpatialBufferIdEXT is used to represent any kind of variable sized data for a spatial component.

The runtime must keep the XrSpatialBufferIdEXT and its data in memory for at least the lifecycle of the XrSpatialSnapshotEXT that contains it. The runtime may keep the XrSpatialBufferIdEXT and its data in memory for longer than the lifecycle of the XrSpatialSnapshotEXT in order to return the same ID as part of snapshots created later on by the application. For the same XrSpatialBufferIdEXT , the runtime must always return the same data via the appropriate xrGetSpatialBuffer* function.

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;

The XrSpatialBufferTypeEXT enumeration identifies the different data types of the buffer represented XrSpatialBufferIdEXT .

Enumerant Descriptions

XR_SPATIAL_BUFFER_TYPE_STRING_EXT . The XrSpatialBufferIdEXT can be passed to xrGetSpatialBufferStringEXT to retrieve a string buffer.
XR_SPATIAL_BUFFER_TYPE_UINT8_EXT . The XrSpatialBufferIdEXT can be passed to xrGetSpatialBufferUint8EXT to retrieve a uint8_t buffer.
XR_SPATIAL_BUFFER_TYPE_UINT16_EXT . The XrSpatialBufferIdEXT can be passed to xrGetSpatialBufferUint16EXT to retrieve a uint16_t buffer.
XR_SPATIAL_BUFFER_TYPE_UINT32_EXT . The XrSpatialBufferIdEXT can be passed to xrGetSpatialBufferUint32EXT to retrieve a uint32_t buffer.
XR_SPATIAL_BUFFER_TYPE_FLOAT_EXT . The XrSpatialBufferIdEXT can be passed to xrGetSpatialBufferFloatEXT to retrieve a float buffer.
XR_SPATIAL_BUFFER_TYPE_VECTOR2F_EXT . The XrSpatialBufferIdEXT can be passed to xrGetSpatialBufferVector2fEXT to retrieve an XrVector2f buffer.
XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT . The XrSpatialBufferIdEXT can be passed to xrGetSpatialBufferVector3fEXT to retrieve an XrVector3f buffer.

The xrGetSpatialBufferStringEXT function is defined as:

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

Parameter Descriptions

snapshot is a handle to an XrSpatialSnapshotEXT .
info holds the information on the buffer to query.
bufferCapacityInput is the capacity of the array, or 0 to indicate a request to retrieve the required capacity.
bufferCountOutput is the number of characters, or the required capacity in the case that bufferCapacityInput is insufficient.
buffer is an array of char . It can be NULL if bufferCapacityInput is 0.
See the Buffer Size Parameters section for a detailed description of retrieving the required buffer size.

The application can get the data for an XrSpatialBufferEXT provided by a component, where XrSpatialBufferEXT :: bufferType is XR_SPATIAL_BUFFER_TYPE_STRING_EXT by using xrGetSpatialBufferStringEXT .

The runtime must return XR_ERROR_VALIDATION_FAILURE if the XrSpatialBufferTypeEXT for XrSpatialBufferGetInfoEXT :: bufferId is not XR_SPATIAL_BUFFER_TYPE_STRING_EXT .

The runtime must return XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT if XrSpatialBufferGetInfoEXT :: bufferId does not belong to snapshot .

buffer filled by the runtime must be a null-terminated UTF-8 string.

Valid Usage (Implicit)

The XR_EXT_spatial_entity extension must be enabled prior to calling xrGetSpatialBufferStringEXT
snapshot must be a valid XrSpatialSnapshotEXT handle
info must be a pointer to a valid XrSpatialBufferGetInfoEXT structure
bufferCountOutput must be a pointer to a uint32_t value
If bufferCapacityInput is not 0 , buffer must be a pointer to an array of bufferCapacityInput char values

Return Codes

Success

XR_SUCCESS
XR_SESSION_LOSS_PENDING

Failure

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

The xrGetSpatialBufferUint8EXT function is defined as:

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

Parameter Descriptions

snapshot is a handle to an XrSpatialSnapshotEXT .
info holds the information on the buffer to query.
bufferCapacityInput is the capacity of the array, or 0 to indicate a request to retrieve the required capacity.
bufferCountOutput is the number of elements in the buffer array, or the required capacity in the case that bufferCapacityInput is insufficient.
buffer is an array of uint8_t . It can be NULL if bufferCapacityInput is 0.
See the Buffer Size Parameters section for a detailed description of retrieving the required buffer size.

The application can get the data for an XrSpatialBufferEXT provided by a component, where XrSpatialBufferEXT :: bufferType is XR_SPATIAL_BUFFER_TYPE_UINT8_EXT by using xrGetSpatialBufferUint8EXT .

The runtime must return XR_ERROR_VALIDATION_FAILURE if the XrSpatialBufferTypeEXT for XrSpatialBufferGetInfoEXT :: bufferId is not XR_SPATIAL_BUFFER_TYPE_UINT8_EXT .

The runtime must return XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT if XrSpatialBufferGetInfoEXT :: bufferId does not belong to snapshot .

Valid Usage (Implicit)

The XR_EXT_spatial_entity extension must be enabled prior to calling xrGetSpatialBufferUint8EXT
snapshot must be a valid XrSpatialSnapshotEXT handle
info must be a pointer to a valid XrSpatialBufferGetInfoEXT structure
bufferCountOutput must be a pointer to a uint32_t value
If bufferCapacityInput is not 0 , buffer must be a pointer to an array of bufferCapacityInput uint8_t values

Return Codes

Success

XR_SUCCESS
XR_SESSION_LOSS_PENDING

Failure

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

The xrGetSpatialBufferUint16EXT function is defined as:

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

Parameter Descriptions

snapshot is a handle to an XrSpatialSnapshotEXT .
info holds the information on the buffer to query.
bufferCapacityInput is the capacity of the array, or 0 to indicate a request to retrieve the required capacity.
bufferCountOutput is the number of elements in the buffer array, or the required capacity in the case that bufferCapacityInput is insufficient.
buffer is an array of uint16_t . It can be NULL if bufferCapacityInput is 0.
See the Buffer Size Parameters section for a detailed description of retrieving the required buffer size.

The application can get the data for an XrSpatialBufferEXT provided by a component, where XrSpatialBufferEXT :: bufferType is XR_SPATIAL_BUFFER_TYPE_UINT16_EXT by using xrGetSpatialBufferUint16EXT .

The runtime must return XR_ERROR_VALIDATION_FAILURE if the XrSpatialBufferTypeEXT for XrSpatialBufferGetInfoEXT :: bufferId is not XR_SPATIAL_BUFFER_TYPE_UINT16_EXT .

The runtime must return XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT if XrSpatialBufferGetInfoEXT :: bufferId does not belong to snapshot .

Valid Usage (Implicit)

The XR_EXT_spatial_entity extension must be enabled prior to calling xrGetSpatialBufferUint16EXT
snapshot must be a valid XrSpatialSnapshotEXT handle
info must be a pointer to a valid XrSpatialBufferGetInfoEXT structure
bufferCountOutput must be a pointer to a uint32_t value
If bufferCapacityInput is not 0 , buffer must be a pointer to an array of bufferCapacityInput uint16_t values

Return Codes

Success

XR_SUCCESS
XR_SESSION_LOSS_PENDING

Failure

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

The xrGetSpatialBufferUint32EXT function is defined as:

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

Parameter Descriptions

snapshot is a handle to an XrSpatialSnapshotEXT .
info holds the information on the buffer to query.
bufferCapacityInput is the capacity of the array, or 0 to indicate a request to retrieve the required capacity.
bufferCountOutput is the number of elements in the buffer array, or the required capacity in the case that bufferCapacityInput is insufficient.
buffer is an array of uint32_t . It can be NULL if bufferCapacityInput is 0.
See the Buffer Size Parameters section for a detailed description of retrieving the required buffer size.

The application can get the data for an XrSpatialBufferEXT provided by a component, where XrSpatialBufferEXT :: bufferType is XR_SPATIAL_BUFFER_TYPE_UINT32_EXT by using xrGetSpatialBufferUint32EXT .

The runtime must return XR_ERROR_VALIDATION_FAILURE if the XrSpatialBufferTypeEXT for XrSpatialBufferGetInfoEXT :: bufferId is not XR_SPATIAL_BUFFER_TYPE_UINT32_EXT .

The runtime must return XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT if XrSpatialBufferGetInfoEXT :: bufferId does not belong to snapshot .

Valid Usage (Implicit)

The XR_EXT_spatial_entity extension must be enabled prior to calling xrGetSpatialBufferUint32EXT
snapshot must be a valid XrSpatialSnapshotEXT handle
info must be a pointer to a valid XrSpatialBufferGetInfoEXT structure
bufferCountOutput must be a pointer to a uint32_t value
If bufferCapacityInput is not 0 , buffer must be a pointer to an array of bufferCapacityInput uint32_t values

Return Codes

Success

XR_SUCCESS
XR_SESSION_LOSS_PENDING

Failure

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

The xrGetSpatialBufferFloatEXT function is defined as:

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

Parameter Descriptions

snapshot is a handle to an XrSpatialSnapshotEXT .
info holds the information on the buffer to query.
bufferCapacityInput is the capacity of the array, or 0 to indicate a request to retrieve the required capacity.
bufferCountOutput is the number of elements in the buffer array, or the required capacity in the case that bufferCapacityInput is insufficient.
buffer is an array of float . It can be NULL if bufferCapacityInput is 0.
See the Buffer Size Parameters section for a detailed description of retrieving the required buffer size.

The application can get the data for an XrSpatialBufferEXT provided by a component, where XrSpatialBufferEXT :: bufferType is XR_SPATIAL_BUFFER_TYPE_FLOAT_EXT by using xrGetSpatialBufferFloatEXT .

The runtime must return XR_ERROR_VALIDATION_FAILURE if the XrSpatialBufferTypeEXT for XrSpatialBufferGetInfoEXT :: bufferId is not XR_SPATIAL_BUFFER_TYPE_FLOAT_EXT .

The runtime must return XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT if XrSpatialBufferGetInfoEXT :: bufferId does not belong to snapshot .

Valid Usage (Implicit)

The XR_EXT_spatial_entity extension must be enabled prior to calling xrGetSpatialBufferFloatEXT
snapshot must be a valid XrSpatialSnapshotEXT handle
info must be a pointer to a valid XrSpatialBufferGetInfoEXT structure
bufferCountOutput must be a pointer to a uint32_t value
If bufferCapacityInput is not 0 , buffer must be a pointer to an array of bufferCapacityInput float values

Return Codes

Success

XR_SUCCESS
XR_SESSION_LOSS_PENDING

Failure

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

The xrGetSpatialBufferVector2fEXT function is defined as:

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

Parameter Descriptions

snapshot is a handle to an XrSpatialSnapshotEXT .
info holds the information on the buffer to query.
bufferCapacityInput is the capacity of the array, or 0 to indicate a request to retrieve the required capacity.
bufferCountOutput is the number of elements in the buffer array, or the required capacity in the case that bufferCapacityInput is insufficient.
buffer is an array of XrVector2f . It can be NULL if bufferCapacityInput is 0.
See the Buffer Size Parameters section for a detailed description of retrieving the required buffer size.

The application can get the data for an XrSpatialBufferEXT provided by a component, where XrSpatialBufferEXT :: bufferType is XR_SPATIAL_BUFFER_TYPE_VECTOR2F_EXT by using xrGetSpatialBufferVector2fEXT .

The runtime must return XR_ERROR_VALIDATION_FAILURE if the XrSpatialBufferTypeEXT for XrSpatialBufferGetInfoEXT :: bufferId is not XR_SPATIAL_BUFFER_TYPE_VECTOR2F_EXT .

The runtime must return XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT if XrSpatialBufferGetInfoEXT :: bufferId does not belong to snapshot .

Valid Usage (Implicit)

The XR_EXT_spatial_entity extension must be enabled prior to calling xrGetSpatialBufferVector2fEXT
snapshot must be a valid XrSpatialSnapshotEXT handle
info must be a pointer to a valid XrSpatialBufferGetInfoEXT structure
bufferCountOutput must be a pointer to a uint32_t value
If bufferCapacityInput is not 0 , buffer must be a pointer to an array of bufferCapacityInput XrVector2f structures

Return Codes

Success

XR_SUCCESS
XR_SESSION_LOSS_PENDING

Failure

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

The xrGetSpatialBufferVector3fEXT function is defined as:

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

Parameter Descriptions

snapshot is a handle to an XrSpatialSnapshotEXT .
info holds the information on the buffer to query.
bufferCapacityInput is the capacity of the array, or 0 to indicate a request to retrieve the required capacity.
bufferCountOutput is the number of elements in the buffer array, or the required capacity in the case that bufferCapacityInput is insufficient.
buffer is an array of XrVector3f . It can be NULL if bufferCapacityInput is 0.
See the Buffer Size Parameters section for a detailed description of retrieving the required buffer size.

The application can get the data for an XrSpatialBufferEXT provided by a component, where XrSpatialBufferEXT :: bufferType is XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT by using xrGetSpatialBufferVector3fEXT .

The runtime must return XR_ERROR_VALIDATION_FAILURE if the XrSpatialBufferTypeEXT for XrSpatialBufferGetInfoEXT :: bufferId is not XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT .

The runtime must return XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT if XrSpatialBufferGetInfoEXT :: bufferId does not belong to snapshot .

Valid Usage (Implicit)

The XR_EXT_spatial_entity extension must be enabled prior to calling xrGetSpatialBufferVector3fEXT
snapshot must be a valid XrSpatialSnapshotEXT handle
info must be a pointer to a valid XrSpatialBufferGetInfoEXT structure
bufferCountOutput must be a pointer to a uint32_t value
If bufferCapacityInput is not 0 , buffer must be a pointer to an array of bufferCapacityInput XrVector3f structures

Return Codes

Success

XR_SUCCESS
XR_SESSION_LOSS_PENDING

Failure

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

The XrSpatialBufferGetInfoEXT structure is defined as:

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

Member Descriptions

type is the XrStructureType of this structure.
next is NULL or a pointer to the next structure in a structure chain.
bufferId an XrSpatialBufferIdEXT for the buffer whose data to retrieve.

Valid Usage (Implicit)

The XR_EXT_spatial_entity extension must be enabled prior to using XrSpatialBufferGetInfoEXT
type must be XR_TYPE_SPATIAL_BUFFER_GET_INFO_EXT
next must be NULL or a valid pointer to the next structure in a structure chain

#define XR_NULL_SPATIAL_BUFFER_ID_EXT 0

XR_NULL_SPATIAL_BUFFER_ID_EXT is a reserved value representing an invalid XrSpatialBufferIdEXT . It may be passed to and returned from API functions only when specifically allowed.

Create Update Snapshot

The xrCreateSpatialUpdateSnapshotEXT function is defined as:

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

Parameter Descriptions

spatialContext is an XrSpatialContextEXT previously created using xrCreateSpatialContextAsyncEXT .
createInfo is a pointer to an XrSpatialUpdateSnapshotCreateInfoEXT .
snapshot is a pointer to the result XrSpatialSnapshotEXT .

The application can use xrCreateSpatialUpdateSnapshotEXT to create a snapshot and get the latest component data for specific entities as known by the runtime. Applications can provide the XrSpatialEntityEXT handles and the component types they are interested in when creating the snapshot.

The application can use XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes to filter the list of components whose data must be included in the snapshot. If the application provides a valid list of spatial component types in XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes , then the runtime must only include spatial entities in the snapshot that have at least one of the components provided in XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes . Also, the runtime must only include data for those components in the snapshot.

The runtime must return XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT if any of the XrSpatialComponentTypeEXT in XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes are not enabled for the spatial capabilities passed to XrSpatialContextCreateInfoEXT :: capabilityConfigs when creating spatialContext .

If the application does not provide a list of spatial component types in XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes , the runtime must include all the spatial entities listed in XrSpatialUpdateSnapshotCreateInfoEXT :: entities in the snapshot and it must include the data for all the enabled components of the capabilities configured for spatialContext .

The runtime must not include spatial entities that are not listed in XrSpatialUpdateSnapshotCreateInfoEXT :: entities in snapshot .

Valid Usage (Implicit)

The XR_EXT_spatial_entity extension must be enabled prior to calling xrCreateSpatialUpdateSnapshotEXT
spatialContext must be a valid XrSpatialContextEXT handle
createInfo must be a pointer to a valid XrSpatialUpdateSnapshotCreateInfoEXT structure
snapshot must be a pointer to an XrSpatialSnapshotEXT handle

Return Codes

Success

XR_SUCCESS
XR_SESSION_LOSS_PENDING

Failure

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

The XrSpatialUpdateSnapshotCreateInfoEXT structure is defined as:

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;

Member Descriptions

type is the XrStructureType of this structure.
next is NULL or a pointer to the next structure in a structure chain. No such structures are defined in core OpenXR or this extension.
entityCount is a uint32_t describing the count of elements in the entities array.
entities is an array of XrSpatialEntityEXT for which the runtime must include the component data in the snapshot.
componentTypeCount is a uint32_t describing the count of elements in the componentTypes array.
componentTypes is an array of XrSpatialComponentTypeEXT for which the runtime must include the data in the snapshot.
baseSpace is the XrSpace relative to which all the locations of the update XrSpatialSnapshotEXT will be located.
time is the XrTime at which all the locations of the update XrSpatialSnapshotEXT will be located.

Valid Usage (Implicit)

The XR_EXT_spatial_entity extension must be enabled prior to using XrSpatialUpdateSnapshotCreateInfoEXT
type must be XR_TYPE_SPATIAL_UPDATE_SNAPSHOT_CREATE_INFO_EXT
next must be NULL or a valid pointer to the next structure in a structure chain
entities must be a pointer to an array of entityCount valid XrSpatialEntityEXT handles
If componentTypeCount is not 0 , componentTypes must be a pointer to an array of componentTypeCount valid XrSpatialComponentTypeEXT values
baseSpace must be a valid XrSpace handle
The entityCount parameter must be greater than 0
Both of baseSpace and the elements of entities must have been created, allocated, or retrieved from the same XrSession

Destroy snapshot

The xrDestroySpatialSnapshotEXT function is defined as:

XrResult xrDestroySpatialSnapshotEXT(
    XrSpatialSnapshotEXT                        snapshot);

Parameter Descriptions

snapshot is an XrSpatialSnapshotEXT previously provided by xrCreateSpatialDiscoverySnapshotCompleteEXT or xrCreateSpatialUpdateSnapshotEXT .

The application can call xrDestroySpatialSnapshotEXT to destroy the XrSpatialSnapshotEXT handle and the resources associated with it.

Valid Usage (Implicit)

The XR_EXT_spatial_entity extension must be enabled prior to calling xrDestroySpatialSnapshotEXT
snapshot must be a valid XrSpatialSnapshotEXT handle

Thread Safety

Access to snapshot , and any child handles, must be externally synchronized

Return Codes

Success

XR_SUCCESS

Failure

XR_ERROR_FUNCTION_UNSUPPORTED
XR_ERROR_HANDLE_INVALID
XR_ERROR_RUNTIME_FAILURE

Common Components

Bounded 2D

Component data

The XrSpatialBounded2DDataEXT structure is defined as:

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

Member Descriptions

center is an XrPosef defining the geometric center of the bounded 2D component.
extents is extents of the bounded 2D component along the x-axis (extents.width), y-axis (extents.height), centered on center .

The extents of the XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT refer to the entity’s size in the x-y plane of the plane’s coordinate system. A plane with a position of {0, 0, 0}, rotation of {0, 0, 0, 1} (no rotation), and an extent of {1, 1} refers to a 1 meter x 1 meter plane centered at {0, 0, 0} with its front face normal vector pointing towards the +Z direction in the component’s space.

X X Y Y Z Z Height Height Y Y Z Z X X Vertical plane Vertical plane Horizontal Plane Horizontal Plane Width Width Width Width Height Height

Figure 24. Bounded2D Component Coordinate System

Note

OpenXR uses an X-Y plane with +Z as the plane normal but other APIs may use an X-Z plane with +Y as the plane normal. The X-Y plane can be converted to an X-Z plane by rotating -π/2 radians around the +X axis.

Valid Usage (Implicit)

The XR_EXT_spatial_entity extension must be enabled prior to using XrSpatialBounded2DDataEXT

Component list structure to query data

The XrSpatialComponentBounded2DListEXT structure is defined as:

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

Member Descriptions

type is the XrStructureType of this structure.
next is NULL or a pointer to the next structure in a structure chain. No such structures are defined in core OpenXR or this extension.
boundCount is a uint32_t describing the count of elements in the bounds array.
bounds is an array of XrSpatialBounded2DDataEXT .

The runtime must return XR_ERROR_VALIDATION_FAILURE from xrQuerySpatialComponentDataEXT if XrSpatialComponentBounded2DListEXT is in the next chain of XrSpatialComponentDataQueryResultEXT :: next but XrSpatialComponentDataQueryConditionEXT ::componentTypeCount is not zero and XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT is not included in XrSpatialComponentDataQueryConditionEXT :: componentTypes .

The runtime must return XR_ERROR_SIZE_INSUFFICIENT from xrQuerySpatialComponentDataEXT if boundCount is less than XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .

If xrQuerySpatialComponentDataEXT :: snapshot was created from xrCreateSpatialDiscoverySnapshotCompleteEXT , then the runtime must provide XrSpatialBounded2DDataEXT :: center in XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: baseSpace and XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: time .

If xrQuerySpatialComponentDataEXT :: snapshot was created from xrCreateSpatialUpdateSnapshotEXT , then the runtime must provide XrSpatialBounded2DDataEXT :: center in XrSpatialUpdateSnapshotCreateInfoEXT :: baseSpace and XrSpatialUpdateSnapshotCreateInfoEXT :: time .

Valid Usage (Implicit)

The XR_EXT_spatial_entity extension must be enabled prior to using XrSpatialComponentBounded2DListEXT
type must be XR_TYPE_SPATIAL_COMPONENT_BOUNDED_2D_LIST_EXT
next must be NULL or a valid pointer to the next structure in a structure chain
bounds must be a pointer to an array of boundCount XrSpatialBounded2DDataEXT structures
The boundCount parameter must be greater than 0

Configuration

If XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT is enumerated in XrSpatialCapabilityComponentTypesEXT :: componentTypes for some capability, the application can enable it by including the enum value in the XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents list. This component does not require any special configuration to be included in the next chain of XrSpatialCapabilityConfigurationBaseHeaderEXT .

Bounded 3D

Component data

XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT uses XrBoxf for its data.

Component list structure to query data

The XrSpatialComponentBounded3DListEXT structure is defined as:

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

Member Descriptions

type is the XrStructureType of this structure.
next is NULL or a pointer to the next structure in a structure chain. No such structures are defined in core OpenXR or this extension.
boundCount is a uint32_t describing the count of elements in the bounds array.
bounds is an array of XrBoxf .

The runtime must return XR_ERROR_VALIDATION_FAILURE from xrQuerySpatialComponentDataEXT if XrSpatialComponentBounded3DListEXT is in the next chain of XrSpatialComponentDataQueryResultEXT :: next but XrSpatialComponentDataQueryConditionEXT ::componentTypeCount is not zero and XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT is not included in XrSpatialComponentDataQueryConditionEXT :: componentTypes .

The runtime must return XR_ERROR_SIZE_INSUFFICIENT from xrQuerySpatialComponentDataEXT if boundCount is less than XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .

If xrQuerySpatialComponentDataEXT :: snapshot was created from xrCreateSpatialDiscoverySnapshotCompleteEXT , then the runtime must provide XrBoxf :: center in XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: baseSpace at XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: time .

If xrQuerySpatialComponentDataEXT :: snapshot was created from xrCreateSpatialUpdateSnapshotEXT , then the runtime must provide XrBoxf :: center in XrSpatialUpdateSnapshotCreateInfoEXT :: baseSpace at XrSpatialUpdateSnapshotCreateInfoEXT :: time .

Valid Usage (Implicit)

The XR_EXT_spatial_entity extension must be enabled prior to using XrSpatialComponentBounded3DListEXT
type must be XR_TYPE_SPATIAL_COMPONENT_BOUNDED_3D_LIST_EXT
next must be NULL or a valid pointer to the next structure in a structure chain
bounds must be a pointer to an array of boundCount XrBoxf structures
The boundCount parameter must be greater than 0

Configuration

If XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT is enumerated in XrSpatialCapabilityComponentTypesEXT :: componentTypes for some capability, the application can enable it by including the enum in the XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents list. This component does not require any special configuration to be included in the next chain of XrSpatialCapabilityConfigurationBaseHeaderEXT .

Parent

Component data

XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT uses XrSpatialEntityIdEXT for its data.

Component list structure to query data

The XrSpatialComponentParentListEXT structure is defined as:

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

Member Descriptions

type is the XrStructureType of this structure.
next is NULL or a pointer to the next structure in a structure chain. No such structures are defined in core OpenXR or this extension.
parentCount is a uint32_t describing the count of elements in the parents array.
parents is an array of XrSpatialEntityIdEXT .

The runtime must return XR_ERROR_VALIDATION_FAILURE from xrQuerySpatialComponentDataEXT if XrSpatialComponentParentListEXT is in the next chain of XrSpatialComponentDataQueryResultEXT :: next but XrSpatialComponentDataQueryConditionEXT ::componentTypeCount is not zero and XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT is not included in XrSpatialComponentDataQueryConditionEXT :: componentTypes .

The runtime must return XR_ERROR_SIZE_INSUFFICIENT from xrQuerySpatialComponentDataEXT if parentCount is less than XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .

Valid Usage (Implicit)

The XR_EXT_spatial_entity extension must be enabled prior to using XrSpatialComponentParentListEXT
type must be XR_TYPE_SPATIAL_COMPONENT_PARENT_LIST_EXT
next must be NULL or a valid pointer to the next structure in a structure chain
parents must be a pointer to an array of parentCount XrSpatialEntityIdEXT values
The parentCount parameter must be greater than 0

Configuration

If XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT is enumerated in XrSpatialCapabilityComponentTypesEXT :: componentTypes for some capability, the application can enable it by including the enum in the XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents list. This component does not require any special configuration to be included in the next chain of XrSpatialCapabilityConfigurationBaseHeaderEXT .

Mesh 3D

Component data

The XrSpatialMeshDataEXT structure is defined as:

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

Member Descriptions

origin is an XrPosef defining the origin of the mesh. All vertices of the mesh must be relative to this origin.
vertexBuffer is an XrSpatialBufferEXT that provides the ID for a buffer that represents the vertex buffer of the entity this component is on. The position of vertices must be relative to origin .
indexBuffer is an XrSpatialBufferEXT that provides the ID for a buffer that represents an array of triangle indices, specifying the indices of the mesh vertices in the vertexBuffer . The triangle indices must be returned in counter-clockwise order and three indices denote one triangle.

The component type using XrSpatialMeshDataEXT must specify the XrSpatialBufferTypeEXT of the vertexBuffer and indexBuffer .

Valid Usage (Implicit)

The XR_EXT_spatial_entity extension must be enabled prior to using XrSpatialMeshDataEXT
vertexBuffer must be a valid XrSpatialBufferEXT structure
indexBuffer must be a valid XrSpatialBufferEXT structure

Component list structure to query data

The XrSpatialComponentMesh3DListEXT structure is defined as:

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

Member Descriptions

type is the XrStructureType of this structure.
next is NULL or a pointer to the next structure in a structure chain.
meshCount is a uint32_t describing the count of elements in the meshes array.
meshes is an array of XrSpatialMeshDataEXT .

The application can query the mesh 3D component of the spatial entities in an XrSpatialSnapshotEXT by adding XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT in XrSpatialComponentDataQueryConditionEXT :: componentTypes and adding XrSpatialComponentMesh3DListEXT to the next pointer chain of XrSpatialComponentDataQueryResultEXT .

The runtime must return XR_ERROR_VALIDATION_FAILURE from xrQuerySpatialComponentDataEXT if XrSpatialComponentMesh3DListEXT is in the next chain of XrSpatialComponentDataQueryResultEXT :: next but XrSpatialComponentDataQueryConditionEXT ::componentTypeCount is not zero and XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT is not included in XrSpatialComponentDataQueryConditionEXT :: componentTypes .

The runtime must return XR_ERROR_SIZE_INSUFFICIENT from xrQuerySpatialComponentDataEXT if meshCount is less than XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .

For the XrSpatialMeshDataEXT filled out by the runtime in the meshes array, the XrSpatialBufferEXT :: bufferType for XrSpatialMeshDataEXT :: vertexBuffer must be XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT and XrSpatialBufferEXT :: bufferType for XrSpatialMeshDataEXT :: indexBuffer must be XR_SPATIAL_BUFFER_TYPE_UINT32_EXT .

Valid Usage (Implicit)

The XR_EXT_spatial_entity extension must be enabled prior to using XrSpatialComponentMesh3DListEXT
type must be XR_TYPE_SPATIAL_COMPONENT_MESH_3D_LIST_EXT
next must be NULL or a valid pointer to the next structure in a structure chain
meshes must be a pointer to an array of meshCount XrSpatialMeshDataEXT structures
The meshCount parameter must be greater than 0

Configuration

If XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT is enumerated in XrSpatialCapabilityComponentTypesEXT :: componentTypes for some capability, the application can enable it by including the enum in the XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents list of the XrSpatialCapabilityConfigurationBaseHeaderEXT derived structure of the capability that supports this component.

This component does not require any special configuration to be included in the next chain of XrSpatialCapabilityConfigurationBaseHeaderEXT .

Tracking state filters

The XrSpatialFilterTrackingStateEXT structure is defined as:

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

Member Descriptions

type is the XrStructureType of this structure.
next is NULL or a pointer to the next structure in a structure chain.
trackingState is the XrSpatialEntityTrackingStateEXT for which the application wants to apply the filter.

The application can use XrSpatialFilterTrackingStateEXT in the next chain of XrSpatialDiscoverySnapshotCreateInfoEXT to scope the discovery to only those entities whose tracking state is trackingState .

The application can use XrSpatialFilterTrackingStateEXT in the next chain of XrSpatialComponentDataQueryConditionEXT to scope the component data query from a snapshot only to entities whose tracking state is trackingState .

Valid Usage (Implicit)

The XR_EXT_spatial_entity extension must be enabled prior to using XrSpatialFilterTrackingStateEXT
type must be XR_TYPE_SPATIAL_FILTER_TRACKING_STATE_EXT
next must be NULL or a valid pointer to the next structure in a structure chain
trackingState must be a valid XrSpatialEntityTrackingStateEXT value

Example code

Application Usage

Applications typically use the spatial entity extension in the following pattern:

An application first enumerates the spatial capabilities of the system using xrEnumerateSpatialCapabilitiesEXT . It then inspects the returned array of XrSpatialCapabilityEXT and enumerates the components and features supported for each of those capabilities by using xrEnumerateSpatialCapabilityComponentTypesEXT and xrEnumerateSpatialCapabilityFeaturesEXT respectively. This gives the application a full picture of the components that it can enable and the configurations the capability accepts.
The application then creates one or many XrSpatialContextEXT handles with specific spatial capability configurations, wherein the configurations enable & configure a specific capability in the spatial context, and enable & configure components for those capabilities.
For each XrSpatialContextEXT , the application waits to receive XrEventDataSpatialDiscoveryRecommendedEXT events for that XrSpatialContextEXT before using xrCreateSpatialDiscoverySnapshotAsyncEXT to discover spatial entities. Once this async operation is complete, the application receives a XrSpatialSnapshotEXT handle.
The application queries for the entities and the component data included in this XrSpatialSnapshotEXT by using xrQuerySpatialComponentDataEXT . The application reads the latest component data of the queried entities from structures attached to the next chain of XrSpatialComponentDataQueryResultEXT if the entity state is XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT .
If there are specific entities that the application identifies as interesting and wants to get updates for over time, it creates XrSpatialEntityEXT handles for those entities by using xrCreateSpatialEntityFromIdEXT . The application gets updates for such interesting entities by using xrCreateSpatialUpdateSnapshotEXT and use the same xrQuerySpatialComponentDataEXT function on the newly created XrSpatialSnapshotEXT to get the latest component data for those entities.

Discover spatial entities & query component data

The following example code demonstrates how to discover spatial entities for capability "Foo" query its component data.

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

Query buffer data

The following example code demonstrates how to get the data of a component that provides an 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.
  }
}

Extension guidelines

If an extension is defining a new XrSpatialComponentTypeEXT which provides additional data about a spatial entity,
- the extension must also define a list structure for that component which allows the application to pass an array to the runtime to fill out with the data for each of the spatial entities that satisfy xrQuerySpatialComponentDataEXT :: queryCondition . Some examples of such list structures are XrSpatialComponentParentListEXT and XrSpatialComponentBounded2DListEXT . If the component data size is variable and requires the application to use the two-call idiom to query it, the component data should provide an XrSpatialBufferEXT for each variable-sized data in the list structure and it must specify the XrSpatialBufferTypeEXT for each buffer. Application can then query the buffer data using functions defined in Two-call idiom for component data . An example of such a structure is XrSpatialMeshDataEXT which is included XrSpatialComponentMesh3DListEXT .
- The extension can also provide structures that the application can chain to XrSpatialComponentDataQueryConditionEXT :: next to provide additional filters for the query pertaining to the data of this component.
Extensions can define structures that extend XrSpatialDiscoverySnapshotCreateInfoEXT to provide additional filters for discovery. The filters for creating the snapshot must not affect the configuration of the spatial context, but instead are to be used to provide hints to the runtime on what entities and data are to be included in the snapshot as tracked by the current configuration of the spatial context (and therefore the current configuration of the underlying services).
If an extension defines a new XrSpatialCapabilityEXT ,
- it should also specify the list of XrSpatialComponentTypeEXT that the runtimes must provide on entities for that capability.
- it must also provide structures derived from XrSpatialCapabilityConfigurationBaseHeaderEXT that will allow the configuration of that capability.
If an extension defines a new XrSpatialCapabilityFeatureEXT , it must also define a corresponding configuration structure that can be chained to the next pointer of XrSpatialCapabilityConfigurationBaseHeaderEXT , that the application can use to enable the feature when creating an XrSpatialContextEXT .
An extension defining a new XrSpatialCapabilityEXT should follow this template for the specification -
- Overview
- Runtime support
- Configuration
- Guaranteed components
- Example Code
An extension defining a new XrSpatialComponentTypeEXT should follow this template for the specification -
- Component data
- Component list structure to query data
- Configuration
When writing an api that provides the application with a XrSpatialBufferIdEXT , it must be accompanied with a XrSpatialBufferTypeEXT to inform the application what the data type of the buffer is and the application can use an appropriate xrGetSpatialBuffer* function to retrieve the actual contents of the buffer.

Semantic Label Design & Extension Guidelines

While this extension does not define any component for conveying the semantic label information of an entity, it lays down the design rules and guidelines for any extensions that do define such a component. In the following text, " should " and " must " constrain the authors of such functionality, rather than constraining a runtime implementation or an application using the API.

If an extension is defining semantic labels for any XrSpatialCapabilityEXT , it should do so by defining a new XrSpatialComponentTypeEXT as well as a new enumeration with a set of labels (a "semantic label set") to be the data for that component.
An enumeration representing a semantic label set must have a value to indicate that the entity is not categorized into any of the labels of this set. The name of this enumerant must include 'UNCATEGORIZED', e.g. XR_SPATIAL_PLANE_SEMANTIC_LABEL_UNCATEGORIZED_EXT . This value indicates to applications that the runtime does recognize this entity, but that there are other semantic label sets where this entity is categorized.
Enumeration of this newly defined XrSpatialComponentTypeEXT in xrEnumerateSpatialCapabilityComponentTypesEXT implies that the runtime supports the semantic label set (and therefore the labels defined in the set) corresponding to that component type.
Applications express their desire to discover entities that have labels belonging to this semantic label set by including the corresponding XrSpatialComponentTypeEXT in the XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents array of the configuration struct for the capability that the component type is enumerated for.
It is possible that a single spatial entity has multiple components on it, each providing it with a label from their own semantic label set. Consider the following example with some hypothetical semantic label sets - XrSpatialObjectSemanticLabel , which might have values like chair, sofa, table etc., XrSpatialSofaBrand , which might have values like IKEA, Wayfair, etc., and XrSpatialIkeaSofa , which might have specific IKEA model names of sofas. In this scenario, the same sofa entity has all 3 components (labels from all 3 semantic label sets) on it, each giving a different granularity of information about the entity.
If an extension is defining a new XrSpatialComponentTypeEXT which provides a new semantic label set containing multiple labels in addition to the UNCATEGORIZED label, the extension should consider defining an XrSpatialCapabilityFeatureEXT which allows applications to activate only a subset of the labels defined in the semantic label set corresponding to that component type. This subset, provided in the next chain of the capability configuration, acts as a hint for runtimes to optimize their tracking pipelines and only track the subset provided. An example of such a feature struct is provided below .
Extensions must not add labels to existing semantic label set enumeration. They must instead define a new enumeration which contains equivalent enumerants with identical semantics and with values equal to those from the other set, in addition to the newly added enumerants. The specification of the newly defined semantic label set must also establish the mapping between the old label set and the new one. See example below .

Example Spatial Feature Definition for Semantic Label Subset

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

Example Spatial Semantic Label Extension

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;

Consider the above example where an extension defines an enumeration XrSpatialExamplePlaneSemanticLabelExtensionEXT in order to extend the existing XrSpatialPlaneSemanticLabelEXT with values to represent doors and windows. The specification for the new enumeration must include text for the following form -

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
|====

New Base Types

XrSpatialBufferIdEXT
XrSpatialEntityIdEXT

New Object Types

XrSpatialContextEXT
XrSpatialEntityEXT
XrSpatialSnapshotEXT

New Commands

xrCreateSpatialContextAsyncEXT
xrCreateSpatialContextCompleteEXT
xrCreateSpatialDiscoverySnapshotAsyncEXT
xrCreateSpatialDiscoverySnapshotCompleteEXT
xrCreateSpatialEntityFromIdEXT
xrCreateSpatialUpdateSnapshotEXT
xrDestroySpatialContextEXT
xrDestroySpatialEntityEXT
xrDestroySpatialSnapshotEXT
xrEnumerateSpatialCapabilitiesEXT
xrEnumerateSpatialCapabilityComponentTypesEXT
xrEnumerateSpatialCapabilityFeaturesEXT
xrGetSpatialBufferFloatEXT
xrGetSpatialBufferStringEXT
xrGetSpatialBufferUint16EXT
xrGetSpatialBufferUint32EXT
xrGetSpatialBufferUint8EXT
xrGetSpatialBufferVector2fEXT
xrGetSpatialBufferVector3fEXT
xrQuerySpatialComponentDataEXT

New Structures

XrCreateSpatialContextCompletionEXT
XrCreateSpatialDiscoverySnapshotCompletionEXT
XrCreateSpatialDiscoverySnapshotCompletionInfoEXT
XrEventDataSpatialDiscoveryRecommendedEXT
XrSpatialBounded2DDataEXT
XrSpatialBufferEXT
XrSpatialBufferGetInfoEXT
XrSpatialCapabilityComponentTypesEXT
XrSpatialCapabilityConfigurationBaseHeaderEXT
XrSpatialComponentDataQueryConditionEXT
XrSpatialComponentDataQueryResultEXT
XrSpatialContextCreateInfoEXT
XrSpatialDiscoverySnapshotCreateInfoEXT
XrSpatialEntityFromIdCreateInfoEXT
XrSpatialMeshDataEXT
XrSpatialUpdateSnapshotCreateInfoEXT
Extending XrSpatialComponentDataQueryResultEXT :
Extending XrSpatialDiscoverySnapshotCreateInfoEXT , XrSpatialComponentDataQueryConditionEXT :
- XrSpatialFilterTrackingStateEXT

New Enums

XrSpatialBufferTypeEXT
XrSpatialCapabilityEXT
XrSpatialCapabilityFeatureEXT
XrSpatialComponentTypeEXT
XrSpatialEntityTrackingStateEXT

New Enum Constants

XR_EXT_SPATIAL_ENTITY_EXTENSION_NAME
XR_EXT_spatial_entity_SPEC_VERSION
Extending XrObjectType :
- XR_OBJECT_TYPE_SPATIAL_CONTEXT_EXT
- XR_OBJECT_TYPE_SPATIAL_ENTITY_EXT
- XR_OBJECT_TYPE_SPATIAL_SNAPSHOT_EXT
Extending 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
Extending 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

Issues

Does a single entity always derive from solely a single capability?
- Resolved
- Answer: No. It is completely upto the runtime based on its own tracking capabilities and how it wants to represent a detected entity. The spec does not prescribe any particular representation of spatial entity except for the guaranteed components of a given capability to set a minimum expectation. A runtime may be able to merge entities detected by separate capabilities and represent them as a single entity with the guaranteed components of all the capabilities that helped identify it. An example of this could be that tables can be detected by both a plane tracking capability and an object tracking capability, with plane tracking providing the XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT component on the entity and object tracking providing XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT . A certain runtime may provide the table as 2 separate entities, each with their own set of guaranteed components, while certain runtimes may provide just 1 entity to represent the table, and have both XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT and XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT on the same entity. What is important to note here is that a given spatial entity can have at most a single component of any given component type . Therefore, if the component data produced by the different capabilities conflicts for a certain entity, the runtime must represent them as 2 separate entities.

Version History

Revision 1, 2024-04-12 (Nihav Jain, Google)
- Initial extension description