Copyright 2014-2024, The Khronos Group Inc.

OpenXR Commands

xrAcquireSwapchainImage(3)

Name

xrAcquireSwapchainImage - Acquire a swapchain image

C Specification

The xrAcquireSwapchainImage function is defined as:

// Provided by XR_VERSION_1_0
XrResult xrAcquireSwapchainImage(
    XrSwapchain                                 swapchain,
    const XrSwapchainImageAcquireInfo*          acquireInfo,
    uint32_t*                                   index);

Parameters

Parameter Descriptions
  • swapchain is the swapchain from which to acquire an image.

  • acquireInfo exists for extensibility purposes, it is NULL or a pointer to a valid XrSwapchainImageAcquireInfo.

  • index is the returned image index that has been acquired.

Description

Acquires the image corresponding to the index position in the array returned by xrEnumerateSwapchainImages. The runtime must return XR_ERROR_CALL_ORDER_INVALID if the next available index has already been acquired and not yet released with xrReleaseSwapchainImage. If the swapchain was created with the XR_SWAPCHAIN_CREATE_STATIC_IMAGE_BIT set in XrSwapchainCreateInfo::createFlags, this function must not have been previously called for this swapchain. The runtime must return XR_ERROR_CALL_ORDER_INVALID if a swapchain created with the XR_SWAPCHAIN_CREATE_STATIC_IMAGE_BIT set in XrSwapchainCreateInfo::createFlags and this function has been successfully called previously for this swapchain.

This function only provides the index of the swapchain image, for example for use in recording command buffers. It does not wait for the image to be usable by the application. The application must call xrWaitSwapchainImage for each "acquire" call before submitting graphics commands that write to the image.

Valid Usage (Implicit)
  • swapchain must be a valid XrSwapchain handle

  • If acquireInfo is not NULL, acquireInfo must be a pointer to a valid XrSwapchainImageAcquireInfo structure

  • index must be a pointer to a uint32_t value

Return Codes
On success, this command returns
  • XR_SUCCESS

  • XR_SESSION_LOSS_PENDING

On failure, this command returns
  • XR_ERROR_VALIDATION_FAILURE

  • XR_ERROR_RUNTIME_FAILURE

  • XR_ERROR_HANDLE_INVALID

  • XR_ERROR_INSTANCE_LOST

  • XR_ERROR_SESSION_LOST

  • XR_ERROR_CALL_ORDER_INVALID

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

xrApplyForceFeedbackCurlMNDX(3)

Name

xrApplyForceFeedbackCurlMNDX - Applies force feedback to a set of locations

C Specification

The xrApplyForceFeedbackCurlMNDX function is defined as:

// Provided by XR_MNDX_force_feedback_curl
XrResult xrApplyForceFeedbackCurlMNDX(
    XrHandTrackerEXT                            handTracker,
    const XrForceFeedbackCurlApplyLocationsMNDX* locations);

Parameters

Parameter Descriptions

Description

The xrApplyForceFeedbackCurlMNDX function applies force feedback to the set locations listed in XrForceFeedbackCurlApplyLocationsMNDX.

xrApplyForceFeedbackCurlMNDX should be called every time an application wishes to update a set of force feedback locations.

Submits a request for force feedback for a set of locations. The runtime should deliver this request to the handTracker device. If the handTracker device is not available, the runtime may ignore this request for force feedback.

If the session associated with handTracker is not focused, the runtime must return XR_SESSION_NOT_FOCUSED, and not apply force feedback.

When an application submits force feedback for a set of locations, the runtime must update the set of locations to that specified by the application. A runtime must set any locations not specified by the application when submitting force feedback to 0.

The runtime may discontinue force feedback if the application that set it loses focus. An application should call the function again after regaining focus if force feedback is still desired.

Valid Usage (Implicit)
Return Codes
On success, this command returns
  • XR_SUCCESS

  • XR_SESSION_LOSS_PENDING

  • XR_SESSION_NOT_FOCUSED

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

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

xrApplyFoveationHTC(3)

Name

xrApplyFoveationHTC - Apply foveation config to system.

C Specification

The xrApplyFoveationHTC function is defined as:

// Provided by XR_HTC_foveation
XrResult xrApplyFoveationHTC(
    XrSession                                   session,
    const XrFoveationApplyInfoHTC*              applyInfo);

Parameters

Parameter Descriptions

Description

The foveation configuration will be applied after this call, and the state will persist until the next call to xrApplyFoveationHTC or the end of this XrSession, whichever comes first. You should not call xrApplyFoveationHTC during rendering to target image layer XrSwapchainSubImage in render loop.

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_LIMIT_REACHED

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

xrApplyHapticFeedback(3)

Name

xrApplyHapticFeedback - Apply haptic feedback

C Specification

The xrApplyHapticFeedback function is defined as:

// Provided by XR_VERSION_1_0
XrResult xrApplyHapticFeedback(
    XrSession                                   session,
    const XrHapticActionInfo*                   hapticActionInfo,
    const XrHapticBaseHeader*                   hapticFeedback);

Parameters

Parameter Descriptions
  • session is the XrSession to start outputting to.

  • hapticActionInfo is a pointer to XrHapticActionInfo to provide action and subaction paths information.

  • hapticFeedback is a pointer to a haptic event structure which starts with an XrHapticBaseHeader.

Description

Triggers a haptic event through the specified action of type XR_ACTION_TYPE_VIBRATION_OUTPUT. The runtime should deliver this request to the appropriate device, but exactly which device, if any, this event is sent to is up to the runtime to decide. If an appropriate device is unavailable the runtime may ignore this request for haptic feedback.

If session is not focused, the runtime must return XR_SESSION_NOT_FOCUSED, and not trigger a haptic event.

If another haptic event from this session is currently happening on the device bound to this action, the runtime must interrupt that other event and replace it with the new one.

Valid Usage (Implicit)
Return Codes
On success, this command returns
  • XR_SUCCESS

  • XR_SESSION_LOSS_PENDING

  • XR_SESSION_NOT_FOCUSED

On failure, this command returns
  • XR_ERROR_VALIDATION_FAILURE

  • XR_ERROR_RUNTIME_FAILURE

  • XR_ERROR_HANDLE_INVALID

  • XR_ERROR_INSTANCE_LOST

  • XR_ERROR_SESSION_LOST

  • XR_ERROR_PATH_UNSUPPORTED

  • XR_ERROR_PATH_INVALID

  • XR_ERROR_ACTION_TYPE_MISMATCH

  • XR_ERROR_ACTIONSET_NOT_ATTACHED

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

xrAttachSessionActionSets(3)

Name

xrAttachSessionActionSets - Attaches action sets to a given session

C Specification

The xrAttachSessionActionSets function is defined as:

// Provided by XR_VERSION_1_0
XrResult xrAttachSessionActionSets(
    XrSession                                   session,
    const XrSessionActionSetsAttachInfo*        attachInfo);

Parameters

Parameter Descriptions

Description

xrAttachSessionActionSets attaches the XrActionSet handles in XrSessionActionSetsAttachInfo::actionSets to the session. Action sets must be attached in order to be synchronized with xrSyncActions.

When an action set is attached to a session, that action set becomes immutable. See xrCreateAction and xrSuggestInteractionProfileBindings for details.

After action sets are attached to a session, if any unattached actions are passed to functions for the same session, then for those functions the runtime must return XR_ERROR_ACTIONSET_NOT_ATTACHED.

The runtime must return XR_ERROR_ACTIONSETS_ALREADY_ATTACHED if xrAttachSessionActionSets is called more than once for a given session.

Valid Usage (Implicit)
Return Codes
On success, this command returns
  • XR_SUCCESS

  • XR_SESSION_LOSS_PENDING

On failure, this command returns
  • XR_ERROR_VALIDATION_FAILURE

  • XR_ERROR_RUNTIME_FAILURE

  • XR_ERROR_HANDLE_INVALID

  • XR_ERROR_INSTANCE_LOST

  • XR_ERROR_SESSION_LOST

  • XR_ERROR_ACTIONSETS_ALREADY_ATTACHED

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

xrBeginFrame(3)

Name

xrBeginFrame - Marks a frame

C Specification

The xrBeginFrame function is defined as:

// Provided by XR_VERSION_1_0
XrResult xrBeginFrame(
    XrSession                                   session,
    const XrFrameBeginInfo*                     frameBeginInfo);

Parameters

Parameter Descriptions
  • session is a valid XrSession handle.

  • frameBeginInfo exists for extensibility purposes, it is NULL or a pointer to a valid XrFrameBeginInfo.

Description

xrBeginFrame is called prior to the start of frame rendering. The application should still call xrBeginFrame but omit rendering work for the frame if XrFrameState::shouldRender is XR_FALSE.

Runtimes must not perform frame synchronization or throttling through the xrBeginFrame function and should instead do so through xrWaitFrame.

The runtime must return the error code XR_ERROR_CALL_ORDER_INVALID if there was no corresponding successful call to xrWaitFrame. The runtime must return the success code XR_FRAME_DISCARDED if a prior xrBeginFrame has been called without an intervening call to xrEndFrame. Refer to xrBeginSession for details on how a transition to session running resets the frame function call order.

The runtime must return XR_ERROR_SESSION_NOT_RUNNING if the session is not running.

Valid Usage (Implicit)
  • session must be a valid XrSession handle

  • If frameBeginInfo is not NULL, frameBeginInfo must be a pointer to a valid XrFrameBeginInfo structure

Thread Safety
  • Access to the session parameter by any other xrBeginFrame or xrEndFrame call must be externally synchronized

Return Codes
On success, this command returns
  • XR_SUCCESS

  • XR_SESSION_LOSS_PENDING

  • XR_FRAME_DISCARDED

On failure, this command returns
  • XR_ERROR_VALIDATION_FAILURE

  • XR_ERROR_RUNTIME_FAILURE

  • XR_ERROR_HANDLE_INVALID

  • XR_ERROR_INSTANCE_LOST

  • XR_ERROR_SESSION_LOST

  • XR_ERROR_SESSION_NOT_RUNNING

  • XR_ERROR_CALL_ORDER_INVALID

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

xrBeginPlaneDetectionEXT(3)

Name

xrBeginPlaneDetectionEXT - Detect planes

C Specification

The xrBeginPlaneDetectionEXT function is defined as:

// Provided by XR_EXT_plane_detection
XrResult xrBeginPlaneDetectionEXT(
    XrPlaneDetectorEXT                          planeDetector,
    const XrPlaneDetectorBeginInfoEXT*          beginInfo);

Parameters

Parameter Descriptions

Description

The xrBeginPlaneDetectionEXT function begins the detection of planes in the scene. Detecting planes in a scene is an asynchronous operation. xrGetPlaneDetectionStateEXT can be used to determine if the query has finished. Once it has finished the results may be retrieved via xrGetPlaneDetectionsEXT. If a detection has already been started on a plane detector handle, calling xrBeginPlaneDetectionEXT again on the same handle will cancel the operation in progress and start a new detection with the new filter parameters.

The bounding volume is resolved and fixed relative to LOCAL space at the time of the call to xrBeginPlaneDetectionEXT using XrPlaneDetectorBeginInfoEXT::baseSpace, XrPlaneDetectorBeginInfoEXT::time, XrPlaneDetectorBeginInfoEXT::boundingBoxPose and XrPlaneDetectorBeginInfoEXT::boundingBoxExtent. The runtime must resolve the location defined by XrPlaneDetectorBeginInfoEXT::baseSpace at the time of the call. The XrPlaneDetectorBeginInfoEXT::boundingBoxPose is the pose of the center of the box defined by XrPlaneDetectorBeginInfoEXT::boundingBoxExtent.

The runtime must return XR_ERROR_SPACE_NOT_LOCATABLE_EXT if the XrPlaneDetectorBeginInfoEXT::baseSpace is not locatable at the time of the call.

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_TIME_INVALID

  • XR_ERROR_SPACE_NOT_LOCATABLE_EXT

  • XR_ERROR_POSE_INVALID

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

xrBeginSession(3)

Name

xrBeginSession - Begins an XrSession

C Specification

The xrBeginSession function is defined as:

// Provided by XR_VERSION_1_0
XrResult xrBeginSession(
    XrSession                                   session,
    const XrSessionBeginInfo*                   beginInfo);

Parameters

Parameter Descriptions

Description

When the application receives XrEventDataSessionStateChanged event with the XR_SESSION_STATE_READY state, the application should then call xrBeginSession to start rendering frames for display to the user.

After this function successfully returns, the session is considered to be running. The application should then start its frame loop consisting of some sequence of xrWaitFrame/xrBeginFrame/xrEndFrame calls.

If the session is already running when the application calls xrBeginSession, the runtime must return error XR_ERROR_SESSION_RUNNING. If the session is not running when the application calls xrBeginSession, but the session is not yet in the XR_SESSION_STATE_READY state, the runtime must return error XR_ERROR_SESSION_NOT_READY.

Note that a runtime may decide not to show the user any given frame from a session at any time, for example if the user has switched to a different application’s running session. The application should check whether xrWaitFrame returns XrFrameState::shouldRender set to true before rendering a given frame to determine whether that frame will be visible to the user.

Runtime session frame state must start in a reset state when a session transitions to running so that no state is carried over from when the same session was previously running. Frame state in this context includes xrWaitFrame, xrBeginFrame, and xrEndFrame call order enforcement.

If XrSessionBeginInfo::primaryViewConfigurationType in beginInfo is not supported by the XrSystemId used to create the session, the runtime must return XR_ERROR_VIEW_CONFIGURATION_TYPE_UNSUPPORTED.

Valid Usage (Implicit)
Return Codes
On success, this command returns
  • XR_SUCCESS

  • XR_SESSION_LOSS_PENDING

On failure, this command returns
  • XR_ERROR_VALIDATION_FAILURE

  • XR_ERROR_RUNTIME_FAILURE

  • XR_ERROR_HANDLE_INVALID

  • XR_ERROR_INSTANCE_LOST

  • XR_ERROR_SESSION_LOST

  • XR_ERROR_VIEW_CONFIGURATION_TYPE_UNSUPPORTED

  • XR_ERROR_SESSION_RUNNING

  • XR_ERROR_SESSION_NOT_READY

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

xrChangeVirtualKeyboardTextContextMETA(3)

Name

xrChangeVirtualKeyboardTextContextMETA - Change virtual keyboard text context

C Specification

The xrChangeVirtualKeyboardTextContextMETA function is defined as:

// Provided by XR_META_virtual_keyboard
XrResult xrChangeVirtualKeyboardTextContextMETA(
    XrVirtualKeyboardMETA                       keyboard,
    const XrVirtualKeyboardTextContextChangeInfoMETA* changeInfo);

Parameters

Parameter Descriptions

Description

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_FEATURE_UNSUPPORTED

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

xrClearSpatialAnchorStoreMSFT(3)

Name

xrClearSpatialAnchorStoreMSFT - Clear all spatial anchors from the spatial anchor store

C Specification

The application can use the xrClearSpatialAnchorStoreMSFT function to remove all spatial anchors from the spatial anchor store for this application. The function only removes the record of the spatial anchors in the store but does not affect any XrSpatialAnchorMSFT handles previously loaded in the current session.

// Provided by XR_MSFT_spatial_anchor_persistence
XrResult xrClearSpatialAnchorStoreMSFT(
    XrSpatialAnchorStoreConnectionMSFT          spatialAnchorStore);

Parameters

Parameter Descriptions

Description

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_HANDLE_INVALID

  • XR_ERROR_INSTANCE_LOST

  • XR_ERROR_SESSION_LOST

  • XR_ERROR_OUT_OF_MEMORY

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

xrComputeNewSceneMSFT(3)

Name

xrComputeNewSceneMSFT - Compute new scene

C Specification

The xrComputeNewSceneMSFT function begins the compute of a new scene and the runtime must return quickly without waiting for the compute to complete. The application should use xrGetSceneComputeStateMSFT to inspect the compute status.

The application can control the compute features by passing a list of XrSceneComputeFeatureMSFT via XrNewSceneComputeInfoMSFT::requestedFeatures.

  • If XR_SCENE_COMPUTE_FEATURE_PLANE_MSFT is passed, but XR_SCENE_COMPUTE_FEATURE_PLANE_MESH_MSFT is not passed, then:

    • The application may be able to read XR_SCENE_COMPONENT_TYPE_PLANE_MSFT and XR_SCENE_COMPONENT_TYPE_OBJECT_MSFT scene components from the resulting XrSceneMSFT handle.

    • XrScenePlaneMSFT::meshBufferId must be zero to indicate that the plane scene component does not have a mesh buffer available to read.

  • If XR_SCENE_COMPUTE_FEATURE_PLANE_MSFT and XR_SCENE_COMPUTE_FEATURE_PLANE_MESH_MSFT are passed, then:

    • the application may be able to read XR_SCENE_COMPONENT_TYPE_PLANE_MSFT and XR_SCENE_COMPONENT_TYPE_OBJECT_MSFT scene components from the resulting XrSceneMSFT handle

    • XrScenePlaneMSFT::meshBufferId may contain a non-zero mesh buffer identifier to indicate that the plane scene component has a mesh buffer available to read.

  • If XR_SCENE_COMPUTE_FEATURE_VISUAL_MESH_MSFT is passed then:

    • the application may be able to read XR_SCENE_COMPONENT_TYPE_VISUAL_MESH_MSFT and XR_SCENE_COMPONENT_TYPE_OBJECT_MSFT scene components from the resulting XrSceneMSFT handle.

  • If XR_SCENE_COMPUTE_FEATURE_COLLIDER_MESH_MSFT is passed then:

    • the application may be able to read XR_SCENE_COMPONENT_TYPE_COLLIDER_MESH_MSFT and XR_SCENE_COMPONENT_TYPE_OBJECT_MSFT scene components from the resulting XrSceneMSFT handle.

// Provided by XR_MSFT_scene_understanding
XrResult xrComputeNewSceneMSFT(
    XrSceneObserverMSFT                         sceneObserver,
    const XrNewSceneComputeInfoMSFT*            computeInfo);

Parameters

Parameter Descriptions

Description

The runtime must return XR_ERROR_SCENE_COMPUTE_FEATURE_INCOMPATIBLE_MSFT if incompatible features were passed or no compatible features were passed.

The runtime must return XR_ERROR_SCENE_COMPUTE_FEATURE_INCOMPATIBLE_MSFT if XR_SCENE_COMPUTE_FEATURE_PLANE_MESH_MSFT was passed but XR_SCENE_COMPUTE_FEATURE_PLANE_MSFT was not passed.

The runtime must return XR_ERROR_COMPUTE_NEW_SCENE_NOT_COMPLETED_MSFT if xrComputeNewSceneMSFT is called while the scene computation is in progress.

An application that wishes to use XR_SCENE_COMPUTE_CONSISTENCY_OCCLUSION_OPTIMIZED_MSFT must create an XrSceneObserverMSFT handle that passes neither XR_SCENE_COMPUTE_CONSISTENCY_SNAPSHOT_COMPLETE_MSFT nor XR_SCENE_COMPUTE_CONSISTENCY_SNAPSHOT_INCOMPLETE_FAST_MSFT to xrComputeNewSceneMSFT for the lifetime of that XrSceneObserverMSFT handle. This allows the runtime to return occlusion mesh at a different cadence than non-occlusion mesh or planes.

  • The runtime must return XR_ERROR_SCENE_COMPUTE_CONSISTENCY_MISMATCH_MSFT if:

  • The runtime must return XR_ERROR_SCENE_COMPUTE_CONSISTENCY_MISMATCH_MSFT if:

  • The runtime must return XR_ERROR_SCENE_COMPUTE_FEATURE_INCOMPATIBLE_MSFT if:

    • XR_SCENE_COMPUTE_CONSISTENCY_OCCLUSION_OPTIMIZED_MSFT is passed to xrComputeNewSceneMSFT and

    • neither XR_SCENE_COMPUTE_FEATURE_VISUAL_MESH_MSFT nor XR_SCENE_COMPUTE_FEATURE_COLLIDER_MESH_MSFT are also passed.

  • The runtime must return XR_ERROR_SCENE_COMPUTE_FEATURE_INCOMPATIBLE_MSFT if:

    • XR_SCENE_COMPUTE_CONSISTENCY_OCCLUSION_OPTIMIZED_MSFT is passed to xrComputeNewSceneMSFT and

    • at least one of XR_SCENE_COMPUTE_FEATURE_SERIALIZE_SCENE_MSFT, XR_SCENE_COMPUTE_FEATURE_PLANE_MSFT, XR_SCENE_COMPUTE_FEATURE_PLANE_MESH_MSFT, or XR_SCENE_COMPUTE_FEATURE_SERIALIZE_SCENE_MSFT are also passed.

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_TIME_INVALID

  • XR_ERROR_SCENE_COMPUTE_FEATURE_INCOMPATIBLE_MSFT

  • XR_ERROR_SCENE_COMPUTE_CONSISTENCY_MISMATCH_MSFT

  • XR_ERROR_POSE_INVALID

  • XR_ERROR_COMPUTE_NEW_SCENE_NOT_COMPLETED_MSFT

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

xrConvertTimeToTimespecTimeKHR(3)

Name

xrConvertTimeToTimespecTimeKHR - Convert XrTime to timespec monotonic time

C Specification

To convert from XrTime to timespec monotonic time, call:

// Provided by XR_KHR_convert_timespec_time
XrResult xrConvertTimeToTimespecTimeKHR(
    XrInstance                                  instance,
    XrTime                                      time,
    struct timespec*                            timespecTime);

Parameters

Parameter Descriptions
  • instance is an XrInstance handle previously created with xrCreateInstance.

  • time is an XrTime.

  • timespecTime is the resulting timespec time that is equivalent to a timespec obtained from clock_gettime with CLOCK_MONOTONIC.

Description

The xrConvertTimeToTimespecTimeKHR function converts an XrTime to time as if generated by clock_gettime.

If the output timespecTime cannot represent the input time, the runtime must return XR_ERROR_TIME_INVALID.

Valid Usage (Implicit)
Return Codes
On success, this command returns
  • XR_SUCCESS

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_TIME_INVALID

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

xrConvertTimeToWin32PerformanceCounterKHR(3)

Name

xrConvertTimeToWin32PerformanceCounterKHR - Convert XrTime to Win32 QueryPerformanceCounter time

C Specification

To convert from XrTime to a Windows performance counter time stamp, call:

// Provided by XR_KHR_win32_convert_performance_counter_time
XrResult xrConvertTimeToWin32PerformanceCounterKHR(
    XrInstance                                  instance,
    XrTime                                      time,
    LARGE_INTEGER*                              performanceCounter);

Parameters

Parameter Descriptions
  • instance is an XrInstance handle previously created with xrCreateInstance.

  • time is an XrTime.

  • performanceCounter is the resulting Windows performance counter time stamp that is equivalent to the time.

Description

The xrConvertTimeToWin32PerformanceCounterKHR function converts an XrTime to time as if generated by the QueryPerformanceCounter Windows function.

If the output performanceCounter cannot represent the input time, the runtime must return XR_ERROR_TIME_INVALID.

Valid Usage (Implicit)
Return Codes
On success, this command returns
  • XR_SUCCESS

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_TIME_INVALID

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

xrConvertTimespecTimeToTimeKHR(3)

Name

xrConvertTimespecTimeToTimeKHR - Convert timespec monotonic time to XrTime

C Specification

To convert from timespec monotonic time to XrTime, call:

// Provided by XR_KHR_convert_timespec_time
XrResult xrConvertTimespecTimeToTimeKHR(
    XrInstance                                  instance,
    const struct timespec*                      timespecTime,
    XrTime*                                     time);

Parameters

Parameter Descriptions
  • instance is an XrInstance handle previously created with xrCreateInstance.

  • timespecTime is a timespec obtained from clock_gettime with CLOCK_MONOTONIC.

  • time is the resulting XrTime that is equivalent to the timespecTime.

Description

The xrConvertTimespecTimeToTimeKHR function converts a time obtained by the clock_gettime function to the equivalent XrTime.

If the output time cannot represent the input timespecTime, the runtime must return XR_ERROR_TIME_INVALID.

Valid Usage (Implicit)
Return Codes
On success, this command returns
  • XR_SUCCESS

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_TIME_INVALID

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

xrConvertWin32PerformanceCounterToTimeKHR(3)

Name

xrConvertWin32PerformanceCounterToTimeKHR - Convert Win32 QueryPerformanceCounter time to XrTime

C Specification

To convert from a Windows performance counter time stamp to XrTime, call:

// Provided by XR_KHR_win32_convert_performance_counter_time
XrResult xrConvertWin32PerformanceCounterToTimeKHR(
    XrInstance                                  instance,
    const LARGE_INTEGER*                        performanceCounter,
    XrTime*                                     time);

Parameters

Parameter Descriptions
  • instance is an XrInstance handle previously created with xrCreateInstance.

  • performanceCounter is a time returned by QueryPerformanceCounter.

  • time is the resulting XrTime that is equivalent to the performanceCounter.

Description

The xrConvertWin32PerformanceCounterToTimeKHR function converts a time stamp obtained by the QueryPerformanceCounter Windows function to the equivalent XrTime.

If the output time cannot represent the input performanceCounter, the runtime must return XR_ERROR_TIME_INVALID.

Valid Usage (Implicit)
Return Codes
On success, this command returns
  • XR_SUCCESS

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_TIME_INVALID

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

xrCreateAction(3)

Name

xrCreateAction - Creates an XrAction

C Specification

The xrCreateAction function is defined as:

// Provided by XR_VERSION_1_0
XrResult xrCreateAction(
    XrActionSet                                 actionSet,
    const XrActionCreateInfo*                   createInfo,
    XrAction*                                   action);

Parameters

Parameter Descriptions
  • actionSet is a handle to an XrActionSet.

  • createInfo is a pointer to a valid XrActionCreateInfo structure that defines the action being created.

  • action is a pointer to an XrAction where the created action is returned.

Description

xrCreateAction creates an action and returns its handle.

If actionSet has been included in a call to xrAttachSessionActionSets, the implementation must return XR_ERROR_ACTIONSETS_ALREADY_ATTACHED.

Valid Usage (Implicit)
Return Codes
On success, this command returns
  • XR_SUCCESS

