C Specification

The xrCreateSpatialDiscoverySnapshotAsyncEXT function is defined as:

// Provided by XR_EXT_spatial_entity
XrResult xrCreateSpatialDiscoverySnapshotAsyncEXT(
    XrSpatialContextEXT                         spatialContext,
    const XrSpatialDiscoverySnapshotCreateInfoEXT* createInfo,
    XrFutureEXT*                                future);

Parameters

Parameter Descriptions

Description

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)
Return Codes
On success, this command returns

  • XR_SUCCESS

  • XR_SESSION_LOSS_PENDING

On failure, this command returns

  • XR_ERROR_FUNCTION_UNSUPPORTED

  • XR_ERROR_VALIDATION_FAILURE

  • XR_ERROR_RUNTIME_FAILURE

  • XR_ERROR_HANDLE_INVALID

  • XR_ERROR_INSTANCE_LOST

  • XR_ERROR_SESSION_LOST

  • XR_ERROR_OUT_OF_MEMORY

  • XR_ERROR_LIMIT_REACHED

  • XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT

See Also

XR_EXT_spatial_entity, XrFutureEXT, XrSpatialContextEXT, XrSpatialDiscoverySnapshotCreateInfoEXT, xrCreateSpatialDiscoverySnapshotCompleteEXT

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.