OpenXR API Reference Pages

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

OpenXR Commands

xrAcquireSwapchainImage(3)

Name

xrAcquireSwapchainImage - Acquire a swapchain image

C Specification

The xrAcquireSwapchainImage function is defined as:

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.

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

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

xrApplyHapticFeedback(3)

Name

xrApplyHapticFeedback - Apply haptic feedback

C Specification

The xrApplyHapticFeedback function is defined as:

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_TYPE_HAPTIC_VIBRATION. 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)

session must be a valid XrSession handle
hapticActionInfo must be a pointer to a valid XrHapticActionInfo structure
hapticFeedback must be a pointer to a valid XrHapticBaseHeader-based structure. See also: XrHapticVibration

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

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

xrAttachSessionActionSets(3)

Name

xrAttachSessionActionSets - Attaches action sets to a given session

C Specification

The xrAttachSessionActionSets function is defined as:

XrResult xrAttachSessionActionSets(
    XrSession                                   session,
    const XrSessionActionSetsAttachInfo*        attachInfo);

Parameters

Parameter Descriptions

session is the XrSession to attach the action sets to.
attachInfo is the XrSessionActionSetsAttachInfo to provide information to attach action sets to the session.

Description

xrAttachSessionActionSets attaches the XrActionSet handles in attachInfo.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)

session must be a valid XrSession handle
attachInfo must be a pointer to a valid XrSessionActionSetsAttachInfo structure

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

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

xrBeginFrame(3)

Name

xrBeginFrame - Marks a frame

C Specification

The xrBeginFrame function is defined as:

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.

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.

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

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

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

xrBeginSession(3)

Name

xrBeginSession - Begins an XrSession

C Specification

The xrBeginSession function is defined as:

XrResult xrBeginSession(
    XrSession                                   session,
    const XrSessionBeginInfo*                   beginInfo);

Parameters

Parameter Descriptions

session is a valid XrSession handle.
beginInfo is a pointer to an XrSessionBeginInfo structure.

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 an XrFrameState with 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.

If 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)

session must be a valid XrSession handle
beginInfo must be a pointer to a valid XrSessionBeginInfo structure

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

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

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.

XrResult xrClearSpatialAnchorStoreMSFT(
    XrSpatialAnchorStoreConnectionMSFT          spatialAnchorStore);

Parameters

Parameter Descriptions

spatialAnchorStore is XrSpatialAnchorStoreConnectionMSFT to perform the clear operation on.

Description

Valid Usage (Implicit)

The [XR_MSFT_spatial_anchor_persistence] extension must be enabled prior to calling xrClearSpatialAnchorStoreMSFT
spatialAnchorStore must be a valid XrSpatialAnchorStoreConnectionMSFT handle

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

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

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.

XrResult xrComputeNewSceneMSFT(
    XrSceneObserverMSFT                         sceneObserver,
    const XrNewSceneComputeInfoMSFT*            computeInfo);

Parameters

Parameter Descriptions

sceneObserver is a handle to an XrSceneObserverMSFT.
computeInfo is a pointer to an XrNewSceneComputeInfoMSFT structure.

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:
- XR_SCENE_COMPUTE_CONSISTENCY_OCCLUSION_OPTIMIZED_MSFT is passed to xrComputeNewSceneMSFT and
- a previous call to xrComputeNewSceneMSFT did not pass XR_SCENE_COMPUTE_CONSISTENCY_OCCLUSION_OPTIMIZED_MSFT for the same XrSceneObserverMSFT handle.
The runtime must return XR_ERROR_SCENE_COMPUTE_CONSISTENCY_MISMATCH_MSFT if:
- XR_SCENE_COMPUTE_CONSISTENCY_OCCLUSION_OPTIMIZED_MSFT is not passed to xrComputeNewSceneMSFT and
- a previous call to xrComputeNewSceneMSFT did pass XR_SCENE_COMPUTE_CONSISTENCY_OCCLUSION_OPTIMIZED_MSFT for the same XrSceneObserverMSFT handle.
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)

The [XR_MSFT_scene_understanding] extension must be enabled prior to calling xrComputeNewSceneMSFT
sceneObserver must be a valid XrSceneObserverMSFT handle
computeInfo must be a pointer to a valid XrNewSceneComputeInfoMSFT structure

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

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

xrConvertTimeToTimespecTimeKHR(3)

Name

xrConvertTimeToTimespecTimeKHR - Convert XrTime to timespec monotonic time

C Specification

To convert from XrTime to timespec monotonic time, call:

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.
unixTime 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 unixTime cannot represent the input time, the runtime must return XR_ERROR_TIME_INVALID.

Valid Usage (Implicit)

The [XR_KHR_convert_timespec_time] extension must be enabled prior to calling xrConvertTimeToTimespecTimeKHR
instance must be a valid XrInstance handle
timespecTime must be a pointer to a timespec value

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

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

xrConvertTimeToWin32PerformanceCounterKHR(3)

Name

xrConvertTimeToWin32PerformanceCounterKHR - Convert XrTime to Win32 QueryPerformanceCounter time

C Specification

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

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)

The [XR_KHR_win32_convert_performance_counter_time] extension must be enabled prior to calling xrConvertTimeToWin32PerformanceCounterKHR
instance must be a valid XrInstance handle
performanceCounter must be a pointer to a LARGE_INTEGER value

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

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

xrConvertTimespecTimeToTimeKHR(3)

Name

xrConvertTimespecTimeToTimeKHR - Convert timespec monotonic time to XrTime

C Specification

To convert from timespec monotonic time to XrTime, call:

XrResult xrConvertTimespecTimeToTimeKHR(
    XrInstance                                  instance,
    const struct timespec*                      timespecTime,
    XrTime*                                     time);

Parameters

Parameter Descriptions

instance is an XrInstance handle previously created with xrCreateInstance.
unixTime is a timespec obtained from clock_gettime with CLOCK_MONOTONIC.
time is the resulting XrTime that is equivalent to the unixTime.

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 unixTime, the runtime must return XR_ERROR_TIME_INVALID.

Valid Usage (Implicit)

The [XR_KHR_convert_timespec_time] extension must be enabled prior to calling xrConvertTimespecTimeToTimeKHR
instance must be a valid XrInstance handle
timespecTime must be a pointer to a valid timespec value
time must be a pointer to an XrTime value

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

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

xrConvertWin32PerformanceCounterToTimeKHR(3)

Name

xrConvertWin32PerformanceCounterToTimeKHR - Convert Win32 QueryPerformanceCounter time to XrTime

C Specification

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

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)

The [XR_KHR_win32_convert_performance_counter_time] extension must be enabled prior to calling xrConvertWin32PerformanceCounterToTimeKHR
instance must be a valid XrInstance handle
performanceCounter must be a pointer to a valid LARGE_INTEGER value
time must be a pointer to an XrTime value

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

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

xrCreateAction(3)

Name

xrCreateAction - Creates an XrAction

C Specification

The xrCreateAction function is defined as:

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)

actionSet must be a valid XrActionSet handle
createInfo must be a pointer to a valid XrActionCreateInfo structure
action must be a pointer to an XrAction handle

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

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

xrCreateActionSet(3)

Name

xrCreateActionSet - Creates an XrActionSet

C Specification

The xrCreateActionSet function is defined as:

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)

instance must be a valid XrInstance handle
createInfo must be a pointer to a valid XrActionSetCreateInfo structure
actionSet must be a pointer to an XrActionSet handle

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

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

xrCreateActionSpace(3)

Name

xrCreateActionSpace - Creates a space based on a pose action

C Specification

The xrCreateActionSpace function is defined as:

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 action is not of type XR_ACTION_TYPE_POSE_INPUT.

Valid Usage (Implicit)

session must be a valid XrSession handle
createInfo must be a pointer to a valid XrActionSpaceCreateInfo structure
space must be a pointer to an XrSpace handle

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

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

xrCreateDebugUtilsMessengerEXT(3)

Name

xrCreateDebugUtilsMessengerEXT - Creates a debug messenger

C Specification

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)

The [XR_EXT_debug_utils] extension must be enabled prior to calling xrCreateDebugUtilsMessengerEXT
instance must be a valid XrInstance handle
createInfo must be a pointer to a valid XrDebugUtilsMessengerCreateInfoEXT structure
messenger must be a pointer to an XrDebugUtilsMessengerEXT handle

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 createInfo->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

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

xrCreateFoveationProfileFB(3)

Name

xrCreateFoveationProfileFB - Create a foveation profile

C Specification

The xrCreateFoveationProfileFB function is defined as:

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)

The [XR_FB_foveation] extension must be enabled prior to calling xrCreateFoveationProfileFB
session must be a valid XrSession handle
createInfo must be a pointer to a valid XrFoveationProfileCreateInfoFB structure
profile must be a pointer to an XrFoveationProfileFB handle

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

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

xrCreateGeometryInstanceFB(3)

Name

xrCreateGeometryInstanceFB - Create a triangle mesh

C Specification

The xrCreateGeometryInstanceFB function is defined as:

XrResult xrCreateGeometryInstanceFB(
    XrSession                                   session,
    const XrGeometryInstanceCreateInfoFB*       createInfo,
    XrGeometryInstanceFB*                       outGeometryInstance);

Parameters

Parameter Descriptions

session is the XrSession.
createInfo is the XrGeometryInstanceCreateInfoFB.
outGeometryInstance is the XrGeometryInstanceFB.

Description

Creates an XrGeometryInstanceFB handle. Geometry instance functionality requires https://www.khronos.org/registry/OpenXR/specs/1.0/html/xrspec.html#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)

The [XR_FB_passthrough] extension must be enabled prior to calling xrCreateGeometryInstanceFB
session must be a valid XrSession handle
createInfo must be a pointer to a valid XrGeometryInstanceCreateInfoFB structure
outGeometryInstance must be a pointer to an XrGeometryInstanceFB handle

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

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

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.

XrResult xrCreateHandMeshSpaceMSFT(
    XrHandTrackerEXT                            handTracker,
    const XrHandMeshSpaceCreateInfoMSFT*        createInfo,
    XrSpace*                                    space);

Parameters

Parameter Descriptions

handTracker is an XrHandTrackerEXT handle previously created with the xrCreateHandTrackerEXT function.
createInfo is the XrHandMeshSpaceCreateInfoMSFT used to specify the hand mesh space.
space is the returned XrSpace handle of the new hand mesh space.

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 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)

The [XR_MSFT_hand_tracking_mesh] extension must be enabled prior to calling xrCreateHandMeshSpaceMSFT
handTracker must be a valid XrHandTrackerEXT handle
createInfo must be a pointer to a valid XrHandMeshSpaceCreateInfoMSFT structure
space must be a pointer to an XrSpace handle

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

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

xrCreateHandTrackerEXT(3)

Name

xrCreateHandTrackerEXT - Create a hand joints handle.

C Specification

An application can create an XrHandTrackerEXT handle using xrCreateHandTrackerEXT function.

XrResult xrCreateHandTrackerEXT(
    XrSession                                   session,
    const XrHandTrackerCreateInfoEXT*           createInfo,
    XrHandTrackerEXT*                           handTracker);

Parameters

Parameter Descriptions

session is an XrSession in which the hand tracker will be active.
createInfo is the XrHandTrackerCreateInfoEXT used to specify the hand tracker.
handTracker is the returned XrHandTrackerEXT handle.

Description

Valid Usage (Implicit)

The [XR_EXT_hand_tracking] extension must be enabled prior to calling xrCreateHandTrackerEXT
session must be a valid XrSession handle
createInfo must be a pointer to a valid XrHandTrackerCreateInfoEXT structure
handTracker must be a pointer to an XrHandTrackerEXT handle

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 supportsHandTracking in XrSystemHandTrackingPropertiesEXT 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

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

xrCreateInstance(3)

Name

xrCreateInstance - Creates an OpenXR Instance

C Specification

The xrCreateInstance function is defined as:

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)

createInfo must be a pointer to a valid XrInstanceCreateInfo structure
instance must be a pointer to an XrInstance handle

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

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

xrCreateMarkerSpaceVARJO(3)

Name

xrCreateMarkerSpaceVARJO - Creates marker space

C Specification

The xrCreateMarkerSpaceVARJO function is defined as:

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 markerId is invalid.

Valid Usage (Implicit)

The [XR_VARJO_marker_tracking] extension must be enabled prior to calling xrCreateMarkerSpaceVARJO
session must be a valid XrSession handle
createInfo must be a pointer to a valid XrMarkerSpaceCreateInfoVARJO structure
space must be a pointer to an XrSpace handle

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

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

xrCreatePassthroughFB(3)

Name

xrCreatePassthroughFB - Create a passthrough feature

C Specification

The xrCreatePassthroughFB function is defined as:

XrResult xrCreatePassthroughFB(
    XrSession                                   session,
    const XrPassthroughCreateInfoFB*            createInfo,
    XrPassthroughFB*                            outPassthrough);

Parameters

Parameter Descriptions

session is the XrSession.
createInfo is the XrPassthroughCreateInfoFB.
outPassthrough is the XrPassthroughFB.

Description

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

Valid Usage (Implicit)

The [XR_FB_passthrough] extension must be enabled prior to calling xrCreatePassthroughFB
session must be a valid XrSession handle
createInfo must be a pointer to a valid XrPassthroughCreateInfoFB structure
outPassthrough must be a pointer to an XrPassthroughFB handle

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

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

xrCreatePassthroughLayerFB(3)

Name

xrCreatePassthroughLayerFB - Create a passthrough layer

C Specification

The xrCreatePassthroughLayerFB function is defined as:

XrResult xrCreatePassthroughLayerFB(
    XrSession                                   session,
    const XrPassthroughLayerCreateInfoFB*       createInfo,
    XrPassthroughLayerFB*                       outLayer);

Parameters

Parameter Descriptions

session is the XrSession.
createInfo is the XrPassthroughLayerCreateInfoFB.
outLayer is the XrPassthroughLayerFB.

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)

The [XR_FB_passthrough] extension must be enabled prior to calling xrCreatePassthroughLayerFB
session must be a valid XrSession handle
createInfo must be a pointer to a valid XrPassthroughLayerCreateInfoFB structure
outLayer must be a pointer to an XrPassthroughLayerFB handle

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

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

xrCreateReferenceSpace(3)

Name

xrCreateReferenceSpace - Creates a reference space

C Specification

The xrCreateReferenceSpace function is defined as:

XrResult xrCreateReferenceSpace(
    XrSession                                   session,
    const XrReferenceSpaceCreateInfo*           createInfo,
    XrSpace*                                    space);

Parameters

Parameter Descriptions

session is a handle to an XrSession previously created with xrCreateSession.
createInfo is the XrReferenceSpaceCreateInfo used to specify the space.
space is the returned space handle.

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)

session must be a valid XrSession handle
createInfo must be a pointer to a valid XrReferenceSpaceCreateInfo structure
space must be a pointer to an XrSpace handle

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

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

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.

XrResult xrCreateSceneMSFT(
    XrSceneObserverMSFT                         sceneObserver,
    const XrSceneCreateInfoMSFT*                createInfo,
    XrSceneMSFT*                                scene);

Parameters

Parameter Descriptions

sceneObserver is a handle to an XrSceneObserverMSFT.
createInfo exists for extensibility purposes, it is NULL or a pointer to a valid XrSceneCreateInfoMSFT structure.
scene is the returned XrSceneMSFT handle.

Description

Valid Usage (Implicit)

The [XR_MSFT_scene_understanding] extension must be enabled prior to calling xrCreateSceneMSFT
sceneObserver must be a valid XrSceneObserverMSFT handle
If createInfo is not NULL, createInfo must be a pointer to a valid XrSceneCreateInfoMSFT structure
scene must be a pointer to an XrSceneMSFT handle

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

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

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

xrCreateSceneObserverMSFT(3)

Name

xrCreateSceneObserverMSFT - Create a scene observer handle

C Specification

An XrSceneObserverMSFT handle is created using xrCreateSceneObserverMSFT.

XrResult xrCreateSceneObserverMSFT(
    XrSession                                   session,
    const XrSceneObserverCreateInfoMSFT*        createInfo,
    XrSceneObserverMSFT*                        sceneObserver);

Parameters

Parameter Descriptions

session is an XrSession in which the scene observer will be active.
createInfo exists for extensibility purposes, it is NULL or a pointer to a valid XrSceneObserverCreateInfoMSFT structure.
sceneObserver is the returned XrSceneObserverMSFT handle.

Description

Valid Usage (Implicit)

The [XR_MSFT_scene_understanding] extension must be enabled prior to calling xrCreateSceneObserverMSFT
session must be a valid XrSession handle
If createInfo is not NULL, createInfo must be a pointer to a valid XrSceneObserverCreateInfoMSFT structure
sceneObserver must be a pointer to an XrSceneObserverMSFT handle

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

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

xrCreateSession(3)

Name

xrCreateSession - Creates an XrSession

C Specification

The xrCreateSession function is defined as:

XrResult xrCreateSession(
    XrInstance                                  instance,
    const XrSessionCreateInfo*                  createInfo,
    XrSession*                                  session);

Parameters

Parameter Descriptions

instance is the instance from which 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)

instance must be a valid XrInstance handle
createInfo must be a pointer to a valid XrSessionCreateInfo structure
session must be a pointer to an XrSession handle

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

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

xrCreateSpatialAnchorFromPerceptionAnchorMSFT(3)

Name

xrCreateSpatialAnchorFromPerceptionAnchorMSFT - Create an XrSpatialAnchorMSFT from a Windows SpatialAnchor pointer

C Specification

The xrCreateSpatialAnchorFromPerceptionAnchorMSFT function creates a XrSpatialAnchorMSFT handle from an IUnknown pointer to Windows.Perception.Spatial.SpatialAnchor.

XrResult xrCreateSpatialAnchorFromPerceptionAnchorMSFT(
    XrSession                                   session,
    IUnknown*                                   perceptionAnchor,
    XrSpatialAnchorMSFT*                        anchor);

Parameters

Parameter Descriptions

session is the specified XrSession.
perceptionAnchor is an IUnknown pointer to a Windows.Perception.Spatial.SpatialAnchor object.
anchor is a pointer to XrSpatialAnchorMSFT to receive the returned anchor handle.

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)

The [XR_MSFT_perception_anchor_interop] extension must be enabled prior to calling xrCreateSpatialAnchorFromPerceptionAnchorMSFT
session must be a valid XrSession handle
perceptionAnchor must be a pointer to an IUnknown value
anchor must be a pointer to an XrSpatialAnchorMSFT handle

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

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

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 spatialAnchorName 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.

XrResult xrCreateSpatialAnchorFromPersistedNameMSFT(
    XrSession                                   session,
    const XrSpatialAnchorFromPersistedAnchorCreateInfoMSFT* spatialAnchorCreateInfo,
    XrSpatialAnchorMSFT*                        spatialAnchor);

Parameters

Parameter Descriptions

session is a handle to an XrSession previously created with xrCreateSession.
spatialAnchorCreateInfo is a pointer to the XrSpatialAnchorFromPersistedAnchorCreateInfoMSFT.
spatialAnchor is a pointer to an XrSpatialAnchorMSFT handle that will be set by the runtime on successful load.

Description

Valid Usage (Implicit)

The [XR_MSFT_spatial_anchor_persistence] extension must be enabled prior to calling xrCreateSpatialAnchorFromPersistedNameMSFT
session must be a valid XrSession handle
spatialAnchorCreateInfo must be a pointer to a valid XrSpatialAnchorFromPersistedAnchorCreateInfoMSFT structure
spatialAnchor must be a pointer to an XrSpatialAnchorMSFT handle

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

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

xrCreateSpatialAnchorMSFT(3)

Name

xrCreateSpatialAnchorMSFT - Creates a spatial anchor

C Specification

The xrCreateSpatialAnchorMSFT function is defined as:

XrResult xrCreateSpatialAnchorMSFT(
    XrSession                                   session,
    const XrSpatialAnchorCreateInfoMSFT*        createInfo,
    XrSpatialAnchorMSFT*                        anchor);

Parameters

Parameter Descriptions

session is a handle to an XrSession.
createInfo is a pointer to an XrSpatialAnchorCreateInfoMSFT structure containing information about how to create the anchor.
anchor is a pointer to a handle in which the created XrSpatialAnchorMSFT is returned.

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 pose within space at time.

If 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 space used to initialize it.

Valid Usage (Implicit)

The [XR_MSFT_spatial_anchor] extension must be enabled prior to calling xrCreateSpatialAnchorMSFT
session must be a valid XrSession handle
createInfo must be a pointer to a valid XrSpatialAnchorCreateInfoMSFT structure
anchor must be a pointer to an XrSpatialAnchorMSFT handle

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

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

xrCreateSpatialAnchorSpaceMSFT(3)

Name

xrCreateSpatialAnchorSpaceMSFT - Creates a space from a spatial anchor

C Specification