On failure, this command returns
  • XR_ERROR_VALIDATION_FAILURE

  • XR_ERROR_RUNTIME_FAILURE

  • XR_ERROR_HANDLE_INVALID

  • XR_ERROR_INSTANCE_LOST

  • XR_ERROR_OUT_OF_MEMORY

  • XR_ERROR_LIMIT_REACHED

  • XR_ERROR_PATH_UNSUPPORTED

  • XR_ERROR_PATH_INVALID

  • XR_ERROR_PATH_FORMAT_INVALID

  • XR_ERROR_NAME_INVALID

  • XR_ERROR_NAME_DUPLICATED

  • XR_ERROR_LOCALIZED_NAME_INVALID

  • XR_ERROR_LOCALIZED_NAME_DUPLICATED

  • XR_ERROR_ACTIONSETS_ALREADY_ATTACHED

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

xrCreateActionSet(3)

Name

xrCreateActionSet - Creates an XrActionSet

C Specification

The xrCreateActionSet function is defined as:

// Provided by XR_VERSION_1_0
XrResult xrCreateActionSet(
    XrInstance                                  instance,
    const XrActionSetCreateInfo*                createInfo,
    XrActionSet*                                actionSet);

Parameters

Parameter Descriptions
  • instance is a handle to an XrInstance.

  • createInfo is a pointer to a valid XrActionSetCreateInfo structure that defines the action set being created.

  • actionSet is a pointer to an XrActionSet where the created action set is returned.

Description

The xrCreateActionSet function creates an action set and returns a handle to the created action set.

Valid Usage (Implicit)
Return Codes
On success, this command returns
  • XR_SUCCESS

On failure, this command returns
  • XR_ERROR_VALIDATION_FAILURE

  • XR_ERROR_RUNTIME_FAILURE

  • XR_ERROR_HANDLE_INVALID

  • XR_ERROR_INSTANCE_LOST

  • XR_ERROR_OUT_OF_MEMORY

  • XR_ERROR_LIMIT_REACHED

  • XR_ERROR_PATH_FORMAT_INVALID

  • XR_ERROR_NAME_INVALID

  • XR_ERROR_NAME_DUPLICATED

  • XR_ERROR_LOCALIZED_NAME_INVALID

  • XR_ERROR_LOCALIZED_NAME_DUPLICATED

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

xrCreateActionSpace(3)

Name

xrCreateActionSpace - Creates a space based on a pose action

C Specification

The xrCreateActionSpace function is defined as:

// Provided by XR_VERSION_1_0
XrResult xrCreateActionSpace(
    XrSession                                   session,
    const XrActionSpaceCreateInfo*              createInfo,
    XrSpace*                                    space);

Parameters

Parameter Descriptions
  • session is the XrSession to create the action space in.

  • createInfo is the XrActionSpaceCreateInfo used to specify the space.

  • space is the returned space handle.

Description

Creates an XrSpace handle based on a chosen pose action. Application can provide an XrPosef to define the position and orientation of the new space’s origin within the natural reference frame of the action space.

Multiple XrSpace handles may exist simultaneously, up to some limit imposed by the runtime. The XrSpace handle must be eventually freed via the xrDestroySpace function or by destroying the parent XrAction handle.

The runtime must return XR_ERROR_ACTION_TYPE_MISMATCH if the action provided in XrActionSpaceCreateInfo::action is not of type XR_ACTION_TYPE_POSE_INPUT.

Valid Usage (Implicit)
Return Codes
On success, this command returns
  • XR_SUCCESS

  • XR_SESSION_LOSS_PENDING

On failure, this command returns
  • 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_PATH_UNSUPPORTED

  • XR_ERROR_PATH_INVALID

  • XR_ERROR_ACTION_TYPE_MISMATCH

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

xrCreateApiLayerInstance(3)

Name

xrCreateApiLayerInstance - xrCreateInstance for API layers

C Specification

The xrCreateApiLayerInstance function is defined as:

// Provided by XR_LOADER_VERSION_1_0
XrResult xrCreateApiLayerInstance(
    const XrInstanceCreateInfo*                 info,
    const XrApiLayerCreateInfo*                 layerInfo,
    XrInstance*                                 instance);

Parameters

Parameter Descriptions
  • info is a pointer to the XrInstanceCreateInfo information passed by the application into the outer xrCreateInstance function.

  • layerInfo is a pointer to an XrApiLayerCreateInfo structure that contains special information required by a API layer during its create instance process. This is generated by the loader.

  • instance is a pointer to store the returned instance in, just as in the standard xrCreateInstance function.

Description

An API layer’s implementation of the xrCreateApiLayerInstance function is invoked during the loader’s implementation of xrCreateInstance, if the layer in question is enabled.

An API layer needs additional information during xrCreateInstance calls, so each API layer must implement the xrCreateApiLayerInstance function, which is a special API layer function.

An API layer must not implement xrCreateInstance.

xrCreateApiLayerInstance must be called by the loader during its implementation of the xrCreateInstance function.

The loader must call the first API layer’s xrCreateApiLayerInstance function passing in the pointer to the created XrApiLayerCreateInfo.

The XrApiLayerCreateInfo::nextInfo must be a linked-list of XrApiLayerNextInfo structures with information about each of the API layers that are to be enabled. Note that this does not operate like a next chain in the OpenXR application API, but instead describes the enabled API layers from outermost to innermost.

The API layer may validate that it is getting the correct next information by checking that the XrApiLayerNextInfo::layerName matches the expected value.

The API layer must use the information in its XrApiLayerNextInfo to call down the call chain to the next xrCreateApiLayerInstance:

Valid Usage (Implicit)
Return Codes
On success, this command returns
  • XR_SUCCESS

On failure, this command returns
  • XR_ERROR_INITIALIZATION_FAILED

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

xrCreateBodyTrackerFB(3)

Name

xrCreateBodyTrackerFB - Create a body joints handle.

C Specification

An application can create an XrBodyTrackerFB handle using xrCreateBodyTrackerFB function.

// Provided by XR_FB_body_tracking
XrResult xrCreateBodyTrackerFB(
    XrSession                                   session,
    const XrBodyTrackerCreateInfoFB*            createInfo,
    XrBodyTrackerFB*                            bodyTracker);

Parameters

Parameter Descriptions

Description

If the system does not support body tracking, the runtime must return XR_ERROR_FEATURE_UNSUPPORTED from xrCreateBodyTrackerFB. In this case, the runtime must return XR_FALSE for XrSystemBodyTrackingPropertiesFB::supportsBodyTracking when the function xrGetSystemProperties is called, so that the application can avoid creating a body tracker.

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_FEATURE_UNSUPPORTED

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

xrCreateDebugUtilsMessengerEXT(3)

Name

xrCreateDebugUtilsMessengerEXT - Creates a debug messenger

C Specification

// Provided by XR_EXT_debug_utils
XrResult xrCreateDebugUtilsMessengerEXT(
    XrInstance                                  instance,
    const XrDebugUtilsMessengerCreateInfoEXT*   createInfo,
    XrDebugUtilsMessengerEXT*                   messenger);

Parameters

Parameter Descriptions
  • instance is the instance the messenger will be used with.

  • createInfo points to an XrDebugUtilsMessengerCreateInfoEXT structure, which contains the callback pointer as well as defines the conditions under which this messenger will trigger the callback.

  • messenger is a pointer to which the created XrDebugUtilsMessengerEXT object is returned.

Description

Valid Usage (Implicit)
Thread Safety
  • Access to instance, and any child handles, must be externally synchronized

Return Codes
On success, this command returns
  • XR_SUCCESS

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_OUT_OF_MEMORY

  • XR_ERROR_LIMIT_REACHED

The application must ensure that xrCreateDebugUtilsMessengerEXT is not executed in parallel with any OpenXR function that is also called with instance or child of instance.

When an event of interest occurs a debug messenger calls its XrDebugUtilsMessengerCreateInfoEXT::userCallback with a debug message from the producer of the event. Additionally, the debug messenger must filter out any debug messages that the application’s callback is not interested in based on XrDebugUtilsMessengerCreateInfoEXT flags, as described below.

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

xrCreateExportedLocalizationMapML(3)

Name

xrCreateExportedLocalizationMapML - Creates an exported localization map handle.

C Specification

The xrCreateExportedLocalizationMapML function is defined as:

// Provided by XR_ML_localization_map
XrResult xrCreateExportedLocalizationMapML(
    XrSession                                   session,
    const XrUuidEXT*                            mapUuid,
    XrExportedLocalizationMapML*                map);

Parameters

Parameter Descriptions
  • session is a handle to an XrSession previously created with xrCreateSession.

  • mapUuid is a pointer to the uuid of the map to export.

  • map is a pointer to a map handle filled in by the runtime.

Description

xrCreateExportedLocalizationMapML creates a frozen copy of the mapUuid localization map that can be exported using xrGetExportedLocalizationMapDataML. Applications should call xrDestroyExportedLocalizationMapML once they are done with the data.

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_LOCALIZATION_MAP_UNAVAILABLE_ML

  • XR_ERROR_LOCALIZATION_MAP_IMPORT_EXPORT_PERMISSION_DENIED_ML

  • XR_ERROR_LOCALIZATION_MAP_CANNOT_EXPORT_CLOUD_MAP_ML

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

xrCreateEyeTrackerFB(3)

Name

xrCreateEyeTrackerFB - Create an eye gaze handle.

C Specification

An application creates an XrEyeTrackerFB handle using xrCreateEyeTrackerFB function.

// Provided by XR_FB_eye_tracking_social
XrResult xrCreateEyeTrackerFB(
    XrSession                                   session,
    const XrEyeTrackerCreateInfoFB*             createInfo,
    XrEyeTrackerFB*                             eyeTracker);

Parameters

Parameter Descriptions

Description

If the system does not support eye tracking, the runtime must return XR_ERROR_FEATURE_UNSUPPORTED from xrCreateEyeTrackerFB. In this case, the runtime must return XR_FALSE for XrSystemEyeTrackingPropertiesFB::supportsEyeTracking when the function xrGetSystemProperties is called, so that the application can avoid creating an eye tracker.

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_FEATURE_UNSUPPORTED

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

xrCreateFaceTracker2FB(3)

Name

xrCreateFaceTracker2FB - Create a face tracking handle.

C Specification

The xrCreateFaceTracker2FB function is defined as:

// Provided by XR_FB_face_tracking2
XrResult xrCreateFaceTracker2FB(
    XrSession                                   session,
    const XrFaceTrackerCreateInfo2FB*           createInfo,
    XrFaceTracker2FB*                           faceTracker);

Parameters

Parameter Descriptions

Description

An application can create an XrFaceTracker2FB handle using xrCreateFaceTracker2FB function.

If the system does not support face tracking, the runtime must return XR_ERROR_FEATURE_UNSUPPORTED from xrCreateFaceTracker2FB. In this case, the runtime must return XR_FALSE for both XrSystemFaceTrackingProperties2FB::supportsVisualFaceTracking and XrSystemFaceTrackingProperties2FB::supportsAudioFaceTracking when the function xrGetSystemProperties is called, so that the application can avoid creating a face tracker.

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_FEATURE_UNSUPPORTED

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

xrCreateFaceTrackerFB(3)

Name

xrCreateFaceTrackerFB - Create a face tracking handle.

C Specification

The xrCreateFaceTrackerFB function is defined as:

// Provided by XR_FB_face_tracking
XrResult xrCreateFaceTrackerFB(
    XrSession                                   session,
    const XrFaceTrackerCreateInfoFB*            createInfo,
    XrFaceTrackerFB*                            faceTracker);

Parameters

Parameter Descriptions

Description

An application can create an XrFaceTrackerFB handle using xrCreateFaceTrackerFB function.

If the system does not support face tracking, the runtime must return XR_ERROR_FEATURE_UNSUPPORTED from xrCreateFaceTrackerFB. In this case, the runtime must return XR_FALSE for XrSystemFaceTrackingPropertiesFB::supportsFaceTracking when the function xrGetSystemProperties is called, so that the application can avoid creating a face tracker.

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_FEATURE_UNSUPPORTED

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

xrCreateFacialTrackerHTC(3)

Name

xrCreateFacialTrackerHTC - Create an facial tracker handle.

C Specification

The xrCreateFacialTrackerHTC function is defined as

// Provided by XR_HTC_facial_tracking
XrResult xrCreateFacialTrackerHTC(
    XrSession                                   session,
    const XrFacialTrackerCreateInfoHTC*         createInfo,
    XrFacialTrackerHTC*                         facialTracker);

Parameters

Parameter Descriptions

Description

An application can create an XrFacialTrackerHTC handle using xrCreateFacialTrackerHTC.

If the system does not support eye tracking or lip tracking, runtime must return XR_ERROR_FEATURE_UNSUPPORTED from xrCreateFacialTrackerHTC according to the corresponding case. In this case, the runtime must return XR_FALSE for XrSystemFacialTrackingPropertiesHTC::supportEyeFacialTracking or XrSystemFacialTrackingPropertiesHTC::supportLipFacialTracking when the function xrGetSystemProperties is called, so that the application may avoid creating a facial tracker.

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_FEATURE_UNSUPPORTED

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

xrCreateFoveationProfileFB(3)

Name

xrCreateFoveationProfileFB - Create a foveation profile

C Specification

The xrCreateFoveationProfileFB function is defined as:

// Provided by XR_FB_foveation
XrResult xrCreateFoveationProfileFB(
    XrSession                                   session,
    const XrFoveationProfileCreateInfoFB*       createInfo,
    XrFoveationProfileFB*                       profile);

Parameters

Parameter Descriptions
  • session is the XrSession that created the swapchains to which this foveation profile will be applied.

  • createInfo is a pointer to an XrFoveationProfileCreateInfoFB structure containing parameters to be used to create the foveation profile.

  • profile is a pointer to a handle in which the created XrFoveationProfileFB is returned.

Description

Creates an XrFoveationProfileFB handle. The returned foveation profile handle may be subsequently used in API calls.

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

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

xrCreateGeometryInstanceFB(3)

Name

xrCreateGeometryInstanceFB - Create a triangle mesh

C Specification

The xrCreateGeometryInstanceFB function is defined as:

// Provided by XR_FB_passthrough
XrResult xrCreateGeometryInstanceFB(
    XrSession                                   session,
    const XrGeometryInstanceCreateInfoFB*       createInfo,
    XrGeometryInstanceFB*                       outGeometryInstance);

Parameters

Parameter Descriptions

Description

Creates an XrGeometryInstanceFB handle. Geometry instance functionality requires XR_FB_triangle_mesh extension to be enabled. An XrGeometryInstanceFB connects a layer, a mesh, and a transformation, with the semantics that a specific mesh will be instantiated in a specific layer with a specific transformation. A mesh can be instantiated multiple times, in the same or in different layers.

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_INSUFFICIENT_RESOURCES_PASSTHROUGH_FB

  • XR_ERROR_FEATURE_UNSUPPORTED

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

xrCreateHandMeshSpaceMSFT(3)

Name

xrCreateHandMeshSpaceMSFT - Create a space for hand mesh tracking

C Specification

The application creates a hand mesh space using function xrCreateHandMeshSpaceMSFT. The position and normal of hand mesh vertices will be represented in this space.

// Provided by XR_MSFT_hand_tracking_mesh
XrResult xrCreateHandMeshSpaceMSFT(
    XrHandTrackerEXT                            handTracker,
    const XrHandMeshSpaceCreateInfoMSFT*        createInfo,
    XrSpace*                                    space);

Parameters

Parameter Descriptions

Description

A hand mesh space location is specified by runtime preference to effectively represent hand mesh vertices without unnecessary transformations. For example, an optical hand tracking system can define the hand mesh space origin at the depth camera’s optical center.

An application should create separate hand mesh space handles for each hand to retrieve the corresponding hand mesh data. The runtime may use the lifetime of this hand mesh space handle to manage the underlying device resources. Therefore, the application should destroy the hand mesh handle after it is finished using the hand mesh.

The hand mesh space can be related to other spaces in the session, such as view reference space, or grip action space from the /interaction_profiles/khr/simple_controller interaction profile. The hand mesh space may be not locatable when the hand is outside of the tracking range, or if focus is removed from the application. In these cases, the runtime must not set the XR_SPACE_LOCATION_POSITION_VALID_BIT and XR_SPACE_LOCATION_ORIENTATION_VALID_BIT bits on calls to xrLocateSpace with the hand mesh space, and the application should avoid using the returned poses or query for hand mesh data.

If the underlying XrHandTrackerEXT is destroyed, the runtime must continue to support xrLocateSpace using the hand mesh space, and it must return space location with XR_SPACE_LOCATION_POSITION_VALID_BIT and XR_SPACE_LOCATION_ORIENTATION_VALID_BIT unset.

The application may create a mesh space for the reference hand by setting XrHandPoseTypeInfoMSFT::handPoseType to XR_HAND_POSE_TYPE_REFERENCE_OPEN_PALM_MSFT. Hand mesh spaces for the reference hand must only be locatable in reference to mesh spaces or joint spaces of the reference hand.

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_FEATURE_UNSUPPORTED

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

xrCreateHandTrackerEXT(3)

Name

xrCreateHandTrackerEXT - Create a hand joints handle.

C Specification

An application can create an XrHandTrackerEXT handle using xrCreateHandTrackerEXT function.

// Provided by XR_EXT_hand_tracking
XrResult xrCreateHandTrackerEXT(
    XrSession                                   session,
    const XrHandTrackerCreateInfoEXT*           createInfo,
    XrHandTrackerEXT*                           handTracker);

Parameters

Parameter Descriptions

Description

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_FEATURE_UNSUPPORTED

If the system does not support hand tracking, runtime must return XR_ERROR_FEATURE_UNSUPPORTED from xrCreateHandTrackerEXT. In this case, the runtime must return XR_FALSE for XrSystemHandTrackingPropertiesEXT::supportsHandTracking when the function xrGetSystemProperties is called, so that the application can avoid creating a hand tracker.

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

xrCreateInstance(3)

Name

xrCreateInstance - Creates an OpenXR Instance

C Specification

The xrCreateInstance function is defined as:

// Provided by XR_VERSION_1_0
XrResult xrCreateInstance(
    const XrInstanceCreateInfo*                 createInfo,
    XrInstance*                                 instance);

Parameters

Parameter Descriptions
  • createInfo points to an instance of XrInstanceCreateInfo controlling creation of the instance.

  • instance points to an XrInstance handle in which the resulting instance is returned.

Description

xrCreateInstance creates the XrInstance, then enables and initializes global API layers and extensions requested by the application. If an extension is provided by an API layer, both the API layer and extension must be specified at xrCreateInstance time. If a specified API layer cannot be found, no XrInstance will be created and the function will return XR_ERROR_API_LAYER_NOT_PRESENT. Likewise, if a specified extension cannot be found, the call must return XR_ERROR_EXTENSION_NOT_PRESENT and no XrInstance will be created. Additionally, some runtimes may limit the number of concurrent instances that may be in use. If the application attempts to create more instances than a runtime can simultaneously support, xrCreateInstance may return XR_ERROR_LIMIT_REACHED.

If the XrApplicationInfo::applicationName is the empty string the runtime must return XR_ERROR_NAME_INVALID.

If the XrInstanceCreateInfo structure contains a platform-specific extension for a platform other than the target platform, XR_ERROR_INITIALIZATION_FAILED may be returned. If a mandatory platform-specific extension is defined for the target platform but no matching extension struct is provided in XrInstanceCreateInfo the runtime must return XR_ERROR_INITIALIZATION_FAILED.

Valid Usage (Implicit)
Return Codes
On success, this command returns
  • XR_SUCCESS

On failure, this command returns
  • XR_ERROR_VALIDATION_FAILURE

  • XR_ERROR_RUNTIME_FAILURE

  • XR_ERROR_OUT_OF_MEMORY

  • XR_ERROR_LIMIT_REACHED

  • XR_ERROR_RUNTIME_UNAVAILABLE

  • XR_ERROR_NAME_INVALID

  • XR_ERROR_INITIALIZATION_FAILED

  • XR_ERROR_EXTENSION_NOT_PRESENT

  • XR_ERROR_API_VERSION_UNSUPPORTED

  • XR_ERROR_API_LAYER_NOT_PRESENT

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

xrCreateKeyboardSpaceFB(3)

Name

xrCreateKeyboardSpaceFB - Create a foveation profile

C Specification

The xrCreateKeyboardSpaceFB function is defined as:

// Provided by XR_FB_keyboard_tracking
XrResult xrCreateKeyboardSpaceFB(
    XrSession                                   session,
    const XrKeyboardSpaceCreateInfoFB*          createInfo,
    XrSpace*                                    keyboardSpace);

Parameters

Parameter Descriptions
  • session is the session that will be associated with the returned keyboard space.

  • createInfo is the XrKeyboardSpaceCreateInfoFB that describes the type of keyboard to track.

  • keyboardSpace is the XrSpace output structure.

Description

The xrCreateKeyboardSpaceFB function returns an XrSpace that can be used to locate a physical keyboard in space. The origin of the created XrSpace is located in the center of the bounding box in the x and z axes, and at the top of the y axis (meaning the keyboard is located entirely in negative y).

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_FEATURE_UNSUPPORTED

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

xrCreateMarkerDetectorML(3)

Name

xrCreateMarkerDetectorML - Create a marker detection handle.

C Specification

The xrCreateMarkerDetectorML function is defined as:

// Provided by XR_ML_marker_understanding
XrResult xrCreateMarkerDetectorML(
    XrSession                                   session,
    const XrMarkerDetectorCreateInfoML*         createInfo,
    XrMarkerDetectorML*                         markerDetector);

Parameters

An application creates an XrMarkerDetectorML handle using the xrCreateMarkerDetectorML function. If createInfo contains mutually exclusive contents, the runtime must return XR_ERROR_MARKER_DETECTOR_INVALID_CREATE_INFO_ML.

Description

If a runtime is unable to create a marker detector due to some internal limit, the runtime must return XR_ERROR_LIMIT_REACHED.

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_MARKER_DETECTOR_PERMISSION_DENIED_ML

  • XR_ERROR_MARKER_DETECTOR_INVALID_CREATE_INFO_ML

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

xrCreateMarkerSpaceML(3)

Name

xrCreateMarkerSpaceML - Create an XrSpace to track a marker spatially

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

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

xrCreateMarkerSpaceVARJO(3)

Name

xrCreateMarkerSpaceVARJO - Creates marker space

C Specification

The xrCreateMarkerSpaceVARJO function is defined as:

// Provided by XR_VARJO_marker_tracking
XrResult xrCreateMarkerSpaceVARJO(
    XrSession                                   session,
    const XrMarkerSpaceCreateInfoVARJO*         createInfo,
    XrSpace*                                    space);

Parameters

Parameter Descriptions
  • session is an XrSession handle previously created with xrCreateSession.

  • createInfo is the structure containing information about how to create the space based on marker.

  • space is a pointer to a handle in which the created XrSpace is returned.

Description

The xrCreateMarkerSpaceVARJO function creates marker XrSpace for pose relative to the marker specified in XrMarkerSpaceCreateInfoVARJO. The runtime must return XR_ERROR_MARKER_ID_INVALID_VARJO if the supplied XrMarkerSpaceCreateInfoVARJO::markerId is invalid.

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_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_ID_INVALID_VARJO

  • XR_ERROR_FEATURE_UNSUPPORTED

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

xrCreatePassthroughColorLutMETA(3)

Name

xrCreatePassthroughColorLutMETA - Create a passthrough color LUT

C Specification

The xrCreatePassthroughColorLutMETA function is defined as:

// Provided by XR_META_passthrough_color_lut
XrResult xrCreatePassthroughColorLutMETA(
    XrPassthroughFB                             passthrough,
    const XrPassthroughColorLutCreateInfoMETA*  createInfo,
    XrPassthroughColorLutMETA*                  colorLut);

Parameters

Parameter Descriptions

Description

Creates a passthrough color LUT. The resulting XrPassthroughColorLutMETA may be referenced in XrPassthroughColorMapLutMETA and XrPassthroughColorMapInterpolatedLutMETA in subsequent calls to xrPassthroughLayerSetStyleFB.

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_PASSTHROUGH_COLOR_LUT_BUFFER_SIZE_MISMATCH_META

  • XR_ERROR_FEATURE_UNSUPPORTED

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

xrCreatePassthroughFB(3)

Name

xrCreatePassthroughFB - Create a passthrough feature

C Specification

The xrCreatePassthroughFB function is defined as:

// Provided by XR_FB_passthrough
XrResult xrCreatePassthroughFB(
    XrSession                                   session,
    const XrPassthroughCreateInfoFB*            createInfo,
    XrPassthroughFB*                            outPassthrough);

Parameters

Parameter Descriptions

Description

Creates an XrPassthroughFB handle. The returned passthrough handle may be subsequently used in API calls.

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_UNKNOWN_PASSTHROUGH_FB

  • XR_ERROR_NOT_PERMITTED_PASSTHROUGH_FB

  • XR_ERROR_FEATURE_UNSUPPORTED

  • XR_ERROR_FEATURE_ALREADY_CREATED_PASSTHROUGH_FB

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

xrCreatePassthroughHTC(3)

Name

xrCreatePassthroughHTC - Create a passthrough handle.

C Specification

The xrCreatePassthroughHTC function is defined as:

// Provided by XR_HTC_passthrough
XrResult xrCreatePassthroughHTC(
    XrSession                                   session,
    const XrPassthroughCreateInfoHTC*           createInfo,
    XrPassthroughHTC*                           passthrough);

Parameters

Parameter Descriptions
  • session is an XrSession in which the passthrough will be active.

  • createInfo is a pointer to an XrPassthroughCreateInfoHTC structure containing information about how to create the passthrough.

  • passthrough is a pointer to a handle in which the created XrPassthroughHTC is returned.

Description

Creates an XrPassthroughHTC handle.

If the function successfully returned, the output passthrough must be a valid handle.

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_FEATURE_UNSUPPORTED

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

xrCreatePassthroughLayerFB(3)

Name

xrCreatePassthroughLayerFB - Create a passthrough layer

C Specification

The xrCreatePassthroughLayerFB function is defined as:

// Provided by XR_FB_passthrough
XrResult xrCreatePassthroughLayerFB(
    XrSession                                   session,
    const XrPassthroughLayerCreateInfoFB*       createInfo,
    XrPassthroughLayerFB*                       outLayer);

Parameters

Parameter Descriptions

Description

Creates an XrPassthroughLayerFB handle. The returned layer handle may be subsequently used in API calls. Layer objects may be used to specify rendering properties of the layer, such as styles, and compositing rules.

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_UNKNOWN_PASSTHROUGH_FB

  • XR_ERROR_INSUFFICIENT_RESOURCES_PASSTHROUGH_FB

  • XR_ERROR_FEATURE_UNSUPPORTED

  • XR_ERROR_FEATURE_REQUIRED_PASSTHROUGH_FB

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

