C Specification

The xrPersistSpatialEntityAsyncEXT function is defined as:

// Provided by XR_EXT_spatial_persistence_operations
XrResult xrPersistSpatialEntityAsyncEXT(
    XrSpatialPersistenceContextEXT              persistenceContext,
    const XrSpatialEntityPersistInfoEXT*        persistInfo,
    XrFutureEXT*                                future);

Parameters

Parameter Descriptions

An application can persist a spatial entity using the xrPersistSpatialEntityAsyncEXT function.

Description

The runtime must return XR_ERROR_SPATIAL_ENTITY_ID_INVALID_EXT if XrSpatialEntityPersistInfoEXT::spatialEntityId does not belong to XrSpatialEntityPersistInfoEXT::spatialContext.

The runtime must return XR_ERROR_PERMISSION_INSUFFICIENT if the XrSpatialPersistenceScopeEXT that persistenceContext was configured with is a read-only scope and does not allow applications to modify the storage represented by it. An example of this would be if persistenceContext was created with XR_SPATIAL_PERSISTENCE_SCOPE_SYSTEM_MANAGED_EXT and the application uses xrPersistSpatialEntityAsyncEXT with that persistenceContext.

The runtime must return XR_ERROR_SPATIAL_PERSISTENCE_SCOPE_INCOMPATIBLE_EXT if the XrSpatialPersistenceScopeEXT that persistenceContext was configured does allow the application to persist entities of its choice in the storage but XrSpatialEntityPersistInfoEXT::spatialEntityId is not covered in the configured scope. An example of this would be if the persistence context scope is set to XR_SPATIAL_PERSISTENCE_SCOPE_LOCAL_ANCHORS_EXT, and XrSpatialEntityPersistInfoEXT::spatialEntityId does not represent an anchor.

The runtime must not return an error if XrSpatialEntityPersistInfoEXT::spatialContext was not configured with persistenceContext using XrSpatialContextPersistenceConfigEXT. Using xrPersistSpatialEntityAsyncEXT does not require that persistenceContext be connected with the spatial context.

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 xrPersistSpatialEntityCompleteEXT, usable when a future from this function is in the READY state, with outputs populated by that function in the completion structure XrPersistSpatialEntityCompletionEXT.

If the XrSpatialEntityTrackingStateEXT of XrSpatialEntityPersistInfoEXT::spatialEntityId is not XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT when xrPersistSpatialEntityAsyncEXT is called, the runtime must not return an error from this function or set XrPersistSpatialEntityCompletionEXT::futureResult to an error code to indicate this. The runtime may either set future to the READY state immediately and set XrPersistSpatialEntityCompletionEXT::persistResult to XR_SPATIAL_PERSISTENCE_CONTEXT_RESULT_ENTITY_NOT_TRACKING_EXT to indicate the lack of tracking state, or wait for the entity to get into tracking state as part of the async operation and set XrPersistSpatialEntityCompletionEXT::persistResult to XR_SPATIAL_PERSISTENCE_CONTEXT_RESULT_ENTITY_NOT_TRACKING_EXT if the entity does not get into tracking state until a runtime determined timeout. A common usage pattern of applications is to create a spatial anchor using xrCreateSpatialAnchorEXT and then immediately request to persist the newly created spatial anchor using xrPersistSpatialEntityAsyncEXT. XR_EXT_spatial_anchor states that the tracking state of an anchor may not be XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT immediately upon its creation. For such cases, the runtime should wait for the anchor to get into tracking state as part of the persist async operation instead of immediately setting future to the READY state and fail the operation with XR_SPATIAL_PERSISTENCE_CONTEXT_RESULT_ENTITY_NOT_TRACKING_EXT only if the anchor does not get into tracking state within a runtime determined timeout.

If the spatial entity represented by XrSpatialEntityPersistInfoEXT::spatialEntityId has already been persisted in the scope associated with persistenceContext, the runtime must not treat that as an error but instead complete the async operation successfully and provide the appropriate persist UUID to the application.

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_PERSISTENCE_SCOPE_INCOMPATIBLE_EXT

  • XR_ERROR_SPATIAL_ENTITY_ID_INVALID_EXT

  • XR_ERROR_PERMISSION_INSUFFICIENT

See Also

XR_EXT_spatial_persistence_operations, XrFutureEXT, XrSpatialContextEXT, XrSpatialEntityIdEXT, XrSpatialEntityPersistInfoEXT, XrSpatialPersistenceContextEXT, xrPersistSpatialEntityCompleteEXT

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.