C Specification

The xrCreateMarkerSpaceML function is defined as:

// Provided by XR_ML_marker_understanding
XrResult xrCreateMarkerSpaceML(
    XrSession                                   session,
    const XrMarkerSpaceCreateInfoML*            createInfo,
    XrSpace*                                    space);

Parameters

Parameter Descriptions

  • session is the session that will own the created space.

  • createInfo is a pointer to the XrMarkerSpaceCreateInfoML used to specify the space creation parameters.

  • space points to an XrSpace handle in which the resulting space is returned.

Description

Creates an XrSpace from a currently snapshotted marker. The space may still be used even if the marker is later not in the FOV, or even if the marker detector has been destroyed. In such a scenario, the XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT and XR_SPACE_LOCATION_POSITION_TRACKED_BIT must be false, but XR_SPACE_LOCATION_POSITION_VALID_BIT and XR_SPACE_LOCATION_ORIENTATION_VALID_BIT may be set as appropriate to the last known location.

Once an application has created a space, it may stop calling xrSnapshotMarkerDetectorML, and the position of the marker must still be updated by the runtime whenever it is aware of a more up to date location.

If a runtime is unable to spatially locate a snapshotted marker, it may return XR_ERROR_MARKER_DETECTOR_LOCATE_FAILED_ML. This is most likely to happen if significant time has passed since the snapshot of markers was acquired, and the marker in question is no longer in the user’s FOV. Thus, an application should call xrCreateMarkerSpaceML immediately after examining a snapshot, but should also be prepared to try again if needed.

must only be called when the state of the detector is XR_MARKER_DETECTOR_STATUS_READY_ML.

If xrGetMarkerDetectorStateML has not been called and returned XR_MARKER_DETECTOR_STATUS_READY_ML since the last invocation of xrSnapshotMarkerDetectorML, the runtime must return XR_ERROR_CALL_ORDER_INVALID.

session must be the same session that created the XrMarkerSpaceCreateInfoML::markerDetector, else the runtime must return XR_ERROR_HANDLE_INVALID.

The runtime must return XR_ERROR_MARKER_INVALID_ML if the marker atom is invalid.

The XrSpace origin must be located at the marker’s center. The X-Y plane of the XrSpace must be aligned with the plane of the marker with the positive Z axis coming out of the marker face.

xr ml marker understanding axis
Figure 1. QR code marker with axis
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_POSE_INVALID

  • XR_ERROR_MARKER_INVALID_ML

  • XR_ERROR_MARKER_DETECTOR_LOCATE_FAILED_ML

  • XR_ERROR_CALL_ORDER_INVALID

See Also

XR_ML_marker_understanding, XrMarkerSpaceCreateInfoML, XrSession, XrSpace, xrGetMarkersML

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-2024, The Khronos Group Inc.

This work is licensed under a Creative Commons Attribution 4.0 International License.