xrCreatePlaneDetectorEXT(3)

Name

xrCreatePlaneDetectorEXT - Create a plane detection handle.

C Specification

The xrCreatePlaneDetectorEXT function is defined as:

// Provided by XR_EXT_plane_detection
XrResult xrCreatePlaneDetectorEXT(
    XrSession                                   session,
    const XrPlaneDetectorCreateInfoEXT*         createInfo,
    XrPlaneDetectorEXT*                         planeDetector);

Parameters

Parameter Descriptions

Description

An application creates an XrPlaneDetectorEXT handle using xrCreatePlaneDetectorEXT function.

If the system does not support plane detection, the runtime must return XR_ERROR_FEATURE_UNSUPPORTED from xrCreatePlaneDetectorEXT.

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_PLANE_DETECTION_PERMISSION_DENIED_EXT

  • XR_ERROR_FEATURE_UNSUPPORTED

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

xrCreateReferenceSpace(3)

Name

xrCreateReferenceSpace - Creates a reference space

C Specification

The xrCreateReferenceSpace function is defined as:

// Provided by XR_VERSION_1_0
XrResult xrCreateReferenceSpace(
    XrSession                                   session,
    const XrReferenceSpaceCreateInfo*           createInfo,
    XrSpace*                                    space);

Parameters

Parameter Descriptions

Description

Creates an XrSpace handle based on a chosen reference space. Application can provide an XrPosef to define the position and orientation of the new space’s origin within the natural reference frame of the reference space.

Multiple XrSpace handles may exist simultaneously, up to some limit imposed by the runtime. The XrSpace handle must be eventually freed via the xrDestroySpace function.

The runtime must return XR_ERROR_REFERENCE_SPACE_UNSUPPORTED if the given reference space type is not supported by this session.

Valid Usage (Implicit)
Return Codes
On success, this command returns
  • XR_SUCCESS

  • XR_SESSION_LOSS_PENDING

On failure, this command returns
  • 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_REFERENCE_SPACE_UNSUPPORTED

  • XR_ERROR_POSE_INVALID

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

xrCreateSceneMSFT(3)

Name

xrCreateSceneMSFT - Create a scene handle

C Specification

The xrCreateSceneMSFT functions creates an XrSceneMSFT handle. It can only be called after xrGetSceneComputeStateMSFT returns XR_SCENE_COMPUTE_STATE_COMPLETED_MSFT to indicate that the asynchronous operation has completed. The XrSceneMSFT handle manages the collection of scene components that represents the detected objects found during the query.

After an XrSceneMSFT handle is created, the handle and associated data must remain valid until destroyed, even after xrCreateSceneMSFT is called again to create the next scene. The runtime must keep alive any component data and mesh buffers relating to this historical scene until its handle is destroyed.

// Provided by XR_MSFT_scene_understanding
XrResult xrCreateSceneMSFT(
    XrSceneObserverMSFT                         sceneObserver,
    const XrSceneCreateInfoMSFT*                createInfo,
    XrSceneMSFT*                                scene);

Parameters

Parameter Descriptions

Description

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_COMPUTE_NEW_SCENE_NOT_COMPLETED_MSFT

Calling xrCreateSceneMSFT when xrGetSceneComputeStateMSFT returns XR_SCENE_COMPUTE_STATE_NONE_MSFT or XR_SCENE_COMPUTE_STATE_UPDATING_MSFT must return the error XR_ERROR_COMPUTE_NEW_SCENE_NOT_COMPLETED_MSFT.

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

xrCreateSceneObserverMSFT(3)

Name

xrCreateSceneObserverMSFT - Create a scene observer handle

C Specification

An XrSceneObserverMSFT handle is created using xrCreateSceneObserverMSFT.

// Provided by XR_MSFT_scene_understanding
XrResult xrCreateSceneObserverMSFT(
    XrSession                                   session,
    const XrSceneObserverCreateInfoMSFT*        createInfo,
    XrSceneObserverMSFT*                        sceneObserver);

Parameters

Parameter Descriptions

Description

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

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

xrCreateSession(3)

Name

xrCreateSession - Creates an XrSession

C Specification

The xrCreateSession function is defined as:

// Provided by XR_VERSION_1_0
XrResult xrCreateSession(
    XrInstance                                  instance,
    const XrSessionCreateInfo*                  createInfo,
    XrSession*                                  session);

Parameters

Parameter Descriptions
  • instance is the instance from which XrSessionCreateInfo::systemId was retrieved.

  • createInfo is a pointer to an XrSessionCreateInfo structure containing information about how to create the session.

  • session is a pointer to a handle in which the created XrSession is returned.

Description

Creates a session using the provided createInfo and returns a handle to that session. This session is created in the XR_SESSION_STATE_IDLE state, and a corresponding XrEventDataSessionStateChanged event to the XR_SESSION_STATE_IDLE state must be generated as the first such event for the new session.

The runtime must return XR_ERROR_GRAPHICS_REQUIREMENTS_CALL_MISSING (XR_ERROR_VALIDATION_FAILURE may be returned due to legacy behavior) on calls to xrCreateSession if a function named like xrGet*GraphicsRequirements has not been called for the same instance and XrSessionCreateInfo::systemId. (See graphics binding extensions for details.)

Valid Usage (Implicit)
Return Codes
On success, this command returns
  • XR_SUCCESS

On failure, this command returns
  • XR_ERROR_VALIDATION_FAILURE

  • XR_ERROR_RUNTIME_FAILURE

  • XR_ERROR_HANDLE_INVALID

  • XR_ERROR_INSTANCE_LOST

  • XR_ERROR_OUT_OF_MEMORY

  • XR_ERROR_LIMIT_REACHED

  • XR_ERROR_SYSTEM_INVALID

  • XR_ERROR_INITIALIZATION_FAILED

  • XR_ERROR_GRAPHICS_REQUIREMENTS_CALL_MISSING

  • XR_ERROR_GRAPHICS_DEVICE_INVALID

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

xrCreateSpaceFromCoordinateFrameUIDML(3)

Name

xrCreateSpaceFromCoordinateFrameUIDML - Creates a space based on a cfuid

C Specification

The xrCreateSpaceFromCoordinateFrameUIDML function is defined as:

// Provided by XR_ML_compat
XrResult xrCreateSpaceFromCoordinateFrameUIDML(
    XrSession                                   session,
    const XrCoordinateSpaceCreateInfoML *       createInfo,
    XrSpace*                                    space);

Parameters

Parameter Descriptions

Description

The service that created the underlying XrCoordinateSpaceCreateInfoML::cfuid must remain active for the lifetime of the XrSpace. If xrLocateSpace is called on a space created from an XrCoordinateSpaceCreateInfoML::cfuid from a no-longer-active service, the runtime may set XrSpaceLocation::locationFlags to 0.

XrSpace handles are destroyed using xrDestroySpace.

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

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

xrCreateSpaceUserFB(3)

Name

xrCreateSpaceUserFB - Creates a user other than the current user

C Specification

The xrCreateSpaceUserFB function is defined as:

// Provided by XR_FB_spatial_entity_user
XrResult xrCreateSpaceUserFB(
    XrSession                                   session,
    const XrSpaceUserCreateInfoFB*              info,
    XrSpaceUserFB*                              user);

Parameters

Parameter Descriptions
  • session is a handle to an XrSession.

  • info is a pointer to an XrSpaceUserCreateInfoFB structure containing information to create the user handle.

  • user is the output parameter that points to the handle of the user being created.

Description

The application can use this function to create a user handle with which it can then interact, such as sharing XrSpace objects.

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

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

xrCreateSpatialAnchorFB(3)

Name

xrCreateSpatialAnchorFB - Creates a new spatial anchor

C Specification

The xrCreateSpatialAnchorFB function is defined as:

// Provided by XR_FB_spatial_entity
XrResult xrCreateSpatialAnchorFB(
    XrSession                                   session,
    const XrSpatialAnchorCreateInfoFB*          info,
    XrAsyncRequestIdFB*                         requestId);

Parameters

Parameter Descriptions
  • session is a handle to an XrSession.

  • info is a pointer to an XrSpatialAnchorCreateInfoFB structure containing information about how to create the anchor.

  • requestId is the output parameter that points to the ID of this asynchronous request.

Description

Creates a Spatial Anchor using the specified tracking origin and pose relative to the specified tracking origin. The anchor will be locatable at the time of creation, and the 6 DOF pose relative to the tracking origin can be queried using the xrLocateSpace method. This operation is asynchronous and the runtime must post an XrEventDataSpatialAnchorCreateCompleteFB event when the operation completes successfully or encounters an error. If this function returns a failure code, no event is posted. The requestId can be used to later refer to the request, such as identifying which request has completed when an XrEventDataSpatialAnchorCreateCompleteFB is posted to the event queue.

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_TIME_INVALID

  • XR_ERROR_POSE_INVALID

  • XR_ERROR_FEATURE_UNSUPPORTED

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

xrCreateSpatialAnchorFromPerceptionAnchorMSFT(3)

Name

xrCreateSpatialAnchorFromPerceptionAnchorMSFT - Create an XrSpatialAnchorMSFT from a Windows SpatialAnchor pointer

C Specification

// Provided by XR_MSFT_perception_anchor_interop
XrResult xrCreateSpatialAnchorFromPerceptionAnchorMSFT(
    XrSession                                   session,
    IUnknown*                                   perceptionAnchor,
    XrSpatialAnchorMSFT*                        anchor);

Parameters

Parameter Descriptions

Description

The input perceptionAnchor must support successful QueryInterface to Windows.Perception.Spatial.SpatialAnchor , otherwise the runtime must return XR_ERROR_VALIDATION_FAILURE.

If the function successfully returned, the output anchor must be a valid handle. This also increments the refcount of the perceptionAnchor object.

When application is done with the anchor handle, it can be destroyed using xrDestroySpatialAnchorMSFT function. This also decrements the refcount of underlying windows perception anchor object.

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_HANDLE_INVALID

  • XR_ERROR_INSTANCE_LOST

  • XR_ERROR_SESSION_LOST

  • XR_ERROR_OUT_OF_MEMORY

  • XR_ERROR_LIMIT_REACHED

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

xrCreateSpatialAnchorFromPersistedNameMSFT(3)

Name

xrCreateSpatialAnchorFromPersistedNameMSFT - Create a spatial anchor from the spatial anchor store by name

C Specification

The application can use the xrCreateSpatialAnchorFromPersistedNameMSFT function to create a XrSpatialAnchorMSFT from the spatial anchor store. If the XrSpatialAnchorFromPersistedAnchorCreateInfoMSFT::spatialAnchorPersistenceName provided does not correspond to a currently stored anchor (i.e. the list of spatial anchor names returned from xrEnumeratePersistedSpatialAnchorNamesMSFT), the function must return XR_ERROR_SPATIAL_ANCHOR_NAME_NOT_FOUND_MSFT.

// Provided by XR_MSFT_spatial_anchor_persistence
XrResult xrCreateSpatialAnchorFromPersistedNameMSFT(
    XrSession                                   session,
    const XrSpatialAnchorFromPersistedAnchorCreateInfoMSFT* spatialAnchorCreateInfo,
    XrSpatialAnchorMSFT*                        spatialAnchor);

Parameters

Parameter Descriptions

Description

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_HANDLE_INVALID

  • XR_ERROR_INSTANCE_LOST

  • XR_ERROR_SESSION_LOST

  • XR_ERROR_OUT_OF_MEMORY

  • XR_ERROR_LIMIT_REACHED

  • XR_ERROR_SPATIAL_ANCHOR_NAME_NOT_FOUND_MSFT

  • XR_ERROR_SPATIAL_ANCHOR_NAME_INVALID_MSFT

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

xrCreateSpatialAnchorHTC(3)

Name

xrCreateSpatialAnchorHTC - Creates a spatial anchor

C Specification

The xrCreateSpatialAnchorHTC function is defined as:

// Provided by XR_HTC_anchor
XrResult xrCreateSpatialAnchorHTC(
    XrSession                                   session,
    const XrSpatialAnchorCreateInfoHTC*         createInfo,
    XrSpace*                                    anchor);

Parameters

Parameter Descriptions

Description

The xrCreateSpatialAnchorHTC function creates a spatial anchor with specified base space and pose in the space. The anchor is represented by an XrSpace and its pose can be tracked via xrLocateSpace. Once the anchor is no longer needed, call xrDestroySpace to erase the anchor.

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_NAME_INVALID

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

xrCreateSpatialAnchorMSFT(3)

Name

xrCreateSpatialAnchorMSFT - Creates a spatial anchor

C Specification

The xrCreateSpatialAnchorMSFT function is defined as:

// Provided by XR_MSFT_spatial_anchor
XrResult xrCreateSpatialAnchorMSFT(
    XrSession                                   session,
    const XrSpatialAnchorCreateInfoMSFT*        createInfo,
    XrSpatialAnchorMSFT*                        anchor);

Parameters

Parameter Descriptions

Description

Creates an XrSpatialAnchorMSFT handle representing a spatial anchor that will track a fixed location in the physical world over time. That real-world location is specified by the position and orientation of the specified XrSpatialAnchorCreateInfoMSFT::pose within XrSpatialAnchorCreateInfoMSFT::space at XrSpatialAnchorCreateInfoMSFT::time.

The runtime must avoid long blocking operations such as networking or disk operations for xrCreateSpatialAnchorMSFT function. The application may safely use this function in UI thread. Though, the created anchor handle may not be ready immediately for certain operations yet. For example, the corresponding anchor space may not return valid location, or its location may not be successfully saved in anchor store.

If XrSpatialAnchorCreateInfoMSFT::space cannot be located relative to the environment at the moment of the call to xrCreateSpatialAnchorMSFT, the runtime must return XR_ERROR_CREATE_SPATIAL_ANCHOR_FAILED_MSFT.

After the anchor is created, the runtime should then adjust its position and orientation over time relative to other spaces so as to maintain maximum alignment to its original real-world location, even if that changes the anchor’s relationship to the original XrSpatialAnchorCreateInfoMSFT::space used to initialize it.

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_HANDLE_INVALID

  • XR_ERROR_INSTANCE_LOST

  • XR_ERROR_SESSION_LOST

  • XR_ERROR_OUT_OF_MEMORY

  • XR_ERROR_LIMIT_REACHED

  • XR_ERROR_TIME_INVALID

  • XR_ERROR_POSE_INVALID

  • XR_ERROR_CREATE_SPATIAL_ANCHOR_FAILED_MSFT

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

xrCreateSpatialAnchorSpaceMSFT(3)

Name

xrCreateSpatialAnchorSpaceMSFT - Creates a space from a spatial anchor

C Specification

The xrCreateSpatialAnchorSpaceMSFT function is defined as:

// Provided by XR_MSFT_spatial_anchor
XrResult xrCreateSpatialAnchorSpaceMSFT(
    XrSession                                   session,
    const XrSpatialAnchorSpaceCreateInfoMSFT*   createInfo,
    XrSpace*                                    space);

Parameters

Parameter Descriptions

Description

Creates an XrSpace handle based on a spatial anchor. Application can provide an XrPosef to define the position and orientation of the new space’s origin relative to the anchor’s natural origin.

Multiple XrSpace handles may exist for a given XrSpatialAnchorMSFT simultaneously, up to some limit imposed by the runtime. The XrSpace handle must be eventually freed via the xrDestroySpace function or by destroying the parent XrSpatialAnchorMSFT handle.

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_HANDLE_INVALID

  • XR_ERROR_INSTANCE_LOST

  • XR_ERROR_SESSION_LOST

  • XR_ERROR_OUT_OF_MEMORY

  • XR_ERROR_LIMIT_REACHED

  • XR_ERROR_POSE_INVALID

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

xrCreateSpatialAnchorStoreConnectionMSFT(3)

Name

xrCreateSpatialAnchorStoreConnectionMSFT - Create a handle to track a connection to the spatial anchor store

C Specification

The application can use the xrCreateSpatialAnchorStoreConnectionMSFT function to create an handle to the spatial anchor store. The application can use this handle to interact with the spatial anchor store in order to persist anchors across application sessions.

The xrCreateSpatialAnchorStoreConnectionMSFT function may be a slow operation and therefore should be invoked from a non-timing critical thread.

// Provided by XR_MSFT_spatial_anchor_persistence
XrResult xrCreateSpatialAnchorStoreConnectionMSFT(
    XrSession                                   session,
    XrSpatialAnchorStoreConnectionMSFT*         spatialAnchorStore);

Parameters

Parameter Descriptions

Description

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_HANDLE_INVALID

  • XR_ERROR_INSTANCE_LOST

  • XR_ERROR_SESSION_LOST

  • XR_ERROR_OUT_OF_MEMORY

  • XR_ERROR_LIMIT_REACHED

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

xrCreateSpatialGraphNodeSpaceMSFT(3)

Name

xrCreateSpatialGraphNodeSpaceMSFT - Create an XrSpace from a spatial graph node.

C Specification

The xrCreateSpatialGraphNodeSpaceMSFT function creates an XrSpace handle for a given spatial graph node type and ID.

// Provided by XR_MSFT_spatial_graph_bridge
XrResult xrCreateSpatialGraphNodeSpaceMSFT(
    XrSession                                   session,
    const XrSpatialGraphNodeSpaceCreateInfoMSFT* createInfo,
    XrSpace*                                    space);

Parameters

Parameter Descriptions

Description

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_HANDLE_INVALID

  • XR_ERROR_INSTANCE_LOST

  • XR_ERROR_SESSION_LOST

  • XR_ERROR_OUT_OF_MEMORY

  • XR_ERROR_LIMIT_REACHED

  • XR_ERROR_POSE_INVALID

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

xrCreateSwapchain(3)

Name

xrCreateSwapchain - Creates an XrSwapchain

C Specification

The xrCreateSwapchain function is defined as:

// Provided by XR_VERSION_1_0
XrResult xrCreateSwapchain(
    XrSession                                   session,
    const XrSwapchainCreateInfo*                createInfo,
    XrSwapchain*                                swapchain);

Parameters

Parameter Descriptions
  • session is the session that creates the image.

  • createInfo is a pointer to an XrSwapchainCreateInfo structure containing parameters to be used to create the image.

  • swapchain is a pointer to a handle in which the created XrSwapchain is returned.

Description

Creates an XrSwapchain handle. The returned swapchain handle may be subsequently used in API calls. Multiple XrSwapchain handles may exist simultaneously, up to some limit imposed by the runtime. The XrSwapchain handle must be eventually freed via the xrDestroySwapchain function. The runtime must return XR_ERROR_SWAPCHAIN_FORMAT_UNSUPPORTED if the image format specified in the XrSwapchainCreateInfo is unsupported. The runtime must return XR_ERROR_FEATURE_UNSUPPORTED if any bit of the create or usage flags specified in the XrSwapchainCreateInfo is unsupported.

Valid Usage (Implicit)
Return Codes
On success, this command returns
  • XR_SUCCESS

  • XR_SESSION_LOSS_PENDING

On failure, this command returns
  • 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_SWAPCHAIN_FORMAT_UNSUPPORTED

  • XR_ERROR_FEATURE_UNSUPPORTED

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

xrCreateSwapchainAndroidSurfaceKHR(3)

Name

xrCreateSwapchainAndroidSurfaceKHR - Creates a swapchain and an Android Surface

C Specification

To create an XrSwapchain object and an Android Surface object call:

// Provided by XR_KHR_android_surface_swapchain
XrResult xrCreateSwapchainAndroidSurfaceKHR(
    XrSession                                   session,
    const XrSwapchainCreateInfo*                info,
    XrSwapchain*                                swapchain,
    jobject*                                    surface);

Parameters

Parameter Descriptions
  • session is an XrSession handle previously created with xrCreateSession.

  • info is a pointer to an XrSwapchainCreateInfo structure.

  • swapchain is a pointer to a handle in which the created XrSwapchain is returned.

  • surface is a pointer to a jobject where the created Android Surface is returned.

Description

xrCreateSwapchainAndroidSurfaceKHR creates an XrSwapchain object returned in swapchain and an Android Surface jobject returned in surface. The jobject must be valid to be passed back to Java code using JNI and must be valid to be used with ordinary Android APIs for submitting images to Surfaces. The returned XrSwapchain must be valid to be referenced in XrSwapchainSubImage structures to show content on the screen. The width and height passed in XrSwapchainCreateInfo may not be persistent throughout the life cycle of the created swapchain, since on Android, the size of the images is controlled by the producer and possibly changes at any time.

The only function that is allowed to be called on the XrSwapchain returned from this function is xrDestroySwapchain. For example, calling any of the functions xrEnumerateSwapchainImages, xrAcquireSwapchainImage, xrWaitSwapchainImage or xrReleaseSwapchainImage is invalid.

When the application receives the XrEventDataSessionStateChanged event with the XR_SESSION_STATE_STOPPING state, it must ensure that no threads are writing to any of the Android surfaces created with this extension before calling xrEndSession. The effect of writing frames to the Surface when the session is in states other than XR_SESSION_STATE_VISIBLE or XR_SESSION_STATE_FOCUSED is undefined.

xrCreateSwapchainAndroidSurfaceKHR must return the same set of error codes as xrCreateSwapchain under the same circumstances, plus XR_ERROR_FUNCTION_UNSUPPORTED in case the function is not supported.

Valid Usage of XrSwapchainCreateInfo members
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

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

xrCreateTriangleMeshFB(3)

Name

xrCreateTriangleMeshFB - Create a triangle mesh

C Specification

The xrCreateTriangleMeshFB function is defined as:

// Provided by XR_FB_triangle_mesh
XrResult xrCreateTriangleMeshFB(
    XrSession                                   session,
    const XrTriangleMeshCreateInfoFB*           createInfo,
    XrTriangleMeshFB*                           outTriangleMesh);

Parameters

Parameter Descriptions
  • session is the XrSession to which the mesh will belong.

  • createInfo is a pointer to an XrTriangleMeshCreateInfoFB structure containing parameters to be used to create the mesh.

  • outTriangleMesh is a pointer to a handle in which the created XrTriangleMeshFB is returned.

Description

This creates an XrTriangleMeshFB handle. The returned triangle mesh handle may be subsequently used in API calls.

When the mesh is mutable (the XR_TRIANGLE_MESH_MUTABLE_BIT_FB bit is set in XrTriangleMeshCreateInfoFB::flags), the created triangle mesh starts in the https://registry.khronos.org/OpenXR/specs/1.0/html/xrspec.html#fb_triangle_mesh_state_undefined_topology state.

Immutable meshes have no state machine; they may be considered to be in state https://registry.khronos.org/OpenXR/specs/1.0/html/xrspec.html#fb_triangle_mesh_state_ready with no valid edges leaving that state.

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_INSUFFICIENT_RESOURCES_PASSTHROUGH_FB

  • XR_ERROR_FEATURE_UNSUPPORTED

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

xrCreateVirtualKeyboardMETA(3)

Name

xrCreateVirtualKeyboardMETA - Create a virtual keyboard

C Specification

The xrCreateVirtualKeyboardMETA function is defined as:

// Provided by XR_META_virtual_keyboard
XrResult xrCreateVirtualKeyboardMETA(
    XrSession                                   session,
    const XrVirtualKeyboardCreateInfoMETA*      createInfo,
    XrVirtualKeyboardMETA*                      keyboard);

Parameters

Parameter Descriptions

Description

xrCreateVirtualKeyboardMETA creates an XrVirtualKeyboardMETA handle and establishes a keyboard within the runtime XrSession. The returned virtual keyboard handle may be subsequently used in API calls.

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_FEATURE_UNSUPPORTED

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

xrCreateVirtualKeyboardSpaceMETA(3)

Name

xrCreateVirtualKeyboardSpaceMETA - Create a virtual keyboard space

C Specification

The xrCreateVirtualKeyboardSpaceMETA function is defined as:

// Provided by XR_META_virtual_keyboard
XrResult xrCreateVirtualKeyboardSpaceMETA(
    XrSession                                   session,
    XrVirtualKeyboardMETA                       keyboard,
    const XrVirtualKeyboardSpaceCreateInfoMETA* createInfo,
    XrSpace*                                    keyboardSpace);

Parameters

Parameter Descriptions

Description

Creates an XrSpace handle and places the keyboard in this space. The returned space handle may be subsequently used in API calls.

Once placed, the application should query the keyboard’s location each frame using xrLocateSpace. It is important to do this every frame as the runtime is in control of the keyboard’s movement.

The runtime must return XR_ERROR_HANDLE_INVALID if session is different than what is used to create keyboard.

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_FEATURE_UNSUPPORTED

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

xrCreateVulkanDeviceKHR(3)

Name

xrCreateVulkanDeviceKHR - Create an OpenXR compatible VkDevice

C Specification

// Provided by XR_KHR_vulkan_enable2
XrResult xrCreateVulkanDeviceKHR(
    XrInstance                                  instance,
    const XrVulkanDeviceCreateInfoKHR*          createInfo,
    VkDevice*                                   vulkanDevice,
    VkResult*                                   vulkanResult);

Parameters

Parameter Descriptions
  • instance is an XrInstance handle previously created with xrCreateInstance.

  • createInfo extensible input struct of type XrCreateVulkanDeviceCreateInfoKHR

  • vulkanDevice points to a VkDevice handle to populate with the new Vulkan device.

  • vulkanResult points to a VkResult to populate with the result of the vkCreateDevice operation as returned by XrVulkanInstanceCreateInfoKHR::pfnGetInstanceProcAddr.

Description

Valid Usage (Implicit)
Return Codes
On success, this command returns
  • XR_SUCCESS

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_OUT_OF_MEMORY

  • XR_ERROR_LIMIT_REACHED

  • XR_ERROR_SYSTEM_INVALID

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

xrCreateVulkanInstanceKHR(3)

Name

xrCreateVulkanInstanceKHR - Create an OpenXR compatible VkInstance

C Specification

// Provided by XR_KHR_vulkan_enable2
XrResult xrCreateVulkanInstanceKHR(
    XrInstance                                  instance,
    const XrVulkanInstanceCreateInfoKHR*        createInfo,
    VkInstance*                                 vulkanInstance,
    VkResult*                                   vulkanResult);

Parameters

Parameter Descriptions

Description

Valid Usage (Implicit)
Return Codes
On success, this command returns
  • XR_SUCCESS

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_OUT_OF_MEMORY

  • XR_ERROR_LIMIT_REACHED

  • XR_ERROR_SYSTEM_INVALID

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

xrDeserializeSceneMSFT(3)

Name

xrDeserializeSceneMSFT - Deserialize scene