The xrCreateSpatialAnchorSpaceMSFT function is defined as:

XrResult xrCreateSpatialAnchorSpaceMSFT(
    XrSession                                   session,
    const XrSpatialAnchorSpaceCreateInfoMSFT*   createInfo,
    XrSpace*                                    space);

Parameters

Parameter Descriptions

session is a handle to an XrSession.
createInfo is a pointer to an XrSpatialAnchorSpaceCreateInfoMSFT structure containing information about how to create the anchor.
space is a pointer to a handle in which the created XrSpace is returned.

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)

The [XR_MSFT_spatial_anchor] extension must be enabled prior to calling xrCreateSpatialAnchorSpaceMSFT
session must be a valid XrSession handle
createInfo must be a pointer to a valid XrSpatialAnchorSpaceCreateInfoMSFT structure
space must be a pointer to an XrSpace handle

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

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

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.

XrResult xrCreateSpatialAnchorStoreConnectionMSFT(
    XrSession                                   session,
    XrSpatialAnchorStoreConnectionMSFT*         spatialAnchorStore);

Parameters

Parameter Descriptions

session is the XrSession the anchor was created with.
spatialAnchorStore is a pointer to the XrSpatialAnchorStoreConnectionMSFT handle.

Description

Valid Usage (Implicit)

The [XR_MSFT_spatial_anchor_persistence] extension must be enabled prior to calling xrCreateSpatialAnchorStoreConnectionMSFT
session must be a valid XrSession handle
spatialAnchorStore must be a pointer to an XrSpatialAnchorStoreConnectionMSFT handle

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

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

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.

XrResult xrCreateSpatialGraphNodeSpaceMSFT(
    XrSession                                   session,
    const XrSpatialGraphNodeSpaceCreateInfoMSFT* createInfo,
    XrSpace*                                    space);

Parameters

Parameter Descriptions

session is the XrSession which will use the created space.
createInfo is an XrSpatialGraphNodeSpaceCreateInfoMSFT specifying the space to be created.
space is the returned XrSpace handle for the given spatial node ID.

Description

Valid Usage (Implicit)

The [XR_MSFT_spatial_graph_bridge] extension must be enabled prior to calling xrCreateSpatialGraphNodeSpaceMSFT
session must be a valid XrSession handle
createInfo must be a pointer to a valid XrSpatialGraphNodeSpaceCreateInfoMSFT structure
space must be a pointer to an XrSpace handle

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

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

xrCreateSwapchain(3)

Name

xrCreateSwapchain - Creates an XrSwapchain

C Specification

The xrCreateSwapchain function is defined as:

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 flags specified in the XrSwapchainCreateInfo is unsupported.

Valid Usage (Implicit)

session must be a valid XrSession handle
createInfo must be a pointer to a valid XrSwapchainCreateInfo structure
swapchain must be a pointer to an XrSwapchain handle

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

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

xrCreateSwapchainAndroidSurfaceKHR(3)

Name

xrCreateSwapchainAndroidSurfaceKHR - Creates a swapchain and an Android Surface

C Specification

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

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

The XrSwapchainCreateInfo::format,
XrSwapchainCreateInfo::sampleCount,
XrSwapchainCreateInfo::faceCount,
XrSwapchainCreateInfo::arraySize and
XrSwapchainCreateInfo::mipCount
members of the structure passed as the info parameter must be zero.

Valid Usage (Implicit)

The [XR_KHR_android_surface_swapchain] extension must be enabled prior to calling xrCreateSwapchainAndroidSurfaceKHR
session must be a valid XrSession handle
info must be a pointer to a valid XrSwapchainCreateInfo structure
swapchain must be a pointer to an XrSwapchain handle
surface must be a pointer to a jobject value

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

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

xrCreateTriangleMeshFB(3)

Name

xrCreateTriangleMeshFB - Create a triangle mesh

C Specification

The xrCreateTriangleMeshFB function is defined as:

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.

Valid Usage (Implicit)

The [XR_FB_triangle_mesh] extension must be enabled prior to calling xrCreateTriangleMeshFB
session must be a valid XrSession handle
createInfo must be a pointer to a valid XrTriangleMeshCreateInfoFB structure
outTriangleMesh must be a pointer to an XrTriangleMeshFB handle

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

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

xrCreateVulkanDeviceKHR(3)

Name

xrCreateVulkanDeviceKHR - Create an OpenXR compatible VkDevice

C Specification

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 pfnGetInstanceProcAddr.

Description

Valid Usage (Implicit)

The [XR_KHR_vulkan_enable2] extension must be enabled prior to calling xrCreateVulkanDeviceKHR
instance must be a valid XrInstance handle
createInfo must be a pointer to a valid XrVulkanDeviceCreateInfoKHR structure
vulkanDevice must be a pointer to a VkDevice value
vulkanResult must be a pointer to a VkResult value

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

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

xrCreateVulkanInstanceKHR(3)

Name

xrCreateVulkanInstanceKHR - Create an OpenXR compatible VkInstance

C Specification

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

Parameters

Parameter Descriptions

instance is an XrInstance handle previously created with xrCreateInstance.
createInfo extensible input struct of type XrCreateVulkanInstanceCreateInfoKHR
vulkanInstance points to a VkInstance handle to populate with the new Vulkan instance.
vulkanResult points to a VkResult to populate with the result of the vkCreateInstance operation as returned by pfnGetInstanceProcAddr.

Description

Valid Usage (Implicit)

The [XR_KHR_vulkan_enable2] extension must be enabled prior to calling xrCreateVulkanInstanceKHR
instance must be a valid XrInstance handle
createInfo must be a pointer to a valid XrVulkanInstanceCreateInfoKHR structure
vulkanInstance must be a pointer to a VkInstance value
vulkanResult must be a pointer to a VkResult value

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

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

xrDeserializeSceneMSFT(3)

Name

xrDeserializeSceneMSFT - Deserialize scene

C Specification

The xrDeserializeSceneMSFT function is defined as:

XrResult xrDeserializeSceneMSFT(
    XrSceneObserverMSFT                         sceneObserver,
    const XrSceneDeserializeInfoMSFT*           deserializeInfo);

Parameters

Parameter Descriptions

sceneObserver is a handle to an XrSceneObserverMSFT previously created with xrCreateSceneObserverMSFT.
deserializeInfo is a pointer to an XrSceneDeserializeInfoMSFT structure.

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 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)

The [XR_MSFT_scene_understanding_serialization] extension must be enabled prior to calling xrDeserializeSceneMSFT
sceneObserver must be a valid XrSceneObserverMSFT handle
deserializeInfo must be a pointer to a valid XrSceneDeserializeInfoMSFT structure

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

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

xrDestroyAction(3)

Name

xrDestroyAction - Destroys an XrAction

C Specification

The xrDestroyAction function is defined as:

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

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

xrDestroyActionSet(3)

Name

xrDestroyActionSet - Destroys an XrActionSet

C Specification

The xrDestroyActionSet function is defined as:

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)

actionSet must be a valid XrActionSet handle

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

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

xrDestroyDebugUtilsMessengerEXT(3)

Name

xrDestroyDebugUtilsMessengerEXT - Destroys a debug messenger

C Specification

XrResult xrDestroyDebugUtilsMessengerEXT(
    XrDebugUtilsMessengerEXT                    messenger);

Parameters

Parameter Descriptions

messenger the XrDebugUtilsMessengerEXT object to destroy. messenger is an externally synchronized object and must not be used on more than one thread at a time. This means that xrDestroyDebugUtilsMessengerEXT must not be called when a callback is active.

Description

Valid Usage (Implicit)

The [XR_EXT_debug_utils] extension must be enabled prior to calling xrDestroyDebugUtilsMessengerEXT
messenger must be a valid XrDebugUtilsMessengerEXT handle

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

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

xrDestroyFoveationProfileFB(3)

Name

xrDestroyFoveationProfileFB - Destroy a foveation profile

C Specification

The xrDestroyFoveationProfileFB function is defined as:

XrResult xrDestroyFoveationProfileFB(
    XrFoveationProfileFB                        profile);

Parameters

Parameter Descriptions

profile is the XrFoveationProfileFB to destroy.

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)

The [XR_FB_foveation] extension must be enabled prior to calling xrDestroyFoveationProfileFB
profile must be a valid XrFoveationProfileFB handle

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

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

xrDestroyGeometryInstanceFB(3)

Name

xrDestroyGeometryInstanceFB - Destroy a geometry instance

C Specification

The xrDestroyGeometryInstanceFB function is defined as:

XrResult xrDestroyGeometryInstanceFB(
    XrGeometryInstanceFB                        instance);

Parameters

Parameter Descriptions

geometryInstance is the XrGeometryInstanceFB to be destroyed.

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)

The [XR_FB_passthrough] extension must be enabled prior to calling xrDestroyGeometryInstanceFB
instance must be a valid XrGeometryInstanceFB handle

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

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

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.

XrResult xrDestroyHandTrackerEXT(
    XrHandTrackerEXT                            handTracker);

Parameters

Parameter Descriptions

handTracker is an XrHandTrackerEXT previously created by xrCreateHandTrackerEXT.

Description

Valid Usage (Implicit)

The [XR_EXT_hand_tracking] extension must be enabled prior to calling xrDestroyHandTrackerEXT
handTracker must be a valid XrHandTrackerEXT handle

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

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

xrDestroyInstance(3)

Name

xrDestroyInstance - Destroy an instance of OpenXR

C Specification

The xrDestroyInstance function is defined as:

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)

instance must be a valid XrInstance handle

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

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

xrDestroyPassthroughFB(3)

Name

xrDestroyPassthroughFB - Destroy a passthrough feature

C Specification

The xrDestroyPassthroughFB function is defined as:

XrResult xrDestroyPassthroughFB(
    XrPassthroughFB                             passthrough);

Parameters

Parameter Descriptions

passthrough is the XrPassthroughFB to be destroyed.

Description

Destroys an XrPassthroughFB handle.

Valid Usage (Implicit)

The [XR_FB_passthrough] extension must be enabled prior to calling xrDestroyPassthroughFB
passthrough must be a valid XrPassthroughFB handle

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

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

xrDestroyPassthroughLayerFB(3)

Name

xrDestroyPassthroughLayerFB - Destroy a passthrough layer

C Specification

The xrDestroyPassthroughLayerFB function is defined as:

XrResult xrDestroyPassthroughLayerFB(
    XrPassthroughLayerFB                        layer);

Parameters

Parameter Descriptions

layer is the XrPassthroughLayerFB to be destroyed.

Description

Destroys an XrPassthroughLayerFB handle.

Valid Usage (Implicit)

The [XR_FB_passthrough] extension must be enabled prior to calling xrDestroyPassthroughLayerFB
layer must be a valid XrPassthroughLayerFB handle

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

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

xrDestroySceneMSFT(3)

Name

xrDestroySceneMSFT - Destroy a scene handle

C Specification

The xrDestroySceneMSFT function releases the scene and the underlying resources.

XrResult xrDestroySceneMSFT(
    XrSceneMSFT                                 scene);

Parameters

Parameter Descriptions

scene is an XrSceneMSFT previously created by xrCreateSceneMSFT.

Description

Valid Usage (Implicit)

The [XR_MSFT_scene_understanding] extension must be enabled prior to calling xrDestroySceneMSFT
scene must be a valid XrSceneMSFT handle

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

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

xrDestroySceneObserverMSFT(3)

Name

xrDestroySceneObserverMSFT - Destroy a scene observer handle

C Specification

The xrDestroySceneObserverMSFT function releases the sceneObserver and the underlying resources.

XrResult xrDestroySceneObserverMSFT(
    XrSceneObserverMSFT                         sceneObserver);

Parameters

Parameter Descriptions

sceneObserver is an XrSceneObserverMSFT previously created by xrCreateSceneObserverMSFT.

Description

Valid Usage (Implicit)

The [XR_MSFT_scene_understanding] extension must be enabled prior to calling xrDestroySceneObserverMSFT
sceneObserver must be a valid XrSceneObserverMSFT handle

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

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

xrDestroySession(3)

Name

xrDestroySession - Destroys an XrSession

C Specification

The xrDestroySession function is defined as.

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)

session must be a valid XrSession handle

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

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

xrDestroySpace(3)

Name

xrDestroySpace - Creates a space based on a pose action

C Specification

The xrDestroySpace function is defined as:

XrResult xrDestroySpace(
    XrSpace                                     space);

Parameters

Parameter Descriptions

space is a handle to an XrSpace previously created by a function such as xrCreateReferenceSpace.

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

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

xrDestroySpatialAnchorMSFT(3)

Name

xrDestroySpatialAnchorMSFT - Destroys a spatial anchor

C Specification

The xrDestroySpatialAnchorMSFT function is defined as:

XrResult xrDestroySpatialAnchorMSFT(
    XrSpatialAnchorMSFT                         anchor);

Parameters

Parameter Descriptions

anchor is a handle to an XrSpatialAnchorMSFT previously created by xrCreateSpatialAnchorMSFT.

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)

The [XR_MSFT_spatial_anchor] extension must be enabled prior to calling xrDestroySpatialAnchorMSFT
anchor must be a valid XrSpatialAnchorMSFT handle

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

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

xrDestroySpatialAnchorStoreConnectionMSFT(3)

Name

xrDestroySpatialAnchorStoreConnectionMSFT - Destroys the anchor store handle

C Specification

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

XrResult xrDestroySpatialAnchorStoreConnectionMSFT(
    XrSpatialAnchorStoreConnectionMSFT          spatialAnchorStore);

Parameters

Parameter Descriptions

spatialAnchorStore is the XrSpatialAnchorStoreConnectionMSFT to be destroyed.

Description

Valid Usage (Implicit)

The [XR_MSFT_spatial_anchor_persistence] extension must be enabled prior to calling xrDestroySpatialAnchorStoreConnectionMSFT
spatialAnchorStore must be a valid XrSpatialAnchorStoreConnectionMSFT handle

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

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

xrDestroySwapchain(3)

Name

xrDestroySwapchain - Destroys an XrSwapchain

C Specification

The xrDestroySwapchain function is defined as:

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)

swapchain must be a valid XrSwapchain handle

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

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

xrDestroyTriangleMeshFB(3)

Name

xrDestroyTriangleMeshFB - Destroy a triangle mesh

C Specification

The xrDestroyTriangleMeshFB function is defined as:

XrResult xrDestroyTriangleMeshFB(
    XrTriangleMeshFB                            mesh);

Parameters

Parameter Descriptions

mesh is the XrTriangleMeshFB to destroy.

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)

The [XR_FB_triangle_mesh] extension must be enabled prior to calling xrDestroyTriangleMeshFB
mesh must be a valid XrTriangleMeshFB handle

Thread Safety

Access to mesh, and any child handles, must be externally synchronized
Access to the buffers returned from calls to xrTriangleMeshGetVertexBufferFB and xrTriangleMeshGetIndexBufferFB on mesh 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

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

xrEndFrame(3)

Name

xrEndFrame - Marks a frame

C Specification

The xrEndFrame function is defined as:

XrResult xrEndFrame(
    XrSession                                   session,
    const XrFrameEndInfo*                       frameEndInfo);

Parameters

Parameter Descriptions

session is a valid XrSession handle.
frameEndInfo is a pointer to a valid XrFrameEndInfo.

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. 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)

session must be a valid XrSession handle
frameEndInfo must be a pointer to a valid XrFrameEndInfo structure

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

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

xrEndSession(3)

Name

xrEndSession - Ends an XrSession

C Specification

The xrEndSession function is defined as:

XrResult xrEndSession(
    XrSession                                   session);

Parameters

Parameter Descriptions

session is a handle to a running XrSession.

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)

session must be a valid XrSession handle

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

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

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:

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 0.
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

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

xrEnumerateBoundSourcesForAction(3)

Name

xrEnumerateBoundSourcesForAction - Queries the bound input sources for an action

C Specification

The xrEnumerateBoundSourcesForAction function is defined as:

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 0.
sources is a pointer to an application-allocated array that will be filled with the XrPath values for all 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.

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

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

xrEnumerateColorSpacesFB(3)

Name

xrEnumerateColorSpacesFB - Enumerates color spaces

C Specification

The xrEnumerateColorSpacesFB function is defined as:

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 0.
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

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

xrEnumerateDisplayRefreshRatesFB(3)

Name

xrEnumerateDisplayRefreshRatesFB - Enumerates display refresh rates

C Specification

The xrEnumerateDisplayRefreshRatesFB function is defined as:

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 0.
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

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

xrEnumerateEnvironmentBlendModes(3)

Name

xrEnumerateEnvironmentBlendModes - Lists environment blend modes

C Specification

The xrEnumerateEnvironmentBlendModes function is defined as:

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 0.
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

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

xrEnumerateInstanceExtensionProperties(3)

Name

xrEnumerateInstanceExtensionProperties - Returns properties of available instance extensions

C Specification

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

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 0.
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

If properties is NULL, then the number of extensions properties available is returned in propertyCountOutput. Otherwise, propertyCountInput must point to a variable set by the user to the number of elements in the properties array. If propertyCountInput is less than the number of extension properties available, the contents of properties will be undefined. If propertyCountInput is smaller than the number of extensions available, the runtime must return the failure code XR_ERROR_SIZE_INSUFFICIENT and the contents of properties are undefined.

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

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

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.

XrResult xrEnumeratePersistedSpatialAnchorNamesMSFT(
    XrSpatialAnchorStoreConnectionMSFT          spatialAnchorStore,
    uint32_t                                    spatialAnchorNamesCapacityInput,
    uint32_t*                                   spatialAnchorNamesCountOutput,
    XrSpatialAnchorPersistenceNameMSFT*         persistedAnchorNames);

Parameters

Parameter Descriptions

spatialAnchorStore is the XrSpatialAnchorStoreConnectionMSFT anchor store to perform the enumeration operation on.
spatialAnchorNamesCapacityInput is the capacity of the spatialAnchorNames array, or 0 to indicate a request to retrieve the required capacity.
spatialAnchorNamesCountOutput is filled in by the runtime with the count of anchor names written or the required capacity in the case that spatialAnchorNamesCapacityInput is 0.
persistedAnchorNames 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 persistedAnchorNames size.

Description

Valid Usage (Implicit)

The [XR_MSFT_spatial_anchor_persistence] extension must be enabled prior to calling xrEnumeratePersistedSpatialAnchorNamesMSFT
spatialAnchorStore must be a valid XrSpatialAnchorStoreConnectionMSFT handle
If spatialAnchorNamesCountOutput is not NULL, spatialAnchorNamesCountOutput must be a pointer to a uint32_t value
If spatialAnchorNamesCapacityInput is not 0, persistedAnchorNames must be a pointer to an array of spatialAnchorNamesCapacityInput XrSpatialAnchorPersistenceNameMSFT structures

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

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

xrEnumerateReferenceSpaces(3)

Name

xrEnumerateReferenceSpaces - Enumerate available reference spaces

C Specification

The xrEnumerateReferenceSpaces function is defined as:

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 0.
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

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

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.

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 0.
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 mode size.

Description

Valid Usage (Implicit)

The [XR_MSFT_composition_layer_reprojection] extension must be enabled prior to calling xrEnumerateReprojectionModesMSFT
instance must be a valid XrInstance handle
viewConfigurationType must be a valid XrViewConfigurationType value
modeCountOutput must be a pointer to a uint32_t value
If modeCapacityInput is not 0, modes must be a pointer to an array of modeCapacityInput XrReprojectionModeMSFT values

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

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

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.

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 0.
features is an array of XrSceneComputeFeatureMSFT.

Description

Valid Usage (Implicit)

The [XR_MSFT_scene_understanding] extension must be enabled prior to calling xrEnumerateSceneComputeFeaturesMSFT
instance must be a valid XrInstance handle
featureCountOutput must be a pointer to a uint32_t value
If featureCapacityInput is not 0, features must be a pointer to an array of featureCapacityInput XrSceneComputeFeatureMSFT values

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

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

xrEnumerateSwapchainFormats(3)

Name

xrEnumerateSwapchainFormats - Enumerates swapchain formats

C Specification

The xrEnumerateSwapchainFormats function is defined as:

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 0.
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

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

xrEnumerateSwapchainImages(3)

Name

xrEnumerateSwapchainImages - Gets images from an XrSwapchain

C Specification

The xrEnumerateSwapchainImages function is defined as:

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 0.
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 type.

Valid Usage (Implicit)

swapchain must be a valid XrSwapchain handle
imageCountOutput must be a pointer to a uint32_t value
If imageCapacityInput is not 0, images must be a pointer to an array of imageCapacityInput XrSwapchainImageBaseHeader-based structures. See also: XrSwapchainImageD3D11KHR, XrSwapchainImageD3D12KHR, XrSwapchainImageOpenGLESKHR, XrSwapchainImageOpenGLKHR, XrSwapchainImageVulkanKHR

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

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

xrEnumerateViewConfigurationViews(3)

