C Specification

The xrCreateSpatialContextAsyncEXT function is defined as:

// Provided by XR_EXT_spatial_entity
XrResult xrCreateSpatialContextAsyncEXT(
    XrSession                                   session,
    const XrSpatialContextCreateInfoEXT*        createInfo,
    XrFutureEXT*                                future);

Parameters

Parameter Descriptions

Description

The application can create an XrSpatialContextEXT handle by:

The runtime must return XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT if XrSpatialContextCreateInfoEXT::capabilityConfigCount is 0. A spatial context handle needs at least one capability.

The runtime must return XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT if any capability in the XrSpatialContextCreateInfoEXT::capabilityConfigs array is not enumerated by xrEnumerateSpatialCapabilitiesEXT.

The runtime must return XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT if any XrSpatialCapabilityConfigurationBaseHeaderEXT::enabledComponentCount in XrSpatialContextCreateInfoEXT::capabilityConfigs is 0. A capability configuration is incomplete without a list of component types to enable for that capability.

The runtime must return XR_ERROR_SPATIAL_COMPONENT_UNSUPPORTED_FOR_CAPABILITY_EXT if any component type listed in XrSpatialCapabilityConfigurationBaseHeaderEXT::enabledComponents is not enumerated for XrSpatialCapabilityConfigurationBaseHeaderEXT::capability in xrEnumerateSpatialCapabilityComponentTypesEXT.

If any of the structures in the next chain of XrSpatialContextCreateInfoEXT::capabilityConfigs corresponds to an XrSpatialCapabilityFeatureEXT that is not enumerated for that capability in xrEnumerateSpatialCapabilityFeaturesEXT, the runtime must ignore that XrSpatialCapabilityFeatureEXT structure.

The runtime must return XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT if XrSpatialContextCreateInfoEXT::capabilityConfigs contains multiple structures with the same XrSpatialCapabilityConfigurationBaseHeaderEXT::capability.

To ensure optimal use of system resources, the runtime may use the configurations provided in XrSpatialContextCreateInfoEXT array to prepare itself for spatial requests to come in. For example, a runtime that supports plane tracking capability may only begin its plane tracking pipeline if a spatial context handle containing the plane tracking capability is created by the application. If the configured capabilities have a long warm-up time, calls to xrCreateSpatialDiscoverySnapshotAsyncEXT may result in an empty snapshot. Application can wait for XrEventDataSpatialDiscoveryRecommendedEXT before using xrCreateSpatialDiscoverySnapshotAsyncEXT to be sure that the underlying tracking services have warmed up.

If a runtime enforces a permission system to control application access to the spatial capabilities being configured for the XrSpatialContextEXT, then the runtime must return XR_ERROR_PERMISSION_INSUFFICIENT if those permissions have not been granted to this application.

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

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_UNSUPPORTED_FOR_CAPABILITY_EXT

  • XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT

  • XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT

  • XR_ERROR_PERMISSION_INSUFFICIENT

See Also

XR_EXT_spatial_entity, XrFutureEXT, XrSession, XrSpatialContextCreateInfoEXT, XrSpatialContextEXT, xrCreateSpatialContextCompleteEXT, xrDestroySpatialContextEXT

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.