C Specification

The xrDeserializeSceneMSFT function is defined as:

// Provided by XR_MSFT_scene_understanding_serialization
XrResult xrDeserializeSceneMSFT(
    XrSceneObserverMSFT                         sceneObserver,
    const XrSceneDeserializeInfoMSFT*           deserializeInfo);

Parameters

Parameter Descriptions

Description

The xrDeserializeSceneMSFT function begins deserializing a list of serialized scene fragments. The runtime must return quickly without waiting for the deserialization to complete. The application should use xrGetSceneComputeStateMSFT to inspect the completeness of the deserialization.

The runtime must return XR_ERROR_COMPUTE_NEW_SCENE_NOT_COMPLETED_MSFT if xrDeserializeSceneMSFT is called while the scene computation is in progress.

The xrGetSceneComputeStateMSFT function must return XR_SCENE_COMPUTE_STATE_UPDATING_MSFT while the deserialization is in progress, and XR_SCENE_COMPUTE_STATE_COMPLETED_MSFT when the deserialization has completed successfully. If the runtime fails to deserialize the binary stream, xrGetSceneComputeStateMSFT must return XR_SCENE_COMPUTE_STATE_COMPLETED_WITH_ERROR_MSFT to indicate that the deserialization has completed but an error occurred.

When xrGetSceneComputeStateMSFT returns XR_SCENE_COMPUTE_STATE_COMPLETED_MSFT, the application may call xrCreateSceneMSFT to create the XrSceneMSFT handle. If xrCreateSceneMSFT is called while xrGetSceneComputeStateMSFT returns XR_SCENE_COMPUTE_STATE_COMPLETED_WITH_ERROR_MSFT, a valid XrSceneMSFT handle must be returned, but that handle must contain zero scene components.

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_COMPUTE_NEW_SCENE_NOT_COMPLETED_MSFT

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

xrDestroyAction(3)

Name

xrDestroyAction - Destroys an XrAction

C Specification

The xrDestroyAction function is defined as:

// Provided by XR_VERSION_1_0
XrResult xrDestroyAction(
    XrAction                                    action);

Parameters

Parameter Descriptions
  • action is the action to destroy.

Description

Action handles can be destroyed by calling xrDestroyAction. Handles for actions that are part of an action set are automatically destroyed when the action set’s handle is destroyed.

The implementation must not destroy the underlying resources for an action when xrDestroyAction is called. Those resources are still used to make action spaces locatable and when processing action priority in xrSyncActions. Destroying the action handle removes the application’s access to these resources, but has no other change on actions.

Resources for all actions in an instance must be freed when the instance containing those actions sets is destroyed.

Valid Usage (Implicit)
  • action must be a valid XrAction handle

Thread Safety
  • Access to action, and any child handles, must be externally synchronized

Return Codes
On success, this command returns
  • XR_SUCCESS

On failure, this command returns
  • XR_ERROR_HANDLE_INVALID

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

xrDestroyActionSet(3)

Name

xrDestroyActionSet - Destroys an XrActionSet

C Specification

The xrDestroyActionSet function is defined as:

// Provided by XR_VERSION_1_0
XrResult xrDestroyActionSet(
    XrActionSet                                 actionSet);

Parameters

Parameter Descriptions
  • actionSet is the action set to destroy.

Description

Action set handles can be destroyed by calling xrDestroyActionSet. When an action set handle is destroyed, all handles of actions in that action set are also destroyed.

The implementation must not free underlying resources for the action set while there are other valid handles that refer to those resources. The implementation may release resources for an action set when all of the action spaces for actions in that action set have been destroyed. See Action Spaces Lifetime for details.

Resources for all action sets in an instance must be freed when the instance containing those actions sets is destroyed.

Valid Usage (Implicit)
Thread Safety
  • Access to actionSet, and any child handles, must be externally synchronized

Return Codes
On success, this command returns
  • XR_SUCCESS

On failure, this command returns
  • XR_ERROR_HANDLE_INVALID

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

xrDestroyBodyTrackerFB(3)

Name

xrDestroyBodyTrackerFB - Destroy a body joints handle

C Specification

xrDestroyBodyTrackerFB function releases the bodyTracker and the underlying resources when the body tracking experience is over.

// Provided by XR_FB_body_tracking
XrResult xrDestroyBodyTrackerFB(
    XrBodyTrackerFB                             bodyTracker);

Parameters

Parameter Descriptions

Description

Valid Usage (Implicit)
Thread Safety
  • Access to bodyTracker, and any child handles, must be externally synchronized

Return Codes
On success, this command returns
  • XR_SUCCESS

On failure, this command returns
  • XR_ERROR_FUNCTION_UNSUPPORTED

  • XR_ERROR_HANDLE_INVALID

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

xrDestroyDebugUtilsMessengerEXT(3)

Name

xrDestroyDebugUtilsMessengerEXT - Destroys a debug messenger

C Specification

// Provided by XR_EXT_debug_utils
XrResult xrDestroyDebugUtilsMessengerEXT(
    XrDebugUtilsMessengerEXT                    messenger);

Parameters

Parameter Descriptions

Description

Valid Usage (Implicit)
Thread Safety
  • Access to messenger must be externally synchronized

  • Access to the XrInstance used to create messenger, and all of its child handles must be externally synchronized

Return Codes
On success, this command returns
  • XR_SUCCESS

On failure, this command returns
  • XR_ERROR_FUNCTION_UNSUPPORTED

  • XR_ERROR_HANDLE_INVALID

The application must ensure that xrDestroyDebugUtilsMessengerEXT is not executed in parallel with any OpenXR function that is also called with the instance or child of instance that it was created with.

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

xrDestroyExportedLocalizationMapML(3)

Name

xrDestroyExportedLocalizationMapML - Destroys an exported localization map.

C Specification

The xrDestroyExportedLocalizationMapML function is defined as:

// Provided by XR_ML_localization_map
XrResult xrDestroyExportedLocalizationMapML(
    XrExportedLocalizationMapML                 map);

Parameters

Parameter Descriptions
  • map is the map to destroy.

Description

Valid Usage (Implicit)
Thread Safety
  • Access to map, and any child handles, must be externally synchronized

Return Codes
On success, this command returns
  • XR_SUCCESS

On failure, this command returns
  • XR_ERROR_FUNCTION_UNSUPPORTED

  • XR_ERROR_RUNTIME_FAILURE

  • XR_ERROR_HANDLE_INVALID

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

xrDestroyEyeTrackerFB(3)

Name

xrDestroyEyeTrackerFB - Destroy an eye gaze handle

C Specification

xrDestroyEyeTrackerFB function releases the eyeTracker and the underlying resources when the eye tracking experience is over.

// Provided by XR_FB_eye_tracking_social
XrResult xrDestroyEyeTrackerFB(
    XrEyeTrackerFB                              eyeTracker);

Parameters

Parameter Descriptions

Description

Valid Usage (Implicit)
Thread Safety
  • Access to eyeTracker, and any child handles, must be externally synchronized

Return Codes
On success, this command returns
  • XR_SUCCESS

On failure, this command returns
  • XR_ERROR_FUNCTION_UNSUPPORTED

  • XR_ERROR_HANDLE_INVALID

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

xrDestroyFaceTracker2FB(3)

Name

xrDestroyFaceTracker2FB - Destroy a facial expressions handle

C Specification

The xrDestroyFaceTracker2FB function is defined as:

// Provided by XR_FB_face_tracking2
XrResult xrDestroyFaceTracker2FB(
    XrFaceTracker2FB                            faceTracker);

Parameters

Parameter Descriptions

Description

The xrDestroyFaceTracker2FB function releases the faceTracker and the underlying resources when face tracking experience is over.

Valid Usage (Implicit)
Thread Safety
  • Access to faceTracker, and any child handles, must be externally synchronized

Return Codes
On success, this command returns
  • XR_SUCCESS

On failure, this command returns
  • XR_ERROR_FUNCTION_UNSUPPORTED

  • XR_ERROR_HANDLE_INVALID

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

xrDestroyFaceTrackerFB(3)

Name

xrDestroyFaceTrackerFB - Destroy a facial expressions handle

C Specification

The xrDestroyFaceTrackerFB function releases the faceTracker and the underlying resources when face tracking experience is over.

// Provided by XR_FB_face_tracking
XrResult xrDestroyFaceTrackerFB(
    XrFaceTrackerFB                             faceTracker);

Parameters

Parameter Descriptions

Description

Valid Usage (Implicit)
Thread Safety
  • Access to faceTracker, and any child handles, must be externally synchronized

Return Codes
On success, this command returns
  • XR_SUCCESS

On failure, this command returns
  • XR_ERROR_FUNCTION_UNSUPPORTED

  • XR_ERROR_HANDLE_INVALID

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

xrDestroyFacialTrackerHTC(3)

Name

xrDestroyFacialTrackerHTC - Destroy a facial tracker handle

C Specification

The xrDestroyFacialTrackerHTC function is defined as:

// Provided by XR_HTC_facial_tracking
XrResult xrDestroyFacialTrackerHTC(
    XrFacialTrackerHTC                          facialTracker);

Parameters

Parameter Descriptions

Description

xrDestroyFacialTrackerHTC releases the facialTracker and the underlying resources when finished with facial tracking experiences.

Valid Usage (Implicit)
Thread Safety
  • Access to facialTracker, and any child handles, must be externally synchronized

Return Codes
On success, this command returns
  • XR_SUCCESS

On failure, this command returns
  • XR_ERROR_FUNCTION_UNSUPPORTED

  • XR_ERROR_HANDLE_INVALID

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

xrDestroyFoveationProfileFB(3)

Name

xrDestroyFoveationProfileFB - Destroy a foveation profile

C Specification

The xrDestroyFoveationProfileFB function is defined as:

// Provided by XR_FB_foveation
XrResult xrDestroyFoveationProfileFB(
    XrFoveationProfileFB                        profile);

Parameters

Parameter Descriptions

Description

XrFoveationProfileFB handles are destroyed using xrDestroyFoveationProfileFB. A XrFoveationProfileFB may be safely destroyed after being applied to a swapchain state using xrUpdateSwapchainFB without affecting the foveation parameters of the swapchain. The application is responsible for ensuring that it has no calls using profile in progress when the foveation profile is destroyed.

Valid Usage (Implicit)
Thread Safety
  • Access to profile, and any child handles, must be externally synchronized

Return Codes
On success, this command returns
  • XR_SUCCESS

On failure, this command returns
  • XR_ERROR_FUNCTION_UNSUPPORTED

  • XR_ERROR_RUNTIME_FAILURE

  • XR_ERROR_HANDLE_INVALID

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

xrDestroyGeometryInstanceFB(3)

Name

xrDestroyGeometryInstanceFB - Destroy a geometry instance

C Specification

The xrDestroyGeometryInstanceFB function is defined as:

// Provided by XR_FB_passthrough
XrResult xrDestroyGeometryInstanceFB(
    XrGeometryInstanceFB                        instance);

Parameters

Parameter Descriptions

Description

Destroys an XrGeometryInstanceFB handle. Destroying an XrGeometryInstanceFB does not destroy a mesh and does not free mesh resources. Destroying a layer invalidates all geometry instances attached to it. Destroying a mesh invalidates all its instances.

Valid Usage (Implicit)
Thread Safety
  • Access to instance, and any child handles, must be externally synchronized

Return Codes
On success, this command returns
  • XR_SUCCESS

On failure, this command returns
  • XR_ERROR_FUNCTION_UNSUPPORTED

  • XR_ERROR_RUNTIME_FAILURE

  • XR_ERROR_HANDLE_INVALID

  • XR_ERROR_FEATURE_UNSUPPORTED

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

xrDestroyHandTrackerEXT(3)

Name

xrDestroyHandTrackerEXT - Destroy a hand joints handle

C Specification

xrDestroyHandTrackerEXT function releases the handTracker and the underlying resources when finished with hand tracking experiences.

// Provided by XR_EXT_hand_tracking
XrResult xrDestroyHandTrackerEXT(
    XrHandTrackerEXT                            handTracker);

Parameters

Parameter Descriptions

Description

Valid Usage (Implicit)
Thread Safety
  • Access to handTracker, and any child handles, must be externally synchronized

Return Codes
On success, this command returns
  • XR_SUCCESS

On failure, this command returns
  • XR_ERROR_FUNCTION_UNSUPPORTED

  • XR_ERROR_HANDLE_INVALID

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

xrDestroyInstance(3)

Name

xrDestroyInstance - Destroy an instance of OpenXR

C Specification

The xrDestroyInstance function is defined as:

// Provided by XR_VERSION_1_0
XrResult xrDestroyInstance(
    XrInstance                                  instance);

Parameters

The xrDestroyInstance function is used to destroy an XrInstance.

Description

Parameter Descriptions
  • instance is the handle to the instance to destroy.

XrInstance handles are destroyed using xrDestroyInstance. When an XrInstance is destroyed, all handles that are children of that XrInstance are also destroyed.

Valid Usage (Implicit)
Thread Safety
  • Access to instance, and any child handles, must be externally synchronized

Return Codes
On success, this command returns
  • XR_SUCCESS

On failure, this command returns
  • XR_ERROR_HANDLE_INVALID

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

xrDestroyMarkerDetectorML(3)

Name

xrDestroyMarkerDetectorML - Destroy a marker detection handle

C Specification

The xrDestroyMarkerDetectorML function is defined as:

// Provided by XR_ML_marker_understanding
XrResult xrDestroyMarkerDetectorML(
    XrMarkerDetectorML                          markerDetector);

Parameters

Parameter Descriptions
  • markerDetector object to destroy.

Description

Destroy a marker detection handle.

Valid Usage (Implicit)
Thread Safety
  • Access to markerDetector, and any child handles, must be externally synchronized

Return Codes
On success, this command returns
  • XR_SUCCESS

On failure, this command returns
  • XR_ERROR_FUNCTION_UNSUPPORTED

  • XR_ERROR_HANDLE_INVALID

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

xrDestroyPassthroughColorLutMETA(3)

Name

xrDestroyPassthroughColorLutMETA - Destroy a passthrough color LUT

C Specification

The xrDestroyPassthroughColorLutMETA function is defined as:

// Provided by XR_META_passthrough_color_lut
XrResult xrDestroyPassthroughColorLutMETA(
    XrPassthroughColorLutMETA                   colorLut);

Parameters

Parameter Descriptions

Description

Destroys a passthrough color LUT. If the color LUT is still in use (i.e. if for at least one passthrough layer, xrPassthroughLayerSetStyleFB has last been called with an instance of XrPassthroughColorMapLutMETA or XrPassthroughColorMapInterpolatedLutMETA in the next chain that references this color LUT), the runtime must retain the color LUT data and continue applying it to the affected passthrough layer until a different style is applied.

Valid Usage (Implicit)
Thread Safety
  • Access to colorLut, and any child handles, must be externally synchronized

Return Codes
On success, this command returns
  • XR_SUCCESS

On failure, this command returns
  • XR_ERROR_FUNCTION_UNSUPPORTED

  • XR_ERROR_RUNTIME_FAILURE

  • XR_ERROR_HANDLE_INVALID

  • XR_ERROR_FEATURE_UNSUPPORTED

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

xrDestroyPassthroughFB(3)

Name

xrDestroyPassthroughFB - Destroy a passthrough feature

C Specification

The xrDestroyPassthroughFB function is defined as:

// Provided by XR_FB_passthrough
XrResult xrDestroyPassthroughFB(
    XrPassthroughFB                             passthrough);

Parameters

Parameter Descriptions

Description

Destroys an XrPassthroughFB handle.

Valid Usage (Implicit)
Thread Safety
  • Access to passthrough, and any child handles, must be externally synchronized

Return Codes
On success, this command returns
  • XR_SUCCESS

On failure, this command returns
  • XR_ERROR_FUNCTION_UNSUPPORTED

  • XR_ERROR_RUNTIME_FAILURE

  • XR_ERROR_HANDLE_INVALID

  • XR_ERROR_FEATURE_UNSUPPORTED

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

xrDestroyPassthroughHTC(3)

Name

xrDestroyPassthroughHTC - Destroy a passthrough handle

C Specification

The xrDestroyPassthroughHTC function is defined as:

// Provided by XR_HTC_passthrough
XrResult xrDestroyPassthroughHTC(
    XrPassthroughHTC                            passthrough);

Parameters

Parameter Descriptions

Description

The xrDestroyPassthroughHTC function releases the passthrough and the underlying resources.

Valid Usage (Implicit)
Thread Safety
  • Access to passthrough, and any child handles, must be externally synchronized

Return Codes
On success, this command returns
  • XR_SUCCESS

On failure, this command returns
  • XR_ERROR_FUNCTION_UNSUPPORTED

  • XR_ERROR_RUNTIME_FAILURE

  • XR_ERROR_HANDLE_INVALID

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

xrDestroyPassthroughLayerFB(3)

Name

xrDestroyPassthroughLayerFB - Destroy a passthrough layer

C Specification

The xrDestroyPassthroughLayerFB function is defined as:

// Provided by XR_FB_passthrough
XrResult xrDestroyPassthroughLayerFB(
    XrPassthroughLayerFB                        layer);

Parameters

Parameter Descriptions

Description

Destroys an XrPassthroughLayerFB handle.

Valid Usage (Implicit)
Thread Safety
  • Access to layer, and any child handles, must be externally synchronized

Return Codes
On success, this command returns
  • XR_SUCCESS

On failure, this command returns
  • XR_ERROR_FUNCTION_UNSUPPORTED

  • XR_ERROR_RUNTIME_FAILURE

  • XR_ERROR_HANDLE_INVALID

  • XR_ERROR_FEATURE_UNSUPPORTED

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

xrDestroyPlaneDetectorEXT(3)

Name

xrDestroyPlaneDetectorEXT - Destroy a plane detection handle

C Specification

The xrDestroyPlaneDetectorEXT function is defined as:

// Provided by XR_EXT_plane_detection
XrResult xrDestroyPlaneDetectorEXT(
    XrPlaneDetectorEXT                          planeDetector);

Parameters

Parameter Descriptions

Description

xrDestroyPlaneDetectorEXT function releases the planeDetector and the underlying resources when finished with plane detection experiences.

Valid Usage (Implicit)
Thread Safety
  • Access to planeDetector, and any child handles, must be externally synchronized

Return Codes
On success, this command returns
  • XR_SUCCESS

On failure, this command returns
  • XR_ERROR_FUNCTION_UNSUPPORTED

  • XR_ERROR_RUNTIME_FAILURE

  • XR_ERROR_HANDLE_INVALID

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

xrDestroySceneMSFT(3)

Name

xrDestroySceneMSFT - Destroy a scene handle

C Specification

The xrDestroySceneMSFT function releases the scene and the underlying resources.

// Provided by XR_MSFT_scene_understanding
XrResult xrDestroySceneMSFT(
    XrSceneMSFT                                 scene);

Parameters

Parameter Descriptions

Description

Valid Usage (Implicit)
Thread Safety
  • Access to scene, and any child handles, must be externally synchronized

Return Codes
On success, this command returns
  • XR_SUCCESS

On failure, this command returns
  • XR_ERROR_FUNCTION_UNSUPPORTED

  • XR_ERROR_HANDLE_INVALID

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

xrDestroySceneObserverMSFT(3)

Name

xrDestroySceneObserverMSFT - Destroy a scene observer handle

C Specification

The xrDestroySceneObserverMSFT function releases the sceneObserver and the underlying resources.

// Provided by XR_MSFT_scene_understanding
XrResult xrDestroySceneObserverMSFT(
    XrSceneObserverMSFT                         sceneObserver);

Parameters

Parameter Descriptions

Description

Valid Usage (Implicit)
Thread Safety
  • Access to sceneObserver, and any child handles, must be externally synchronized

Return Codes
On success, this command returns
  • XR_SUCCESS

On failure, this command returns
  • XR_ERROR_FUNCTION_UNSUPPORTED

  • XR_ERROR_HANDLE_INVALID

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

xrDestroySession(3)

Name

xrDestroySession - Destroys an XrSession

C Specification

The xrDestroySession function is defined as.

// Provided by XR_VERSION_1_0
XrResult xrDestroySession(
    XrSession                                   session);

Parameters

Parameter Descriptions
  • session is the session to destroy.

Description

XrSession handles are destroyed using xrDestroySession. When an XrSession is destroyed, all handles that are children of that XrSession are also destroyed.

The application is responsible for ensuring that it has no calls using session in progress when the session is destroyed.

xrDestroySession can be called when the session is in any session state.

Valid Usage (Implicit)
Thread Safety
  • Access to session, and any child handles, must be externally synchronized

Return Codes
On success, this command returns
  • XR_SUCCESS

On failure, this command returns
  • XR_ERROR_HANDLE_INVALID

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

xrDestroySpace(3)

Name

xrDestroySpace - Destroys an XrSpace

C Specification

The xrDestroySpace function is defined as:

// Provided by XR_VERSION_1_0
XrResult xrDestroySpace(
    XrSpace                                     space);

Parameters

Parameter Descriptions

Description

XrSpace handles are destroyed using xrDestroySpace. The runtime may still use this space if there are active dependencies (e.g, compositions in progress).

Valid Usage (Implicit)
  • space must be a valid XrSpace handle

Thread Safety
  • Access to space, and any child handles, must be externally synchronized

Return Codes
On success, this command returns
  • XR_SUCCESS

On failure, this command returns
  • XR_ERROR_HANDLE_INVALID

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

xrDestroySpaceUserFB(3)

Name

xrDestroySpaceUserFB - Destroys a user handle

C Specification

The xrDestroySpaceUserFB function is defined as:

// Provided by XR_FB_spatial_entity_user
XrResult xrDestroySpaceUserFB(
    XrSpaceUserFB                               user);

Parameters

Parameter Descriptions
  • user is a handle to the user object to be destroyed.

Description

The application should use this function to release resources tied to a given XrSpaceUserFB once the application no longer needs to reference the user.

Valid Usage (Implicit)
Thread Safety
  • Access to user, and any child handles, must be externally synchronized

Return Codes
On success, this command returns
  • XR_SUCCESS

On failure, this command returns
  • XR_ERROR_FUNCTION_UNSUPPORTED

  • XR_ERROR_RUNTIME_FAILURE

  • XR_ERROR_HANDLE_INVALID

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

xrDestroySpatialAnchorMSFT(3)

Name

xrDestroySpatialAnchorMSFT - Destroys a spatial anchor

C Specification

The xrDestroySpatialAnchorMSFT function is defined as:

// Provided by XR_MSFT_spatial_anchor
XrResult xrDestroySpatialAnchorMSFT(
    XrSpatialAnchorMSFT                         anchor);

Parameters

Parameter Descriptions

Description

XrSpatialAnchorMSFT handles are destroyed using xrDestroySpatialAnchorMSFT. By destroying an anchor, the runtime can stop spending resources used to maintain tracking for that anchor’s origin.

Valid Usage (Implicit)
Thread Safety
  • Access to anchor, and any child handles, must be externally synchronized

Return Codes
On success, this command returns
  • XR_SUCCESS

On failure, this command returns
  • XR_ERROR_FUNCTION_UNSUPPORTED

  • XR_ERROR_HANDLE_INVALID

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

xrDestroySpatialAnchorStoreConnectionMSFT(3)

Name

xrDestroySpatialAnchorStoreConnectionMSFT - Destroys the anchor store handle

C Specification

The application can use the xrDestroySpatialAnchorStoreConnectionMSFT function to destroy an anchor store connection.

// Provided by XR_MSFT_spatial_anchor_persistence
XrResult xrDestroySpatialAnchorStoreConnectionMSFT(
    XrSpatialAnchorStoreConnectionMSFT          spatialAnchorStore);

Parameters

Parameter Descriptions

Description

Valid Usage (Implicit)
Thread Safety
  • Access to spatialAnchorStore, and any child handles, must be externally synchronized

Return Codes
On success, this command returns
  • XR_SUCCESS

On failure, this command returns
  • XR_ERROR_FUNCTION_UNSUPPORTED

  • XR_ERROR_HANDLE_INVALID

  • XR_ERROR_OUT_OF_MEMORY

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

xrDestroySpatialGraphNodeBindingMSFT(3)

Name

xrDestroySpatialGraphNodeBindingMSFT - Destroy a spatial graph node handle

C Specification

The xrDestroySpatialGraphNodeBindingMSFT function releases the nodeBinding and the underlying resources.

// Provided by XR_MSFT_spatial_graph_bridge
XrResult xrDestroySpatialGraphNodeBindingMSFT(
    XrSpatialGraphNodeBindingMSFT               nodeBinding);

Parameters

Parameter Descriptions

Description

Valid Usage (Implicit)
Thread Safety
  • Access to nodeBinding, and any child handles, must be externally synchronized

Return Codes
On success, this command returns
  • XR_SUCCESS

On failure, this command returns
  • XR_ERROR_FUNCTION_UNSUPPORTED

  • XR_ERROR_HANDLE_INVALID

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

xrDestroySwapchain(3)

Name

xrDestroySwapchain - Destroys an XrSwapchain

C Specification

The xrDestroySwapchain function is defined as:

// Provided by XR_VERSION_1_0
XrResult xrDestroySwapchain(
    XrSwapchain                                 swapchain);

Parameters

Parameter Descriptions
  • swapchain is the swapchain to destroy.

Description

All submitted graphics API commands that refer to swapchain must have completed execution. Runtimes may continue to utilize swapchain images after xrDestroySwapchain is called.

Valid Usage (Implicit)
Thread Safety
  • Access to swapchain, and any child handles, must be externally synchronized

Return Codes
On success, this command returns
  • XR_SUCCESS

On failure, this command returns
  • XR_ERROR_HANDLE_INVALID

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

xrDestroyTriangleMeshFB(3)

Name

xrDestroyTriangleMeshFB - Destroy a triangle mesh

C Specification

The xrDestroyTriangleMeshFB function is defined as:

// Provided by XR_FB_triangle_mesh
XrResult xrDestroyTriangleMeshFB(
    XrTriangleMeshFB                            mesh);

Parameters

Parameter Descriptions

Description

XrTriangleMeshFB handles and their associated data are destroyed by xrDestroyTriangleMeshFB. The mesh buffers retrieved by xrTriangleMeshGetVertexBufferFB and xrTriangleMeshGetIndexBufferFB must not be accessed anymore after their parent mesh object has been destroyed.

Valid Usage (Implicit)
Thread Safety
Return Codes
On success, this command returns
  • XR_SUCCESS