Name

xrEnumerateViewConfigurationViews - Gets view configuration views

C Specification

The xrEnumerateViewConfigurationViews function is defined as:

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

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

xrEnumerateViewConfigurations(3)

Name

xrEnumerateViewConfigurations - Enumerates supported view configurations

C Specification

The xrEnumerateViewConfigurations function is defined as:

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.
viewConfigurationsTypeCapacityInput is the capacity of the viewConfigurations array, or 0 to indicate a request to retrieve the required capacity.
viewConfigurationsTypeCountOutput is a pointer to the count of viewConfigurations written, or a pointer to the required capacity in the case that viewConfigurationsTypeCapacityInput is 0.
viewConfigurationsTypes is a pointer to an array of XrViewConfigurationType values, but can be NULL if viewConfigurationsTypeCapacityInput is 0.
See Buffer Size Parameters chapter for a detailed description of retrieving the required viewConfigurations 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

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

xrEnumerateViveTrackerPathsHTCX(3)

Name

xrEnumerateViveTrackerPathsHTCX - Enumerates all connected VIVE trackers

C Specification

The xrEnumerateViveTrackerPathsHTCX function is defined as:

XrResult xrEnumerateViveTrackerPathsHTCX(
    XrInstance                                  instance,
    uint32_t                                    pathCapacityInput,
    uint32_t*                                   pathCountOutput,
    XrViveTrackerPathsHTCX*                     paths);

Parameters

Parameter Descriptions

instance is an instance previously created.
pathsCapacityInput is the capacity of the viveTrackerPaths, or 0 to retrieve the required capacity.
pathsCountOutput is a pointer to the count of XrViveTrackerPathsHTCX viveTrackerPaths written, or a pointer to the required capacity in the case that pathsCapacityInput is 0.
viveTrackerPaths is a pointer to an array of XrViveTrackerPathsHTCX VIVE tracker paths, but can be NULL if pathsCapacityInput is 0.
See Buffer Size Parameters chapter for a detailed description of retrieving the required viveTrackerPaths size.

Description

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

Valid Usage (Implicit)

The [XR_HTCX_vive_tracker_interaction] extension must be enabled prior to calling xrEnumerateViveTrackerPathsHTCX
instance must be a valid XrInstance handle
pathCountOutput must be a pointer to a uint32_t value
If pathCapacityInput is not 0, paths must be a pointer to an array of pathCapacityInput XrViveTrackerPathsHTCX structures

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

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

xrGeometryInstanceSetTransformFB(3)

Name

xrGeometryInstanceSetTransformFB - Create a triangle mesh

C Specification

The xrGeometryInstanceSetTransformFB function is defined as:

XrResult xrGeometryInstanceSetTransformFB(
    XrGeometryInstanceFB                        instance,
    const XrGeometryInstanceTransformFB*        transformation);

Parameters

Parameter Descriptions

geometryInstance is the XrGeometryInstanceFB to get the transform.
transform is the XrGeometryInstanceTransformFB to be set.

Description

Sets an XrGeometryInstanceTransformFB transform on an XrGeometryInstanceFB geometry instance.

Valid Usage (Implicit)

The [XR_FB_passthrough] extension must be enabled prior to calling xrGeometryInstanceSetTransformFB
instance must be a valid XrGeometryInstanceFB handle
transformation must be a pointer to a valid XrGeometryInstanceTransformFB structure

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

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

xrGetActionStateBoolean(3)

Name

xrGetActionStateBoolean - Gets boolean action state

C Specification

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

XrResult xrGetActionStateBoolean(
    XrSession                                   session,
    const XrActionStateGetInfo*                 getInfo,
    XrActionStateBoolean*                       state);

Parameters

Parameter Descriptions

session is the XrSession to query.
getInfo is a pointer to XrActionStateGetInfo to provide action and subaction paths information.
state is a pointer to a valid XrActionStateBoolean into which the state will be placed.

Description

Valid Usage (Implicit)

session must be a valid XrSession handle
getInfo must be a pointer to a valid XrActionStateGetInfo structure
state must be a pointer to an XrActionStateBoolean structure

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

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

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:

XrResult xrGetActionStateFloat(
    XrSession                                   session,
    const XrActionStateGetInfo*                 getInfo,
    XrActionStateFloat*                         state);

Parameters

Parameter Descriptions

session is the XrSession to query.
getInfo is a pointer to XrActionStateGetInfo to provide action and subaction paths information.
state is a pointer to a valid XrActionStateFloat into which the state will be placed.

Description

Valid Usage (Implicit)

session must be a valid XrSession handle
getInfo must be a pointer to a valid XrActionStateGetInfo structure
state must be a pointer to an XrActionStateFloat structure

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

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

xrGetActionStatePose(3)

Name

xrGetActionStatePose - Gets metadata from a pose action

C Specification

The xrGetActionStatePose function is defined as:

XrResult xrGetActionStatePose(
    XrSession                                   session,
    const XrActionStateGetInfo*                 getInfo,
    XrActionStatePose*                          state);

Parameters

Parameter Descriptions

session is the XrSession to query.
getInfo is a pointer to XrActionStateGetInfo to provide action and subaction paths information.
state is a pointer to a valid XrActionStatePose into which the state will be placed.

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)

session must be a valid XrSession handle
getInfo must be a pointer to a valid XrActionStateGetInfo structure
state must be a pointer to an XrActionStatePose structure

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

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

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:

XrResult xrGetActionStateVector2f(
    XrSession                                   session,
    const XrActionStateGetInfo*                 getInfo,
    XrActionStateVector2f*                      state);

Parameters

Parameter Descriptions

session is the XrSession to query.
getInfo is a pointer to XrActionStateGetInfo to provide action and subaction paths information.
state is a pointer to a valid XrActionStateVector2f into which the state will be placed.

Description

Valid Usage (Implicit)

session must be a valid XrSession handle
getInfo must be a pointer to a valid XrActionStateGetInfo structure
state must be a pointer to an XrActionStateVector2f structure

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

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

xrGetAudioInputDeviceGuidOculus(3)

Name

xrGetAudioInputDeviceGuidOculus - Query the GUID for the active audio input device

C Specification

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)

The [XR_OCULUS_audio_device_guid] extension must be enabled prior to calling xrGetAudioInputDeviceGuidOculus
instance must be a valid XrInstance handle
buffer must be a wide character array of length XR_MAX_AUDIO_DEVICE_STR_SIZE_OCULUS

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

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

xrGetAudioOutputDeviceGuidOculus(3)

Name

xrGetAudioOutputDeviceGuidOculus - Query the GUID for the active audio output device

C Specification

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)

The [XR_OCULUS_audio_device_guid] extension must be enabled prior to calling xrGetAudioOutputDeviceGuidOculus
instance must be a valid XrInstance handle
buffer must be a wide character array of length XR_MAX_AUDIO_DEVICE_STR_SIZE_OCULUS

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

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

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:

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)

The [XR_MSFT_controller_model] extension must be enabled prior to calling xrGetControllerModelKeyMSFT
session must be a valid XrSession handle
controllerModelKeyState must be a pointer to an XrControllerModelKeyStateMSFT structure

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

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

xrGetControllerModelPropertiesMSFT(3)

Name

xrGetControllerModelPropertiesMSFT - Get controller model properties

C Specification

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

XrResult xrGetControllerModelPropertiesMSFT(
    XrSession                                   session,
    XrControllerModelKeyMSFT                    modelKey,
    XrControllerModelPropertiesMSFT*            properties);

Parameters

Parameter Descriptions

session is the specified XrSession.
modelKey is a valid model key obtained from XrControllerModelKeyStateMSFT
properties is an XrControllerModelPropertiesMSFT returning the properties of the controller model

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)

The [XR_MSFT_controller_model] extension must be enabled prior to calling xrGetControllerModelPropertiesMSFT
session must be a valid XrSession handle
properties must be a pointer to an XrControllerModelPropertiesMSFT structure

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

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

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.

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.

Valid Usage (Implicit)

The [XR_MSFT_controller_model] extension must be enabled prior to calling xrGetControllerModelStateMSFT
session must be a valid XrSession handle
state must be a pointer to an XrControllerModelStateMSFT structure

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

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

xrGetCurrentInteractionProfile(3)

Name

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

C Specification

The xrGetCurrentInteractionProfile function is defined as:

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)

session must be a valid XrSession handle
interactionProfile must be a pointer to an XrInteractionProfileState structure

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

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

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:

XrResult xrGetD3D11GraphicsRequirementsKHR(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    XrGraphicsRequirementsD3D11KHR*             graphicsRequirements);

Parameters

Parameter Descriptions

instance is an XrInstance handle previously created with xrCreateInstance.
systemId is an XrSystemId handle for the system which will be used to create a session.
graphicsRequirements is the XrGraphicsRequirementsD3D11KHR output structure.

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 should be used to create the ID3D11Device that the application passes to xrCreateSession in the XrGraphicsBindingD3D11KHR.

Valid Usage (Implicit)

The [XR_KHR_D3D11_enable] extension must be enabled prior to calling xrGetD3D11GraphicsRequirementsKHR
instance must be a valid XrInstance handle
graphicsRequirements must be a pointer to an XrGraphicsRequirementsD3D11KHR structure

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

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

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:

XrResult xrGetD3D12GraphicsRequirementsKHR(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    XrGraphicsRequirementsD3D12KHR*             graphicsRequirements);

Parameters

Parameter Descriptions

instance is an XrInstance handle previously created with xrCreateInstance.
systemId is an XrSystemId handle for the system which will be used to create a session.
graphicsRequirements is the XrGraphicsRequirementsD3D12KHR output structure.

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 should be used to create the ID3D12Device that the application passes to xrCreateSession in the XrGraphicsBindingD3D12KHR.

Valid Usage (Implicit)

The [XR_KHR_D3D12_enable] extension must be enabled prior to calling xrGetD3D12GraphicsRequirementsKHR
instance must be a valid XrInstance handle
graphicsRequirements must be a pointer to an XrGraphicsRequirementsD3D12KHR structure

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

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

xrGetDisplayRefreshRateFB(3)

Name

xrGetDisplayRefreshRateFB - Get the current display refresh rate

C Specification

The xrGetDisplayRefreshRateFB function is defined as:

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)

The [XR_FB_display_refresh_rate] extension must be enabled prior to calling xrGetDisplayRefreshRateFB
session must be a valid XrSession handle
displayRefreshRate must be a pointer to a float value

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

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

xrGetHandMeshFB(3)

Name

xrGetHandMeshFB - Create a foveation profile

C Specification

The xrGetHandMeshFB function is defined as:

XrResult xrGetHandMeshFB(
    XrHandTrackerEXT                            handTracker,
    XrHandTrackingMeshFB*                       mesh);

Parameters

Parameter Descriptions

handTracker is the XrHandTrackerEXT that is associated with a particular hand.
mesh is the XrHandTrackingMeshFB output structure.

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)

The [XR_FB_hand_tracking_mesh] extension must be enabled prior to calling xrGetHandMeshFB
handTracker must be a valid XrHandTrackerEXT handle
mesh must be a pointer to an XrHandTrackingMeshFB structure

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

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

xrGetInputSourceLocalizedName(3)

Name

xrGetInputSourceLocalizedName - Gets a localized source name

C Specification

The xrGetInputSourceLocalizedName function is defined as:

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 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 (including the terminating \0), or a pointer to the required capacity in the case that bufferCapacityInput is 0.
buffer is a pointer to an application-allocated buffer that will be filled with the 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 input 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

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

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.

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:

No Instance Required

xrEnumerateInstanceExtensionProperties
xrEnumerateApiLayerProperties
xrCreateInstance

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	fp¹
instance	enabled extension function for `instance`	fp¹
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)

If instance is not XR_NULL_HANDLE, instance must be a valid XrInstance handle
name must be a null-terminated UTF-8 string
function must be a pointer to a PFN_xrVoidFunction value

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

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

xrGetInstanceProperties(3)

Name

xrGetInstanceProperties - Gets information about the instance

C Specification

The xrGetInstanceProperties function provides information about the instance and the associated runtime.

XrResult xrGetInstanceProperties(
    XrInstance                                  instance,
    XrInstanceProperties*                       instanceProperties);

Parameters

Parameter Descriptions

instance is a handle to an XrInstance previously created with xrCreateInstance.
instanceProperties points to an XrInstanceProperties which describes the instance.

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)

instance must be a valid XrInstance handle
instanceProperties must be a pointer to an XrInstanceProperties structure

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

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

xrGetMarkerSizeVARJO(3)

Name

xrGetMarkerSizeVARJO - Gets physical size of marker

C Specification

The xrGetMarkerSizeVARJO function is defined as:

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)

The [XR_VARJO_marker_tracking] extension must be enabled prior to calling xrGetMarkerSizeVARJO
session must be a valid XrSession handle
size must be a pointer to an XrExtent2Df structure

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

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

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:

XrResult xrGetOpenGLESGraphicsRequirementsKHR(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    XrGraphicsRequirementsOpenGLESKHR*          graphicsRequirements);

Parameters

Parameter Descriptions

instance is an XrInstance handle previously created with xrCreateInstance.
systemId is an XrSystemId handle for the system which will be used to create a session.
graphicsRequirements is the XrGraphicsRequirementsOpenGLESKHR output structure.

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)

The [XR_KHR_opengl_es_enable] extension must be enabled prior to calling xrGetOpenGLESGraphicsRequirementsKHR
instance must be a valid XrInstance handle
graphicsRequirements must be a pointer to an XrGraphicsRequirementsOpenGLESKHR structure

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

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

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:

XrResult xrGetOpenGLGraphicsRequirementsKHR(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    XrGraphicsRequirementsOpenGLKHR*            graphicsRequirements);

Parameters

Parameter Descriptions

instance is an XrInstance handle previously created with xrCreateInstance.
systemId is an XrSystemId handle for the system which will be used to create a session.
graphicsRequirements is the XrGraphicsRequirementsOpenGLKHR output structure.

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)

The [XR_KHR_opengl_enable] extension must be enabled prior to calling xrGetOpenGLGraphicsRequirementsKHR
instance must be a valid XrInstance handle
graphicsRequirements must be a pointer to an XrGraphicsRequirementsOpenGLKHR structure

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

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

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 createInfo is not supported by this session.

When a runtime will begin operating with updated space bounds, the runtime must queue a corresponding XrEventDataReferenceSpaceChangePending event.

XrResult xrGetReferenceSpaceBoundsRect(
    XrSession                                   session,
    XrReferenceSpaceType                        referenceSpaceType,
    XrExtent2Df*                                bounds);

Parameters

Parameter Descriptions

type is the XrStructureType of this structure.
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)

session must be a valid XrSession handle
referenceSpaceType must be a valid XrReferenceSpaceType value
bounds must be a pointer to an XrExtent2Df structure

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

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

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.

If XR_SCENE_COMPONENT_TYPE_OBJECT_MSFT is passed to xrGetSceneComponentsMSFT, then XrSceneObjectsMSFT may be included in the XrSceneComponentsMSFT::next chain.
If XR_SCENE_COMPONENT_TYPE_PLANE_MSFT is passed to xrGetSceneComponentsMSFT, then XrScenePlanesMSFT may be included in the XrSceneComponentsMSFT::next chain.
If XR_SCENE_COMPONENT_TYPE_VISUAL_MESH_MSFT or XR_SCENE_COMPONENT_TYPE_COLLIDER_MESH_MSFT are passed to xrGetSceneComponentsMSFT, then XrSceneMeshesMSFT may be included in the XrSceneComponentsMSFT::next chain.

XrResult xrGetSceneComponentsMSFT(
    XrSceneMSFT                                 scene,
    const XrSceneComponentsGetInfoMSFT*         getInfo,
    XrSceneComponentsMSFT*                      components);

Parameters

Parameter Descriptions

scene is an XrSceneMSFT previously created by xrCreateSceneMSFT.
getInfo is a pointer to an XrSceneComponentsGetInfoMSFT structure.
components is the XrSceneComponentsMSFT output structure.

Description

Valid Usage (Implicit)

The [XR_MSFT_scene_understanding] extension must be enabled prior to calling xrGetSceneComponentsMSFT
scene must be a valid XrSceneMSFT handle
getInfo must be a pointer to a valid XrSceneComponentsGetInfoMSFT structure
components must be a pointer to an XrSceneComponentsMSFT structure

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

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

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.

XrResult xrGetSceneComputeStateMSFT(
    XrSceneObserverMSFT                         sceneObserver,
    XrSceneComputeStateMSFT*                    state);

Parameters

Parameter Descriptions

sceneObserver is a handle to an XrSceneObserverMSFT.
state is the returned XrSceneComputeStateMSFT value.

Description

Valid Usage (Implicit)

The [XR_MSFT_scene_understanding] extension must be enabled prior to calling xrGetSceneComputeStateMSFT
sceneObserver must be a valid XrSceneObserverMSFT handle
state must be a pointer to an XrSceneComputeStateMSFT value

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

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

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:

XrResult xrGetSceneMeshBuffersMSFT(
    XrSceneMSFT                                 scene,
    const XrSceneMeshBuffersGetInfoMSFT*        getInfo,
    XrSceneMeshBuffersMSFT*                     buffers);

Parameters

Parameter Descriptions

scene is an XrSceneMSFT previously created by xrCreateSceneMSFT.
getInfo is a pointer to an XrSceneMeshBuffersGetInfoMSFT structure.
buffers is a pointer to an XrSceneMeshBuffersMSFT structure for reading a scene mesh buffer.

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)

The [XR_MSFT_scene_understanding] extension must be enabled prior to calling xrGetSceneMeshBuffersMSFT
scene must be a valid XrSceneMSFT handle
getInfo must be a pointer to a valid XrSceneMeshBuffersGetInfoMSFT structure
buffers must be a pointer to an XrSceneMeshBuffersMSFT structure

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

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

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.

The xrGetSerializedSceneFragmentDataMSFT function is defined as:

XrResult xrGetSerializedSceneFragmentDataMSFT(
    XrSceneMSFT                                 scene,
    const XrSerializedSceneFragmentDataGetInfoMSFT* getInfo,
    uint32_t                                    countInput,
    uint32_t*                                   readOutput,
    uint8_t*                                    buffer);

Parameters

Parameter Descriptions

scene is the XrSceneMSFT handle to read from.
getInfo is a pointer to an XrSerializedSceneFragmentDataGetInfoMSFT structure.
countInput is the number of bytes that should be read.
readOutput is the number of bytes read.
buffer is a pointer to the buffer where the data should be copied.

Description

The runtime must return XR_ERROR_SCENE_COMPONENT_ID_INVALID_MSFT if the given scene fragment XrUuidMSFT was not found.

Valid Usage (Implicit)

The [XR_MSFT_scene_understanding_serialization] extension must be enabled prior to calling xrGetSerializedSceneFragmentDataMSFT
scene must be a valid XrSceneMSFT handle
getInfo must be a pointer to a valid XrSerializedSceneFragmentDataGetInfoMSFT structure
readOutput must be a pointer to a uint32_t value
If countInput is not 0, buffer must be a pointer to an array of countInput 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

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

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

xrGetSwapchainStateFB(3)

Name

xrGetSwapchainStateFB - Query state for the corresponding swapchain

C Specification

The xrGetSwapchainStateFB function is defined as:

XrResult xrGetSwapchainStateFB(
    XrSwapchain                                 swapchain,
    XrSwapchainStateBaseHeaderFB*               state);

Parameters

Parameter Descriptions

swapchain is the XrSwapchain to update state for.
state is a pointer to a XrSwapchainState structure based off of XrSwapchainStateBaseHeaderFB.

Description

xrGetSwapchainStateFB provides support for an application to query specific mutable state associated with an XrSwapchain.

Valid Usage (Implicit)

The [XR_FB_swapchain_update_state] extension must be enabled prior to calling xrGetSwapchainStateFB
swapchain must be a valid XrSwapchain handle
state must be a pointer to an XrSwapchainStateBaseHeaderFB-based structure. See also: XrSwapchainStateAndroidSurfaceDimensionsFB, XrSwapchainStateFoveationFB, XrSwapchainStateSamplerOpenGLESFB, XrSwapchainStateSamplerVulkanFB

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

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

xrGetSystem(3)

Name

xrGetSystem - Gets a system identifier

C Specification

The xrGetSystem function is defined as:

XrResult xrGetSystem(
    XrInstance                                  instance,
    const XrSystemGetInfo*                      getInfo,
    XrSystemId*                                 systemId);

Parameters

Parameter Descriptions

instance is the handle of the instance from which to get the information.
getInfo is a pointer to an XrSystemGetInfo structure containing the application’s requests for a system.
systemId is the returned XrSystemId.

Description

To get an XrSystemId, an application specifies its desired form factor to xrGetSystem and gets the runtime’s XrSystemId associated with that configuration.

