C Specification

// Provided by XR_EXT_spatial_entity
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;

Description

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 1. 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.

See Also

XR_EXT_spatial_entity, XrSpatialComponentDataQueryResultEXT, XrSpatialEntityEXT, XrSpatialFilterTrackingStateEXT

Document Notes

For more information, see the OpenXR Specification

This page is extracted from the OpenXR Specification. Fixes and changes should be made to the Specification, not directly.

Copyright

Copyright 2014-2025 The Khronos Group Inc.

This work is licensed under a Creative Commons Attribution 4.0 International License.