On failure, this command returns
  • XR_ERROR_FUNCTION_UNSUPPORTED

  • XR_ERROR_RUNTIME_FAILURE

  • XR_ERROR_HANDLE_INVALID

  • XR_ERROR_FEATURE_UNSUPPORTED

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

xrDestroyVirtualKeyboardMETA(3)

Name

xrDestroyVirtualKeyboardMETA - Destroy a virtual keyboard

C Specification

The xrDestroyVirtualKeyboardMETA function is defined as:

// Provided by XR_META_virtual_keyboard
XrResult xrDestroyVirtualKeyboardMETA(
    XrVirtualKeyboardMETA                       keyboard);

Parameters

Parameter Descriptions

Description

Valid Usage (Implicit)
Thread Safety
  • Access to keyboard, and any child handles, must be externally synchronized

Return Codes
On success, this command returns
  • XR_SUCCESS

On failure, this command returns
  • XR_ERROR_FUNCTION_UNSUPPORTED

  • XR_ERROR_RUNTIME_FAILURE

  • XR_ERROR_HANDLE_INVALID

  • XR_ERROR_FEATURE_UNSUPPORTED

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

xrEnableLocalizationEventsML(3)

Name

xrEnableLocalizationEventsML - Retrieve the current localization status.

C Specification

The xrEnableLocalizationEventsML function is defined as:

// Provided by XR_ML_localization_map
XrResult xrEnableLocalizationEventsML(
    XrSession                                   session,
    const XrLocalizationEnableEventsInfoML *    info);

Parameters

Parameter Descriptions

Description

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_LOCALIZATION_MAP_PERMISSION_DENIED_ML

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

xrEnableUserCalibrationEventsML(3)

Name

xrEnableUserCalibrationEventsML - Enable/disable user calibration events.

C Specification

The xrEnableUserCalibrationEventsML function is defined as:

// Provided by XR_ML_user_calibration
XrResult xrEnableUserCalibrationEventsML(
    XrInstance                                  instance,
    const XrUserCalibrationEnableEventsInfoML*  enableInfo);

Parameters

Parameter Descriptions

Description

Valid Usage (Implicit)
Return Codes
On success, this command returns
  • XR_SUCCESS

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

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

xrEndFrame(3)

Name

xrEndFrame - Marks a frame

C Specification

The xrEndFrame function is defined as:

// Provided by XR_VERSION_1_0
XrResult xrEndFrame(
    XrSession                                   session,
    const XrFrameEndInfo*                       frameEndInfo);

Parameters

Parameter Descriptions

Description

xrEndFrame may return immediately to the application. XrFrameEndInfo::displayTime should be computed using values returned by xrWaitFrame. The runtime should be robust against variations in the timing of calls to xrWaitFrame, since a pipelined system may call xrWaitFrame on a separate thread from xrBeginFrame and xrEndFrame without any synchronization guarantees.

Note

An accurate predicted display time is very important to avoid black pull-in by reprojection and to reduce motion judder in case the runtime does not implement a translational reprojection. Reprojection should never display images before the display refresh period they were predicted for, even if they are completed early, because this will cause motion judder just the same. In other words, the better the predicted display time, the less latency experienced by the user.

Every call to xrEndFrame must be preceded by a successful call to xrBeginFrame. Failure to do so must result in XR_ERROR_CALL_ORDER_INVALID being returned by xrEndFrame. Refer to xrBeginSession for details on how a transition to session running resets the frame function call order. XrFrameEndInfo may reference swapchains into which the application has rendered for this frame. From each XrSwapchain only one image index is implicitly referenced per frame, the one corresponding to the last call to xrReleaseSwapchainImage. However, a specific swapchain (and by extension a specific swapchain image index) may be referenced in XrFrameEndInfo multiple times. This can be used for example to render a side by side image into a single swapchain image and referencing it twice with differing image rectangles in different layers.

If no layers are provided then the display must be cleared.

XR_ERROR_LAYER_INVALID must be returned if an unknown, unsupported layer type, or NULL pointer is passed as one of the XrFrameEndInfo::layers.

XR_ERROR_LAYER_INVALID must be returned if a layer references a swapchain that has no released swapchain image.

XR_ERROR_LAYER_LIMIT_EXCEEDED must be returned if XrFrameEndInfo::layerCount exceeds XrSystemGraphicsProperties::maxLayerCount or if the runtime is unable to composite the specified layers due to resource constraints.

XR_ERROR_SWAPCHAIN_RECT_INVALID must be returned if XrFrameEndInfo::layers contains a composition layer which references pixels outside of the associated swapchain image or if negatively sized.

XR_ERROR_ENVIRONMENT_BLEND_MODE_UNSUPPORTED must be returned if XrFrameEndInfo::environmentBlendMode is not supported.

XR_ERROR_SESSION_NOT_RUNNING must be returned if the session is not running.

Note

Applications should discard frames for which xrEndFrame returns a recoverable error over attempting to resubmit the frame with different frame parameters to provide a more consistent experience across different runtime implementations.

Valid Usage (Implicit)
Thread Safety
  • Access to the session parameter by any other xrBeginFrame or xrEndFrame call must be externally synchronized

Return Codes
On success, this command returns
  • XR_SUCCESS

  • XR_SESSION_LOSS_PENDING

On failure, this command returns
  • XR_ERROR_VALIDATION_FAILURE

  • XR_ERROR_RUNTIME_FAILURE

  • XR_ERROR_HANDLE_INVALID

  • XR_ERROR_INSTANCE_LOST

  • XR_ERROR_SESSION_LOST

  • XR_ERROR_TIME_INVALID

  • XR_ERROR_SWAPCHAIN_RECT_INVALID

  • XR_ERROR_SESSION_NOT_RUNNING

  • XR_ERROR_POSE_INVALID

  • XR_ERROR_LAYER_LIMIT_EXCEEDED

  • XR_ERROR_LAYER_INVALID

  • XR_ERROR_ENVIRONMENT_BLEND_MODE_UNSUPPORTED

  • XR_ERROR_CALL_ORDER_INVALID

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

xrEndSession(3)

Name

xrEndSession - Ends an XrSession

C Specification

The xrEndSession function is defined as:

// Provided by XR_VERSION_1_0
XrResult xrEndSession(
    XrSession                                   session);

Parameters

Parameter Descriptions

Description

When the application receives XrEventDataSessionStateChanged event with the XR_SESSION_STATE_STOPPING state, the application should stop its frame loop and then call xrEndSession to end the running session. This function signals to the runtime that the application will no longer call xrWaitFrame, xrBeginFrame or xrEndFrame from any thread allowing the runtime to safely transition the session to XR_SESSION_STATE_IDLE. The application must also avoid reading input state or sending haptic output after calling xrEndSession.

If the session is not running when the application calls xrEndSession, the runtime must return error XR_ERROR_SESSION_NOT_RUNNING. If the session is still running when the application calls xrEndSession, but the session is not yet in the XR_SESSION_STATE_STOPPING state, the runtime must return error XR_ERROR_SESSION_NOT_STOPPING.

If the application wishes to exit a running session, the application can call xrRequestExitSession so that the session transitions from XR_SESSION_STATE_IDLE to XR_SESSION_STATE_EXITING.

Valid Usage (Implicit)
Return Codes
On success, this command returns
  • XR_SUCCESS

  • XR_SESSION_LOSS_PENDING

On failure, this command returns
  • XR_ERROR_VALIDATION_FAILURE

  • XR_ERROR_RUNTIME_FAILURE

  • XR_ERROR_HANDLE_INVALID

  • XR_ERROR_INSTANCE_LOST

  • XR_ERROR_SESSION_LOST

  • XR_ERROR_SESSION_NOT_STOPPING

  • XR_ERROR_SESSION_NOT_RUNNING

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

xrEnumerateApiLayerProperties(3)

Name

xrEnumerateApiLayerProperties - Returns up to requested number of global layer properties

C Specification

To determine what set of API layers are available, OpenXR provides the xrEnumerateApiLayerProperties function:

// Provided by XR_VERSION_1_0
XrResult xrEnumerateApiLayerProperties(
    uint32_t                                    propertyCapacityInput,
    uint32_t*                                   propertyCountOutput,
    XrApiLayerProperties*                       properties);

Parameters

Parameter Descriptions
  • propertyCapacityInput is the capacity of the properties array, or 0 to indicate a request to retrieve the required capacity.

  • propertyCountOutput is a pointer to the count of properties written, or a pointer to the required capacity in the case that propertyCapacityInput is insufficient.

  • properties is a pointer to an array of XrApiLayerProperties structures, but can be NULL if propertyCapacityInput is 0.

  • See the Buffer Size Parameters section for a detailed description of retrieving the required properties size.

Description

The list of available layers may change at any time due to actions outside of the OpenXR runtime, so two calls to xrEnumerateApiLayerProperties with the same parameters may return different results, or retrieve different propertyCountOutput values or properties contents.

Once an instance has been created, the layers enabled for that instance will continue to be enabled and valid for the lifetime of that instance, even if some of them become unavailable for future instances.

Valid Usage (Implicit)
  • propertyCountOutput must be a pointer to a uint32_t value

  • If propertyCapacityInput is not 0, properties must be a pointer to an array of propertyCapacityInput XrApiLayerProperties structures

Return Codes
On success, this command returns
  • XR_SUCCESS

On failure, this command returns
  • XR_ERROR_VALIDATION_FAILURE

  • XR_ERROR_RUNTIME_FAILURE

  • XR_ERROR_OUT_OF_MEMORY

  • XR_ERROR_SIZE_INSUFFICIENT

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

xrEnumerateBoundSourcesForAction(3)

Name

xrEnumerateBoundSourcesForAction - Queries the bound input sources for an action

C Specification

The xrEnumerateBoundSourcesForAction function is defined as:

// Provided by XR_VERSION_1_0
XrResult xrEnumerateBoundSourcesForAction(
    XrSession                                   session,
    const XrBoundSourcesForActionEnumerateInfo* enumerateInfo,
    uint32_t                                    sourceCapacityInput,
    uint32_t*                                   sourceCountOutput,
    XrPath*                                     sources);

Parameters

Parameter Descriptions
  • session is the XrSession being queried.

  • enumerateInfo is an XrBoundSourcesForActionEnumerateInfo providing the query information.

  • sourceCapacityInput is the capacity of the array, or 0 to indicate a request to retrieve the required capacity.

  • sourceCountOutput is a pointer to the count of sources, or a pointer to the required capacity in the case that sourceCapacityInput is insufficient.

  • sources is a pointer to an application-allocated array that will be filled with the XrPath values for all bound sources. It can be NULL if sourceCapacityInput is 0.

  • See Buffer Size Parameters chapter for a detailed description of retrieving the required sources size.

Description

If an action is unbound, xrEnumerateBoundSourcesForAction must assign 0 to the value pointed-to by sourceCountOutput and not modify the array.

xrEnumerateBoundSourcesForAction must return XR_ERROR_ACTIONSET_NOT_ATTACHED if passed an action in an action set never attached to the session with xrAttachSessionActionSets.

As bindings for actions do not change between calls to xrSyncActions, xrEnumerateBoundSourcesForAction must enumerate the same set of bound sources, or absence of bound sources, for a given query (defined by the enumerateInfo parameter) between any two calls to xrSyncActions.

Note

The XrPath bound sources returned by the runtime are opaque values and should not be inspected or persisted. They are only intended for use in conjunction with xrGetInputSourceLocalizedName.

Valid Usage (Implicit)
  • session must be a valid XrSession handle

  • enumerateInfo must be a pointer to a valid XrBoundSourcesForActionEnumerateInfo structure

  • sourceCountOutput must be a pointer to a uint32_t value

  • If sourceCapacityInput is not 0, sources must be a pointer to an array of sourceCapacityInput XrPath values

Return Codes
On success, this command returns
  • XR_SUCCESS

  • XR_SESSION_LOSS_PENDING

On failure, this command returns
  • XR_ERROR_VALIDATION_FAILURE

  • XR_ERROR_RUNTIME_FAILURE

  • XR_ERROR_HANDLE_INVALID

  • XR_ERROR_INSTANCE_LOST

  • XR_ERROR_SESSION_LOST

  • XR_ERROR_SIZE_INSUFFICIENT

  • XR_ERROR_PATH_INVALID

  • XR_ERROR_ACTIONSET_NOT_ATTACHED

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

xrEnumerateColorSpacesFB(3)

Name

xrEnumerateColorSpacesFB - Enumerates color spaces

C Specification

The xrEnumerateColorSpacesFB function is defined as:

// Provided by XR_FB_color_space
XrResult xrEnumerateColorSpacesFB(
    XrSession                                   session,
    uint32_t                                    colorSpaceCapacityInput,
    uint32_t*                                   colorSpaceCountOutput,
    XrColorSpaceFB*                             colorSpaces);

Parameters

Parameter Descriptions
  • session is the session that enumerates the supported color spaces.

  • colorSpaceCapacityInput is the capacity of the colorSpaces array, or 0 to retrieve the required capacity.

  • colorSpaceCountOutput is a pointer to the count of XrColorSpaceFB colorSpaces written, or a pointer to the required capacity in the case that colorSpaceCapacityInput is insufficient.

  • colorSpaces is a pointer to an array of XrColorSpaceFB color spaces, but can be NULL if colorSpaceCapacityInput is 0.

  • See Buffer Size Parameters chapter for a detailed description of retrieving the required colorSpaces size.

Description

xrEnumerateColorSpacesFB enumerates the color spaces supported by the current session. Runtimes must always return identical buffer contents from this enumeration for the lifetime of the session.

Valid Usage (Implicit)
  • The XR_FB_color_space extension must be enabled prior to calling xrEnumerateColorSpacesFB

  • session must be a valid XrSession handle

  • colorSpaceCountOutput must be a pointer to a uint32_t value

  • If colorSpaceCapacityInput is not 0, colorSpaces must be a pointer to an array of colorSpaceCapacityInput XrColorSpaceFB values

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

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

xrEnumerateDisplayRefreshRatesFB(3)

Name

xrEnumerateDisplayRefreshRatesFB - Enumerates display refresh rates

C Specification

The xrEnumerateDisplayRefreshRatesFB function is defined as:

// Provided by XR_FB_display_refresh_rate
XrResult xrEnumerateDisplayRefreshRatesFB(
    XrSession                                   session,
    uint32_t                                    displayRefreshRateCapacityInput,
    uint32_t*                                   displayRefreshRateCountOutput,
    float*                                      displayRefreshRates);

Parameters

Parameter Descriptions
  • session is the session that enumerates the supported display refresh rates.

  • displayRefreshRateCapacityInput is the capacity of the displayRefreshRates, or 0 to retrieve the required capacity.

  • displayRefreshRateCountOutput is a pointer to the count of float displayRefreshRates written, or a pointer to the required capacity in the case that displayRefreshRateCapacityInput is insufficient.

  • displayRefreshRates is a pointer to an array of float display refresh rates, but can be NULL if displayRefreshRateCapacityInput is 0.

  • See Buffer Size Parameters chapter for a detailed description of retrieving the required displayRefreshRates size.

Description

xrEnumerateDisplayRefreshRatesFB enumerates the display refresh rates supported by the current session. Display refresh rates must be in order from lowest to highest supported display refresh rates. Runtimes must always return identical buffer contents from this enumeration for the lifetime of the session.

Valid Usage (Implicit)
  • The XR_FB_display_refresh_rate extension must be enabled prior to calling xrEnumerateDisplayRefreshRatesFB

  • session must be a valid XrSession handle

  • displayRefreshRateCountOutput must be a pointer to a uint32_t value

  • If displayRefreshRateCapacityInput is not 0, displayRefreshRates must be a pointer to an array of displayRefreshRateCapacityInput float values

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

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

xrEnumerateEnvironmentBlendModes(3)

Name

xrEnumerateEnvironmentBlendModes - Lists environment blend modes

C Specification

The xrEnumerateEnvironmentBlendModes function is defined as:

// Provided by XR_VERSION_1_0
XrResult xrEnumerateEnvironmentBlendModes(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    XrViewConfigurationType                     viewConfigurationType,
    uint32_t                                    environmentBlendModeCapacityInput,
    uint32_t*                                   environmentBlendModeCountOutput,
    XrEnvironmentBlendMode*                     environmentBlendModes);

Parameters

Parameter Descriptions
  • instance is the instance from which systemId was retrieved.

  • systemId is the XrSystemId whose environment blend modes will be enumerated.

  • viewConfigurationType is the XrViewConfigurationType to enumerate.

  • environmentBlendModeCapacityInput is the capacity of the environmentBlendModes array, or 0 to indicate a request to retrieve the required capacity.

  • environmentBlendModeCountOutput is a pointer to the count of environmentBlendModes written, or a pointer to the required capacity in the case that environmentBlendModeCapacityInput is insufficient.

  • environmentBlendModes is a pointer to an array of XrEnvironmentBlendMode values, but can be NULL if environmentBlendModeCapacityInput is 0.

  • See Buffer Size Parameters chapter for a detailed description of retrieving the required environmentBlendModes size.

Description

Enumerates the set of environment blend modes that this runtime supports for a given view configuration of the system. Environment blend modes should be in order from highest to lowest runtime preference.

Runtimes must always return identical buffer contents from this enumeration for the given systemId and viewConfigurationType for the lifetime of the instance.

Valid Usage (Implicit)
  • instance must be a valid XrInstance handle

  • viewConfigurationType must be a valid XrViewConfigurationType value

  • environmentBlendModeCountOutput must be a pointer to a uint32_t value

  • If environmentBlendModeCapacityInput is not 0, environmentBlendModes must be a pointer to an array of environmentBlendModeCapacityInput XrEnvironmentBlendMode values

Return Codes
On success, this command returns
  • XR_SUCCESS

On failure, this command returns
  • XR_ERROR_VALIDATION_FAILURE

  • XR_ERROR_RUNTIME_FAILURE

  • XR_ERROR_HANDLE_INVALID

  • XR_ERROR_INSTANCE_LOST

  • XR_ERROR_SIZE_INSUFFICIENT

  • XR_ERROR_VIEW_CONFIGURATION_TYPE_UNSUPPORTED

  • XR_ERROR_SYSTEM_INVALID

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

xrEnumerateExternalCamerasOCULUS(3)

Name

xrEnumerateExternalCamerasOCULUS - Enumerates all the external cameras that are supported by the runtime

C Specification

The xrEnumerateExternalCamerasOCULUS function enumerates all the external cameras that are supported by the runtime, it is defined as:

// Provided by XR_OCULUS_external_camera
XrResult xrEnumerateExternalCamerasOCULUS(
    XrSession                                   session,
    uint32_t                                    cameraCapacityInput,
    uint32_t*                                   cameraCountOutput,
    XrExternalCameraOCULUS*                     cameras);

Parameters

Parameter Descriptions
  • session is the XrSession to query the external cameras in

  • cameraCapacityInput is the capacity of the cameras array, or 0 to indicate a request to retrieve the required capacity.

  • cameraCountOutput is filled in by the runtime with the count of cameras written or the required capacity in the case that cameraCapacityInput is insufficient.

  • cameras is an array of XrExternalCameraOCULUS filled in by the runtime which contains all the available external cameras, but can be NULL if cameraCapacityInput is 0.

  • See the Buffer Size Parameters section for a detailed description of retrieving the required cameras size.

Description

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_SIZE_INSUFFICIENT

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

xrEnumerateInstanceExtensionProperties(3)

Name

xrEnumerateInstanceExtensionProperties - Returns properties of available instance extensions

C Specification

The application can determine the available instance extensions by calling xrEnumerateInstanceExtensionProperties:

// Provided by XR_VERSION_1_0
XrResult xrEnumerateInstanceExtensionProperties(
    const char*                                 layerName,
    uint32_t                                    propertyCapacityInput,
    uint32_t*                                   propertyCountOutput,
    XrExtensionProperties*                      properties);

Parameters

Parameter Descriptions
  • layerName is either NULL or a pointer to a string naming the API layer to retrieve extensions from, as returned by xrEnumerateApiLayerProperties.

  • propertyCapacityInput is the capacity of the properties array, or 0 to indicate a request to retrieve the required capacity.

  • propertyCountOutput is a pointer to the count of properties written, or a pointer to the required capacity in the case that propertyCapacityInput is insufficient.

  • properties is a pointer to an array of XrExtensionProperties structures, but can be NULL if propertyCapacityInput is 0.

  • See the Buffer Size Parameters section for a detailed description of retrieving the required properties size.

Description

Because the list of available layers may change externally between calls to xrEnumerateInstanceExtensionProperties, two calls may retrieve different results if a layerName is available in one call but not in another. The extensions supported by a layer may also change between two calls, e.g. if the layer implementation is replaced by a different version between those calls.

Valid Usage (Implicit)
  • If layerName is not NULL, layerName must be a null-terminated UTF-8 string

  • propertyCountOutput must be a pointer to a uint32_t value

  • If propertyCapacityInput is not 0, properties must be a pointer to an array of propertyCapacityInput XrExtensionProperties structures

Return Codes
On success, this command returns
  • XR_SUCCESS

On failure, this command returns
  • XR_ERROR_VALIDATION_FAILURE

  • XR_ERROR_RUNTIME_FAILURE

  • XR_ERROR_OUT_OF_MEMORY

  • XR_ERROR_SIZE_INSUFFICIENT

  • XR_ERROR_RUNTIME_UNAVAILABLE

  • XR_ERROR_API_LAYER_NOT_PRESENT

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

xrEnumeratePerformanceMetricsCounterPathsMETA(3)

Name

xrEnumeratePerformanceMetricsCounterPathsMETA - Enumerate all performance metrics counter paths that supported by the runtime

C Specification

The xrEnumeratePerformanceMetricsCounterPathsMETA function enumerates all performance metrics counter paths that supported by the runtime, it is defined as:

// Provided by XR_META_performance_metrics
XrResult xrEnumeratePerformanceMetricsCounterPathsMETA(
    XrInstance                                  instance,
    uint32_t                                    counterPathCapacityInput,
    uint32_t*                                   counterPathCountOutput,
    XrPath*                                     counterPaths);

Parameters

Parameter Descriptions
  • instance is an XrInstance handle previously created with xrCreateInstance.

  • counterPathCapacityInput is the capacity of the counterPaths array, or 0 to indicate a request to retrieve the required capacity.

  • counterPathCountOutput is filled in by the runtime with the count of counterPaths written or the required capacity in the case that counterPathCapacityInput is insufficient.

  • counterPaths is an array of XrPath filled in by the runtime which contains all the available performance metrics counters, but can be NULL if counterPathCapacityInput is 0.

  • See the Buffer Size Parameters section for a detailed description of retrieving the required counterPaths size.

Description

Valid Usage (Implicit)
Return Codes
On success, this command returns
  • XR_SUCCESS

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_SIZE_INSUFFICIENT

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

xrEnumeratePersistedSpatialAnchorNamesMSFT(3)

Name

xrEnumeratePersistedSpatialAnchorNamesMSFT - Enumerate the names of currently persisted spatial anchors in the spatial anchor store

C Specification

The application can use the xrEnumeratePersistedSpatialAnchorNamesMSFT function to enumerate the names of all spatial anchors currently persisted in the spatial anchor store for this application. This function follows the two-call idiom for filling the spatialAnchorNames.

// Provided by XR_MSFT_spatial_anchor_persistence
XrResult xrEnumeratePersistedSpatialAnchorNamesMSFT(
    XrSpatialAnchorStoreConnectionMSFT          spatialAnchorStore,
    uint32_t                                    spatialAnchorNameCapacityInput,
    uint32_t*                                   spatialAnchorNameCountOutput,
    XrSpatialAnchorPersistenceNameMSFT*         spatialAnchorNames);

Parameters

Parameter Descriptions
  • spatialAnchorStore is the XrSpatialAnchorStoreConnectionMSFT anchor store to perform the enumeration operation on.

  • spatialAnchorNameCapacityInput is the capacity of the spatialAnchorNames array, or 0 to indicate a request to retrieve the required capacity.

  • spatialAnchorNameCountOutput is filled in by the runtime with the count of anchor names written or the required capacity in the case that spatialAnchorNameCapacityInput is insufficient.

  • spatialAnchorNames is a pointer to an array of XrSpatialAnchorPersistenceNameMSFT structures, but can be NULL if propertyCapacityInput is 0.

  • See the Buffer Size Parameters section for a detailed description of retrieving the required spatialAnchorNames size.

Description

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_HANDLE_INVALID

  • XR_ERROR_INSTANCE_LOST

  • XR_ERROR_SESSION_LOST

  • XR_ERROR_OUT_OF_MEMORY

  • XR_ERROR_SIZE_INSUFFICIENT

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

xrEnumerateReferenceSpaces(3)

Name

xrEnumerateReferenceSpaces - Enumerate available reference spaces

C Specification

The xrEnumerateReferenceSpaces function is defined as:

// Provided by XR_VERSION_1_0
XrResult xrEnumerateReferenceSpaces(
    XrSession                                   session,
    uint32_t                                    spaceCapacityInput,
    uint32_t*                                   spaceCountOutput,
    XrReferenceSpaceType*                       spaces);

Parameters

Parameter Descriptions
  • session is a handle to an XrSession previously created with xrCreateSession.

  • spaceCapacityInput is the capacity of the spaces array, or 0 to indicate a request to retrieve the required capacity.

  • spaceCountOutput is a pointer to the count of spaces written, or a pointer to the required capacity in the case that spaceCapacityInput is insufficient.

  • spaces is a pointer to an application-allocated array that will be filled with the enumerant of each supported reference space. It can be NULL if spaceCapacityInput is 0.

  • See Buffer Size Parameters chapter for a detailed description of retrieving the required spaces size.

Description

Enumerates the set of reference space types that this runtime supports for a given session. Runtimes must always return identical buffer contents from this enumeration for the lifetime of the session.

If a session enumerates support for a given reference space type, calls to xrCreateReferenceSpace must succeed for that session, with any transient unavailability of poses expressed later during calls to xrLocateSpace.

Valid Usage (Implicit)
  • session must be a valid XrSession handle

  • spaceCountOutput must be a pointer to a uint32_t value

  • If spaceCapacityInput is not 0, spaces must be a pointer to an array of spaceCapacityInput XrReferenceSpaceType values

Return Codes
On success, this command returns
  • XR_SUCCESS

  • XR_SESSION_LOSS_PENDING

On failure, this command returns
  • XR_ERROR_VALIDATION_FAILURE

  • XR_ERROR_RUNTIME_FAILURE

  • XR_ERROR_HANDLE_INVALID

  • XR_ERROR_INSTANCE_LOST

  • XR_ERROR_SESSION_LOST

  • XR_ERROR_SIZE_INSUFFICIENT

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