If the form factor is supported but temporarily unavailable, xrGetSystem must return XR_ERROR_FORM_FACTOR_UNAVAILABLE. A runtime may return XR_SUCCESS on a subsequent call for a form factor it previously returned XR_ERROR_FORM_FACTOR_UNAVAILABLE. For example, connecting or warming up hardware might cause an unavailable form factor to become available.

Valid Usage (Implicit)

instance must be a valid XrInstance handle
getInfo must be a pointer to a valid XrSystemGetInfo structure
systemId must be a pointer to an XrSystemId value

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_FORM_FACTOR_UNSUPPORTED
XR_ERROR_FORM_FACTOR_UNAVAILABLE

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

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

xrGetSystemProperties(3)

Name

xrGetSystemProperties - Gets the properties of a particular system

C Specification

The xrGetSystemProperties function is defined as:

XrResult xrGetSystemProperties(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    XrSystemProperties*                         properties);

Parameters

Parameter Descriptions

instance is the instance from which systemId was retrieved.
systemId is the XrSystemId whose properties will be queried.
properties points to an instance of the XrSystemProperties structure, that will be filled with returned information.

Description

An application can call xrGetSystemProperties to retrieve information about the system such as vendor ID, system name, and graphics and tracking properties.

Valid Usage (Implicit)

instance must be a valid XrInstance handle
properties must be a pointer to an XrSystemProperties structure

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

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

xrGetViewConfigurationProperties(3)

Name

xrGetViewConfigurationProperties - Gets information for a view configuration

C Specification

The xrGetViewConfigurationProperties function is defined as:

XrResult xrGetViewConfigurationProperties(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    XrViewConfigurationType                     viewConfigurationType,
    XrViewConfigurationProperties*              configurationProperties);

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.
configurationProperties is a pointer to view configuration properties to return.

Description

xrGetViewConfigurationProperties queries properties of an individual view configuration. Applications must use one of the supported view configuration types returned by xrEnumerateViewConfigurations. If viewConfigurationType is not supported by this XrInstance the runtime must return XR_ERROR_VIEW_CONFIGURATION_TYPE_UNSUPPORTED.

Valid Usage (Implicit)

instance must be a valid XrInstance handle
viewConfigurationType must be a valid XrViewConfigurationType value
configurationProperties must be a pointer to an XrViewConfigurationProperties structure

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

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

xrGetVisibilityMaskKHR(3)

Name

xrGetVisibilityMaskKHR - Gets visibility mask

C Specification

The xrGetVisibilityMaskKHR function is defined as:

XrResult xrGetVisibilityMaskKHR(
    XrSession                                   session,
    XrViewConfigurationType                     viewConfigurationType,
    uint32_t                                    viewIndex,
    XrVisibilityMaskTypeKHR                     visibilityMaskType,
    XrVisibilityMaskKHR*                        visibilityMask);

Parameters

Parameter Descriptions

session is an XrSession handle previously created with xrCreateSession.
viewConfigurationType is the view configuration from which to retrieve mask information.
viewIndex is the individual view within the view configuration from which to retrieve mask information.
visibilityMaskType is the type of visibility mask requested.
visibilityMask is an input/output struct which specifies the view mask.

Description

xrGetVisibilityMaskKHR retrieves the view mask for a given view. This function follows the two-call idiom for filling multiple buffers in a struct. Specifically, if either vertexCapacityInput or indexCapacityInput is 0, the runtime must respond as if both fields were set to 0, returning the vertex count and index count through vertexCountOutput or indexCountOutput respectively. If a view mask for the specified view isn’t available, the returned vertex and index counts must be 0.

Valid Usage (Implicit)

The [XR_KHR_visibility_mask] extension must be enabled prior to calling xrGetVisibilityMaskKHR
session must be a valid XrSession handle
viewConfigurationType must be a valid XrViewConfigurationType value
visibilityMaskType must be a valid XrVisibilityMaskTypeKHR value
visibilityMask must be a pointer to an XrVisibilityMaskKHR structure

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_VIEW_CONFIGURATION_TYPE_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

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

xrGetVulkanDeviceExtensionsKHR(3)

Name

xrGetVulkanDeviceExtensionsKHR - Get list of required Vulkan device extensions for an OpenXR instance and system

C Specification

XrResult xrGetVulkanDeviceExtensionsKHR(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    char*                                       buffer);

Parameters

Parameter Descriptions

instance is an XrInstance handle previously created with xrCreateInstance.
systemId is an XrSystemId handle for the system which will be used to create a session.
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 (including terminating \0), or a pointer to the required capacity in the case that bufferCapacityInput is 0.
buffer is a pointer to an array of characters, but can be NULL if bufferCapacityInput is 0. The format of the output is a single space (ASCII 0x20) delimited string of extension names.
See Buffer Size Parameters chapter for a detailed description of retrieving the required buffer size.

Description

Valid Usage (Implicit)

The [XR_KHR_vulkan_enable] extension must be enabled prior to calling xrGetVulkanDeviceExtensionsKHR
instance must be a valid XrInstance handle
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

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

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

xrGetVulkanGraphicsDevice2KHR(3)

Name

xrGetVulkanGraphicsDevice2KHR - Retrieve the Vulkan physical device associated with an OpenXR instance and system

C Specification

XrResult xrGetVulkanGraphicsDevice2KHR(
    XrInstance                                  instance,
    const XrVulkanGraphicsDeviceGetInfoKHR*     getInfo,
    VkPhysicalDevice*                           vulkanPhysicalDevice);

Parameters

Parameter Descriptions

instance is an XrInstance handle previously created with xrCreateInstance.
getInfo extensible input struct of type XrVulkanGraphicsDeviceGetInfoKHR
vulkanPhysicalDevice is a pointer to a VkPhysicalDevice handle to populate.

Description

Valid Usage (Implicit)

The [XR_KHR_vulkan_enable2] extension must be enabled prior to calling xrGetVulkanGraphicsDevice2KHR
instance must be a valid XrInstance handle
getInfo must be a pointer to a valid XrVulkanGraphicsDeviceGetInfoKHR structure
vulkanPhysicalDevice must be a pointer to a VkPhysicalDevice value

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

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

xrGetVulkanGraphicsDeviceKHR(3)

Name

xrGetVulkanGraphicsDeviceKHR - Retrieve the Vulkan physical device associated with an OpenXR instance and system

C Specification

To identify what graphics device needs to be used for an instance and system, call:

XrResult xrGetVulkanGraphicsDeviceKHR(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    VkInstance                                  vkInstance,
    VkPhysicalDevice*                           vkPhysicalDevice);

Parameters

Parameter Descriptions

instance is an XrInstance handle previously created with xrCreateInstance.
systemId is an XrSystemId handle for the system which will be used to create a session.
vkInstance is a valid Vulkan VkInstance.
vkPhysicalDevice is a pointer to a VkPhysicalDevice value to populate.

Description

xrGetVulkanGraphicsDeviceKHR function identifies to the application what graphics device (Vulkan VkPhysicalDevice) needs to be used. xrGetVulkanGraphicsDeviceKHR must be called prior to calling xrCreateSession, and the VkPhysicalDevice that xrGetVulkanGraphicsDeviceKHR returns should be passed to xrCreateSession in the XrGraphicsBindingVulkanKHR.

Valid Usage (Implicit)

The [XR_KHR_vulkan_enable] extension must be enabled prior to calling xrGetVulkanGraphicsDeviceKHR
instance must be a valid XrInstance handle
vkInstance must be a valid VkInstance value
vkPhysicalDevice must be a pointer to a VkPhysicalDevice value

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

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

xrGetVulkanGraphicsRequirementsKHR(3)

Name

xrGetVulkanGraphicsRequirementsKHR - Retrieve the Vulkan version requirements for an instance and system

C Specification

To query Vulkan API version requirements, call:

XrResult xrGetVulkanGraphicsRequirementsKHR(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    XrGraphicsRequirementsVulkanKHR*            graphicsRequirements);

Parameters

Parameter Descriptions

instance is an XrInstance handle previously created with xrCreateInstance.
systemId is an XrSystemId handle for the system which will be used to create a session.
graphicsRequirements is the XrGraphicsRequirementsVulkanKHR output structure.

Description

The xrGetVulkanGraphicsRequirementsKHR function identifies to the application the minimum Vulkan version requirement and the highest known tested Vulkan 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 xrGetVulkanGraphicsRequirementsKHR has not been called for the same instance and systemId.

Valid Usage (Implicit)

The [XR_KHR_vulkan_enable] extension must be enabled prior to calling xrGetVulkanGraphicsRequirementsKHR
instance must be a valid XrInstance handle
graphicsRequirements must be a pointer to an XrGraphicsRequirementsVulkanKHR structure

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

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

xrGetVulkanInstanceExtensionsKHR(3)

Name

xrGetVulkanInstanceExtensionsKHR - Get list of required Vulkan instance extensions for an OpenXR instance and system

C Specification

XrResult xrGetVulkanInstanceExtensionsKHR(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    char*                                       buffer);

Parameters

Parameter Descriptions

instance is an XrInstance handle previously created with xrCreateInstance.
systemId is an XrSystemId handle for the system which will be used to create a session.
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 (including terminating \0), or a pointer to the required capacity in the case that bufferCapacityInput is 0.
buffer is a pointer to an array of characters, but can be NULL if bufferCapacityInput is 0. The format of the output is a single space (ASCII 0x20) delimited string of extension names.
See Buffer Size Parameters chapter for a detailed description of retrieving the required buffer size.

Description

Valid Usage (Implicit)

The [XR_KHR_vulkan_enable] extension must be enabled prior to calling xrGetVulkanInstanceExtensionsKHR
instance must be a valid XrInstance handle
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

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

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

xrInitializeLoaderKHR(3)

Name

xrInitializeLoaderKHR - Initializes loader

C Specification

To initialize an OpenXR loader with platform or implementation-specific parameters, call:

XrResult xrInitializeLoaderKHR(
    const XrLoaderInitInfoBaseHeaderKHR*        loaderInitInfo);

Parameters

Parameter Descriptions

loaderInitInfo is a pointer to an XrLoaderInitInfoBaseHeaderKHR structure, which is a polymorphic type defined by other platform- or implementation-specific extensions.

== Description

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

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

xrLoadControllerModelMSFT(3)

Name

xrLoadControllerModelMSFT - Load controller render model

C Specification

The xrLoadControllerModelMSFT function loads the controller model as a byte buffer containing a binary form of glTF (a.k.a GLB file format) for the controller. The binary glTF data must conform to glTF 2.0 format defined at https://github.com/KhronosGroup/glTF/tree/master/specification/2.0.

XrResult xrLoadControllerModelMSFT(
    XrSession                                   session,
    XrControllerModelKeyMSFT                    modelKey,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    uint8_t*                                    buffer);

Parameters

Parameter Descriptions

session is the specified XrSession.
modelKey is the model key corresponding to the controller render model being queried.
bufferCapacityInput is the capacity of the buffer array, or 0 to indicate a request to retrieve the required capacity.
bufferCountOutput filled in by the runtime with the count of elements in buffer array, or returns the required capacity in the case that bufferCapacityInput is 0.
buffer is a pointer to an application-allocated array of the model for the device that will be filled with the uint8_t values by the runtime. 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 xrLoadControllerModelMSFT function may be a slow operation and therefore should be invoked from a non-timing critical thread.

Valid Usage (Implicit)

The [XR_MSFT_controller_model] extension must be enabled prior to calling xrLoadControllerModelMSFT
session must be a valid XrSession handle
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_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

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

xrLocateHandJointsEXT(3)

Name

xrLocateHandJointsEXT - Locate hand joint locations

C Specification

The xrLocateHandJointsEXT function locates an array of hand joints to a base space at given time.

XrResult xrLocateHandJointsEXT(
    XrHandTrackerEXT                            handTracker,
    const XrHandJointsLocateInfoEXT*            locateInfo,
    XrHandJointLocationsEXT*                    locations);

Parameters

Parameter Descriptions

handTracker is an XrHandTrackerEXT previously created by xrCreateHandTrackerEXT.
locateInfo is a pointer to XrHandJointsLocateInfoEXT describing information to locate hand joints.
locations is a pointer to XrHandJointLocationsEXT receiving the returned hand joint locations.

Description

Valid Usage (Implicit)

The [XR_EXT_hand_tracking] extension must be enabled prior to calling xrLocateHandJointsEXT
handTracker must be a valid XrHandTrackerEXT handle
locateInfo must be a pointer to a valid XrHandJointsLocateInfoEXT structure
locations must be a pointer to an XrHandJointLocationsEXT structure

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

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

xrLocateSceneComponentsMSFT(3)

Name

xrLocateSceneComponentsMSFT - Locate scene components

C Specification

The xrLocateSceneComponentsMSFT function locates an array of scene components to a base space at a given time.

XrResult xrLocateSceneComponentsMSFT(
    XrSceneMSFT                                 scene,
    const XrSceneComponentsLocateInfoMSFT*      locateInfo,
    XrSceneComponentLocationsMSFT*              locations);

Parameters

Parameter Descriptions

scene is a handle to an XrSceneMSFT.
locateInfo is a pointer to XrSceneComponentsLocateInfoMSFT describing information to locate scene components.
locations is a pointer to XrSceneComponentLocationsMSFT receiving the returned scene component locations.

Description

The runtime must return XR_ERROR_SIZE_INSUFFICIENT if XrSceneComponentLocationsMSFT::locationCount is less than XrSceneComponentsLocateInfoMSFT::componentIdCount.

Note

Similar to xrLocateSpace, apps should call xrLocateSceneComponentsMSFT each frame because the location returned by xrLocateSceneComponentsMSFT in later frames may change over time as the target space or the scene components may refine their locations.

Valid Usage (Implicit)

The [XR_MSFT_scene_understanding] extension must be enabled prior to calling xrLocateSceneComponentsMSFT
scene must be a valid XrSceneMSFT handle
locateInfo must be a pointer to a valid XrSceneComponentsLocateInfoMSFT structure
locations must be a pointer to an XrSceneComponentLocationsMSFT structure

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

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

xrLocateSpace(3)

Name

xrLocateSpace - Locates a space with reference to another space

C Specification

xrLocateSpace provides the physical location of a space in a base space at a specified time, if currently known by the runtime.

XrResult xrLocateSpace(
    XrSpace                                     space,
    XrSpace                                     baseSpace,
    XrTime                                      time,
    XrSpaceLocation*                            location);

Parameters

Parameter Descriptions

space identifies the target space to locate.
baseSpace identifies the underlying space in which to locate space.
time is the time for which the location should be provided.
location provides the location of space in baseSpace.

Description

For a time in the past, the runtime should locate the spaces based on the runtime’s most accurate current understanding of how the world was at that historical time.

For a time in the future, the runtime should locate the spaces based on the runtime’s most up-to-date prediction of how the world will be at that future time.

The minimum valid range of values for time are described in https://www.khronos.org/registry/OpenXR/specs/1.0/html/xrspec.html#prediction-time-limits. For values of time outside this range, xrLocateSpace may return a location with no position and XR_SPACE_LOCATION_POSITION_VALID_BIT unset.

Some devices improve their understanding of the world as the device is used. The location returned by xrLocateSpace for a given space, baseSpace and time may change over time, even for spaces that track static objects, as one or both spaces adjust their origins.

During tracking loss of space relative to baseSpace, runtimes should continue to provide inferred or last-known position and orientation values. These inferred poses can, for example, be based on neck model updates, inertial dead reckoning, or a last-known position, so long as it is still reasonable for the application to use that pose. While a runtime is providing position data, it must continue to set XR_SPACE_LOCATION_POSITION_VALID_BIT but it can clear XR_SPACE_LOCATION_POSITION_TRACKED_BIT to indicate that the position is inferred or last-known in this way.

If the runtime has not yet observed even a last-known pose for how to locate space in baseSpace (e.g. one space is an action space bound to a motion controller that has not yet been detected, or the two spaces are in disconnected fragments of the runtime’s tracked volume), the runtime should return a location with no position and XR_SPACE_LOCATION_POSITION_VALID_BIT unset.

The runtime must return a location with both XR_SPACE_LOCATION_POSITION_VALID_BIT and XR_SPACE_LOCATION_POSITION_TRACKED_BIT set when locating space and baseSpace if both spaces were created relative to the same entity (e.g. two action spaces for the same action), even if the entity is currently untracked. The location in this case is the difference in the two spaces' application-specified transforms relative to that common entity.

The runtime should return a location with XR_SPACE_LOCATION_POSITION_VALID_BIT set and XR_SPACE_LOCATION_POSITION_TRACKED_BIT unset for spaces tracking two static entities in the world when their relative pose is known to the runtime. This enables applications to make use of the runtime’s latest knowledge of the world, even during tracking loss.

If an XrSpaceVelocity structure is chained to the next pointer of XrSpaceLocation and the velocity is observed or can be calculated by the runtime, the runtime must fill in the linear velocity of the origin of space within the reference frame of baseSpace and set the XR_SPACE_VELOCITY_LINEAR_VALID_BIT. Similarly, if an XrSpaceVelocity structure is chained to the next pointer of XrSpaceLocation and the angular velocity is observed or can be calculated by the runtime, the runtime must fill in the angular velocity of the origin of space within the reference frame of baseSpace and set the XR_SPACE_VELOCITY_ANGULAR_VALID_BIT.

The following example code shows how an application can get both the location and velocity of a space within a base space using the xrLocateSpace function by chaining an XrSpaceVelocity to the next pointer of XrSpaceLocation and calling xrLocateSpace.

XrSpace space;      // previously initialized
XrSpace baseSpace;  // previously initialized
XrTime time;        // previously initialized

XrSpaceVelocity velocity {XR_TYPE_SPACE_VELOCITY};
XrSpaceLocation location {XR_TYPE_SPACE_LOCATION, &velocity};
xrLocateSpace(space, baseSpace, time, &location);

Valid Usage (Implicit)

space must be a valid XrSpace handle
baseSpace must be a valid XrSpace handle
location must be a pointer to an XrSpaceLocation structure
Both of baseSpace and space must have been created, allocated, or retrieved from the same XrSession

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

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

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

xrLocateViews(3)

Name

xrLocateViews - Gets view and projection info

C Specification

The xrLocateViews function is defined as:

XrResult xrLocateViews(
    XrSession                                   session,
    const XrViewLocateInfo*                     viewLocateInfo,
    XrViewState*                                viewState,
    uint32_t                                    viewCapacityInput,
    uint32_t*                                   viewCountOutput,
    XrView*                                     views);

Parameters

Parameter Descriptions

session is a handle to the provided XrSession.
viewLocateInfo is a pointer to a valid XrViewLocateInfo structure.
viewState is the output structure with the viewer state information.
viewCapacityInput is an input parameter which specifies the capacity of the views array. The required capacity must be same as defined by the corresponding XrViewConfigurationType.
viewCountOutput is an output parameter which identifies the valid count of views.
views is an array of XrView.
See Buffer Size Parameters chapter for a detailed description of retrieving the required views size.

Description

The xrLocateViews function returns the view and projection info for a particular display time. This time is typically the target display time for a given frame. Repeatedly calling xrLocateViews with the same time may not necessarily return the same result. Instead the prediction gets increasingly accurate as the function is called closer to the given time for which a prediction is made. This allows an application to get the predicted views as late as possible in its pipeline to get the least amount of latency and prediction error.

xrLocateViews returns an array of XrView elements, one for each view of the specified view configuration type, along with an XrViewState containing additional state data shared across all views. The eye each view corresponds to is statically defined in XrViewConfigurationType in case the application wants to apply eye-specific rendering traits. The XrViewState and XrView member data may change on subsequent calls to xrLocateViews, and so applications must not assume it to be constant.

Valid Usage (Implicit)

session must be a valid XrSession handle
viewLocateInfo must be a pointer to a valid XrViewLocateInfo structure
viewState must be a pointer to an XrViewState structure
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 XrView structures

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_VIEW_CONFIGURATION_TYPE_UNSUPPORTED
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

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

xrPassthroughLayerPauseFB(3)

Name

xrPassthroughLayerPauseFB - Pause a passthrough layer

C Specification

The xrPassthroughLayerPauseFB function is defined as:

XrResult xrPassthroughLayerPauseFB(
    XrPassthroughLayerFB                        layer);

Parameters

Parameter Descriptions

layer is the XrPassthroughLayerFB to be paused.

Description

Pauses an XrPassthroughLayerFB layer. Runtime will not render or composite paused layers.

Valid Usage (Implicit)

The [XR_FB_passthrough] extension must be enabled prior to calling xrPassthroughLayerPauseFB
layer must be a valid XrPassthroughLayerFB handle

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_UNEXPECTED_STATE_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

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

xrPassthroughLayerResumeFB(3)

Name

xrPassthroughLayerResumeFB - Resume a passthrough layer

C Specification

The xrPassthroughLayerResumeFB function is defined as:

XrResult xrPassthroughLayerResumeFB(
    XrPassthroughLayerFB                        layer);

