C Specification

The xrStartColocationAdvertisementMETA function is defined as:

// Provided by XR_META_colocation_discovery
XrResult xrStartColocationAdvertisementMETA(
    XrSession                                   session,
    const XrColocationAdvertisementStartInfoMETA* info,
    XrAsyncRequestIdFB*                         advertisementRequestId);

Parameters

Parameter Descriptions

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

  • info is a pointer to XrColocationAdvertisementStartInfoMETA structure to specify the visibility configuration.

  • advertisementRequestId 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 xrStartColocationAdvertisementMETA function requests that the current device become discoverable by other physically colocated devices running the same application.

If the system does not support colocation advertisement and discovery, the runtime must return XR_ERROR_FEATURE_UNSUPPORTED from xrStartColocationAdvertisementMETA. 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 XrEventDataStartColocationAdvertisementCompleteMETA.

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 XrEventDataStartColocationAdvertisementCompleteMETA event identified with a advertisementRequestId matching the advertisementRequestId 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 XrEventDataStartColocationAdvertisementCompleteMETA events with advertisementRequestId field matching the advertisementRequestId populated by this function.)

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

If the asynchronous operation is scheduled but not successful, in the corresponding completion event, the runtime must set the XrEventDataStartColocationAdvertisementCompleteMETA::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_RUNTIME_UNAVAILABLE

  • XR_ERROR_FEATURE_UNSUPPORTED

  • XR_ERROR_EXTENSION_NOT_PRESENT

See Also

XR_META_colocation_discovery, XrAsyncRequestIdFB, XrColocationAdvertisementStartInfoMETA, XrEventDataStartColocationAdvertisementCompleteMETA, 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.