xrEnumerateRenderModelPathsFB(3)

Name

xrEnumerateRenderModelPathsFB - Enumerate supported render model paths

C Specification

The xrEnumerateRenderModelPathsFB function is defined as:

// Provided by XR_FB_render_model
XrResult xrEnumerateRenderModelPathsFB(
    XrSession                                   session,
    uint32_t                                    pathCapacityInput,
    uint32_t*                                   pathCountOutput,
    XrRenderModelPathInfoFB*                    paths);

Parameters

Parameter Descriptions
  • session is the specified XrSession.

  • pathCapacityInput is the capacity of the paths, or 0 to retrieve the required capacity.

  • pathCountOutput is a pointer to the count of float paths written, or a pointer to the required capacity in the case that pathCapacityInput is insufficient.

  • paths is a pointer to an application-allocated array that will be filled with XrRenderModelPathInfoFB values that are supported by the runtime, but can be NULL if pathCapacityInput is 0

  • See Buffer Size Parameters chapter for a detailed description of retrieving the required paths size.

Description

The application must call xrEnumerateRenderModelPathsFB to enumerate the valid render model paths that are supported by the runtime before calling xrGetRenderModelPropertiesFB. The paths returned may be used later in xrGetRenderModelPropertiesFB.

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_HANDLE_INVALID

  • XR_ERROR_INSTANCE_LOST

  • XR_ERROR_SESSION_LOST

  • XR_ERROR_OUT_OF_MEMORY

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

xrEnumerateReprojectionModesMSFT(3)

Name

xrEnumerateReprojectionModesMSFT - Queries the supported reprojection modes.

C Specification

First, the application uses xrEnumerateReprojectionModesMSFT to inspect what reprojection mode the view configuration supports.

The xrEnumerateReprojectionModesMSFT function returns the supported reprojection modes of the view configuration.

// Provided by XR_MSFT_composition_layer_reprojection
XrResult xrEnumerateReprojectionModesMSFT(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    XrViewConfigurationType                     viewConfigurationType,
    uint32_t                                    modeCapacityInput,
    uint32_t*                                   modeCountOutput,
    XrReprojectionModeMSFT*                     modes);

Parameters

Parameter Descriptions
  • instance is the instance from which systemId was retrieved.

  • systemId is the XrSystemId whose reprojection modes will be enumerated.

  • viewConfigurationType is the XrViewConfigurationType to enumerate.

  • modeCapacityInput is the capacity of the array, or 0 to indicate a request to retrieve the required capacity.

  • modeCountOutput is a pointer to the count of the array, or a pointer to the required capacity in the case that modeCapacityInput is insufficient.

  • modes is a pointer to an application-allocated array that will be filled with the XrReprojectionModeMSFT values that are supported by the runtime. It can be NULL if modeCapacityInput is 0.

  • See Buffer Size Parameters chapter for a detailed description of retrieving the required modes size.

Description

Valid Usage (Implicit)
Return Codes
On success, this command returns
  • XR_SUCCESS

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_SIZE_INSUFFICIENT

  • XR_ERROR_VIEW_CONFIGURATION_TYPE_UNSUPPORTED

  • XR_ERROR_SYSTEM_INVALID

A system may support different sets of reprojection modes for different view configuration types.

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

xrEnumerateSceneComputeFeaturesMSFT(3)

Name

xrEnumerateSceneComputeFeaturesMSFT - Enumerates scene compute features

C Specification

The xrEnumerateSceneComputeFeaturesMSFT function enumerates the supported scene compute features of the given system.

This function follows the two-call idiom for filling the features array.

// Provided by XR_MSFT_scene_understanding
XrResult xrEnumerateSceneComputeFeaturesMSFT(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    uint32_t                                    featureCapacityInput,
    uint32_t*                                   featureCountOutput,
    XrSceneComputeFeatureMSFT*                  features);

Parameters

Parameter Descriptions
  • instance is a handle to an XrInstance.

  • systemId is the XrSystemId whose scene compute features will be enumerated.

  • featureCapacityInput is the capacity of the array, or 0 to indicate a request to retrieve the required capacity.

  • featureCountOutput is a pointer to the count of scene compute features, or a pointer to the required capacity in the case that featureCapacityInput is insufficient.

  • features is an array of XrSceneComputeFeatureMSFT.

Description

Valid Usage (Implicit)
Return Codes
On success, this command returns
  • XR_SUCCESS

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_OUT_OF_MEMORY

  • XR_ERROR_SIZE_INSUFFICIENT

  • XR_ERROR_SYSTEM_INVALID

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

xrEnumerateSpaceSupportedComponentsFB(3)

Name

xrEnumerateSpaceSupportedComponentsFB - Enumerates supported components for a given spatial entity

C Specification

The xrEnumerateSpaceSupportedComponentsFB function is defined as:

// Provided by XR_FB_spatial_entity
XrResult xrEnumerateSpaceSupportedComponentsFB(
    XrSpace                                     space,
    uint32_t                                    componentTypeCapacityInput,
    uint32_t*                                   componentTypeCountOutput,
    XrSpaceComponentTypeFB*                     componentTypes);

Parameters

Parameter Descriptions
  • space is the XrSpace handle to the spatial entity.

  • componentTypeCapacityInput is the capacity of the componentTypes array, or 0 to indicate a request to retrieve the required capacity.

  • componentTypeCountOutput is a pointer to the count of componentTypes written, or a pointer to the required capacity in the case that componentTypeCapacityInput is insufficient.

  • componentTypes is a pointer to an array of XrSpaceComponentTypeFB values, but can be NULL if componentTypeCapacityInput is 0.

  • See Buffer Size Parameters chapter for a detailed description of retrieving the required componentTypes size.

Description

Lists any component types that an entity supports. The list of component types available for an entity depends on which extensions are enabled. Component types must not be enumerated unless the corresponding extension that defines them is also enabled.

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

  • XR_ERROR_FEATURE_UNSUPPORTED

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

xrEnumerateSwapchainFormats(3)

Name

xrEnumerateSwapchainFormats - Enumerates swapchain formats

C Specification

The xrEnumerateSwapchainFormats function is defined as:

// Provided by XR_VERSION_1_0
XrResult xrEnumerateSwapchainFormats(
    XrSession                                   session,
    uint32_t                                    formatCapacityInput,
    uint32_t*                                   formatCountOutput,
    int64_t*                                    formats);

Parameters

Parameter Descriptions
  • session is the session that enumerates the supported formats.

  • formatCapacityInput is the capacity of the formats, or 0 to retrieve the required capacity.

  • formatCountOutput is a pointer to the count of uint64_t formats written, or a pointer to the required capacity in the case that formatCapacityInput is insufficient.

  • formats is a pointer to an array of int64_t format ids, but can be NULL if formatCapacityInput is 0. The format ids are specific to the specified graphics API.

  • See Buffer Size Parameters chapter for a detailed description of retrieving the required formats size.

Description

xrEnumerateSwapchainFormats enumerates the texture formats supported by the current session. The type of formats returned are dependent on the graphics API specified in xrCreateSession. For example, if a DirectX graphics API was specified, then the enumerated formats correspond to the DXGI formats, such as DXGI_FORMAT_R8G8B8A8_UNORM_SRGB. Texture formats should be in order from highest to lowest runtime preference. The application should use the highest preference format that it supports for optimal performance and quality.

With an OpenGL-based graphics API, the texture formats correspond to OpenGL internal formats.

With a Direct3D-based graphics API, xrEnumerateSwapchainFormats never returns typeless formats (e.g. DXGI_FORMAT_R8G8B8A8_TYPELESS). Only concrete formats are returned, and only concrete formats may be specified by applications for swapchain creation.

Runtimes must always return identical buffer contents from this enumeration for the lifetime of the session.

Valid Usage (Implicit)
  • session must be a valid XrSession handle

  • formatCountOutput must be a pointer to a uint32_t value

  • If formatCapacityInput is not 0, formats must be a pointer to an array of formatCapacityInput int64_t values

Return Codes
On success, this command returns
  • XR_SUCCESS

  • XR_SESSION_LOSS_PENDING

On failure, this command returns
  • XR_ERROR_VALIDATION_FAILURE

  • XR_ERROR_RUNTIME_FAILURE

  • XR_ERROR_HANDLE_INVALID

  • XR_ERROR_INSTANCE_LOST

  • XR_ERROR_SESSION_LOST

  • XR_ERROR_SIZE_INSUFFICIENT

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

xrEnumerateSwapchainImages(3)

Name

xrEnumerateSwapchainImages - Gets images from an XrSwapchain

C Specification

The xrEnumerateSwapchainImages function is defined as:

// Provided by XR_VERSION_1_0
XrResult xrEnumerateSwapchainImages(
    XrSwapchain                                 swapchain,
    uint32_t                                    imageCapacityInput,
    uint32_t*                                   imageCountOutput,
    XrSwapchainImageBaseHeader*                 images);

Parameters

Parameter Descriptions
  • swapchain is the XrSwapchain to get images from.

  • imageCapacityInput is the capacity of the images array, or 0 to indicate a request to retrieve the required capacity.

  • imageCountOutput is a pointer to the count of images written, or a pointer to the required capacity in the case that imageCapacityInput is insufficient.

  • images is a pointer to an array of graphics API-specific XrSwapchainImage structures, all of the same type, based on XrSwapchainImageBaseHeader. It can be NULL if imageCapacityInput is 0.

  • See Buffer Size Parameters chapter for a detailed description of retrieving the required images size.

Description

Fills an array of graphics API-specific XrSwapchainImage structures. The resources must be constant and valid for the lifetime of the XrSwapchain.

Runtimes must always return identical buffer contents from this enumeration for the lifetime of the swapchain.

Note: images is a pointer to an array of structures of graphics API-specific type, not an array of structure pointers.

The pointer submitted as images will be treated as an array of the expected graphics API-specific type based on the graphics API used at session creation time. If the type member of any array element accessed in this way does not match the expected value, the runtime must return XR_ERROR_VALIDATION_FAILURE.

Note

Under a typical memory model, a runtime must treat the supplied pointer as an opaque blob beginning with XrSwapchainImageBaseHeader, until after it has verified the XrSwapchainImageBaseHeader::type.

Valid Usage (Implicit)
Return Codes
On success, this command returns
  • XR_SUCCESS

  • XR_SESSION_LOSS_PENDING

On failure, this command returns
  • XR_ERROR_VALIDATION_FAILURE

  • XR_ERROR_RUNTIME_FAILURE

  • XR_ERROR_HANDLE_INVALID

  • XR_ERROR_INSTANCE_LOST

  • XR_ERROR_SESSION_LOST

  • XR_ERROR_SIZE_INSUFFICIENT

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

xrEnumerateViewConfigurationViews(3)

Name

xrEnumerateViewConfigurationViews - Gets view configuration views

C Specification

The xrEnumerateViewConfigurationViews function is defined as:

// Provided by XR_VERSION_1_0
XrResult xrEnumerateViewConfigurationViews(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    XrViewConfigurationType                     viewConfigurationType,
    uint32_t                                    viewCapacityInput,
    uint32_t*                                   viewCountOutput,
    XrViewConfigurationView*                    views);

Parameters

Parameter Descriptions
  • instance is the instance from which systemId was retrieved.

  • systemId is the XrSystemId whose view configuration is being queried.

  • viewConfigurationType is the XrViewConfigurationType of the configuration to get.

  • viewCapacityInput is the capacity of the views array, or 0 to indicate a request to retrieve the required capacity.

  • viewCountOutput is a pointer to the count of views written, or a pointer to the required capacity in the case that viewCapacityInput is 0.

  • views is a pointer to an array of XrViewConfigurationView values, but can be NULL if viewCapacityInput is 0.

Description

Each XrViewConfigurationType defines the number of views associated with it. Applications can query more details of each view element using xrEnumerateViewConfigurationViews. If the supplied viewConfigurationType is not supported by this XrInstance and XrSystemId, the runtime must return XR_ERROR_VIEW_CONFIGURATION_TYPE_UNSUPPORTED.

Runtimes must always return identical buffer contents from this enumeration for the given systemId and viewConfigurationType for the lifetime of the instance.

Valid Usage (Implicit)
  • instance must be a valid XrInstance handle

  • viewConfigurationType must be a valid XrViewConfigurationType value

  • viewCountOutput must be a pointer to a uint32_t value

  • If viewCapacityInput is not 0, views must be a pointer to an array of viewCapacityInput XrViewConfigurationView structures

Return Codes
On success, this command returns
  • XR_SUCCESS

On failure, this command returns
  • XR_ERROR_VALIDATION_FAILURE

  • XR_ERROR_RUNTIME_FAILURE

  • XR_ERROR_HANDLE_INVALID

  • XR_ERROR_INSTANCE_LOST

  • XR_ERROR_SIZE_INSUFFICIENT

  • XR_ERROR_VIEW_CONFIGURATION_TYPE_UNSUPPORTED

  • XR_ERROR_SYSTEM_INVALID

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

xrEnumerateViewConfigurations(3)

Name

xrEnumerateViewConfigurations - Enumerates supported view configurations

C Specification

The xrEnumerateViewConfigurations function is defined as:

// Provided by XR_VERSION_1_0
XrResult xrEnumerateViewConfigurations(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    uint32_t                                    viewConfigurationTypeCapacityInput,
    uint32_t*                                   viewConfigurationTypeCountOutput,
    XrViewConfigurationType*                    viewConfigurationTypes);

Parameters

Parameter Descriptions
  • instance is the instance from which systemId was retrieved.

  • systemId is the XrSystemId whose view configurations will be enumerated.

  • viewConfigurationTypeCapacityInput is the capacity of the viewConfigurationTypes array, or 0 to indicate a request to retrieve the required capacity.

  • viewConfigurationTypeCountOutput is a pointer to the count of viewConfigurationTypes written, or a pointer to the required capacity in the case that viewConfigurationTypeCapacityInput is insufficient.

  • viewConfigurationTypes is a pointer to an array of XrViewConfigurationType values, but can be NULL if viewConfigurationTypeCapacityInput is 0.

  • See Buffer Size Parameters chapter for a detailed description of retrieving the required viewConfigurationTypes size.

Description

xrEnumerateViewConfigurations enumerates the view configuration types supported by the XrSystemId. The supported set for that system must not change during the lifetime of its XrInstance. The returned list of primary view configurations should be in order from what the runtime considered highest to lowest user preference. Thus the first enumerated view configuration type should be the one the runtime prefers the application to use if possible.

Runtimes must always return identical buffer contents from this enumeration for the given systemId and for the lifetime of the instance.

Valid Usage (Implicit)
  • instance must be a valid XrInstance handle

  • viewConfigurationTypeCountOutput must be a pointer to a uint32_t value

  • If viewConfigurationTypeCapacityInput is not 0, viewConfigurationTypes must be a pointer to an array of viewConfigurationTypeCapacityInput XrViewConfigurationType values

Return Codes
On success, this command returns
  • XR_SUCCESS

On failure, this command returns
  • XR_ERROR_VALIDATION_FAILURE

  • XR_ERROR_RUNTIME_FAILURE

  • XR_ERROR_HANDLE_INVALID

  • XR_ERROR_INSTANCE_LOST

  • XR_ERROR_SIZE_INSUFFICIENT

  • XR_ERROR_SYSTEM_INVALID

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

xrEnumerateViveTrackerPathsHTCX(3)

Name

xrEnumerateViveTrackerPathsHTCX - Enumerates all connected VIVE trackers

C Specification

The xrEnumerateViveTrackerPathsHTCX function is defined as:

// Provided by XR_HTCX_vive_tracker_interaction
XrResult xrEnumerateViveTrackerPathsHTCX(
    XrInstance                                  instance,
    uint32_t                                    pathCapacityInput,
    uint32_t*                                   pathCountOutput,
    XrViveTrackerPathsHTCX*                     paths);

Parameters

Parameter Descriptions
  • instance is an instance previously created.

  • pathCapacityInput is the capacity of the paths, or 0 to retrieve the required capacity.

  • pathCountOutput is a pointer to the count of XrViveTrackerPathsHTCX paths written, or a pointer to the required capacity in the case that pathCapacityInput is insufficient.

  • paths is a pointer to an array of XrViveTrackerPathsHTCX VIVE tracker paths, but can be NULL if pathCapacityInput is 0.

  • See Buffer Size Parameters chapter for a detailed description of retrieving the required paths size.

Description

xrEnumerateViveTrackerPathsHTCX enumerates all connected VIVE trackers to retrieve their paths under current instance.

Valid Usage (Implicit)
Return Codes
On success, this command returns
  • XR_SUCCESS

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_SIZE_INSUFFICIENT

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

xrEraseSpaceFB(3)

Name

xrEraseSpaceFB - Erases a spatial entity from persistent storage

C Specification

The xrEraseSpaceFB function is defined as:

// Provided by XR_FB_spatial_entity_storage
XrResult xrEraseSpaceFB(
    XrSession                                   session,
    const XrSpaceEraseInfoFB*                   info,
    XrAsyncRequestIdFB*                         requestId);

Parameters

Parameter Descriptions
  • session is a handle to an XrSession.

  • info contains the parameters for the erase operation.

  • requestId is an output parameter, and the variable it points to will be populated with the ID of this asynchronous request.

Description

The xrEraseSpaceFB function erases a spatial entity from storage at the specified location. The XrSpace remains valid in the current session until the application destroys it or the session ends. The runtime must return XR_ERROR_VALIDATION_FAILURE if XrSpaceEraseInfoFB::space is XR_NULL_HANDLE or otherwise invalid. The runtime must return XR_ERROR_VALIDATION_FAILURE if XrSpaceEraseInfoFB::location is invalid. This operation is asynchronous and the runtime must post an XrEventDataSpaceEraseCompleteFB event when the operation completes successfully or encounters an error. If this function returns a failure code, no event is posted.

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_COMPONENT_NOT_ENABLED_FB

  • XR_ERROR_FEATURE_UNSUPPORTED

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

xrGeometryInstanceSetTransformFB(3)

Name

xrGeometryInstanceSetTransformFB - Create a triangle mesh

C Specification

The xrGeometryInstanceSetTransformFB function is defined as:

// Provided by XR_FB_passthrough
XrResult xrGeometryInstanceSetTransformFB(
    XrGeometryInstanceFB                        instance,
    const XrGeometryInstanceTransformFB*        transformation);

Parameters

Parameter Descriptions

Description

Sets an XrGeometryInstanceTransformFB transform on an XrGeometryInstanceFB geometry instance.

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_TIME_INVALID

  • XR_ERROR_POSE_INVALID

  • XR_ERROR_FEATURE_UNSUPPORTED

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

xrGetActionStateBoolean(3)

Name

xrGetActionStateBoolean - Gets boolean action state

C Specification

xrGetActionStateBoolean retrieves the current state of a boolean action. It is defined as:

// Provided by XR_VERSION_1_0
XrResult xrGetActionStateBoolean(
    XrSession                                   session,
    const XrActionStateGetInfo*                 getInfo,
    XrActionStateBoolean*                       state);

Parameters

Parameter Descriptions

Description

Valid Usage (Implicit)
Return Codes
On success, this command returns
  • XR_SUCCESS

  • XR_SESSION_LOSS_PENDING

On failure, this command returns
  • XR_ERROR_VALIDATION_FAILURE

  • XR_ERROR_RUNTIME_FAILURE

  • XR_ERROR_HANDLE_INVALID

  • XR_ERROR_INSTANCE_LOST

  • XR_ERROR_SESSION_LOST

  • XR_ERROR_PATH_UNSUPPORTED

  • XR_ERROR_PATH_INVALID

  • XR_ERROR_ACTION_TYPE_MISMATCH

  • XR_ERROR_ACTIONSET_NOT_ATTACHED

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

xrGetActionStateFloat(3)

Name

xrGetActionStateFloat - Gets a floating point action state

C Specification

xrGetActionStateFloat retrieves the current state of a floating-point action. It is defined as:

// Provided by XR_VERSION_1_0
XrResult xrGetActionStateFloat(
    XrSession                                   session,
    const XrActionStateGetInfo*                 getInfo,
    XrActionStateFloat*                         state);

Parameters

Parameter Descriptions

Description

Valid Usage (Implicit)
Return Codes
On success, this command returns
  • XR_SUCCESS

  • XR_SESSION_LOSS_PENDING

On failure, this command returns
  • XR_ERROR_VALIDATION_FAILURE

  • XR_ERROR_RUNTIME_FAILURE

  • XR_ERROR_HANDLE_INVALID

  • XR_ERROR_INSTANCE_LOST

  • XR_ERROR_SESSION_LOST

  • XR_ERROR_PATH_UNSUPPORTED

  • XR_ERROR_PATH_INVALID

  • XR_ERROR_ACTION_TYPE_MISMATCH

  • XR_ERROR_ACTIONSET_NOT_ATTACHED

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

xrGetActionStatePose(3)

Name

xrGetActionStatePose - Gets metadata from a pose action

C Specification

The xrGetActionStatePose function is defined as:

// Provided by XR_VERSION_1_0
XrResult xrGetActionStatePose(
    XrSession                                   session,
    const XrActionStateGetInfo*                 getInfo,
    XrActionStatePose*                          state);

Parameters

Parameter Descriptions

Description

xrGetActionStatePose returns information about the binding and active state for the specified action. To determine the pose of this action at a historical or predicted time, the application can create an action space using xrCreateActionSpace. Then, after each sync, the application can locate the pose of this action space within a base space using xrLocateSpace.

Valid Usage (Implicit)
Return Codes
On success, this command returns
  • XR_SUCCESS

  • XR_SESSION_LOSS_PENDING

On failure, this command returns
  • XR_ERROR_VALIDATION_FAILURE

  • XR_ERROR_RUNTIME_FAILURE

  • XR_ERROR_HANDLE_INVALID

  • XR_ERROR_INSTANCE_LOST

  • XR_ERROR_SESSION_LOST

  • XR_ERROR_PATH_UNSUPPORTED

  • XR_ERROR_PATH_INVALID

  • XR_ERROR_ACTION_TYPE_MISMATCH

  • XR_ERROR_ACTIONSET_NOT_ATTACHED

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

xrGetActionStateVector2f(3)

Name

xrGetActionStateVector2f - Gets 2D float vector action state

C Specification

xrGetActionStateVector2f retrieves the current state of a two-dimensional vector action. It is defined as:

// Provided by XR_VERSION_1_0
XrResult xrGetActionStateVector2f(
    XrSession                                   session,
    const XrActionStateGetInfo*                 getInfo,
    XrActionStateVector2f*                      state);

Parameters

Parameter Descriptions

Description

Valid Usage (Implicit)
Return Codes
On success, this command returns
  • XR_SUCCESS

  • XR_SESSION_LOSS_PENDING

On failure, this command returns
  • XR_ERROR_VALIDATION_FAILURE

  • XR_ERROR_RUNTIME_FAILURE

  • XR_ERROR_HANDLE_INVALID

  • XR_ERROR_INSTANCE_LOST

  • XR_ERROR_SESSION_LOST

  • XR_ERROR_PATH_UNSUPPORTED

  • XR_ERROR_PATH_INVALID

  • XR_ERROR_ACTION_TYPE_MISMATCH

  • XR_ERROR_ACTIONSET_NOT_ATTACHED

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

xrGetAudioInputDeviceGuidOculus(3)

Name

xrGetAudioInputDeviceGuidOculus - Query the GUID for the active audio input device

C Specification

// Provided by XR_OCULUS_audio_device_guid
XrResult xrGetAudioInputDeviceGuidOculus(
    XrInstance                                  instance,
    wchar_t                                     buffer[XR_MAX_AUDIO_DEVICE_STR_SIZE_OCULUS]);

Parameters

Parameter Descriptions
  • instance is the XrInstance to query the audio device state in.

  • buffer is a fixed size buffer which will contain the audio device GUID. The format of this data matches the IMMDevice::GetId API.

Description

Valid Usage (Implicit)
Return Codes
On success, this command returns
  • XR_SUCCESS

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_FEATURE_UNSUPPORTED

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

xrGetAudioOutputDeviceGuidOculus(3)

Name

xrGetAudioOutputDeviceGuidOculus - Query the GUID for the active audio output device

C Specification

// Provided by XR_OCULUS_audio_device_guid
XrResult xrGetAudioOutputDeviceGuidOculus(
    XrInstance                                  instance,
    wchar_t                                     buffer[XR_MAX_AUDIO_DEVICE_STR_SIZE_OCULUS]);

Parameters

Parameter Descriptions
  • instance is the XrInstance to query the audio device state in.

  • buffer is a fixed size buffer which will contain the audio device GUID. The format of this data matches the IMMDevice::GetId API.

Description

Valid Usage (Implicit)
Return Codes
On success, this command returns
  • XR_SUCCESS

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_FEATURE_UNSUPPORTED

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

xrGetBodySkeletonFB(3)

Name

xrGetBodySkeletonFB - Retrieve body skeleton

C Specification

The xrGetBodySkeletonFB function returns the body skeleton in T-pose.

// Provided by XR_FB_body_tracking
XrResult xrGetBodySkeletonFB(
    XrBodyTrackerFB                             bodyTracker,
    XrBodySkeletonFB*                           skeleton);

Parameters

Parameter Descriptions

Description

This function can be used to query the skeleton scale and proportions in conjunction with XrBodyJointLocationsFB::skeletonChangedCount. XrBodyJointLocationsFB::skeletonChangedCount is incremented whenever the tracking auto-calibrates the user skeleton scale and proportions.

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

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

xrGetControllerModelKeyMSFT(3)

Name

xrGetControllerModelKeyMSFT - Retrieve the model key for the controller

C Specification

xrGetControllerModelKeyMSFT retrieves the XrControllerModelKeyMSFT for a controller. This model key may later be used to retrieve the model data.

The xrGetControllerModelKeyMSFT function is defined as:

// Provided by XR_MSFT_controller_model
XrResult xrGetControllerModelKeyMSFT(
    XrSession                                   session,
    XrPath                                      topLevelUserPath,
    XrControllerModelKeyStateMSFT*              controllerModelKeyState);

Parameters

Parameter Descriptions
  • session is the specified XrSession.

  • topLevelUserPath is the top level user path corresponding to the controller render model being queried (e.g. /user/hand/left or /user/hand/right).

  • controllerModelKeyState is a pointer to the XrControllerModelKeyStateMSFT to write the model key state to.