Parameters

Parameter Descriptions

layer is the XrPassthroughLayerFB to be resumed.

Description

Resumes an XrPassthroughLayerFB layer.

Valid Usage (Implicit)

The [XR_FB_passthrough] extension must be enabled prior to calling xrPassthroughLayerResumeFB
layer must be a valid XrPassthroughLayerFB handle

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_UNEXPECTED_STATE_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

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

xrPassthroughLayerSetStyleFB(3)

Name

xrPassthroughLayerSetStyleFB - Set style on a passthrough layer

C Specification

The xrPassthroughLayerSetStyleFB function is defined as:

XrResult xrPassthroughLayerSetStyleFB(
    XrPassthroughLayerFB                        layer,
    const XrPassthroughStyleFB*                 style);

Parameters

Parameter Descriptions

layer is the XrPassthroughLayerFB to get the style.
style is the XrPassthroughStyleFB to be set.

Description

Sets an XrPassthroughStyleFB style on an XrPassthroughLayerFB layer.

Valid Usage (Implicit)

The [XR_FB_passthrough] extension must be enabled prior to calling xrPassthroughLayerSetStyleFB
layer must be a valid XrPassthroughLayerFB handle
style must be a pointer to a valid XrPassthroughStyleFB structure

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

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

xrPassthroughPauseFB(3)

Name

xrPassthroughPauseFB - Pause a passthrough feature

C Specification

The xrPassthroughPauseFB function is defined as:

XrResult xrPassthroughPauseFB(
    XrPassthroughFB                             passthrough);

Parameters

Parameter Descriptions

passthrough is the XrPassthroughFB to be paused.

Description

Pauses an XrPassthroughFB feature. When the feature is paused, runtime will stop rendering and compositing all passthrough layers produced on behalf of the application, and may free up some or all the resources used to produce passthrough until xrPassthroughStartFB is called.

Valid Usage (Implicit)

The [XR_FB_passthrough] extension must be enabled prior to calling xrPassthroughPauseFB
passthrough must be a valid XrPassthroughFB handle

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_UNEXPECTED_STATE_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

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

xrPassthroughStartFB(3)

Name

xrPassthroughStartFB - Start a passthrough feature

C Specification

The xrPassthroughStartFB function is defined as:

XrResult xrPassthroughStartFB(
    XrPassthroughFB                             passthrough);

Parameters

Parameter Descriptions

passthrough is the XrPassthroughFB to be started.

Description

Starts an XrPassthroughFB feature. If the feature is not started, either explicitly with a call to xrPassthroughStartFB, or implicitly at creation using the behavior flags, it is considered paused. When the feature is paused, runtime will stop rendering and compositing all passthrough layers produced on behalf of the application, and may free up some or all the resources used to produce passthrough until xrPassthroughStartFB is called.

Valid Usage (Implicit)

The [XR_FB_passthrough] extension must be enabled prior to calling xrPassthroughStartFB
passthrough must be a valid XrPassthroughFB handle

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_UNEXPECTED_STATE_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

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

xrPathToString(3)

Name

xrPathToString - Converts a semantic path to a string

C Specification

XrResult xrPathToString(
    XrInstance                                  instance,
    XrPath                                      path,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    char*                                       buffer);

Parameters

Parameter Descriptions

instance is an instance previously created.
path is the valid XrPath value to retrieve the path string for.
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 (including the terminating '\0'), or a pointer to the required capacity in the case that bufferCapacityInput is 0.
buffer is a pointer to an application-allocated buffer that will be filled with the semantic path string. It can be NULL if bufferCapacityInput is 0.
See Buffer Size Parameters chapter for a detailed description of retrieving the required buffer size.

Description

xrPathToString retrieves the path name string associated with an XrPath, in the context of a given XrInstance, in the form of a NULL terminated string placed into a caller-allocated buffer. Since the mapping between a well-formed path name string and an XrPath is bijective, there will always be exactly one string for each valid XrPath value. This can be useful if the calling application receives an XrPath value that they had not previously retrieved via xrStringToPath. During the lifetime of the given XrInstance, the path name string retrieved by this function for a given valid XrPath will not change. For invalid paths, including XR_NULL_PATH, XR_ERROR_PATH_INVALID must be returned.

Valid Usage (Implicit)

instance must be a valid XrInstance handle
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

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_PATH_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

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

xrPerfSettingsSetPerformanceLevelEXT(3)

Name

xrPerfSettingsSetPerformanceLevelEXT - xrPerfSettingsSetPerformanceLevelEXT

C Specification

XrResult xrPerfSettingsSetPerformanceLevelEXT(
    XrSession                                   session,
    XrPerfSettingsDomainEXT                     domain,
    XrPerfSettingsLevelEXT                      level);

Parameters

Parameter Descriptions

session is a valid XrSession handle.
domain: the processing domain for which the level hint is applied
level: the level hint to be applied

Description

Valid Usage (Implicit)

The [XR_EXT_performance_settings] extension must be enabled prior to calling xrPerfSettingsSetPerformanceLevelEXT
session must be a valid XrSession handle
domain must be a valid XrPerfSettingsDomainEXT value
level must be a valid XrPerfSettingsLevelEXT value

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

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

xrPersistSpatialAnchorMSFT(3)

Name

xrPersistSpatialAnchorMSFT - Persist the spatial anchor in the spatial anchor store

C Specification

The application can use the xrPersistSpatialAnchorMSFT function to persist a spatial anchor in the spatial anchor store for this application. The given spatialAnchorName will be the string to retrieve the spatial anchor from the Spatial Anchor store or subsequently remove the record of this spatial anchor from the store. This name will uniquely identify the spatial anchor for the current application. If there is already a spatial anchor of the same name persisted in the spatial anchor store, the existing spatial anchor will be replaced and xrPersistSpatialAnchorMSFT must return XR_SUCCESS.

XrResult xrPersistSpatialAnchorMSFT(
    XrSpatialAnchorStoreConnectionMSFT          spatialAnchorStore,
    const XrSpatialAnchorPersistenceInfoMSFT*   spatialAnchorPersistenceInfo);

Parameters

Parameter Descriptions

spatialAnchorStore is the XrSpatialAnchorStoreConnectionMSFT with which to persist the spatialAnchor.
spatialAnchorPersistenceInfo is a pointer to XrSpatialAnchorPersistenceInfoMSFT structure to specify the anchor and its name to persist.

Description

Valid Usage (Implicit)

The [XR_MSFT_spatial_anchor_persistence] extension must be enabled prior to calling xrPersistSpatialAnchorMSFT
spatialAnchorStore must be a valid XrSpatialAnchorStoreConnectionMSFT handle
spatialAnchorPersistenceInfo must be a pointer to a valid XrSpatialAnchorPersistenceInfoMSFT structure

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

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

xrPollEvent(3)

Name

xrPollEvent - Polls for events

C Specification

XrResult xrPollEvent(
    XrInstance                                  instance,
    XrEventDataBuffer*                          eventData);

Parameters

xrPollEvent polls for the next event and returns an event if one is available. xrPollEvent returns immediately regardless of whether an event was available. The event (if present) is unilaterally removed from the queue if a valid XrInstance is provided. On return the eventData parameter is filled with the event’s data and the type field is changed to the event’s type. Runtimes may create valid next chains depending on enabled extensions, but they must guarantee that any such chains point only to objects which fit completely within the original XrEventDataBuffer pointed to by eventData.

Description

Parameter Descriptions

instance is a valid XrInstance.
eventData is a pointer to a valid XrEventDataBuffer.

Valid Usage (Implicit)

instance must be a valid XrInstance handle
eventData must be a pointer to an XrEventDataBuffer structure

Return Codes

On success, this command returns

XR_SUCCESS
XR_EVENT_UNAVAILABLE

On failure, this command returns

XR_ERROR_VALIDATION_FAILURE
XR_ERROR_RUNTIME_FAILURE
XR_ERROR_HANDLE_INVALID
XR_ERROR_INSTANCE_LOST

The runtime must discard queued events which contain destroyed or otherwise invalid handles.

Table 2. Event Descriptions
Event	Description
XrEventDataEventsLost	event queue has overflowed and some events were lost
XrEventDataInstanceLossPending	application is about to lose the instance
XrEventDataInteractionProfileChanged	active input form factor for one or more top level user paths has changed
XrEventDataReferenceSpaceChangePending	runtime will begin operating with updated space bounds
XrEventDataSessionStateChanged	application has changed lifecycle state

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

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

xrReleaseSwapchainImage(3)

Name

xrReleaseSwapchainImage - Release a swapchain image

C Specification

The xrReleaseSwapchainImage function is defined as:

XrResult xrReleaseSwapchainImage(
    XrSwapchain                                 swapchain,
    const XrSwapchainImageReleaseInfo*          releaseInfo);

Parameters

Parameter Descriptions

swapchain is the XrSwapchain from which to release an image.
releaseInfo exists for extensibility purposes, it is NULL or a pointer to a valid XrSwapchainImageReleaseInfo.

Description

If the swapchain was created with the XR_SWAPCHAIN_CREATE_STATIC_IMAGE_BIT set in XrSwapchainCreateInfo::createFlags structure, this function must not have been previously called for this swapchain.

The runtime must return XR_ERROR_CALL_ORDER_INVALID if no image has been waited on by calling xrWaitSwapchainImage.

Valid Usage (Implicit)

swapchain must be a valid XrSwapchain handle
If releaseInfo is not NULL, releaseInfo must be a pointer to a valid XrSwapchainImageReleaseInfo structure

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

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

xrRequestDisplayRefreshRateFB(3)

Name

xrRequestDisplayRefreshRateFB - Request a display refresh rate

C Specification

The xrRequestDisplayRefreshRateFB function is defined as:

XrResult xrRequestDisplayRefreshRateFB(
    XrSession                                   session,
    float                                       displayRefreshRate);

Parameters

Parameter Descriptions

session is a valid XrSession handle.
displayRefreshRate is 0.0f or a supported display refresh rate. Supported display refresh rates are indicated by xrEnumerateDisplayRefreshRatesFB.

Description

xrRequestDisplayRefreshRateFB provides a mechanism for an application to request the system to dynamically change the display refresh rate to the application preferred value. The runtime must return XR_ERROR_DISPLAY_REFRESH_RATE_UNSUPPORTED_FB if displayRefreshRate is not either 0.0f or one of the values enumerated by xrEnumerateDisplayRefreshRatesFB. A display refresh rate of 0.0f indicates the application has no preference.

Note that this is only a request and does not guarantee the system will switch to the requested display refresh rate.

Valid Usage (Implicit)

The [XR_FB_display_refresh_rate] extension must be enabled prior to calling xrRequestDisplayRefreshRateFB
session must be a valid XrSession handle

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
XR_ERROR_DISPLAY_REFRESH_RATE_UNSUPPORTED_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

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

xrRequestExitSession(3)

Name

xrRequestExitSession - Request to exit a running session.

C Specification

When an application wishes to exit a running session, it can call xrRequestExitSession, requesting that the runtime transition through the various intermediate session states including XR_SESSION_STATE_STOPPING to XR_SESSION_STATE_EXITING.

On platforms where an application’s lifecycle is managed by the system, session state changes may be implicitly triggered by application lifecycle state changes. On such platforms, using platform-specific methods to alter application lifecycle state may be the preferred method of provoking session state changes. The behavior of xrRequestExitSession is not altered, however explicit session exit may not interact with the platform-specific application lifecycle.

The xrRequestExitSession function is defined as:

XrResult xrRequestExitSession(
    XrSession                                   session);

Parameters

Parameter Descriptions

session is a handle to a running XrSession.

Description

If session is not running when xrRequestExitSession is called, XR_ERROR_SESSION_NOT_RUNNING must be returned.

Valid Usage (Implicit)

session must be a valid XrSession handle

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

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

xrResultToString(3)

Name

xrResultToString - Converts an XrResult to a UTF-8 string

C Specification

XrResult xrResultToString(
    XrInstance                                  instance,
    XrResult                                    value,
    char                                        buffer[XR_MAX_RESULT_STRING_SIZE]);

Parameters

Parameter Descriptions

instance is the handle of the instance to ask for the string.
value is the XrResult value to turn into a string.
buffer is the buffer that will be used to return the string in.

Description

Returns the text version of the provided XrResult value as a UTF-8 string.

In all cases the returned string must be one of:

Result String Return Values

The literal string defined for the provide numeric value in the core spec or extension. (e.g. the value 0 results in the string XR_SUCCESS)
XR_UNKNOWN_SUCCESS_ concatenated with the positive result number expressed as a decimal number.
XR_UNKNOWN_FAILURE_ concatenated with the negative result number expressed as a decimal number.

Valid Usage (Implicit)

instance must be a valid XrInstance handle
value must be a valid XrResult value
buffer must be a character array of length XR_MAX_RESULT_STRING_SIZE

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

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

xrSessionBeginDebugUtilsLabelRegionEXT(3)

Name

xrSessionBeginDebugUtilsLabelRegionEXT - Session begin debug utils label region

C Specification

XrResult xrSessionBeginDebugUtilsLabelRegionEXT(
    XrSession                                   session,
    const XrDebugUtilsLabelEXT*                 labelInfo);

Parameters

Parameter Descriptions

session is the XrSession that a label region should be associated with.
labelInfo is the XrDebugUtilsLabelEXT containing the label information for the region that should be begun.

Description

Valid Usage (Implicit)

The [XR_EXT_debug_utils] extension must be enabled prior to calling xrSessionBeginDebugUtilsLabelRegionEXT
session must be a valid XrSession handle
labelInfo must be a pointer to a valid XrDebugUtilsLabelEXT structure

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

The xrSessionBeginDebugUtilsLabelRegionEXT function begins a label region within session.

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

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

xrSessionEndDebugUtilsLabelRegionEXT(3)

Name

xrSessionEndDebugUtilsLabelRegionEXT - Session end debug utils label region

C Specification

XrResult xrSessionEndDebugUtilsLabelRegionEXT(
    XrSession                                   session);

Parameters

Parameter Descriptions

session is the XrSession that a label region should be associated with.

Description

Valid Usage

xrSessionEndDebugUtilsLabelRegionEXT must be called only after a matching xrSessionBeginDebugUtilsLabelRegionEXT.

Valid Usage (Implicit)

The [XR_EXT_debug_utils] extension must be enabled prior to calling xrSessionEndDebugUtilsLabelRegionEXT
session must be a valid XrSession handle

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

This function ends the last label region begun with the xrSessionBeginDebugUtilsLabelRegionEXT function within the same session.

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

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

xrSessionInsertDebugUtilsLabelEXT(3)

Name

xrSessionInsertDebugUtilsLabelEXT - Session insert debug utils label

C Specification

XrResult xrSessionInsertDebugUtilsLabelEXT(
    XrSession                                   session,
    const XrDebugUtilsLabelEXT*                 labelInfo);

Parameters

Parameter Descriptions

session is the XrSession that a label region should be associated with.
labelInfo is the XrDebugUtilsLabelEXT containing the label information for the region that should be begun.

Description

Valid Usage (Implicit)

The [XR_EXT_debug_utils] extension must be enabled prior to calling xrSessionInsertDebugUtilsLabelEXT
session must be a valid XrSession handle
labelInfo must be a pointer to a valid XrDebugUtilsLabelEXT structure

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

The xrSessionInsertDebugUtilsLabelEXT function inserts an individual label within session. The individual labels are useful for different reasons based on the type of debugging scenario. When used with something active like a profiler or debugger, it identifies a single point of time. When used with logging, the individual label identifies that a particular location has been passed at the point the log message is triggered. Because of this usage, individual labels only exist in a log until the next call to any of the label functions:

xrSessionBeginDebugUtilsLabelRegionEXT
xrSessionEndDebugUtilsLabelRegionEXT
xrSessionInsertDebugUtilsLabelEXT

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

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

xrSetAndroidApplicationThreadKHR(3)

Name

xrSetAndroidApplicationThreadKHR - declare threads to be of a certain priority type

C Specification

To declare a thread to be of a certain XrAndroidThreadTypeKHR type call:

XrResult xrSetAndroidApplicationThreadKHR(
    XrSession                                   session,
    XrAndroidThreadTypeKHR                      threadType,
    uint32_t                                    threadId);

Parameters

Parameter Descriptions

session is a valid XrSession handle.
threadType is a classification of the declared thread allowing the XR runtime to apply the relevant priority and attributes. If such settings fail, the runtime must return XR_ERROR_ANDROID_THREAD_SETTINGS_FAILURE_KHR.
threadId is the kernel thread ID of the declared thread, as returned by gettid() or android.os.process.myTid(). If the thread ID is invalid, the runtime must return XR_ERROR_ANDROID_THREAD_SETTINGS_ID_INVALID_KHR.

Description

xrSetAndroidApplicationThreadKHR allows to declare an XR-critical thread and to classify it.

Valid Usage (Implicit)

The [XR_KHR_android_thread_settings] extension must be enabled prior to calling xrSetAndroidApplicationThreadKHR
session must be a valid XrSession handle
threadType must be a valid XrAndroidThreadTypeKHR value

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_ANDROID_THREAD_SETTINGS_ID_INVALID_KHR
XR_ERROR_ANDROID_THREAD_SETTINGS_FAILURE_KHR

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

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

xrSetColorSpaceFB(3)

Name

xrSetColorSpaceFB - Set a color space

C Specification

The xrSetColorSpaceFB function is defined as:

XrResult xrSetColorSpaceFB(
    XrSession                                   session,
    const XrColorSpaceFB                        colorspace);

Parameters

Parameter Descriptions

session is a valid XrSession handle.
colorSpace is a supported color space. Supported color spaces are indicated by xrEnumerateColorSpacesFB.

Description

xrSetColorSpaceFB provides a mechanism for an application to specify the color space used in the final rendered frame. If this function is not called, the session will use the color space deemed appropriate by the runtime. Oculus HMDs for both PC and Mobile product lines default to XR_COLOR_SPACE_RIFT_CV1_FB. The runtime must return XR_ERROR_COLOR_SPACE_UNSUPPORTED_FB if colorSpace is not one of the values enumerated by xrEnumerateColorSpacesFB.

Valid Usage (Implicit)

The [XR_FB_color_space] extension must be enabled prior to calling xrSetColorSpaceFB
session must be a valid XrSession handle
colorspace must be a valid XrColorSpaceFB value

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
XR_ERROR_COLOR_SPACE_UNSUPPORTED_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

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

xrSetDebugUtilsObjectNameEXT(3)

Name

xrSetDebugUtilsObjectNameEXT - Sets debug utils object name

C Specification

XrResult xrSetDebugUtilsObjectNameEXT(
    XrInstance                                  instance,
    const XrDebugUtilsObjectNameInfoEXT*        nameInfo);

Parameters

Parameter Descriptions

instance is the XrInstance that the object was created under.
nameInfo is a pointer to an instance of the XrDebugUtilsObjectNameInfoEXT structure specifying the parameters of the name to set on the object.

Description

Valid Usage

In the structure pointed to by nameInfo, XrDebugUtilsObjectNameInfoEXT::objectType must not be XR_OBJECT_TYPE_UNKNOWN
In the structure pointed to by nameInfo, XrDebugUtilsObjectNameInfoEXT::objectHandle must not be XR_NULL_HANDLE

Valid Usage (Implicit)

The [XR_EXT_debug_utils] extension must be enabled prior to calling xrSetDebugUtilsObjectNameEXT
instance must be a valid XrInstance handle
nameInfo must be a pointer to a valid XrDebugUtilsObjectNameInfoEXT structure

Thread Safety

Access to the objectHandle member of the nameInfo parameter 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

Applications may change the name associated with an object simply by calling xrSetDebugUtilsObjectNameEXT again with a new string. If XrDebugUtilsObjectNameInfoEXT::objectName is an empty string, then any previously set name is removed.

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

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

xrSetEnvironmentDepthEstimationVARJO(3)

Name

xrSetEnvironmentDepthEstimationVARJO - Enable or disable environment depth estimation functionality

C Specification

The xrSetEnvironmentDepthEstimationVARJO function is defined as:

XrResult xrSetEnvironmentDepthEstimationVARJO(
    XrSession                                   session,
    XrBool32                                    enabled);

Parameters

Parameter Descriptions

session is an XrSession handle previously created with xrCreateSession.
enabled is a boolean that specifies whether depth estimation functionality should be activated. Compositor will disable depth estimation functionality if environment blend mode is not XR_ENVIRONMENT_BLEND_MODE_ALPHA_BLEND and will enable the functionality when environment blend mode is set to XR_ENVIRONMENT_BLEND_MODE_ALPHA_BLEND.

Description

Valid Usage (Implicit)

The [XR_VARJO_environment_depth_estimation] extension must be enabled prior to calling xrSetEnvironmentDepthEstimationVARJO
session must be a valid XrSession handle

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

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

xrSetInputDeviceActiveEXT(3)

Name

