C Specification

The xrStartColocationDiscoveryMETA function is defined as:

// Provided by XR_META_colocation_discovery
XrResult xrStartColocationDiscoveryMETA(
    XrSession                                   session,
    const XrColocationDiscoveryStartInfoMETA*   info,
    XrAsyncRequestIdFB*                         discoveryRequestId);

Parameters

Parameter Descriptions

  • session is an XrSession in which the colocation discovery will be active.

  • info is a pointer to XrColocationDiscoveryStartInfoMETA structure to specify the discovery request information.

  • discoveryRequestId is an output parameter, and the variable it points to will be populated with the ID of this asynchronous request. Note that this ID is used for associating additional events with this original call, in addition to the typical completion event.

Description

The application can call xrStartColocationDiscoveryMETA to start discovering physically colocated devices.

If the system does not support colocation advertisement and discovery, the runtime must return XR_ERROR_FEATURE_UNSUPPORTED from xrStartColocationDiscoveryMETA. In this case, the runtime must return XR_FALSE for XrSystemColocationDiscoveryPropertiesMETA::supportsColocationDiscovery when the function xrGetSystemProperties is called, so that the application knows to not use this functionality.

This is an asynchronous operation. Completion results are conveyed in the event XrEventDataStartColocationDiscoveryCompleteMETA.

If the asynchronous operation is scheduled successfully, the runtime must return XR_SUCCESS.

If and only if the runtime returns XR_SUCCESS, the runtime must queue a single XrEventDataStartColocationDiscoveryCompleteMETA event identified with a discoveryRequestId matching the discoveryRequestId value output by this function, referred to as the "corresponding completion event."

(This implies that if the runtime returns anything other than XR_SUCCESS, the runtime must not queue any XrEventDataStartColocationDiscoveryCompleteMETA events with discoveryRequestId field matching the discoveryRequestId populated by this function.)

If the asynchronous operation is successful, in the corresponding completion event, the runtime must set the XrEventDataStartColocationDiscoveryCompleteMETA::result field to XR_SUCCESS. The runtime may subsequently queue zero or more XrEventDataColocationDiscoveryResultMETA events asynchronously as the runtime discovers nearby advertisements. Once the application or runtime stops the colocation discovery, the runtime must queue a single XrEventDataColocationDiscoveryCompleteMETA event. All XrEventDataColocationDiscoveryResultMETA and XrEventDataColocationDiscoveryCompleteMETA events will identified with discoveryRequestId matching the value populated in discoveryRequestId by xrStartColocationDiscoveryMETA.

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

If the application already has an active colocation discovery, in the corresponding completion event, the runtime must set the XrEventDataStartColocationDiscoveryCompleteMETA::result field to XR_COLOCATION_DISCOVERY_ALREADY_DISCOVERING_META.

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_RUNTIME_UNAVAILABLE

  • XR_ERROR_FEATURE_UNSUPPORTED

  • XR_ERROR_EXTENSION_NOT_PRESENT

See Also

XR_META_colocation_discovery, XrAsyncRequestIdFB, XrColocationDiscoveryStartInfoMETA, XrEventDataStartColocationDiscoveryCompleteMETA, XrSession

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.