Description

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_HANDLE_INVALID

  • XR_ERROR_INSTANCE_LOST

  • XR_ERROR_SESSION_LOST

  • XR_ERROR_OUT_OF_MEMORY

  • XR_ERROR_PATH_UNSUPPORTED

  • XR_ERROR_PATH_INVALID

  • XR_ERROR_CONTROLLER_MODEL_KEY_INVALID_MSFT

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

xrGetControllerModelPropertiesMSFT(3)

Name

xrGetControllerModelPropertiesMSFT - Get controller model properties

C Specification

The xrGetControllerModelPropertiesMSFT function returns the controller model properties for a given modelKey.

// Provided by XR_MSFT_controller_model
XrResult xrGetControllerModelPropertiesMSFT(
    XrSession                                   session,
    XrControllerModelKeyMSFT                    modelKey,
    XrControllerModelPropertiesMSFT*            properties);

Parameters

Parameter Descriptions

Description

The runtime must return the same data in XrControllerModelPropertiesMSFT for a valid modelKey. Therefore, the application can cache the returned XrControllerModelPropertiesMSFT using modelKey and reuse the data for each frame.

If the input modelKey is invalid, i.e. it is XR_NULL_CONTROLLER_MODEL_KEY_MSFT or not a key returned from XrControllerModelKeyStateMSFT, the runtime must return XR_ERROR_CONTROLLER_MODEL_KEY_INVALID_MSFT.

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_HANDLE_INVALID

  • XR_ERROR_INSTANCE_LOST

  • XR_ERROR_SESSION_LOST

  • XR_ERROR_OUT_OF_MEMORY

  • XR_ERROR_SIZE_INSUFFICIENT

  • XR_ERROR_CONTROLLER_MODEL_KEY_INVALID_MSFT

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

xrGetControllerModelStateMSFT(3)

Name

xrGetControllerModelStateMSFT - Get controller model state

C Specification

The xrGetControllerModelStateMSFT function returns the current state of the controller model representing user’s interaction to the controller, such as pressing a button or pulling a trigger.

// Provided by XR_MSFT_controller_model
XrResult xrGetControllerModelStateMSFT(
    XrSession                                   session,
    XrControllerModelKeyMSFT                    modelKey,
    XrControllerModelStateMSFT*                 state);

Parameters

Parameter Descriptions
  • session is the specified XrSession.

  • modelKey is the model key corresponding to the controller model being queried.

  • state is a pointer to XrControllerModelNodeStateMSFT returns the current controller model state.

Description

The runtime may return different state for a model key after each call to xrSyncActions, which represents the latest state of the user interactions.

If the input modelKey is invalid, i.e. it is XR_NULL_CONTROLLER_MODEL_KEY_MSFT or not a key returned from XrControllerModelKeyStateMSFT, the runtime must return XR_ERROR_CONTROLLER_MODEL_KEY_INVALID_MSFT.

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_HANDLE_INVALID

  • XR_ERROR_INSTANCE_LOST

  • XR_ERROR_SESSION_LOST

  • XR_ERROR_OUT_OF_MEMORY

  • XR_ERROR_CONTROLLER_MODEL_KEY_INVALID_MSFT

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

xrGetCurrentInteractionProfile(3)

Name

xrGetCurrentInteractionProfile - Gets the current interaction profile for a top level user paths

C Specification

The xrGetCurrentInteractionProfile function is defined as:

// Provided by XR_VERSION_1_0
XrResult xrGetCurrentInteractionProfile(
    XrSession                                   session,
    XrPath                                      topLevelUserPath,
    XrInteractionProfileState*                  interactionProfile);

Parameters

Parameter Descriptions
  • session is the XrSession for which the application would like to retrieve the current interaction profile.

  • topLevelUserPath is the top level user path the application would like to retrieve the interaction profile for.

  • interactionProfile is a pointer to an XrInteractionProfileState structure to receive the current interaction profile.

Description

xrGetCurrentInteractionProfile asks the runtime for the active interaction profiles for a top level user path.

The runtime must return only interaction profiles for which the application has provided bindings with xrSuggestInteractionProfileBindings or XR_NULL_PATH. The runtime may return interaction profiles that do not represent physically present hardware, for example if the runtime is using a known interaction profile to bind to hardware that the application is not aware of. The runtime may return the last-known interaction profile in the event that no controllers are active.

If xrAttachSessionActionSets has not yet been called for the session, the runtime must return XR_ERROR_ACTIONSET_NOT_ATTACHED. If topLevelUserPath is not one of the device input subpaths described in section /user paths, the runtime must return XR_ERROR_PATH_UNSUPPORTED.

Valid Usage (Implicit)
Return Codes
On success, this command returns
  • XR_SUCCESS

  • XR_SESSION_LOSS_PENDING

On failure, this command returns
  • XR_ERROR_VALIDATION_FAILURE

  • XR_ERROR_RUNTIME_FAILURE

  • XR_ERROR_HANDLE_INVALID

  • XR_ERROR_INSTANCE_LOST

  • XR_ERROR_SESSION_LOST

  • XR_ERROR_PATH_UNSUPPORTED

  • XR_ERROR_PATH_INVALID

  • XR_ERROR_ACTIONSET_NOT_ATTACHED

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

xrGetD3D11GraphicsRequirementsKHR(3)

Name

xrGetD3D11GraphicsRequirementsKHR - Retrieve the D3D11 feature level and graphics device requirements for an instance and system

C Specification

To retrieve the D3D11 feature level and graphics device for an instance and system, call:

// Provided by XR_KHR_D3D11_enable
XrResult xrGetD3D11GraphicsRequirementsKHR(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    XrGraphicsRequirementsD3D11KHR*             graphicsRequirements);

Parameters

Parameter Descriptions

Description

The xrGetD3D11GraphicsRequirementsKHR function identifies to the application what graphics device (Windows LUID) needs to be used and the minimum feature level to use. The runtime must return XR_ERROR_GRAPHICS_REQUIREMENTS_CALL_MISSING (XR_ERROR_VALIDATION_FAILURE may be returned due to legacy behavior) on calls to xrCreateSession if xrGetD3D11GraphicsRequirementsKHR has not been called for the same instance and systemId. The LUID and feature level that xrGetD3D11GraphicsRequirementsKHR returns must be used to create the ID3D11Device that the application passes to xrCreateSession in the XrGraphicsBindingD3D11KHR.

Valid Usage (Implicit)
Return Codes
On success, this command returns
  • XR_SUCCESS

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_SYSTEM_INVALID

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

xrGetD3D12GraphicsRequirementsKHR(3)

Name

xrGetD3D12GraphicsRequirementsKHR - Retrieve the D3D12 feature level and graphics device requirements for an instance and system

C Specification

To retrieve the D3D12 feature level and graphics device for an instance and system, call:

// Provided by XR_KHR_D3D12_enable
XrResult xrGetD3D12GraphicsRequirementsKHR(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    XrGraphicsRequirementsD3D12KHR*             graphicsRequirements);

Parameters

Parameter Descriptions

Description

The xrGetD3D12GraphicsRequirementsKHR function identifies to the application what graphics device (Windows LUID) needs to be used and the minimum feature level to use. The runtime must return XR_ERROR_GRAPHICS_REQUIREMENTS_CALL_MISSING (XR_ERROR_VALIDATION_FAILURE may be returned due to legacy behavior) on calls to xrCreateSession if xrGetD3D12GraphicsRequirementsKHR has not been called for the same instance and systemId. The LUID and feature level that xrGetD3D12GraphicsRequirementsKHR returns must be used to create the ID3D12Device that the application passes to xrCreateSession in the XrGraphicsBindingD3D12KHR.

Valid Usage (Implicit)
Return Codes
On success, this command returns
  • XR_SUCCESS

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_SYSTEM_INVALID

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

xrGetDeviceSampleRateFB(3)

Name

xrGetDeviceSampleRateFB - Get device sample rate

C Specification

// Provided by XR_FB_haptic_pcm
XrResult xrGetDeviceSampleRateFB(
    XrSession                                   session,
    const XrHapticActionInfo*                   hapticActionInfo,
    XrDevicePcmSampleRateGetInfoFB*             deviceSampleRate);

Parameters

Parameter Descriptions

Description

The runtime must use the hapticActionInfo to get the sample rate of the currently bound device on which haptics is triggered and populate the deviceSampleRate structure. The device is determined by the XrHapticActionInfo::action and XrHapticActionInfo::subactionPath. If the hapticActionInfo is bound to more than one device, then runtime should assume that the all these bound devices have the same deviceSampleRate and the runtime should return the sampleRate for any of those bound devices. If the device is invalid, the runtime must populate the deviceSampleRate of XrDevicePcmSampleRateStateFB as 0. A device can be invalid if the runtime does not find any device (which can play haptics) connected to the headset, or if the device does not support PCM haptic effect.

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_HANDLE_INVALID

  • XR_ERROR_INSTANCE_LOST

  • XR_ERROR_SESSION_LOST

  • XR_ERROR_PATH_UNSUPPORTED

  • XR_ERROR_PATH_INVALID

  • XR_ERROR_ACTION_TYPE_MISMATCH

  • XR_ERROR_ACTIONSET_NOT_ATTACHED

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

xrGetDisplayRefreshRateFB(3)

Name

xrGetDisplayRefreshRateFB - Get the current display refresh rate

C Specification

The xrGetDisplayRefreshRateFB function is defined as:

// Provided by XR_FB_display_refresh_rate
XrResult xrGetDisplayRefreshRateFB(
    XrSession                                   session,
    float*                                      displayRefreshRate);

Parameters

Parameter Descriptions
  • session is the XrSession to query.

  • displayRefreshRate is a pointer to a float into which the current display refresh rate will be placed.

Description

xrGetDisplayRefreshRateFB retrieves the current display refresh rate.

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

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

xrGetExportedLocalizationMapDataML(3)

Name

xrGetExportedLocalizationMapDataML - Returns the exported localization map data.

C Specification

The xrGetExportedLocalizationMapDataML function is defined as:

// Provided by XR_ML_localization_map
XrResult xrGetExportedLocalizationMapDataML(
    XrExportedLocalizationMapML                 map,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    char*                                       buffer);

Parameters

Parameter Descriptions
  • map is the map to export.

  • bufferCapacityInput is the capacity of the buffer array, or 0 to indicate a request to retrieve the required capacity.

  • bufferCountOutput is filled in by the runtime with the count of bytes written or the required capacity in the case that bufferCapacityInput is insufficient.

  • buffer is an array of bytes filled in by the runtime.

Description

xrGetExportedLocalizationMapDataML may take a long time to complete; as such applications should not call this from the frame loop.

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

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

xrGetEyeGazesFB(3)

Name

xrGetEyeGazesFB - Locate eye gaze directions

C Specification

The xrGetEyeGazesFB function is defined as:

// Provided by XR_FB_eye_tracking_social
XrResult xrGetEyeGazesFB(
    XrEyeTrackerFB                              eyeTracker,
    const XrEyeGazesInfoFB*                     gazeInfo,
    XrEyeGazesFB*                               eyeGazes);

Parameters

Parameter Descriptions

Description

The xrGetEyeGazesFB function obtains pose for a user’s eyes at a specific time and within a specific coordinate system.

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_TIME_INVALID

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

xrGetFaceExpressionWeights2FB(3)

Name

xrGetFaceExpressionWeights2FB - Obtain blend shapes of facial expression

C Specification

The xrGetFaceExpressionWeights2FB function is defined as:

// Provided by XR_FB_face_tracking2
XrResult xrGetFaceExpressionWeights2FB(
    XrFaceTracker2FB                            faceTracker,
    const XrFaceExpressionInfo2FB*              expressionInfo,
    XrFaceExpressionWeights2FB*                 expressionWeights);

Parameters

Parameter Descriptions

Description

The xrGetFaceExpressionWeights2FB function return blend shapes of facial expression at a given time.

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_TIME_INVALID

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

xrGetFaceExpressionWeightsFB(3)

Name

xrGetFaceExpressionWeightsFB - Obtain blend shapes of facial expression

C Specification

The xrGetFaceExpressionWeightsFB function return blend shapes of facial expression at a given time.

// Provided by XR_FB_face_tracking
XrResult xrGetFaceExpressionWeightsFB(
    XrFaceTrackerFB                             faceTracker,
    const XrFaceExpressionInfoFB*               expressionInfo,
    XrFaceExpressionWeightsFB*                  expressionWeights);

Parameters

Parameter Descriptions

Description

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_TIME_INVALID

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

xrGetFacialExpressionsHTC(3)

Name

xrGetFacialExpressionsHTC - Retrieve facial expressions

C Specification

The xrGetFacialExpressionsHTC function is defined as:

// Provided by XR_HTC_facial_tracking
XrResult xrGetFacialExpressionsHTC(
    XrFacialTrackerHTC                          facialTracker,
    XrFacialExpressionsHTC*                     facialExpressions);

Parameters

Parameter Descriptions

Description

xrGetFacialExpressionsHTC retrieves an array of values of blend shapes for a facial expression on a given time.

Valid Usage (Implicit)
Return Codes
On success, this command returns
  • XR_SUCCESS

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_TIME_INVALID

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

xrGetFoveationEyeTrackedStateMETA(3)

Name

xrGetFoveationEyeTrackedStateMETA - Get the current eye tracked foveation state

C Specification

The xrGetFoveationEyeTrackedStateMETA function is defined as:

// Provided by XR_META_foveation_eye_tracked
XrResult xrGetFoveationEyeTrackedStateMETA(
    XrSession                                   session,
    XrFoveationEyeTrackedStateMETA*             foveationState);

Parameters

Parameter Descriptions
  • session is the XrSession in which the eye tracked foveation profile is applied.

  • foveationState is a pointer to an XrFoveationEyeTrackedStateMETA structure returning the current eye tracked foveation state.

Description

The xrGetFoveationEyeTrackedStateMETA function returns the current eye tracked foveation state including the center of the foveal region, validity of the foveation data, etc.

Note that xrUpdateSwapchainFB should be called right before the xrGetFoveationEyeTrackedStateMETA function in order to (1) request a foveation pattern update by the runtime (2) optionally instruct the runtime to adjust the eye tracking camera capture start time in order to optimize for pipeline latency.

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_FEATURE_UNSUPPORTED

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

xrGetHandMeshFB(3)

Name

xrGetHandMeshFB - Create a foveation profile

C Specification

The xrGetHandMeshFB function is defined as:

// Provided by XR_FB_hand_tracking_mesh
XrResult xrGetHandMeshFB(
    XrHandTrackerEXT                            handTracker,
    XrHandTrackingMeshFB*                       mesh);

Parameters

Parameter Descriptions

Description

The xrGetHandMeshFB function populates an XrHandTrackingMeshFB structure with enough information to render a skinned mesh driven by the hand joints. As discussed in the specification for that structure, the data enumerated by this call is constant during the lifetime of an XrInstance.

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

  • XR_ERROR_FEATURE_UNSUPPORTED

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

xrGetInputSourceLocalizedName(3)

Name

xrGetInputSourceLocalizedName - Gets a localized source name

C Specification

The xrGetInputSourceLocalizedName function is defined as:

// Provided by XR_VERSION_1_0
XrResult xrGetInputSourceLocalizedName(
    XrSession                                   session,
    const XrInputSourceLocalizedNameGetInfo*    getInfo,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    char*                                       buffer);

Parameters

Parameter Descriptions
  • session is a handle to the XrSession associated with the action that reported this bound source.

  • getInfo is an XrInputSourceLocalizedNameGetInfo providing the query information.

  • bufferCapacityInput is the capacity of the buffer, or 0 to indicate a request to retrieve the required capacity.

  • bufferCountOutput is a pointer to the count of name characters written to buffer (including the terminating \0), or a pointer to the required capacity in the case that bufferCapacityInput is insufficient.

  • buffer is a pointer to an application-allocated buffer that will be filled with the bound source name. It can be NULL if bufferCapacityInput is 0.

  • See Buffer Size Parameters chapter for a detailed description of retrieving the required buffer size.

Description

xrGetInputSourceLocalizedName returns a string for the bound source in the current system locale.

If xrAttachSessionActionSets has not yet been called for the session, the runtime must return XR_ERROR_ACTIONSET_NOT_ATTACHED.

Valid Usage (Implicit)
  • session must be a valid XrSession handle

  • getInfo must be a pointer to a valid XrInputSourceLocalizedNameGetInfo structure

  • bufferCountOutput must be a pointer to a uint32_t value

  • If bufferCapacityInput is not 0, buffer must be a pointer to an array of bufferCapacityInput char values

Return Codes
On success, this command returns
  • XR_SUCCESS

  • XR_SESSION_LOSS_PENDING

On failure, this command returns
  • XR_ERROR_VALIDATION_FAILURE

  • XR_ERROR_RUNTIME_FAILURE

  • XR_ERROR_HANDLE_INVALID

  • XR_ERROR_INSTANCE_LOST

  • XR_ERROR_SESSION_LOST

  • XR_ERROR_SIZE_INSUFFICIENT

  • XR_ERROR_PATH_UNSUPPORTED

  • XR_ERROR_PATH_INVALID

  • XR_ERROR_ACTIONSET_NOT_ATTACHED

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

xrGetInstanceProcAddr(3)

Name

xrGetInstanceProcAddr - Gets a function pointer for an OpenXR function

C Specification

Function pointers for all OpenXR functions can be obtained with the function xrGetInstanceProcAddr.

// Provided by XR_VERSION_1_0
XrResult xrGetInstanceProcAddr(
    XrInstance                                  instance,
    const char*                                 name,
    PFN_xrVoidFunction*                         function);

Parameters

Parameter Descriptions
  • instance is the instance that the function pointer will be compatible with, or NULL for functions not dependent on any instance.

  • name is the name of the function to obtain.

  • function is the address of the function pointer to get.

Description

xrGetInstanceProcAddr itself is obtained in a platform- and loader- specific manner. Typically, the loader library will export this function as a function symbol, so applications can link against the loader library, or load it dynamically and look up the symbol using platform-specific APIs. Loaders must export function symbols for all core OpenXR functions. Because of this, applications that use only the core OpenXR functions have no need to use xrGetInstanceProcAddr.

Because an application can call xrGetInstanceProcAddr before creating an instance, xrGetInstanceProcAddr returns a valid function pointer when the instance parameter is XR_NULL_HANDLE and the name parameter is one of the following strings:

xrGetInstanceProcAddr must return XR_ERROR_HANDLE_INVALID if name is not one of the above strings and instance is XR_NULL_HANDLE. xrGetInstanceProcAddr may return XR_ERROR_HANDLE_INVALID if name is not one of the above strings and instance is invalid but not XR_NULL_HANDLE.

xrGetInstanceProcAddr must return XR_ERROR_FUNCTION_UNSUPPORTED if instance is a valid instance and the string specified in name is not the name of an OpenXR core or enabled extension function.

If name is the name of an extension function, then the result returned by xrGetInstanceProcAddr will depend upon how the instance was created. If instance was created with the related extension’s name appearing in the XrInstanceCreateInfo::enabledExtensionNames array, then xrGetInstanceProcAddr returns a valid function pointer. If the related extension’s name did not appear in the XrInstanceCreateInfo::enabledExtensionNames array during the creation of instance, then xrGetInstanceProcAddr returns XR_ERROR_FUNCTION_UNSUPPORTED. Because of this, function pointers returned by xrGetInstanceProcAddr using one XrInstance may not be valid when used with objects related to a different XrInstance.

The returned function pointer is of type PFN_xrVoidFunction, and must be cast to the type of the function being queried.

The table below defines the various use cases for xrGetInstanceProcAddr and return value (“fp” is “function pointer”) for each case.

Table 1. xrGetInstanceProcAddr behavior
instance parameter name parameter return value

*

NULL

undefined

invalid instance

*

undefined

NULL

xrEnumerateInstanceExtensionProperties

fp

NULL

xrEnumerateApiLayerProperties

fp

NULL

xrCreateInstance

fp

NULL

* (any name not covered above)

NULL

instance

core OpenXR function

fp1

instance

enabled extension function for instance

fp1

instance

* (any name not covered above)

NULL

1

The returned function pointer must only be called with a handle (the first parameter) that is instance or a child of instance.

Valid Usage (Implicit)
Return Codes
On success, this command returns
  • XR_SUCCESS

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_OUT_OF_MEMORY

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

xrGetInstanceProperties(3)

Name

xrGetInstanceProperties - Gets information about the instance

C Specification

The xrGetInstanceProperties function provides information about the instance and the associated runtime.

// Provided by XR_VERSION_1_0
XrResult xrGetInstanceProperties(
    XrInstance                                  instance,
    XrInstanceProperties*                       instanceProperties);

Parameters

Parameter Descriptions

Description

The instanceProperties parameter must be filled out by the runtime in response to this call, with information as defined in XrInstanceProperties.

Valid Usage (Implicit)
Return Codes
On success, this command returns
  • XR_SUCCESS

On failure, this command returns
  • XR_ERROR_VALIDATION_FAILURE

  • XR_ERROR_RUNTIME_FAILURE

  • XR_ERROR_HANDLE_INVALID

  • XR_ERROR_INSTANCE_LOST

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

xrGetMarkerDetectorStateML(3)

Name

xrGetMarkerDetectorStateML - Get the current state of the marker detector

C Specification

The xrGetMarkerDetectorStateML function is defined as:

// Provided by XR_ML_marker_understanding
XrResult xrGetMarkerDetectorStateML(
    XrMarkerDetectorML                          markerDetector,
    XrMarkerDetectorStateML*                    state);

Parameters

Parameter Descriptions
  • markerDetector object to retrieve state information from.

  • state points to an XrMarkerDetectorStateML in which the current state of the marker detector is returned.

Description

xrGetMarkerDetectorStateML is used after calling xrSnapshotMarkerDetectorML to check the current status of the snapshot in progress. When XrMarkerDetectorStateML::state == XR_MARKER_DETECTOR_STATUS_READY_ML, the detector is ready to be queried, while XR_MARKER_DETECTOR_STATUS_PENDING_ML indicates the snapshot is still in progress. XR_MARKER_DETECTOR_STATUS_ERROR_ML indicates that the runtime has encountered an error getting a snapshot for the requested detector, which may require user intervention to solve.

If xrSnapshotMarkerDetectorML has not yet been called for the markerDetector, the runtime must return XR_ERROR_CALL_ORDER_INVALID.

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_CALL_ORDER_INVALID

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

xrGetMarkerLengthML(3)

Name

xrGetMarkerLengthML - Query for the length of a marker

C Specification

The xrGetMarkerLengthML function is defined as:

// Provided by XR_ML_marker_understanding
XrResult xrGetMarkerLengthML(
    XrMarkerDetectorML                          markerDetector,
    XrMarkerML                                  marker,
    float*                                      meters);

Parameters

Parameter Descriptions
  • markerDetector is the detector object to retrieve marker information from.

  • marker is the marker atom to be examined.

  • meters points to a float in which the size per side of the queried marker is returned.

Description

Get the size of the marker, defined as the length in meters per side. If the application created the detector while passing in a XrMarkerDetectorSizeInfoML, this query may be redundant. xrGetMarkerLengthML is primarily intended to query for a runtime estimated size when an application did not indicate the expected size via XrMarkerDetectorSizeInfoML.

xrGetMarkerLengthML 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.

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

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_MARKER_INVALID_ML

  • XR_ERROR_CALL_ORDER_INVALID

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

xrGetMarkerNumberML(3)

Name

xrGetMarkerNumberML - Get the number of a marker, such as the ArUco ID.

C Specification

The xrGetMarkerNumberML function is defined as:

// Provided by XR_ML_marker_understanding
XrResult xrGetMarkerNumberML(
    XrMarkerDetectorML                          markerDetector,
    XrMarkerML                                  marker,
    uint64_t*                                   number);

Parameters

Parameter Descriptions
  • markerDetector is the detector object to retrieve marker information from.

  • marker is the marker atom to be examined.

  • number points to a float in which the numerical value associated with the marker is returned.

Description

Get the numerical value of a marker, such as the ArUco ID. xrGetMarkerNumberML must only be called when the state of the detector is XR_MARKER_DETECTOR_STATUS_READY_ML. If the marker does not have an associated numerical value, the runtime must return XR_ERROR_MARKER_DETECTOR_INVALID_DATA_QUERY_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.

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

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_MARKER_INVALID_ML

  • XR_ERROR_MARKER_DETECTOR_INVALID_DATA_QUERY_ML

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

xrGetMarkerReprojectionErrorML(3)

Name

xrGetMarkerReprojectionErrorML - Get the reprojection error of a marker.

C Specification

The xrGetMarkerReprojectionErrorML function is defined as:

// Provided by XR_ML_marker_understanding
XrResult xrGetMarkerReprojectionErrorML(
    XrMarkerDetectorML                          markerDetector,
    XrMarkerML                                  marker,
    float*                                      reprojectionErrorMeters);

Parameters

Parameter Descriptions
  • markerDetector is the detector object to retrieve marker information from.

  • marker is the marker atom to be examined.

  • reprojectionErrorMeters points to a float in which the estimated reprojection error in meters is returned.

Description

Get the reprojection error of a marker, only available for certain types of markers. 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.

A high reprojection error means that the estimated pose of the marker does not match well with the 2D detection on the processed video frame and thus the pose may be inaccurate. The error is given in meters, representing the displacement between real marker and its estimated pose. This means this is a normalized number, independent of marker distance or length.

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

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_MARKER_INVALID_ML

  • XR_ERROR_CALL_ORDER_INVALID

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

xrGetMarkerSizeVARJO(3)

Name

xrGetMarkerSizeVARJO - Gets physical size of marker

C Specification

The xrGetMarkerSizeVARJO function is defined as:

// Provided by XR_VARJO_marker_tracking
XrResult xrGetMarkerSizeVARJO(
    XrSession                                   session,
    uint64_t                                    markerId,
    XrExtent2Df*                                size);

Parameters

Parameter Descriptions
  • session is an XrSession handle previously created with xrCreateSession.

  • markerId is the unique identifier of the marker for which size is requested.

  • size is pointer to the size to populate by the runtime with the physical size of plane marker in meters.

Description

The xrGetMarkerSizeVARJO function retrieves the height and width of an active marker. The runtime must return XR_ERROR_MARKER_NOT_TRACKED_VARJO if marker tracking functionality is disabled or the marker with given markerId is inactive. The runtime must return XR_ERROR_MARKER_ID_INVALID_VARJO if the supplied markerId is invalid.

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_RUNTIME_FAILURE

  • XR_ERROR_HANDLE_INVALID

  • XR_ERROR_INSTANCE_LOST

  • XR_ERROR_SESSION_LOST

  • XR_ERROR_MARKER_NOT_TRACKED_VARJO

  • XR_ERROR_MARKER_ID_INVALID_VARJO

  • XR_ERROR_FEATURE_UNSUPPORTED

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