xrSetInputDeviceActiveEXT - Sets the active state of the input device

C Specification

XrResult xrSetInputDeviceActiveEXT(
    XrSession                                   session,
    XrPath                                      interactionProfile,
    XrPath                                      topLevelPath,
    XrBool32                                    isActive);

Parameters

Parameter Descriptions

session is the XrSession to set the input device state in.
interactionProfile is the path representing the interaction profile of the input device (e.g. /interaction_profiles/khr/simple_controller).
topLevelPath is the path representing the input device (e.g. /user/hand/left).
isActive is the requested activation state of the input device.

Description

Warning

This belongs to the [XR_EXT_conformance_automation] extension. This extension is not intended for use by non-conformance-test applications. A runtime may require a runtime-specified configuration such as a "developer mode" to be enabled before reporting support for this extension or providing a non-stub implementation of it.

Do not use this functionality in a non-conformance-test application!

Valid Usage

session must be a valid session handle.
topLevelPath must be a valid top level path.

Valid Usage (Implicit)

The [XR_EXT_conformance_automation] extension must be enabled prior to calling xrSetInputDeviceActiveEXT
session must be a valid XrSession handle

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

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

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

xrSetInputDeviceLocationEXT(3)

Name

xrSetInputDeviceLocationEXT - Sets the effective location of a pose input source on the input device

C Specification

XrResult xrSetInputDeviceLocationEXT(
    XrSession                                   session,
    XrPath                                      topLevelPath,
    XrPath                                      inputSourcePath,
    XrSpace                                     space,
    XrPosef                                     pose);

Parameters

Parameter Descriptions

session is the XrSession to set the input device state in.
topLevelPath is the path representing the input device (e.g. /user/hand/left).
inputSourcePath is the full path of the input component for which we wish to set the pose for (e.g. /user/hand/left/input/grip/pose).
pose is the requested pose state of the input device.

Description

Warning

Do not use this functionality in a non-conformance-test application!

Valid Usage

session must be a valid session handle.
topLevelPath must be a valid top level path.
inputSourcePath must be a valid input source path.

Valid Usage (Implicit)

The [XR_EXT_conformance_automation] extension must be enabled prior to calling xrSetInputDeviceLocationEXT
session must be a valid XrSession handle
space must be a valid XrSpace handle
space must have been created, allocated, or retrieved from session

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_POSE_INVALID
XR_ERROR_PATH_UNSUPPORTED
XR_ERROR_PATH_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

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

xrSetInputDeviceStateBoolEXT(3)

Name

xrSetInputDeviceStateBoolEXT - Sets the state of a boolean input source on the input device

C Specification

XrResult xrSetInputDeviceStateBoolEXT(
    XrSession                                   session,
    XrPath                                      topLevelPath,
    XrPath                                      inputSourcePath,
    XrBool32                                    state);

Parameters

Parameter Descriptions

session is the XrSession to set the input device state in.
topLevelPath is the path representing the input device (e.g. /user/hand/left).
inputSourcePath is the full path of the input component for which we wish to set the state for (e.g. /user/hand/left/input/select/click).
state is the requested boolean state of the input device.

Description

Warning

Do not use this functionality in a non-conformance-test application!

Valid Usage

session must be a valid session handle.
topLevelPath must be a valid top level path.
inputSourcePath must be a valid input source path.

Valid Usage (Implicit)

The [XR_EXT_conformance_automation] extension must be enabled prior to calling xrSetInputDeviceStateBoolEXT
session must be a valid XrSession handle

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

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

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

xrSetInputDeviceStateFloatEXT(3)

Name

xrSetInputDeviceStateFloatEXT - Sets the state of a float input source on the input device

C Specification

XrResult xrSetInputDeviceStateFloatEXT(
    XrSession                                   session,
    XrPath                                      topLevelPath,
    XrPath                                      inputSourcePath,
    float                                       state);

Parameters

Parameter Descriptions

session is the XrSession to set the input device state in.
topLevelPath is the path representing the input device (e.g. /user/hand/left).
inputSourcePath is the full path of the input component for which we wish to set the state for (e.g. /user/hand/left/input/trigger/value).
state is the requested float state of the input device.

Description

Warning

Do not use this functionality in a non-conformance-test application!

Valid Usage

session must be a valid session handle.
topLevelPath must be a valid top level path.
inputSourcePath must be a valid input source path.

Valid Usage (Implicit)

The [XR_EXT_conformance_automation] extension must be enabled prior to calling xrSetInputDeviceStateFloatEXT
session must be a valid XrSession handle

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

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

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

xrSetInputDeviceStateVector2fEXT(3)

Name

xrSetInputDeviceStateVector2fEXT - Sets the state of a 2D vector input source on the input device

C Specification

XrResult xrSetInputDeviceStateVector2fEXT(
    XrSession                                   session,
    XrPath                                      topLevelPath,
    XrPath                                      inputSourcePath,
    XrVector2f                                  state);

Parameters

Parameter Descriptions

session is the XrSession to set the input device state in.
topLevelPath is the path representing the input device (e.g. /user/hand/left).
inputSourcePath is the full path of the input component for which we wish to set the state for (e.g. /user/hand/left/input/thumbstick).
state is the requested two-dimensional state of the input device.

Description

Warning

Do not use this functionality in a non-conformance-test application!

Valid Usage

session must be a valid session handle.
topLevelPath must be a valid top level path.
inputSourcePath must be a valid input source path.

Valid Usage (Implicit)

The [XR_EXT_conformance_automation] extension must be enabled prior to calling xrSetInputDeviceStateVector2fEXT
session must be a valid XrSession handle

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

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

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

xrSetMarkerTrackingPredictionVARJO(3)

Name

xrSetMarkerTrackingPredictionVARJO - Sets marker tracking with prediction

C Specification

The xrSetMarkerTrackingPredictionVARJO function is defined as:

XrResult xrSetMarkerTrackingPredictionVARJO(
    XrSession                                   session,
    uint64_t                                    markerId,
    XrBool32                                    enabled);

Parameters

Parameter Descriptions

session is an XrSession handle previously created with xrCreateSession.
markerId is the unique identifier of the marker which should be tracked with prediction.
enable is whether to enable the prediction feature.

Description

The xrSetMarkerTrackingPredictionVARJO function enables or disables the prediction feature for a specified marker. By default, markers are created with disabled prediction. This works well for markers that are supposed to be stationary. The prediction can be used to improve tracking of movable markers. The runtime must return XR_ERROR_MARKER_ID_INVALID_VARJO if the supplied markerId is invalid.

Valid Usage (Implicit)

The [XR_VARJO_marker_tracking] extension must be enabled prior to calling xrSetMarkerTrackingPredictionVARJO
session must be a valid XrSession handle

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

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

xrSetMarkerTrackingTimeoutVARJO(3)

Name

xrSetMarkerTrackingTimeoutVARJO - Sets marker lifetime duration

C Specification

The xrSetMarkerTrackingTimeoutVARJO function is defined as:

XrResult xrSetMarkerTrackingTimeoutVARJO(
    XrSession                                   session,
    uint64_t                                    markerId,
    XrDuration                                  timeout);

Parameters

Parameter Descriptions

session is an XrSession handle previously created with xrCreateSession.
markerId is the unique identifier of the marker for which the timeout will be updated.
timeout is the desired lifetime duration for a specified marker.

Description

The xrSetMarkerTrackingTimeoutVARJO function sets a desired lifetime duration for a specified marker. The default value is XR_NO_DURATION. Negative value will be clamped to XR_NO_DURATION. It defines the time period during which the runtime must keep returning poses of previously tracked markers. The tracking may be lost if the marker went outside of the trackable field of view. In this case the runtime still will try to predict marker’s pose for the timeout period. The runtime must return XR_ERROR_MARKER_ID_INVALID_VARJO if the supplied markerId is invalid.

Valid Usage (Implicit)

The [XR_VARJO_marker_tracking] extension must be enabled prior to calling xrSetMarkerTrackingTimeoutVARJO
session must be a valid XrSession handle

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

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

xrSetMarkerTrackingVARJO(3)

Name

xrSetMarkerTrackingVARJO - Enables marker tracking

C Specification

The xrSetMarkerTrackingVARJO function is defined as:

XrResult  xrSetMarkerTrackingVARJO(
    XrSession                                   session,
    XrBool32                                    enabled);

Parameters

Parameter Descriptions

session is an XrSession handle previously created with xrCreateSession.
enabled is the flag to enable or disable marker tracking.

Description

The xrSetMarkerTrackingVARJO function enables or disables marker tracking functionality. As soon as feature is become disabled all trackable markers become inactive and corresponding events will be generated. An application may call any of the functions in this extension regardless if the marker tracking functionality is enabled or disabled.

Valid Usage (Implicit)

The [XR_VARJO_marker_tracking] extension must be enabled prior to calling xrSetMarkerTrackingVARJO
session must be a valid XrSession handle

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

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

xrStopHapticFeedback(3)

Name

xrStopHapticFeedback - Stop haptic feedback

C Specification

The xrStopHapticFeedback function is defined as:

XrResult xrStopHapticFeedback(
    XrSession                                   session,
    const XrHapticActionInfo*                   hapticActionInfo);

Parameters

Parameter Descriptions

session is the XrSession to stop outputting to.
hapticActionInfo is a pointer to an XrHapticActionInfo to provide action and subaction path information.

Description

If a haptic event from this XrAction is in progress, when this function is called the runtime must stop that event.

If session is not focused, the runtime must return XR_SESSION_NOT_FOCUSED.

Valid Usage (Implicit)

session must be a valid XrSession handle
hapticActionInfo must be a pointer to a valid XrHapticActionInfo structure

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

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

xrStringToPath(3)

Name

xrStringToPath - Converts a string to a semantic path

C Specification

The xrStringToPath function is defined as:

XrResult xrStringToPath(
    XrInstance                                  instance,
    const char*                                 pathString,
    XrPath*                                     path);

Parameters

Parameter Descriptions

instance is an instance previously created.
pathString is the path name string to retrieve the associated XrPath for.
path is the output parameter, which must point to an XrPath. Given a well-formed path name string, this will be populated with an opaque value that is constant for that path string during the lifetime of that instance.

Description

xrStringToPath retrieves the XrPath value for a well-formed path string. If such a value had not yet been assigned by the runtime to the provided path string in this XrInstance, one must be assigned at this point. All calls to this function with the same XrInstance and path string must retrieve the same XrPath value. Upon failure, xrStringToPath must return an appropriate XrResult, and may set the output parameter to XR_NULL_PATH. See Path Atom Type for the conditions under which an error may be returned when this function is given a valid XrInstance and a well-formed path string.

If the runtime’s resources are exhausted and it cannot create the path, a return value of XR_ERROR_PATH_COUNT_EXCEEDED must be returned. If the application specifies a string that is not a well-formed path string, XR_ERROR_PATH_FORMAT_INVALID must be returned.

A return value of XR_SUCCESS from xrStringToPath may not necessarily imply that the runtime has a component or other source of data that will be accessible through that semantic path. It only means that the path string supplied was well-formed and that the retrieved XrPath maps to the given path string within and during the lifetime of the XrInstance given.

Valid Usage (Implicit)

instance must be a valid XrInstance handle
pathString must be a null-terminated UTF-8 string
path must be a pointer to an XrPath value

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_PATH_FORMAT_INVALID
XR_ERROR_PATH_COUNT_EXCEEDED

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

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

xrStructureTypeToString(3)

Name

xrStructureTypeToString - Converts an XrStructureType to a UTF-8 string

C Specification

The xrStructureTypeToString function is defined as:

XrResult xrStructureTypeToString(
    XrInstance                                  instance,
    XrStructureType                             value,
    char                                        buffer[XR_MAX_STRUCTURE_NAME_SIZE]);

Parameters

Parameter Descriptions

instance is the handle of the instance to ask for the string.
value is the XrStructureType value to turn into a string.
buffer is the buffer that will be used to return the string in.

Description

Returns the text version of the provided XrStructureType value as a UTF-8 string.

In all cases the returned string must be one of:

Structure Type String Return Values

The literal string defined for the provide numeric value in the core spec or extension. (e.g. the value of XR_TYPE_INSTANCE_CREATE_INFO results in the string XR_TYPE_INSTANCE_CREATE_INFO)
XR_UNKNOWN_STRUCTURE_TYPE_ concatenated with the structure type number expressed as a decimal number.

Valid Usage (Implicit)

instance must be a valid XrInstance handle
value must be a valid XrStructureType value
buffer must be a character array of length XR_MAX_STRUCTURE_NAME_SIZE

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

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

xrSubmitDebugUtilsMessageEXT(3)

Name

xrSubmitDebugUtilsMessageEXT - Submits debug utils message

C Specification

XrResult                                    xrSubmitDebugUtilsMessageEXT(
    XrInstance                                  instance,
    XrDebugUtilsMessageSeverityFlagsEXT         messageSeverity,
    XrDebugUtilsMessageTypeFlagsEXT             messageTypes,
    const XrDebugUtilsMessengerCallbackDataEXT* callbackData);

Parameters

Parameter Descriptions

instance is the debug stream’s XrInstance.
messageSeverity is a single bit value of XrDebugUtilsMessageSeverityFlagsEXT severity of this event/message.
messageTypes is an XrDebugUtilsMessageTypeFlagsEXT bitmask of XrDebugUtilsMessageTypeFlagBitsEXT specifying which types of event to identify this message with.
callbackData contains all the callback related data in the XrDebugUtilsMessengerCallbackDataEXT structure.

Description

Valid Usage

For each structure in objects found in callbackData, the value of XrDebugUtilsObjectNameInfoEXT::objectType must not be XR_OBJECT_TYPE_UNKNOWN

Valid Usage (Implicit)

The [XR_EXT_debug_utils] extension must be enabled prior to calling xrSubmitDebugUtilsMessageEXT
instance must be a valid XrInstance handle
messageSeverity must be a valid combination of XrDebugUtilsMessageSeverityFlagBitsEXT values
messageSeverity must not be 0
messageTypes must be a valid combination of XrDebugUtilsMessageTypeFlagBitsEXT values
messageTypes must not be 0
callbackData must be a pointer to a valid XrDebugUtilsMessengerCallbackDataEXT structure

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

The application can also produce a debug message, and submit it into the OpenXR messaging system.

The call will propagate through the layers and generate callback(s) as indicated by the message’s flags. The parameters are passed on to the callback in addition to the userData value that was defined at the time the messenger was created.

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

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

xrSuggestInteractionProfileBindings(3)

Name

xrSuggestInteractionProfileBindings - Sets the application-suggested bindings for the interaction profile

C Specification

The xrSuggestInteractionProfileBindings function is defined as:

XrResult xrSuggestInteractionProfileBindings(
    XrInstance                                  instance,
    const XrInteractionProfileSuggestedBinding* suggestedBindings);

Parameters

Parameter Descriptions

instance is the XrInstance for which the application would like to set suggested bindings
suggestedBindings is the XrInteractionProfileSuggestedBinding that the application would like to set

Description

xrSuggestInteractionProfileBindings sets an interaction profile for which the application can provide default bindings. The application can call xrSuggestInteractionProfileBindings once per interaction profile that it supports.

The application can provide any number of bindings for each action.

If the application successfully calls xrSuggestInteractionProfileBindings more than once for an interaction profile, the runtime must discard the previous suggested bindings and replace them with the new suggested bindings for that profile.

If the interaction profile path does not follow the structure defined in Interaction Profiles or suggested bindings contain paths that do not follow the format defined in Device input subpaths, the runtime must return XR_ERROR_PATH_UNSUPPORTED. If the interaction profile or input source for any of the suggested bindings does not exist in the allowlist defined in Interaction Profile Paths, the runtime must return XR_ERROR_PATH_UNSUPPORTED. A runtime must accept every valid binding in the allowlist though it is free to ignore any of them.

If the action set for any action referenced in the suggestedBindings parameter has been included in a call to xrAttachSessionActionSets, the implementation must return XR_ERROR_ACTIONSETS_ALREADY_ATTACHED.

Valid Usage (Implicit)

instance must be a valid XrInstance handle
suggestedBindings must be a pointer to a valid XrInteractionProfileSuggestedBinding structure

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_PATH_UNSUPPORTED
XR_ERROR_PATH_INVALID
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

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

xrSyncActions(3)

Name

xrSyncActions - Updates the current state of input actions

C Specification

The xrSyncActions function is defined as:

XrResult xrSyncActions(
    XrSession                                   session,
    const XrActionsSyncInfo*                    syncInfo);

Parameters

Parameter Descriptions

session is a handle to the XrSession that all provided action set handles belong to.
syncInfo is an XrActionsSyncInfo providing information to synchronize action states.

Description

xrSyncActions updates the current state of input actions. Repeated input action state queries between subsequent synchronization calls must return the same values. The XrActionSet structures referenced in the syncInfo.activeActionSets must have been previously attached to the session via xrAttachSessionActionSets. If any action sets not attached to this session are passed to xrSyncActions it must return XR_ERROR_ACTIONSET_NOT_ATTACHED. Subsets of the bound action sets can be synchronized in order to control which actions are seen as active.

If session is not focused, the runtime must return XR_SESSION_NOT_FOCUSED, and all action states in the session must be inactive.

Valid Usage (Implicit)

session must be a valid XrSession handle
syncInfo must be a pointer to a valid XrActionsSyncInfo structure

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

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

xrThermalGetTemperatureTrendEXT(3)

Name

xrThermalGetTemperatureTrendEXT - xrThermalGetTemperatureTrendEXT

C Specification

XrResult xrThermalGetTemperatureTrendEXT(
    XrSession                                   session,
    XrPerfSettingsDomainEXT                     domain,
    XrPerfSettingsNotificationLevelEXT*         notificationLevel,
    float*                                      tempHeadroom,
    float*                                      tempSlope);

Parameters

Parameter Descriptions

session is a valid XrSession handle.
domain : the processing domain
notificationLevel : the current warning level
tempHeadroom : temperature headroom in degrees Celsius, expressing how far the most-critical temperature of the domain is from its thermal throttling threshold temperature.
tempSlope : the current trend in degrees Celsius per second of the most critical temperature of the domain.

Description

Valid Usage (Implicit)

The [XR_EXT_thermal_query] extension must be enabled prior to calling xrThermalGetTemperatureTrendEXT
session must be a valid XrSession handle
domain must be a valid XrPerfSettingsDomainEXT value
notificationLevel must be a pointer to an XrPerfSettingsNotificationLevelEXT value
tempHeadroom must be a pointer to a float value
tempSlope must be a pointer to a float value

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

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

xrTriangleMeshBeginUpdateFB(3)

Name

xrTriangleMeshBeginUpdateFB - Begin an update of the mesh data

C Specification

The xrTriangleMeshBeginUpdateFB function is defined as:

XrResult xrTriangleMeshBeginUpdateFB(
    XrTriangleMeshFB                            mesh);

Parameters

Parameter Descriptions

mesh is the XrTriangleMeshFB to update.

Description

Begins updating the mesh buffer data. The application must call this function before it makes any modifications to the buffers retrieved by xrTriangleMeshGetVertexBufferFB and xrTriangleMeshGetIndexBufferFB. If only the vertex buffer needs to be updated, xrTriangleMeshBeginVertexBufferUpdateFB may be used instead. To commit the modifications, the application must call xrTriangleMeshEndUpdateFB. Runtime must return XR_ERROR_VALIDATION_FAILURE if the mesh is immutable.

Valid Usage (Implicit)

The [XR_FB_triangle_mesh] extension must be enabled prior to calling xrTriangleMeshBeginUpdateFB
mesh must be a valid XrTriangleMeshFB handle

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

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

xrTriangleMeshBeginVertexBufferUpdateFB(3)

Name

xrTriangleMeshBeginVertexBufferUpdateFB - Begin an update of the vertex data

C Specification

The xrTriangleMeshBeginVertexBufferUpdateFB function is defined as:

XrResult xrTriangleMeshBeginVertexBufferUpdateFB(
    XrTriangleMeshFB                            mesh,
    uint32_t*                                   outVertexCount);

Parameters

Parameter Descriptions

mesh is the XrTriangleMeshFB to update.
outVertexCount is the current vertex count. The updated data must have the exact same number of vertices.

Description

Begins an update of the vertex positions of a triangle mesh. Can only be called once the mesh topology has been set using xrTriangleMeshBeginUpdateFB followed by xrTriangleMeshEndUpdateFB. The vertex count is defined by the last invocation to xrTriangleMeshEndUpdateFB. Once the modification is done, call xrTriangleMeshEndVertexBufferUpdateFB to commit the changes. Runtime must return XR_ERROR_VALIDATION_FAILURE if an invalid count is passed. Runtime must return XR_ERROR_VALIDATION_FAILURE if the mesh is immutable.

Valid Usage (Implicit)

