C Specification

The xrRetrieveSpaceDiscoveryResultsMETA function is defined as:

// Provided by XR_META_spatial_entity_discovery
XrResult xrRetrieveSpaceDiscoveryResultsMETA(
    XrSession                                   session,
    XrAsyncRequestIdFB                          requestId,
    XrSpaceDiscoveryResultsMETA*                results);

Parameters

Parameter Descriptions

Description

The xrRetrieveSpaceDiscoveryResultsMETA function is synchronous, and follows the 2-call idiom, where the first call is made to determine the number of results, populated in the XrSpaceDiscoveryResultsMETA::resultCountOutput. The application uses this value to initialize the XrSpaceDiscoveryResultsMETA::resultCapacityInput and XrSpaceDiscoveryResultsMETA::results fields. The second call to xrRetrieveSpaceDiscoveryResultsMETA must then populate the results field with whatever results are available. See https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#fundamentals-buffer-size-parameters for a detailed description of retrieving the required results size.

Note that after any results have been retrieved, those specific results will be unavailable for retrieval again. Application developers can choose to retrieve discovered Spatial Entities either after receiving an XrEventDataSpaceDiscoveryResultsAvailableMETA event or after receiving an XrEventDataSpaceDiscoveryCompleteMETA event. If application developers choose to retrieve after XrEventDataSpaceDiscoveryResultsAvailableMETA events (before the XrEventDataSpaceDiscoveryCompleteMETA event), more results may be discovered between the first and the second call to xrRetrieveSpaceDiscoveryResultsMETA. If this occurs, and if the application chose the result array capacity to match the XrSpaceDiscoveryResultsMETA::resultCountOutput, that capacity is no longer sufficient to receive all available results, so the second call will fail due to insufficient size. This will not lose results, and the application can begin the two-call process for xrRetrieveSpaceDiscoveryResultsMETA again.

xrPollEvent and xrRetrieveSpaceDiscoveryResultsMETA may be called simultaneously (without external synchronization).

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_SIZE_INSUFFICIENT

See Also

XR_META_spatial_entity_discovery, XrAsyncRequestIdFB, XrSession, XrSpaceDiscoveryResultsMETA, xrDiscoverSpacesMETA

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.