xrGetMarkerStringML(3)

Name

xrGetMarkerStringML - Get string information from detected marker

C Specification

The xrGetMarkerStringML function is defined as:

// Provided by XR_ML_marker_understanding
XrResult xrGetMarkerStringML(
    XrMarkerDetectorML                          markerDetector,
    XrMarkerML                                  marker,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    char*                                       buffer);

Parameters

Parameter Descriptions
  • markerDetector is the detector object to retrieve marker information from.

  • marker is the marker atom to be examined.

  • bufferCapacityInput is the capacity of the buffer, or 0 to indicate a request to retrieve the required capacity.

  • bufferCountOutput is a pointer to the count of characters written to buffer (including the terminating '\0'), or a pointer to the required capacity in the case that bufferCapacityInput is insufficient.

  • buffer is a pointer to an application-allocated buffer that should be filled with the QR code’s contents. It can be NULL if bufferCapacityInput is 0.

  • See the Buffer Size Parameters section for a detailed description of retrieving the required buffer size.

Description

Get the string value of a marker, such as the QR encoded string. xrCreateMarkerSpaceML must only be called when the state of the detector is XR_MARKER_DETECTOR_STATUS_READY_ML.

If the marker does not have an associated string value, the runtime must return XR_ERROR_MARKER_DETECTOR_INVALID_DATA_QUERY_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.

This function follows the two-call idiom for filling the buffer.

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

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_MARKER_INVALID_ML

  • XR_ERROR_MARKER_DETECTOR_INVALID_DATA_QUERY_ML

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

xrGetMarkersML(3)

Name

xrGetMarkersML - Examine marker detection snapshot

C Specification

The xrGetMarkersML function is defined as:

// Provided by XR_ML_marker_understanding
XrResult xrGetMarkersML(
    XrMarkerDetectorML                          markerDetector,
    uint32_t                                    markerCapacityInput,
    uint32_t*                                   markerCountOutput,
    XrMarkerML*                                 markers);

Parameters

Parameter Descriptions
  • markerDetector is the detector object to retrieve marker information from.

  • markerCapacityInput is the capacity of the markers array or 0 to indicate a request to retrieve the required capacity.

  • markerCountOutput is filled in by the runtime with the count of marker atoms written or the required capacity in the case that markerCapacityInput is insufficient.

  • markers is a pointer to an array of XrMarkerML atoms, but can be NULL if propertyCapacityInput is 0.

  • See the Buffer Size Parameters section for a detailed description of retrieving the required markers size.

Description

Get the list of current snapshotted marker atoms, 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.

The returned atoms are only valid while in the XR_MARKER_DETECTOR_STATUS_READY_ML state. The runtime must return the same atom value for the same uniquely identifiable marker across successive snapshots. It is unspecified what happens if the detector is observing two markers with the same identification patterns.

Assuming the same set of markers are in view across several snapshots, the runtime should return the same set of atoms. An application can use the list of atoms as a simple test for if a particular marker has gone in or out of view.

Note that XrMarkerML atoms are only usable with the XrMarkerDetectorML that returned them.

This function follows the two-call idiom for filling the markers.

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_CALL_ORDER_INVALID

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

xrGetOpenGLESGraphicsRequirementsKHR(3)

Name

xrGetOpenGLESGraphicsRequirementsKHR - Retrieve the OpenGL ES version requirements for an instance and system

C Specification

To query OpenGL ES API version requirements for an instance and system, call:

// Provided by XR_KHR_opengl_es_enable
XrResult xrGetOpenGLESGraphicsRequirementsKHR(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    XrGraphicsRequirementsOpenGLESKHR*          graphicsRequirements);

Parameters

Parameter Descriptions

Description

The xrGetOpenGLESGraphicsRequirementsKHR function identifies to the application the minimum OpenGL ES version requirement and the highest known tested OpenGL ES version. The runtime must return XR_ERROR_GRAPHICS_REQUIREMENTS_CALL_MISSING (XR_ERROR_VALIDATION_FAILURE may be returned due to legacy behavior) on calls to xrCreateSession if xrGetOpenGLESGraphicsRequirementsKHR has not been called for the same instance and systemId.

Valid Usage (Implicit)
Return Codes
On success, this command returns
  • XR_SUCCESS

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_SYSTEM_INVALID

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

xrGetOpenGLGraphicsRequirementsKHR(3)

Name

xrGetOpenGLGraphicsRequirementsKHR - Retrieve the OpenGL version requirements for an instance and system

C Specification

To query OpenGL API version requirements for an instance and system, call:

// Provided by XR_KHR_opengl_enable
XrResult xrGetOpenGLGraphicsRequirementsKHR(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    XrGraphicsRequirementsOpenGLKHR*            graphicsRequirements);

Parameters

Parameter Descriptions

Description

The xrGetOpenGLGraphicsRequirementsKHR function identifies to the application the minimum OpenGL version requirement and the highest known tested OpenGL version. The runtime must return XR_ERROR_GRAPHICS_REQUIREMENTS_CALL_MISSING (XR_ERROR_VALIDATION_FAILURE may be returned due to legacy behavior) on calls to xrCreateSession if xrGetOpenGLGraphicsRequirementsKHR has not been called for the same instance and systemId.

Valid Usage (Implicit)
Return Codes
On success, this command returns
  • XR_SUCCESS

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_SYSTEM_INVALID

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

xrGetPassthroughPreferencesMETA(3)

Name

xrGetPassthroughPreferencesMETA - Get passthrough preferences

C Specification

The xrGetPassthroughPreferencesMETA function is defined as:

// Provided by XR_META_passthrough_preferences
XrResult xrGetPassthroughPreferencesMETA(
    XrSession                                   session,
    XrPassthroughPreferencesMETA*               preferences);

Parameters

Parameter Descriptions

Description

An application can call xrGetPassthroughPreferencesMETA to retrieve passthrough-related preferences from the system.

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

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

xrGetPerformanceMetricsStateMETA(3)

Name

xrGetPerformanceMetricsStateMETA - Get current state of performance metrics

C Specification

The xrGetPerformanceMetricsStateMETA function is defined as:

// Provided by XR_META_performance_metrics
XrResult xrGetPerformanceMetricsStateMETA(
    XrSession                                   session,
    XrPerformanceMetricsStateMETA*              state);

Parameters

Parameter Descriptions

Description

The xrGetPerformanceMetricsStateMETA function gets the current state of the performance metrics system.

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_HANDLE_INVALID

  • XR_ERROR_INSTANCE_LOST

  • XR_ERROR_SESSION_LOST

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

xrGetPlaneDetectionStateEXT(3)

Name

xrGetPlaneDetectionStateEXT - Get the state of the plane detection pass

C Specification

The xrGetPlaneDetectionStateEXT function is defined as:

// Provided by XR_EXT_plane_detection
XrResult xrGetPlaneDetectionStateEXT(
    XrPlaneDetectorEXT                          planeDetector,
    XrPlaneDetectionStateEXT*                   state);

Parameters

Parameter Descriptions

Description

The xrGetPlaneDetectionStateEXT function retrieves the state of the plane query and must be called before calling xrGetPlaneDetectionsEXT.

If the plane detection has not yet finished state must be XR_PLANE_DETECTION_STATE_PENDING_EXT. If the plane detection has finished state must be XR_PLANE_DETECTION_STATE_DONE_EXT. If no plane detection was previously started XR_PLANE_DETECTION_STATE_NONE_EXT must be returned. For all three states the function must return XR_SUCCESS.

When a query error occurs the function must return XR_SUCCESS and the appropriate error state value must be set.

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

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

xrGetPlaneDetectionsEXT(3)

Name

xrGetPlaneDetectionsEXT - Get the detected planes

C Specification

The xrGetPlaneDetectionsEXT function is defined as:

// Provided by XR_EXT_plane_detection
XrResult xrGetPlaneDetectionsEXT(
    XrPlaneDetectorEXT                          planeDetector,
    const XrPlaneDetectorGetInfoEXT*            info,
    XrPlaneDetectorLocationsEXT*                locations);

Parameters

Parameter Descriptions

Description

xrGetPlaneDetectionsEXT must return XR_ERROR_CALL_ORDER_INVALID if the detector state reported by xrGetPlaneDetectionStateEXT is not XR_PLANE_DETECTION_STATE_DONE_EXT for the current query started by xrBeginPlaneDetectionEXT.

If the XrPlaneDetectorGetInfoEXT::baseSpace is not locatable XR_ERROR_SPACE_NOT_LOCATABLE_EXT must be returned.

Once xrBeginPlaneDetectionEXT is called again, the previous results for that handle are no longer available. The application should cache them before calling xrBeginPlaneDetectionEXT again if it needs access to that data while waiting for updated detection results.

Upon the completion of a detection cycle (xrBeginPlaneDetectionEXT, xrGetPlaneDetectionStateEXT to xrGetPlaneDetectionsEXT) the runtime must keep a snapshot of the plane data and no data may be modified. Calling xrGetPlaneDetectionsEXT multiple times with the same baseSpace and time must return the same plane pose data.

The current snapshot, if any, must be discarded upon calling xrBeginPlaneDetectionEXT.

If the XrEventDataReferenceSpaceChangePending is queued and the changeTime elapsed while the application is holding cached data the application may use the event data to adjusted poses accordingly.

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_TIME_INVALID

  • XR_ERROR_SPACE_NOT_LOCATABLE_EXT

  • XR_ERROR_CALL_ORDER_INVALID

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

xrGetPlanePolygonBufferEXT(3)

Name

xrGetPlanePolygonBufferEXT - Gets the plane

C Specification

The xrGetPlanePolygonBufferEXT function is defined as:

// Provided by XR_EXT_plane_detection
XrResult xrGetPlanePolygonBufferEXT(
    XrPlaneDetectorEXT                          planeDetector,
    uint64_t                                    planeId,
    uint32_t                                    polygonBufferIndex,
    XrPlaneDetectorPolygonBufferEXT*            polygonBuffer);

Parameters

Parameter Descriptions

Description

The xrGetPlanePolygonBufferEXT function retrieves the plane’s polygon buffer for the given planeId and polygonBufferIndex. Calling xrGetPlanePolygonBufferEXT with polygonBufferIndex equal to 0 must return the outside contour, if available. Calls with non-zero indices less than XrPlaneDetectorLocationEXT::polygonBufferCount must return polygons corresponding to holes in the plane. This feature may not be supported by all runtimes, check the XrSystemPlaneDetectionPropertiesEXT::supportedFeatures for support.

Outside contour polygon vertices must be ordered in counter clockwise order. Vertices of holes must be ordered in clockwise order. The right-hand rule is used to determine the direction of the normal of this plane. The polygon contour data is relative to the pose of the plane and coplanar with it.

This function only retrieves polygons, which means that it needs to be converted to a regular mesh to be rendered.

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

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

xrGetRecommendedLayerResolutionMETA(3)

Name

xrGetRecommendedLayerResolutionMETA - Get the recommended layer resolution for a layer from the runtime

C Specification

The xrGetRecommendedLayerResolutionMETA function is defined as:

// Provided by XR_META_recommended_layer_resolution
XrResult xrGetRecommendedLayerResolutionMETA(
    XrSession                                   session,
    const XrRecommendedLayerResolutionGetInfoMETA* info,
    XrRecommendedLayerResolutionMETA*           resolution);

Parameters

Parameter Descriptions

Description

The xrGetRecommendedLayerResolutionMETA function returns the recommendation that the runtime wishes to make to the application for the layer provided in the XrRecommendedLayerResolutionGetInfoMETA structure. Application may choose to reallocate their swapchain or scale view resolution accordingly. Applications rendering multiple views into the swapchain may scale individual views to match the recommended swapchain resolution.

The runtime may not wish to make any recommendation, in which case it must return an XrRecommendedLayerResolutionMETA::isValid value of XR_FALSE.

If the XrRecommendedLayerResolutionGetInfoMETA::layer attribute of the info argument of the function contains valid swapchain handles in all fields where required, the runtime must return a resolution recommendation which is less than or equal to the size of that swapchain, so that the application may render into an existing swapchain or swapchains without reallocation. As an exception to valid usage, an otherwise-valid structure passed as XrRecommendedLayerResolutionGetInfoMETA::layer may contain XR_NULL_HANDLE in place of valid XrSwapchain handle(s) for this function only, to obtain a recommended resolution resolution for the purpose of allocating a swapchain. If at least one otherwise-required XrSwapchain handle within XrRecommendedLayerResolutionGetInfoMETA::layer is XR_NULL_HANDLE, the runtime must interpret this as a request for recommended resolution without limitation to the allocated size of any existing swapchain.

If the runtime makes a recommendation, it should make a recommendation that is directly usable by the application to render its frames without creating adverse visual effects for the user.

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

xrGetReferenceSpaceBoundsRect(3)

Name

xrGetReferenceSpaceBoundsRect - Gets the bounds rectangle of a reference space

C Specification

XR systems may have limited real world spatial ranges in which users can freely move around while remaining tracked. Applications may wish to query these boundaries and alter application behavior or content placement to ensure the user can complete the experience while remaining within the boundary. Applications can query this information using xrGetReferenceSpaceBoundsRect.

When called, xrGetReferenceSpaceBoundsRect should return the extents of a rectangle that is clear of obstacles down to the floor, allowing where the user can freely move while remaining tracked, if available for that reference space. The returned extent represents the dimensions of an axis-aligned bounding box where the XrExtent2Df::width and XrExtent2Df::height fields correspond to the X and Z axes of the provided space, with the extents centered at the origin of the space. Not all systems or spaces may support boundaries. If a runtime is unable to provide bounds for a given space, XR_SPACE_BOUNDS_UNAVAILABLE will be returned and all fields of bounds will be set to 0.

The returned extents are expressed relative to the natural origin of the provided XrReferenceSpaceType and must not incorporate any origin offsets specified by the application during calls to xrCreateReferenceSpace.

The runtime must return XR_ERROR_REFERENCE_SPACE_UNSUPPORTED if the XrReferenceSpaceType passed in referenceSpaceType is not supported by this session.

When a runtime will begin operating with updated space bounds, the runtime must queue a corresponding XrEventDataReferenceSpaceChangePending event.

// Provided by XR_VERSION_1_0
XrResult xrGetReferenceSpaceBoundsRect(
    XrSession                                   session,
    XrReferenceSpaceType                        referenceSpaceType,
    XrExtent2Df*                                bounds);

Parameters

Parameter Descriptions
  • session is a handle to an XrSession previously created with xrCreateSession.

  • referenceSpaceType is the reference space type whose bounds should be retrieved.

  • bounds is the returned space extents.

Description

Valid Usage (Implicit)
Return Codes
On success, this command returns
  • XR_SUCCESS

  • XR_SESSION_LOSS_PENDING

  • XR_SPACE_BOUNDS_UNAVAILABLE

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_REFERENCE_SPACE_UNSUPPORTED

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

xrGetRenderModelPropertiesFB(3)

Name

xrGetRenderModelPropertiesFB - Get information for a render model

C Specification

The xrGetRenderModelPropertiesFB function is defined as:

// Provided by XR_FB_render_model
XrResult xrGetRenderModelPropertiesFB(
    XrSession                                   session,
    XrPath                                      path,
    XrRenderModelPropertiesFB*                  properties);

Parameters

Parameter Descriptions
  • session is the specified XrSession.

  • path is the path of the render model to get the properties for.

  • properties is a pointer to the XrRenderModelPropertiesFB to write the render model information to.

Description

xrGetRenderModelPropertiesFB is used for getting information for a render model using a path retrieved from xrEnumerateRenderModelPathsFB. The information returned will be for the connected device that corresponds to the path given. For example, using /model_fb/controller/left will return information for the left controller that is currently connected and will change if a different device that also represents a left controller is connected.

The runtime must return XR_ERROR_CALL_ORDER_INVALID if xrGetRenderModelPropertiesFB is called with render model paths before calling xrEnumerateRenderModelPathsFB. The runtime must return XR_ERROR_PATH_INVALID if a path not given by xrEnumerateRenderModelPathsFB is used.

If xrGetRenderModelPropertiesFB returns a success code of XR_RENDER_MODEL_UNAVAILABLE_FB and has a XrRenderModelPropertiesFB::modelKey of XR_NULL_RENDER_MODEL_KEY_FB, this indicates that the model for the device is unavailable. The application may keep calling xrGetRenderModelPropertiesFB because the model may become available later when a device is connected.

Valid Usage (Implicit)
Return Codes
On success, this command returns
  • XR_SUCCESS

  • XR_SESSION_LOSS_PENDING

  • XR_RENDER_MODEL_UNAVAILABLE_FB

On failure, this command returns
  • XR_ERROR_FUNCTION_UNSUPPORTED

  • XR_ERROR_VALIDATION_FAILURE

  • XR_ERROR_HANDLE_INVALID

  • XR_ERROR_INSTANCE_LOST

  • XR_ERROR_SESSION_LOST

  • XR_ERROR_OUT_OF_MEMORY

  • XR_ERROR_PATH_UNSUPPORTED

  • XR_ERROR_PATH_INVALID

  • XR_ERROR_CALL_ORDER_INVALID

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

xrGetSceneComponentsMSFT(3)

Name

xrGetSceneComponentsMSFT - Get scene components from a scene

C Specification

Scene components are read from an XrSceneMSFT using xrGetSceneComponentsMSFT and passing one XrSceneComponentTypeMSFT. This function follows the two-call idiom for filling multiple buffers in a struct. Different scene component types may have additional properties that can be read by chaining additional structures to XrSceneComponentsMSFT. Those additional structures must have an array size that is at least as large as XrSceneComponentsMSFT::componentCapacityInput, otherwise the runtime must return XR_ERROR_SIZE_INSUFFICIENT.

// Provided by XR_MSFT_scene_understanding
XrResult xrGetSceneComponentsMSFT(
    XrSceneMSFT                                 scene,
    const XrSceneComponentsGetInfoMSFT*         getInfo,
    XrSceneComponentsMSFT*                      components);

Parameters

Parameter Descriptions

Description

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_SIZE_INSUFFICIENT

  • XR_ERROR_SCENE_COMPONENT_TYPE_MISMATCH_MSFT

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

xrGetSceneComputeStateMSFT(3)

Name

xrGetSceneComputeStateMSFT - Get the scene compute state

C Specification

An application can inspect the completion of the compute by polling xrGetSceneComputeStateMSFT. This function should typically be called once per frame per XrSceneObserverMSFT.

// Provided by XR_MSFT_scene_understanding
XrResult xrGetSceneComputeStateMSFT(
    XrSceneObserverMSFT                         sceneObserver,
    XrSceneComputeStateMSFT*                    state);

Parameters

Parameter Descriptions

Description

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

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

xrGetSceneMarkerDecodedStringMSFT(3)

Name

xrGetSceneMarkerDecodedStringMSFT - Get the string encoded in the scene marker.

C Specification

The xrGetSceneMarkerDecodedStringMSFT function is defined as:

// Provided by XR_MSFT_scene_marker
XrResult xrGetSceneMarkerDecodedStringMSFT(
    XrSceneMSFT                                 scene,
    const XrUuidMSFT*                           markerId,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    char*                                       buffer);

Parameters

Parameter Descriptions
  • scene is an XrSceneMSFT previously created by xrCreateSceneMSFT.

  • markerId is an XrUuidMSFT identifying the marker, returned previously from XrSceneComponentMSFT::id when calling xrGetSceneComponentsMSFT.

  • bufferCapacityInput is the capacity of the string buffer, or 0 to indicate a request to retrieve the required capacity.

  • bufferCountOutput is a pointer to the count of characters written (including the terminating '\0'), or a pointer to the required capacity in the case that bufferCapacityInput is insufficient.

  • buffer is a pointer to an application-allocated buffer that will be filled with the string stored in the QR Code. It can be NULL if bufferCapacityInput is 0.

  • See Buffer Size Parameters chapter for a detailed description of retrieving the required buffer size.

Description

The xrGetSceneMarkerDecodedStringMSFT function retrieves the string stored in the scene marker as an UTF-8 string, including the terminating '\0'. This function follows the two-call idiom for filling the buffer array.

If the stored data in the marker is not an encoded string, the runtime must return the success code XR_SCENE_MARKER_DATA_NOT_STRING_MSFT, set bufferCountOutput to 1, and make buffer an empty string.

Valid Usage (Implicit)
Return Codes
On success, this command returns
  • XR_SUCCESS

  • XR_SESSION_LOSS_PENDING

  • XR_SCENE_MARKER_DATA_NOT_STRING_MSFT

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_SIZE_INSUFFICIENT

  • XR_ERROR_SCENE_COMPONENT_TYPE_MISMATCH_MSFT

  • XR_ERROR_SCENE_COMPONENT_ID_INVALID_MSFT

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

xrGetSceneMarkerRawDataMSFT(3)

Name

xrGetSceneMarkerRawDataMSFT - Get the data stored in the scene marker

C Specification

The xrGetSceneMarkerRawDataMSFT function is defined as:

// Provided by XR_MSFT_scene_marker
XrResult xrGetSceneMarkerRawDataMSFT(
    XrSceneMSFT                                 scene,
    const XrUuidMSFT*                           markerId,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    uint8_t*                                    buffer);

Parameters

Parameter Descriptions
  • scene is an XrSceneMSFT previously created by xrCreateSceneMSFT.

  • markerId is an XrUuidMSFT identifying the marker, and it is returned previous from XrSceneComponentMSFT when calling xrGetSceneComponentsMSFT.

  • bufferCapacityInput is the capacity of the buffer, or 0 to indicate a request to retrieve the required capacity.

  • bufferCountOutput is a pointer to the count of bytes written, or a pointer to the required capacity in the case that bufferCapacityInput is insufficient.

  • buffer is a pointer to an application-allocated buffer that will be filled with the data stored in the QR Code. It can be NULL if bufferCapacityInput is 0.

  • See Buffer Size Parameters chapter for a detailed description of retrieving the required buffer size.

Description

The xrGetSceneMarkerRawDataMSFT function retrieves the data stored in the scene marker.

Valid Usage (Implicit)
  • The XR_MSFT_scene_marker extension must be enabled prior to calling xrGetSceneMarkerRawDataMSFT

  • scene must be a valid XrSceneMSFT handle

  • markerId must be a pointer to a valid XrUuidMSFT structure

  • bufferCountOutput must be a pointer to a uint32_t value

  • If bufferCapacityInput is not 0, buffer must be a pointer to an array of bufferCapacityInput uint8_t values

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_SIZE_INSUFFICIENT

  • XR_ERROR_SCENE_COMPONENT_TYPE_MISMATCH_MSFT

  • XR_ERROR_SCENE_COMPONENT_ID_INVALID_MSFT

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

xrGetSceneMeshBuffersMSFT(3)

Name

xrGetSceneMeshBuffersMSFT - Get scene mesh buffers

C Specification

The xrGetSceneMeshBuffersMSFT function retrieves the scene mesh vertex buffer and index buffer for the given scene mesh buffer identifier.

Note

Applications may use the scene mesh buffer identifier as a key to cache the vertices and indices of a mesh for reuse within an XrSceneMSFT or across multiple XrSceneMSFT for the same XrSession.

Applications can avoid unnecessarily calling xrGetSceneMeshBuffersMSFT for a scene component if XrSceneComponentMSFT::updateTime is equal to the XrSceneComponentMSFT::updateTime value in the previous XrSceneMSFT. A scene component is uniquely identified by XrUuidMSFT.

This function follows the two-call idiom for filling multiple buffers in a struct.

The xrGetSceneMeshBuffersMSFT function is defined as:

// Provided by XR_MSFT_scene_understanding
XrResult xrGetSceneMeshBuffersMSFT(
    XrSceneMSFT                                 scene,
    const XrSceneMeshBuffersGetInfoMSFT*        getInfo,
    XrSceneMeshBuffersMSFT*                     buffers);

Parameters

Parameter Descriptions

Description

Applications can request the vertex buffer of the mesh by including XrSceneMeshVertexBufferMSFT in the XrSceneMeshBuffersMSFT::next chain. Runtimes must support requesting a 32-bit index buffer and may support requesting a 16-bit index buffer. Applications can request a 32-bit index buffer by including XrSceneMeshIndicesUint32MSFT in the XrSceneMeshBuffersMSFT::next chain. Applications can request a 16-bit index buffer by including XrSceneMeshIndicesUint16MSFT in the XrSceneMeshBuffersMSFT::next chain. If the runtime for the given scene mesh buffer does not support requesting a 16-bit index buffer then XR_ERROR_VALIDATION_FAILURE must be returned. The runtime must support reading a 16-bit index buffer for the given scene mesh buffer if XrScenePlaneMSFT:supportsIndicesUint16 or XrSceneMeshMSFT:supportsIndicesUint16 are XR_TRUE for the scene component that contained that scene mesh buffer identifier.

The runtime must return XR_ERROR_SCENE_MESH_BUFFER_ID_INVALID_MSFT if none of the scene components in the given XrSceneMSFT contain XrSceneMeshBuffersGetInfoMSFT::meshBufferId. The runtime must return XR_ERROR_SCENE_MESH_BUFFER_ID_INVALID_MSFT if XrSceneMeshBuffersGetInfoMSFT::meshBufferId is zero. The runtime must return XR_ERROR_VALIDATION_FAILURE if both XrSceneMeshIndicesUint32MSFT and XrSceneMeshIndicesUint16MSFT are included in the XrSceneMeshBuffersMSFT::next chain. The runtime must return XR_ERROR_VALIDATION_FAILURE if the XrSceneMeshBuffersMSFT::next does not contain at least one of XrSceneMeshVertexBufferMSFT, XrSceneMeshIndicesUint32MSFT or XrSceneMeshIndicesUint16MSFT.

The runtime must return the same vertices and indices for a given scene mesh buffer identifier and XrSession. A runtime may return zero vertices and indices if the underlying mesh data is no longer available.

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_SCENE_MESH_BUFFER_ID_INVALID_MSFT

  • XR_ERROR_SCENE_COMPONENT_ID_INVALID_MSFT

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

xrGetSerializedSceneFragmentDataMSFT(3)

Name

xrGetSerializedSceneFragmentDataMSFT - Get serialized scene fragment data

C Specification

The application can call the xrGetSerializedSceneFragmentDataMSFT function to read the binary data of a serialized scene fragment from the XrSceneMSFT handle. This function follows the two-call idiom for filling the buffer.