The [XR_FB_triangle_mesh] extension must be enabled prior to calling xrTriangleMeshBeginVertexBufferUpdateFB
mesh must be a valid XrTriangleMeshFB handle
outVertexCount 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_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

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

xrTriangleMeshEndUpdateFB(3)

Name

xrTriangleMeshEndUpdateFB - End an update of the mesh data

C Specification

The xrTriangleMeshEndUpdateFB function is defined as:

XrResult xrTriangleMeshEndUpdateFB(
    XrTriangleMeshFB                            mesh,
    uint32_t                                    vertexCount,
    uint32_t                                    triangleCount);

Parameters

Parameter Descriptions

mesh is the XrTriangleMeshFB to update.
vertexCount is the vertex count after the update.
triangleCount is the triangle count after the update.

Description

Signals to the runtime that the application has finished updating the mesh buffers following a call to xrTriangleMeshBeginUpdateFB. vertexCount and triangleCount specify the actual number of primitives that make up the mesh after the update. They must be larger than zero but smaller or equal to the maximum counts defined at create time.

Valid Usage (Implicit)

The [XR_FB_triangle_mesh] extension must be enabled prior to calling xrTriangleMeshEndUpdateFB
mesh must be a valid XrTriangleMeshFB handle

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

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

xrTriangleMeshEndVertexBufferUpdateFB(3)

Name

xrTriangleMeshEndVertexBufferUpdateFB - End an update of the vertex data

C Specification

The xrTriangleMeshEndVertexBufferUpdateFB function is defined as:

XrResult xrTriangleMeshEndVertexBufferUpdateFB(
    XrTriangleMeshFB                            mesh);

Parameters

Parameter Descriptions

mesh is the XrTriangleMeshFB to update.

Description

Signals to the runtime that the application has finished updating the vertex buffer data following a call to xrTriangleMeshBeginVertexBufferUpdateFB.

Valid Usage (Implicit)

The [XR_FB_triangle_mesh] extension must be enabled prior to calling xrTriangleMeshEndVertexBufferUpdateFB
mesh must be a valid XrTriangleMeshFB handle

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

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

xrTriangleMeshGetIndexBufferFB(3)

Name

xrTriangleMeshGetIndexBufferFB - Obtain the index buffer of a triangle mesh

C Specification

The xrTriangleMeshGetIndexBufferFB function is defined as:

XrResult xrTriangleMeshGetIndexBufferFB(
    XrTriangleMeshFB                            mesh,
    uint32_t**                                  outIndexBuffer);

Parameters

Parameter Descriptions

mesh is the XrTriangleMeshFB to get the index buffer for.
outIndexBuffer is a pointer to return the index buffer into.

Description

Retrieves a pointer to the index buffer that defines the topology of the triangle mesh. Each triplet of consecutive elements points to three vertices in the vertex buffer and thus form a triangle.

The application must call xrTriangleMeshBeginUpdateFB before making modifications to the index buffer. The buffer location is guaranteed to remain constant over the lifecycle of the mesh object.

Valid Usage (Implicit)

The [XR_FB_triangle_mesh] extension must be enabled prior to calling xrTriangleMeshGetIndexBufferFB
mesh must be a valid XrTriangleMeshFB handle
outIndexBuffer must be a pointer to 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_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

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

xrTriangleMeshGetVertexBufferFB(3)

Name

xrTriangleMeshGetVertexBufferFB - Obtain the vertex buffer of a triangle mesh

C Specification

The xrTriangleMeshGetVertexBufferFB function is defined as:

XrResult xrTriangleMeshGetVertexBufferFB(
    XrTriangleMeshFB                            mesh,
    XrVector3f**                                outVertexBuffer);

Parameters

Parameter Descriptions

mesh is the XrTriangleMeshFB to get the vertex buffer for.
outVertexBuffer is a pointer to return the vertex buffer into.

Description

Retrieves a pointer to the vertex buffer. The vertex buffer is structured as an array of XrVector3f. The size of the buffer is vertexCount. The application must call xrTriangleMeshBeginUpdateFB or xrTriangleMeshBeginVertexBufferUpdateFB before making modifications to the vertex buffer. The buffer location is guaranteed to remain constant over the lifecycle of the mesh object.

Valid Usage (Implicit)

The [XR_FB_triangle_mesh] extension must be enabled prior to calling xrTriangleMeshGetVertexBufferFB
mesh must be a valid XrTriangleMeshFB handle
outVertexBuffer must be a pointer to a pointer to an XrVector3f structure

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

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

xrTryGetPerceptionAnchorFromSpatialAnchorMSFT(3)

Name

xrTryGetPerceptionAnchorFromSpatialAnchorMSFT - Convert an XrSpatialAnchorMSFT to a Windows SpatialAnchor

C Specification

The xrTryGetPerceptionAnchorFromSpatialAnchorMSFT function converts a XrSpatialAnchorMSFT handle into an IUnknown pointer to Windows.Perception.Spatial.SpatialAnchor.

XrResult xrTryGetPerceptionAnchorFromSpatialAnchorMSFT(
    XrSession                                   session,
    XrSpatialAnchorMSFT                         anchor,
    IUnknown**                                  perceptionAnchor);

Parameters

Parameter Descriptions

session is the specified XrSession.
anchor is a valid XrSpatialAnchorMSFT handle.
perceptionAnchor is a valid pointer to IUnknown pointer to receive the output Windows.Perception.Spatial.SpatialAnchor object.

Description

If the runtime can convert the anchor to a Windows.Perception.Spatial.SpatialAnchor object, this function must return XR_SUCCESS, and the output IUnknown in the pointer of perceptionAnchor must be not NULL. This also increments the refcount of the object. The application can then use QueryInterface to get the pointer for Windows.Perception.Spatial.SpatialAnchor object. The application should release the COM pointer after done with the object, or attach it to a smart COM pointer such as winrt::com_ptr.

If the runtime cannot convert the anchor to a Windows.Perception.Spatial.SpatialAnchor object, the function must return XR_SUCCESS, and the output IUnknown in the pointer of perceptionAnchor must be NULL.

Valid Usage (Implicit)

The [XR_MSFT_perception_anchor_interop] extension must be enabled prior to calling xrTryGetPerceptionAnchorFromSpatialAnchorMSFT
session must be a valid XrSession handle
anchor must be a valid XrSpatialAnchorMSFT handle
perceptionAnchor must be a pointer to a pointer to an IUnknown value
anchor must have been created, allocated, or retrieved from session

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

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

xrUnpersistSpatialAnchorMSFT(3)

Name

xrUnpersistSpatialAnchorMSFT - Removes an anchor from the store

C Specification

The application can use the xrUnpersistSpatialAnchorMSFT function to remove the record of the anchor in the spatial anchor store. This operation will not affect any XrSpatialAnchorMSFT handles previously created. If the spatialAnchorName provided does not correspond to a currently stored anchor, the function must return XR_ERROR_SPATIAL_ANCHOR_NAME_NOT_FOUND_MSFT.

XrResult xrUnpersistSpatialAnchorMSFT(
    XrSpatialAnchorStoreConnectionMSFT          spatialAnchorStore,
    const XrSpatialAnchorPersistenceNameMSFT*   spatialAnchorPersistenceName);

Parameters

Parameter Descriptions

spatialAnchorStore is an XrSpatialAnchorStoreConnectionMSFT anchor store to perform the unpersist operation on.
spatialAnchorPersistenceName is a pointer to the XrSpatialAnchorPersistenceNameMSFT.

Description

Valid Usage (Implicit)

The [XR_MSFT_spatial_anchor_persistence] extension must be enabled prior to calling xrUnpersistSpatialAnchorMSFT
spatialAnchorStore must be a valid XrSpatialAnchorStoreConnectionMSFT handle
spatialAnchorPersistenceName must be a pointer to a valid XrSpatialAnchorPersistenceNameMSFT structure

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

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

xrUpdateHandMeshMSFT(3)

Name

xrUpdateHandMeshMSFT - Update hand mesh buffers

C Specification

The application can use the xrUpdateHandMeshMSFT function to retrieve the hand mesh at a given timestamp. The hand mesh’s vertices position and normal are represented in the hand mesh space created by xrCreateHandMeshSpaceMSFT with a same XrHandTrackerEXT.

XrResult xrUpdateHandMeshMSFT(
    XrHandTrackerEXT                            handTracker,
    const XrHandMeshUpdateInfoMSFT*             updateInfo,
    XrHandMeshMSFT*                             handMesh);

Parameters

Parameter Descriptions

handTracker is an XrHandTrackerEXT handle previously created with xrCreateHandTrackerEXT.
updateInfo is an XrHandMeshUpdateInfoMSFT which contains information to query the hand mesh.
handMesh is an XrHandMeshMSFT structure to receive the updates of hand mesh data.

Description

The application should preallocate the index buffer and vertex buffer in XrHandMeshMSFT using the maxHandMeshIndexCount and maxHandMeshVertexCount from the XrSystemHandTrackingMeshPropertiesMSFT returned from the xrGetSystemProperties function.

The application should preallocate the XrHandMeshMSFT structure and reuse it for each frame so as to reduce the copies of data when underlying tracking data is not changed. The application should use indexBufferChanged and vertexBufferChanged in XrHandMeshMSFT to detect changes and avoid unnecessary data processing when there is no changes.

Valid Usage (Implicit)

The [XR_MSFT_hand_tracking_mesh] extension must be enabled prior to calling xrUpdateHandMeshMSFT
handTracker must be a valid XrHandTrackerEXT handle
updateInfo must be a pointer to a valid XrHandMeshUpdateInfoMSFT structure
handMesh must be a pointer to an XrHandMeshMSFT structure

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_TIME_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

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

xrUpdateSwapchainFB(3)

Name

xrUpdateSwapchainFB - Updates state for the corresponding swapchain

C Specification

The xrUpdateSwapchainFB function is defined as:

XrResult xrUpdateSwapchainFB(
    XrSwapchain                                 swapchain,
    const XrSwapchainStateBaseHeaderFB*         state);

Parameters

Parameter Descriptions

swapchain is the XrSwapchain to update state for.
state is a pointer to a XrSwapchainState structure based off of XrSwapchainStateBaseHeaderFB.

Description

xrUpdateSwapchainFB provides support for an application to update specific mutable state associated with an XrSwapchain.

Valid Usage (Implicit)

The [XR_FB_swapchain_update_state] extension must be enabled prior to calling xrUpdateSwapchainFB
swapchain must be a valid XrSwapchain handle
state must be a pointer to a valid XrSwapchainStateBaseHeaderFB-based structure. See also: XrSwapchainStateAndroidSurfaceDimensionsFB, XrSwapchainStateFoveationFB, XrSwapchainStateSamplerOpenGLESFB, XrSwapchainStateSamplerVulkanFB

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

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

xrWaitFrame(3)

Name

xrWaitFrame - Frame timing function

C Specification

The xrWaitFrame function is defined as:

XrResult xrWaitFrame(
    XrSession                                   session,
    const XrFrameWaitInfo*                      frameWaitInfo,
    XrFrameState*                               frameState);

Parameters

Parameter Descriptions

session is a valid XrSession handle.
frameWaitInfo exists for extensibility purposes, it is NULL or a pointer to a valid XrFrameWaitInfo.
frameState is a pointer to a valid XrFrameState, an output parameter.

Description

xrWaitFrame throttles the application frame loop in order to synchronize application frame submissions with the display. xrWaitFrame returns a predicted display time for the next time that the runtime predicts a composited frame will be displayed. The runtime may affect this computation by changing the return values and throttling of xrWaitFrame in response to feedback from frame submission and completion times in xrEndFrame. An application must eventually match each xrWaitFrame call with one call to xrBeginFrame. A subsequent xrWaitFrame call must block until the previous frame has been begun with xrBeginFrame and must unblock independently of the corresponding call to xrEndFrame. When less than one frame interval has passed since the previous return from xrWaitFrame, the runtime should block until the beginning of the next frame interval. If more than one frame interval has passed since the last return from xrWaitFrame, the runtime may return immediately or block until the beginning of the next frame interval.

In the case that an application has pipelined frame submissions, the application should compute the appropriate target display time using both the predicted display time and predicted display interval. The application should use the computed target display time when requesting space and view locations for rendering.

The XrFrameState::predictedDisplayTime returned by xrWaitFrame must be monotonically increasing.

The runtime may dynamically adjust the start time of the frame interval relative to the display hardware’s refresh cycle to minimize graphics processor contention between the application and the compositor.

xrWaitFrame must be callable from any thread, including a different thread than xrBeginFrame/xrEndFrame are being called from.

Calling xrWaitFrame must be externally synchronized by the application, concurrent calls may result in undefined behavior.

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

Note

The engine simulation should advance based on the display time. Every stage in the engine pipeline should use the exact same display time for one particular application-generated frame. An accurate and consistent display time across all stages and threads in the engine pipeline is important to avoid object motion judder. If the application has multiple pipeline stages, the application should pass its computed display time through its pipeline, as xrWaitFrame must be called only once per frame.

Valid Usage (Implicit)

session must be a valid XrSession handle
If frameWaitInfo is not NULL, frameWaitInfo must be a pointer to a valid XrFrameWaitInfo structure
frameState must be a pointer to an XrFrameState structure

Thread Safety

Access to the session parameter by any other xrWaitFrame 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_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

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

xrWaitSwapchainImage(3)

Name

xrWaitSwapchainImage - Wait for a swapchain image to be available

C Specification

The xrWaitSwapchainImage function is defined as:

XrResult xrWaitSwapchainImage(
    XrSwapchain                                 swapchain,
    const XrSwapchainImageWaitInfo*             waitInfo);

Parameters

Parameter Descriptions

swapchain is the swapchain from which to wait for an image.
waitInfo is a pointer to an XrSwapchainImageWaitInfo structure.

Description

Before an application can begin writing to a swapchain image, it must first wait on the image to avoid writing to it before the compositor has finished reading from it. xrWaitSwapchainImage will implicitly wait on the oldest acquired swapchain image which has not yet been successfully waited on. Once a swapchain image has been successfully waited on without timeout, the app must release before waiting on the next acquired swapchain image.

This function may block for longer than the timeout specified in XrSwapchainImageWaitInfo due to scheduling or contention.

If the timeout expires without the image becoming available for writing, XR_TIMEOUT_EXPIRED must be returned. If xrWaitSwapchainImage returns XR_TIMEOUT_EXPIRED, the next call to xrWaitSwapchainImage will wait on the same image index again until the function succeeds with XR_SUCCESS. Note that this is not an error code; XR_SUCCEEDED(XR_TIMEOUT_EXPIRED) is true.

The runtime must eventually relinquish ownership of a swapchain image to the application and must not block indefinitely.

The runtime must return XR_ERROR_CALL_ORDER_INVALID if no image has been acquired by calling xrAcquireSwapchainImage.

Valid Usage (Implicit)

swapchain must be a valid XrSwapchain handle
waitInfo must be a pointer to a valid XrSwapchainImageWaitInfo structure

Return Codes

On success, this command returns

XR_SUCCESS
XR_SESSION_LOSS_PENDING
XR_TIMEOUT_EXPIRED

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

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

Object Handles

XrAction(3)

Name

XrAction - Opaque handle to an action

C Specification

XR_DEFINE_HANDLE(XrAction)

Description

Action handles are used to refer to individual actions when retrieving action data, creating action spaces, or sending haptic events.

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

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

XrActionSet(3)

Name

XrActionSet - Opaque handle to an action set

C Specification

XR_DEFINE_HANDLE(XrActionSet)

Description

Action sets are application-defined collections of actions. They are attached to a given XrSession with a xrAttachSessionActionSets call. They are enabled or disabled by the application via xrSyncActions depending on the current application context. For example, a game may have one set of actions that apply to controlling a character and another set for navigating a menu system. When these actions are grouped into two XrActionSet handles they can be selectively enabled and disabled using a single function call.

Actions are passed a handle to their XrActionSet when they are created.

Action sets are created by calling xrCreateActionSet:

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

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

XrDebugUtilsMessengerEXT(3)

Name

XrDebugUtilsMessengerEXT - Callback for debug data

C Specification

XR_DEFINE_HANDLE(XrDebugUtilsMessengerEXT)

Description

XrDebugUtilsMessengerEXT represents a callback function and associated filters registered with the runtime.

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

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

XrFoveationProfileFB(3)

Name

XrFoveationProfileFB - Foveation profile

C Specification

XR_DEFINE_HANDLE(XrFoveationProfileFB)

Description

XrFoveationProfileFB represents a set of properties and resources that define a foveation pattern for the runtime, which can be applied to individual swapchains.

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

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

XrGeometryInstanceFB(3)

Name

XrGeometryInstanceFB - Triangle mesh

C Specification

XR_DEFINE_HANDLE(XrGeometryInstanceFB)

Description

XrGeometryInstanceFB represents a geometry instance used in a passthrough layer.

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

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

XrHandTrackerEXT(3)

Name

XrHandTrackerEXT - Represents a tracker for a hand joints.

C Specification

The XrHandTrackerEXT handle represents the resources for hand tracking of the specific hand.

XR_DEFINE_HANDLE(XrHandTrackerEXT)

Description

An application creates separate XrHandTrackerEXT handles for left and right hands. This handle can be used to locate hand joints using xrLocateHandJointsEXT function.

A hand tracker provides joint locations with an unobstructed range of motion of an empty human hand.

Note

This behavior can be modified by the https://www.khronos.org/registry/OpenXR/specs/1.0/html/xrspec.html#XR_EXT_hand_joints_motion_range extension

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

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

XrInstance(3)

Name

XrInstance - Opaque handle to an instance object

C Specification

XR_DEFINE_HANDLE(XrInstance)

Description

An OpenXR instance is an object that allows an OpenXR application to communicate with an OpenXR runtime. The application accomplishes this communication by calling xrCreateInstance and receiving a handle to the resulting XrInstance object.

The XrInstance object stores and tracks OpenXR-related application state, without storing any such state in the application’s global address space. This allows the application to create multiple instances as well as safely encapsulate the application’s OpenXR state since this object is opaque to the application. OpenXR runtimes may limit the number of simultaneous XrInstance objects that may be created and used, but they must support the creation and usage of at least one XrInstance object per process.

Physically, this state may be stored in any of the OpenXR loader, OpenXR API layers or the OpenXR runtime components. The exact storage and distribution of this saved state is implementation-dependent, except where indicated by this specification.

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

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

XrPassthroughFB(3)

Name

XrPassthroughFB - Passthrough feature

C Specification

XR_DEFINE_HANDLE(XrPassthroughFB)

Description

XrPassthroughFB represents a passthrough feature.

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

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

XrPassthroughLayerFB(3)

Name

XrPassthroughLayerFB - Passthrough layer

C Specification

XR_DEFINE_HANDLE(XrPassthroughLayerFB)

Description

XrPassthroughLayerFB represents a layer of passthrough content.

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

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

XrSceneMSFT(3)

Name

XrSceneMSFT - Represents a scene

C Specification

An XrSceneMSFT handle represents the collection of scene components that were detected during the scene computation.

            XR_DEFINE_HANDLE(XrSceneMSFT)

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

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

XrSceneObserverMSFT(3)

Name

XrSceneObserverMSFT - Represents a scene observer

C Specification

The XrSceneObserverMSFT handle represents the resources for computing scenes. It maintains a correlation of scene component identifiers across multiple scene computes.

Note

The application should destroy the XrSceneObserverMSFT handle when it is done with scene compute and scene component data to save system power consumption.

            XR_DEFINE_HANDLE(XrSceneObserverMSFT)

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

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

XrSession(3)

Name

XrSession - Opaque handle to a session object

C Specification

XR_DEFINE_HANDLE(XrSession)

Description

A session represents an application’s intention to display XR content to 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

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

XrSpace(3)

Name

XrSpace - Opaque handle to a space

C Specification

Across both virtual reality and augmented reality, XR applications have a core need to map the location of virtual objects to the corresponding real-world locations where they will be rendered. Spaces allow applications to explicitly create and specify the frames of reference in which they choose to track the real world, and then determine how those frames of reference move relative to one another over time.

XR_DEFINE_HANDLE(XrSpace)

Description

Spaces are represented by XrSpace handles, which the application creates and then uses in API calls. Whenever an application calls a function that returns coordinates, it provides an XrSpace to specify the frame of reference in which those coordinates will be expressed. Similarly, when providing coordinates to a function, the application specifies which XrSpace the runtime should use to interpret those coordinates.

OpenXR defines a set of well-known reference spaces that applications use to bootstrap their spatial reasoning. These reference spaces are: VIEW, LOCAL and STAGE. Each reference space has a well-defined meaning, which establishes where its origin is positioned and how its axes are oriented.

Runtimes whose tracking systems improve their understanding of the world over time may track spaces independently. For example, even though a LOCAL space and a STAGE space each map their origin to a static position in the world, a runtime with an inside-out tracking system may introduce slight adjustments to the origin of each space on a continuous basis to keep each origin in place.

