C Specification

The xrSaveSpacesMETA function is defined as:

// Provided by XR_META_spatial_entity_persistence
XrResult xrSaveSpacesMETA(
    XrSession                                   session,
    const XrSpacesSaveInfoMETA*                 info,
    XrAsyncRequestIdFB*                         requestId);

Parameters

Parameter Descriptions

  • session is a handle to an XrSession.

  • info contains the input struct XrSpacesSaveInfoMETA for the save operation.

  • requestId is a pointer to an XrAsyncRequestIdFB value and is an output parameter. The variable it points to is populated with the ID of this asynchronous request.

Description

The xrSaveSpacesMETA function persists the space(s) provided. The scope of the save operation is same-user, same-device, same-app. This is an asynchronous operation. Completion results are conveyed in the event XrEventDataSpacesSaveResultMETA.

The runtime must return XR_ERROR_HANDLE_INVALID from xrSaveSpacesMETA if any of the XrSpacesSaveInfoMETA::spaces are XR_NULL_HANDLE or otherwise invalid (e.g. not a Meta Spatial Entity XrSpace). Note that saving an entity which has already been saved previously is valid and a no-op.

The runtime must return XR_ERROR_VALIDATION_FAILURE from xrSaveSpacesMETA if either one of the following is true:

The length of the array XrSpacesSaveInfoMETA::spaces must have a size of at least XrSpacesSaveInfoMETA::spaceCount.

When initiated unsuccessfully (i.e. the immediate return value of the xrSaveSpacesMETA call is an error), the save operation terminates without saving any entities, and no save result event is queued.

When initiated successfully (i.e. the immediate return value of the xrSaveSpacesMETA call is not an error), the full save operation is asynchronous. The runtime must queue an XrEventDataSpacesSaveResultMETA event when the save operation completes, either successfully, qualified success (warning), or with an error. See the XrEventDataSpacesSaveResultMETA for which XrResult enumerants may be returned in the event.

Note that if the XrEventDataSpacesSaveResultMETA::result is an error, it is possible that any subset of the Spatial Entity Spaces were saved.

Valid Usage (Implicit)
Return Codes
On success, this command returns

  • XR_SUCCESS

  • XR_SESSION_LOSS_PENDING

  • XR_SESSION_NOT_FOCUSED

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_SPACE_RATE_LIMITED_META

  • XR_ERROR_SPACE_COMPONENT_NOT_ENABLED_FB

  • XR_ERROR_SESSION_NOT_RUNNING

  • XR_ERROR_INITIALIZATION_FAILED

See Also

XR_META_spatial_entity_persistence, XrAsyncRequestIdFB, XrSession, XrSpacesSaveInfoMETA, xrEraseSpacesMETA

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.