C Specification

The XrEventDataSpatialDiscoveryRecommendedEXT structure is defined as:

// Provided by XR_EXT_spatial_entity
typedef struct XrEventDataSpatialDiscoveryRecommendedEXT {
    XrStructureType        type;
    const void*            next;
    XrSpatialContextEXT    spatialContext;
} XrEventDataSpatialDiscoveryRecommendedEXT;

Members

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.

Description

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)

See Also

XR_EXT_spatial_entity, XrSpatialContextEXT, XrStructureType, xrCreateSpatialDiscoverySnapshotAsyncEXT, xrPollEvent

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.