Beyond well-known reference spaces, runtimes expose other independently-tracked spaces, such as a pose action space that tracks the pose of a motion controller over time.

When one or both spaces are tracking a dynamic object, passing in an updated time to xrLocateSpace each frame will result in an updated relative pose. For example, the location of the left hand’s pose action space in the STAGE reference space will change each frame as the user’s hand moves relative to the stage’s predefined origin on the floor. In other XR APIs, it is common to report the "pose" of an object relative to some presumed underlying global space. This API is careful to not explicitly define such an underlying global space, because it does not apply to all systems. Some systems will support no STAGE space, while others may support a STAGE space that switches between various physical stages with dynamic availability. To satisfy this wide variability, "poses" are always described as the relationship between two spaces.

Some devices improve their understanding of the world as the device is used. The location returned by xrLocateSpace in later frames may change over time, even for spaces that track static objects, as either the target space or base space adjusts its origin.

Composition layers submitted by the application include an XrSpace for the runtime to use to position that layer over time. Composition layers whose XrSpace is relative to the VIEW reference space are implicitly "head-locked", even if they may not be "display-locked" for non-head-mounted form factors.

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

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

XrSpatialAnchorMSFT(3)

Name

XrSpatialAnchorMSFT - Represents a spatial anchor

C Specification

This extension allows an application to create a spatial anchor, an arbitrary freespace point in the user’s physical environment that will then be tracked by the runtime. The runtime should then adjust the position and orientation of that anchor’s origin over time as needed, independently of all other spaces and anchors, to ensure that it maintains its original mapping to the real world.

XR_DEFINE_HANDLE(XrSpatialAnchorMSFT)

Description

Spatial anchors are often used in combination with an UNBOUNDED_MSFT reference space. UNBOUNDED_MSFT reference spaces adjust their origin as necessary to keep the viewer’s coordinates relative to the space’s origin stable. Such adjustments maintain the visual stability of content currently near the viewer, but may cause content placed far from the viewer to drift in its alignment to the real world by the time the user moves close again. By creating an XrSpatialAnchorMSFT where a piece of content is placed and then always rendering that content relative to its anchor’s space, an application can ensure that each piece of content stays at a fixed location in the environment.

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

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

XrSpatialAnchorStoreConnectionMSFT(3)

Name

XrSpatialAnchorStoreConnectionMSFT - Represents an open connection to the spatial anchor store

C Specification

The XrSpatialAnchorStoreConnectionMSFT handle represents a connection to the spatial anchor store and is used by the application to perform operations on the spatial anchor store such as:

Persisting and unpersisting of spatial anchors.
Enumeration of currently persisted anchors.
Clearing the spatial anchor store of all anchors.

XR_DEFINE_HANDLE(XrSpatialAnchorStoreConnectionMSFT)

Description

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

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

XrSwapchain(3)

Name

XrSwapchain - Opaque handle to a swapchain object

C Specification

XR_DEFINE_HANDLE(XrSwapchain)

Description

Normal XR applications will want to present rendered images to the user. To allow this, the runtime provides images organized in swapchains for the application to render into. The runtime must allow applications to create multiple swapchains.

Swapchain image format support by the runtime is specified by the xrEnumerateSwapchainFormats function. Runtimes should support R8G8B8A8 and R8G8B8A8 sRGB formats if possible.

Swapchain images can be 2D or 2D Array.

Rendering operations involving composition of submitted layers should be assumed to be internally performed by the runtime in linear color space. Images submitted in sRGB color space must be created using an API-specific sRGB format (e.g. DXGI_FORMAT_R8G8B8A8_UNORM_SRGB, GL_SRGB8_ALPHA8, VK_FORMAT_R8G8B8A8_SRGB) to apply automatic sRGB-to-linear conversion when read by the runtime. All other formats will be treated as linear values.

Note

OpenXR applications should avoid submitting linear encoded 8 bit color data (e.g. DXGI_FORMAT_R8G8B8A8_UNORM) whenever possible as it may result in color banding.

Gritz, L. and d’Eon, E. 2007. The Importance of Being Linear. In: H. Nguyen, ed., GPU Gems 3. Addison-Wesley Professional. https://developer.nvidia.com/gpugems/gpugems3/part-iv-image-effects/chapter-24-importance-being-linear

Note

DXGI resources will be created with their associated TYPELESS format, but the runtime will use the application-specified format for reading the data.

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

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

XrTriangleMeshFB(3)

Name

XrTriangleMeshFB - Triangle mesh

C Specification

XR_DEFINE_HANDLE(XrTriangleMeshFB)

Description

XrTriangleMeshFB represents a triangle mesh with its corresponding mesh data: a vertex buffer and an index buffer.

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

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

Structures

XrActionCreateInfo(3)

Name

XrActionCreateInfo - XrAction creation info

C Specification

The XrActionCreateInfo structure is defined as:

typedef struct XrActionCreateInfo {
    XrStructureType    type;
    const void*        next;
    char               actionName[XR_MAX_ACTION_NAME_SIZE];
    XrActionType       actionType;
    uint32_t           countSubactionPaths;
    const XrPath*      subactionPaths;
    char               localizedActionName[XR_MAX_LOCALIZED_ACTION_NAME_SIZE];
} XrActionCreateInfo;

Members

Member Descriptions

type is the XrStructureType of this structure.
next is NULL or a pointer to the next structure in a structure chain. No such structures are defined in core OpenXR.
actionName is an array containing a NULL terminated string with the name of this action.
actionType is the XrActionType of the action to be created.
countSubactionPaths is the number of elements in the subactionPaths array. If subactionPaths is NULL, this parameter must be 0.
subactionPaths is an array of XrPath or NULL. If this array is specified, it contains one or more subaction paths that the application intends to query action state for.
localizedActionName is an array containing a NULL terminated UTF-8 string that can be presented to the user as a description of the action. This string should be in the system’s current active locale.

Description

Subaction paths are a mechanism that enables applications to use the same action name and handle on multiple devices. Applications can query action state using subaction paths that differentiate data coming from each device. This allows the runtime to group logically equivalent actions together in system UI. For instance, an application could create a single pick_up action with the /user/hand/left and /user/hand/right subaction paths and use the subaction paths to independently query the state of pick_up_with_left_hand and pick_up_with_right_hand.

Applications can create actions with or without the subactionPaths set to a list of paths. If this list of paths is omitted (i.e. subactionPaths is set to NULL, and countSubactionPaths is set to 0), the application is opting out of filtering action results by subaction paths and any call to get action data must also omit subaction paths.

If subactionPaths is specified and any of the following conditions are not satisfied, the runtime must return XR_ERROR_PATH_UNSUPPORTED:

Each path provided is one of:
- /user/head
- /user/hand/left
- /user/hand/right
- /user/gamepad
No path appears in the list more than once

Extensions may append additional top level user paths to the above list.

Note

Earlier revisions of the spec mentioned /user but it could not be implemented as specified and was removed as errata.

The runtime must return XR_ERROR_PATH_UNSUPPORTED in the following circumstances:

The application specified subaction paths at action creation and the application called xrGetActionState* or a haptic function with an empty subaction path array.
The application called xrGetActionState* or a haptic function with a subaction path that was not specified when the action was created.

If actionName or localizedActionName are empty strings, the runtime must return XR_ERROR_NAME_INVALID or XR_ERROR_LOCALIZED_NAME_INVALID respectively. If actionName or localizedActionName are duplicates of the corresponding field for any existing action in the specified action set, the runtime must return XR_ERROR_NAME_DUPLICATED or XR_ERROR_LOCALIZED_NAME_DUPLICATED respectively. If the conflicting action is destroyed, the conflicting field is no longer considered duplicated. If actionName contains characters which are not allowed in a single level of a well-formed path string, the runtime must return XR_ERROR_PATH_FORMAT_INVALID.

Valid Usage (Implicit)

type must be XR_TYPE_ACTION_CREATE_INFO
next must be NULL or a valid pointer to the next structure in a structure chain
actionName must be a null-terminated UTF-8 string whose length is less than or equal to XR_MAX_ACTION_NAME_SIZE
actionType must be a valid XrActionType value
If countSubactionPaths is not 0, subactionPaths must be a pointer to an array of countSubactionPaths valid XrPath values
localizedActionName must be a null-terminated UTF-8 string whose length is less than or equal to XR_MAX_LOCALIZED_ACTION_NAME_SIZE

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

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

XrActionSetCreateInfo(3)

Name

XrActionSetCreateInfo - XrActionSet creation info

C Specification

The XrActionSetCreateInfo structure is defined as:

typedef struct XrActionSetCreateInfo {
    XrStructureType    type;
    const void*        next;
    char               actionSetName[XR_MAX_ACTION_SET_NAME_SIZE];
    char               localizedActionSetName[XR_MAX_LOCALIZED_ACTION_SET_NAME_SIZE];
    uint32_t           priority;
} XrActionSetCreateInfo;

Members

Member Descriptions

type is the XrStructureType of this structure.
next is NULL or a pointer to the next structure in a structure chain. No such structures are defined in core OpenXR.
actionSetName is an array containing a NULL terminated non-empty string with the name of this action set.
localizedActionSetName is an array containing a NULL terminated UTF-8 string that can be presented to the user as a description of the action set. This string should be presented in the system’s current active locale.
priority defines which action sets' actions are active on a given input source when actions on multiple active action sets are bound to the same input source. Larger priority numbers take precedence over smaller priority numbers.

Description

When multiple actions are bound to the same input source, the priority of each action set determines which bindings are suppressed. Runtimes must ignore input sources from action sets with a lower priority number if those specific input sources are also present in active actions within a higher priority action set. If multiple action sets with the same priority are bound to the same input source and that is the highest priority number, runtimes must process all those bindings at the same time.

Two actions are considered to be bound to the same input source if they use the same identifier and optional location path segments, even if they have different component segments.

When runtimes are ignoring bindings because of priority, they must treat the binding to that input source as though they do not exist. That means the isActive field must be XR_FALSE when retrieving action data, and that the runtime must not provide any visual, haptic, or other feedback related to the binding of that action to that input source. Other actions in the same action set which are bound to input sources that do not collide are not affected and are processed as normal.

If actionSetName or localizedActionSetName are empty strings, the runtime must return XR_ERROR_NAME_INVALID or XR_ERROR_LOCALIZED_NAME_INVALID respectively. If actionSetName or localizedActionSetName are duplicates of the corresponding field for any existing action set in the specified instance, the runtime must return XR_ERROR_NAME_DUPLICATED or XR_ERROR_LOCALIZED_NAME_DUPLICATED respectively. If the conflicting action set is destroyed, the conflicting field is no longer considered duplicated. If actionSetName contains characters which are not allowed in a single level of a well-formed path string, the runtime must return XR_ERROR_PATH_FORMAT_INVALID.

Valid Usage (Implicit)

type must be XR_TYPE_ACTION_SET_CREATE_INFO
next must be NULL or a valid pointer to the next structure in a structure chain
actionSetName must be a null-terminated UTF-8 string whose length is less than or equal to XR_MAX_ACTION_SET_NAME_SIZE
localizedActionSetName must be a null-terminated UTF-8 string whose length is less than or equal to XR_MAX_LOCALIZED_ACTION_SET_NAME_SIZE

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

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

XrActionSpaceCreateInfo(3)

Name

XrActionSpaceCreateInfo - Creation info for an action space

C Specification

The XrActionSpaceCreateInfo structure is defined as:

typedef struct XrActionSpaceCreateInfo {
    XrStructureType    type;
    const void*        next;
    XrAction           action;
    XrPath             subactionPath;
    XrPosef            poseInActionSpace;
} XrActionSpaceCreateInfo;

Members

Member Descriptions

type is the XrStructureType of this structure.
next is NULL or a pointer to the next structure in a structure chain. No such structures are defined in core OpenXR.
action is a handle to a pose XrAction previously created with xrCreateAction.
subactionPath is XR_NULL_PATH or an XrPath that was specified when the action was created. If subactionPath is a valid path not specified when the action was created the runtime must return XR_ERROR_PATH_UNSUPPORTED. If this parameter is set, the runtime must create a space that is relative to only that subaction’s pose binding.
poseInActionSpace is an XrPosef defining the position and orientation of the new space’s origin within the natural reference frame of the pose action.

Description

Valid Usage (Implicit)

type must be XR_TYPE_ACTION_SPACE_CREATE_INFO
next must be NULL or a valid pointer to the next structure in a structure chain
action must be a valid XrAction handle

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

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

XrActionStateBoolean(3)

Name

XrActionStateBoolean - Boolean action state

C Specification

The XrActionStateBoolean structure is defined as:

typedef struct XrActionStateBoolean {
    XrStructureType    type;
    void*              next;
    XrBool32           currentState;
    XrBool32           changedSinceLastSync;
    XrTime             lastChangeTime;
    XrBool32           isActive;
} XrActionStateBoolean;

Members

Member Descriptions

type is the XrStructureType of this structure.
next is NULL or a pointer to the next structure in a structure chain. No such structures are defined in core OpenXR.
currentState is the current state of the action.
changedSinceLastSync is XR_TRUE if the value of currentState is different than it was before the most recent call to xrSyncActions. This parameter can be combined with currentState to detect rising and falling edges since the previous call to xrSyncActions. E.g. if both changedSinceLastSync and currentState are XR_TRUE then a rising edge (XR_FALSE to XR_TRUE) has taken place.
lastChangeTime is the XrTime when this action’s value last changed.
isActive is XR_TRUE if and only if there exists an input source that is contributing to the current state of this action.

Description

When multiple input sources are bound to this action, the currentState follows the previously defined rule to resolve ambiguity.

Valid Usage (Implicit)

type must be XR_TYPE_ACTION_STATE_BOOLEAN
next must be NULL or a valid pointer to the next structure in a structure chain

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

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

XrActionStateFloat(3)

Name

XrActionStateFloat - Floating point action state

C Specification

The XrActionStateFloat structure is defined as:

typedef struct XrActionStateFloat {
    XrStructureType    type;
    void*              next;
    float              currentState;
    XrBool32           changedSinceLastSync;
    XrTime             lastChangeTime;
    XrBool32           isActive;
} XrActionStateFloat;

Members

Member Descriptions

type is the XrStructureType of this structure.
next is NULL or a pointer to the next structure in a structure chain. No such structures are defined in core OpenXR.
currentState is the current state of the Action.
changedSinceLastSync is XR_TRUE if the value of currentState is different than it was before the most recent call to xrSyncActions.
lastChangeTime is the XrTime in nanoseconds since this action’s value last changed.
isActive is XR_TRUE if and only if there exists an input source that is contributing to the current state of this action.

Description

When multiple input sources are bound to this action, the currentState follows the previously defined rule to resolve ambiguity.

Valid Usage (Implicit)

type must be XR_TYPE_ACTION_STATE_FLOAT
next must be NULL or a valid pointer to the next structure in a structure chain

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

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

XrActionStateGetInfo(3)

Name

XrActionStateGetInfo - Information to get action state

C Specification

The XrActionStateGetInfo structure is used to provide action and subaction paths when calling xrGetActionState* function. It is defined as:

typedef struct XrActionStateGetInfo {
    XrStructureType    type;
    const void*        next;
    XrAction           action;
    XrPath             subactionPath;
} XrActionStateGetInfo;

Members

Member Descriptions

type is the XrStructureType of this structure.
next is NULL or a pointer to the next structure in a structure chain. No such structures are defined in core OpenXR.
action is the XrAction being queried.
subactionPath is the subaction path XrPath to query data from, or XR_NULL_PATH to specify all subaction paths. If the subaction path is specified, it is one of the subaction paths that were specified when the action was created. If the subaction path was not specified when the action was created, the runtime must return XR_ERROR_PATH_UNSUPPORTED. If this parameter is specified, the runtime must return data that originates only from the subaction paths specified.

Description

See XrActionCreateInfo for a description of subaction paths, and the restrictions on their use.

Valid Usage (Implicit)

type must be XR_TYPE_ACTION_STATE_GET_INFO
next must be NULL or a valid pointer to the next structure in a structure chain
action must be a valid XrAction handle

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

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

XrActionStatePose(3)

Name

XrActionStatePose - Pose action metadata

C Specification

The XrActionStatePose structure is defined as:

typedef struct XrActionStatePose {
    XrStructureType    type;
    void*              next;
    XrBool32           isActive;
} XrActionStatePose;

Members

Member Descriptions

type is the XrStructureType of this structure.
next is NULL or a pointer to the next structure in a structure chain. No such structures are defined in core OpenXR.
isActive is XR_TRUE if and only if there exists an input source that is being tracked by this pose action.

Description

A pose action must not be bound to multiple input sources, according to the previously defined rule.

Valid Usage (Implicit)

type must be XR_TYPE_ACTION_STATE_POSE
next must be NULL or a valid pointer to the next structure in a structure chain

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

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

XrActionStateVector2f(3)

Name

XrActionStateVector2f - 2D float vector action state

C Specification

The XrActionStateVector2f structure is defined as:

typedef struct XrActionStateVector2f {
    XrStructureType    type;
    void*              next;
    XrVector2f         currentState;
    XrBool32           changedSinceLastSync;
    XrTime             lastChangeTime;
    XrBool32           isActive;
} XrActionStateVector2f;

Members

Member Descriptions

type is the XrStructureType of this structure.
next is NULL or a pointer to the next structure in a structure chain. No such structures are defined in core OpenXR.
currentState is the current XrVector2f state of the Action.
changedSinceLastSync is XR_TRUE if the value of currentState is different than it was before the most recent call to xrSyncActions.
lastChangeTime is the XrTime in nanoseconds since this action’s value last changed.
isActive is XR_TRUE if and only if there exists an input source that is contributing to the current state of this action.

Description

When multiple input sources are bound to this action, the currentState follows the previously defined rule to resolve ambiguity.

Valid Usage (Implicit)

type must be XR_TYPE_ACTION_STATE_VECTOR2F
next must be NULL or a valid pointer to the next structure in a structure chain

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

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

XrActionSuggestedBinding(3)

Name

XrActionSuggestedBinding - Suggested binding for a single action

C Specification

The XrActionSuggestedBinding structure is defined as:

typedef struct XrActionSuggestedBinding {
    XrAction    action;
    XrPath      binding;
} XrActionSuggestedBinding;

Members

Member Descriptions

action is the XrAction handle for an action
binding is the XrPath of a binding for the action specified in action. This path is any top level user path plus input source path, for example /user/hand/right/input/trigger/click. See suggested bindings for more details.

Description

Valid Usage (Implicit)

action must be a valid XrAction handle

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

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

XrActionsSyncInfo(3)

Name

XrActionsSyncInfo - Information to sync actions

C Specification

The XrActionsSyncInfo structure is defined as:

typedef struct XrActionsSyncInfo {
    XrStructureType             type;
    const void*                 next;
    uint32_t                    countActiveActionSets;
    const XrActiveActionSet*    activeActionSets;
} XrActionsSyncInfo;

Members

Member Descriptions

type is the XrStructureType of this structure.
next is NULL or a pointer to the next structure in a structure chain. No such structures are defined in core OpenXR.
countActiveActionSets is an integer specifying the number of valid elements in the activeActionSets array.
activeActionSets is NULL or a pointer to an array of one or more XrActiveActionSet structures that should be synchronized.

Description

Valid Usage (Implicit)

type must be XR_TYPE_ACTIONS_SYNC_INFO
next must be NULL or a valid pointer to the next structure in a structure chain
If countActiveActionSets is not 0, activeActionSets must be a pointer to an array of countActiveActionSets valid XrActiveActionSet structures

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

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

XrActiveActionSet(3)

Name

XrActiveActionSet - Describes an active action set

OpenXR API Reference Pages

OpenXR Commands

xrAcquireSwapchainImage(3)

Name

C Specification

Parameters

Description

See Also

Document Notes

Copyright

xrApplyHapticFeedback(3)

Name

C Specification

Parameters

Description

See Also

Document Notes

Copyright

xrAttachSessionActionSets(3)

Name

C Specification

Parameters

Description

See Also

Document Notes

Copyright

xrBeginFrame(3)

Name

C Specification

Parameters

Description

See Also

Document Notes

Copyright

xrBeginSession(3)

Name

C Specification

Parameters

Description

See Also

Document Notes

Copyright

xrClearSpatialAnchorStoreMSFT(3)

Name

C Specification

Parameters

Description

See Also

Document Notes

Copyright

xrComputeNewSceneMSFT(3)

Name

C Specification

Parameters

Description

See Also

Document Notes

Copyright

xrConvertTimeToTimespecTimeKHR(3)

Name

C Specification

Parameters

Description

See Also

Document Notes

Copyright

xrConvertTimeToWin32PerformanceCounterKHR(3)

Name

C Specification

Parameters

Description

See Also

Document Notes

Copyright

xrConvertTimespecTimeToTimeKHR(3)

Name

C Specification

Parameters

Description

See Also