C Specification

The xrDiscoverSpacesMETA function is defined as:

// Provided by XR_META_spatial_entity_discovery
XrResult xrDiscoverSpacesMETA(
    XrSession                                   session,
    const XrSpaceDiscoveryInfoMETA*             info,
    XrAsyncRequestIdFB*                         requestId);

Parameters

Parameter Descriptions

  • session is a handle to an XrSession.

  • info contains the input struct XrSpaceDiscoveryInfoMETA for the Discovery 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 xrDiscoverSpacesMETA function discovers spaces that were persisted previously, and which comply with the filters passed in the XrSpaceDiscoveryInfoMETA info structure.

This operation is asynchronous.

If xrDiscoverSpacesMETA returns a XR_FAILED result, no discovery operation takes place and no events will be queued for this operation.

If the asynchronous operation is scheduled successfully, the runtime must return XR_SUCCESS and the asynchronous discovery operation will queue at least 1 event.

If Spatial Entities have been discovered and are ready for retrieval, the runtime must queue an XrEventDataSpaceDiscoveryResultsAvailableMETA event. The runtime may queue 0, 1, or more XrEventDataSpaceDiscoveryResultsAvailableMETA events depending on the Spatial Entities found.

If and only if the runtime returns XR_SUCCESS, the runtime must queue a single XrEventDataSpaceDiscoveryCompleteMETA event identified with a XrEventDataSpaceDiscoveryCompleteMETA::requestId matching the requestId value output by this function, referred to as the "corresponding completion event." The XrEventDataSpaceDiscoveryCompleteMETA event is queued after all XrEventDataSpaceDiscoveryResultsAvailableMETA events for this operation have been queued.

Completion results are conveyed in the event XrEventDataSpaceDiscoveryCompleteMETA, while availability of output for xrRetrieveSpaceDiscoveryResultsMETA is signaled by either this completion event or the event XrEventDataSpaceDiscoveryResultsAvailableMETA.

If the asynchronous operation is successful, in the corresponding completion event, the runtime must set the XrEventDataSpaceDiscoveryCompleteMETA::result field to XR_SUCCESS.

If the asynchronous operation is scheduled but not successful, in the corresponding completion event, the runtime must set the XrEventDataSpaceDiscoveryCompleteMETA::result field to an appropriate error code instead of XR_SUCCESS.

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_SPACE_RATE_LIMITED_META

  • XR_ERROR_SESSION_NOT_RUNNING

  • XR_ERROR_INITIALIZATION_FAILED

See Also

XR_META_spatial_entity_discovery, XrAsyncRequestIdFB, XrSession, XrSpaceDiscoveryInfoMETA, xrRetrieveSpaceDiscoveryResultsMETA

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.