XrInstance - Opaque handle to an instance object

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 createInstance and receiving a handle to the resulting Instance object.

The Instance 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 Instance objects that may be created and used, but they must support the creation and usage of at least one Instance 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.

See Also

InstanceCreateInfo, InstanceProperties, convertTimeToTimespecTimeKHR, convertTimeToWin32PerformanceCounterKHR, convertTimespecTimeToTimeKHR, convertWin32PerformanceCounterToTimeKHR, createActionSet, createDebugUtilsMessengerEXT, createInstance, createSession, createVulkanDeviceKHR, createVulkanInstanceKHR, destroyInstance, enumerateEnvironmentBlendModes, enumerateViewConfigurationViews, enumerateViewConfigurations, getD3D11GraphicsRequirementsKHR, getD3D12GraphicsRequirementsKHR, getInstanceProcAddr, getInstanceProperties, getOpenGLESGraphicsRequirementsKHR, getOpenGLGraphicsRequirementsKHR, getSystem, getSystemProperties, getViewConfigurationProperties, getVulkanDeviceExtensionsKHR, getVulkanGraphicsDevice2KHR, getVulkanGraphicsDeviceKHR, getVulkanGraphicsRequirements2KHR, getVulkanGraphicsRequirementsKHR, getVulkanInstanceExtensionsKHR, pathToString, pollEvent, resultToString, setDebugUtilsObjectNameEXT, stringToPath, structureTypeToString, submitDebugUtilsMessageEXT, suggestInteractionProfileBindings

An opaque type for representing pointers to XrInstance handles

XrSession - Opaque handle to a session object

Description

A session represents an application’s intention to display XR content to the user.

First, the application creates a session by choosing a system and a graphics API and calling createSession, which creates a session in the SESSION_STATE_IDLE state. The application then sets up an pollEvent loop to monitor for session state changes delivered through the EventDataSessionStateChanged event. When the runtime determines that the system is ready to start transitioning to this session’s XR content, it notifies the application that its session has moved into the SESSION_STATE_READY state. When the application is ready to proceed and display its XR content, it calls beginSession and starts its frame loop, which starts its session running. While the session is running, the application is expected to continuously run its frame loop by calling waitFrame, beginFrame and endFrame each frame, to establish synchronization with the runtime. Once the runtime is synchronized with the application’s frame loop and ready to display its frames, the session will move into the SESSION_STATE_SYNCHRONIZED state. For frames where waitFrame returns an FrameState with shouldRender set to true, the application should render its composition layers and submit them to endFrame. If the application desires to leave a running session, it should call the requestExitSession function to request that the runtime transition its session to the SESSION_STATE_STOPPING state as soon as possible. Once the application reaches the SESSION_STATE_STOPPING state, it can call endSession to stop the XR session, after which the session will transition through SESSION_STATE_IDLE to the SESSION_STATE_EXITING state.

A session is considered running after a successful call to beginSession and remains running until any call is made to endSession. Certain functions are only valid to call when a session is running, such as waitFrame, or else the ERROR_SESSION_NOT_RUNNING error must be returned by the runtime.

A session is considered not running before a successful call to beginSession and becomes not running again after any call is made to endSession. Certain functions are only valid to call when a session is not running, such as beginSession, or else the ERROR_SESSION_RUNNING error must be returned by the runtime.

If an error is returned from beginSession, the session remains in its current running or not running state. Calling endSession always transitions a session to the not running state, regardless of any errors returned.

Only running sessions may become focused sessions that receive XR input. When a session is not running, the application must not submit frames. This is important because without a running session, the runtime no longer has to spend resources on sub-systems (tracking etc.) that are no longer needed by the application.

See Also

EventDataInteractionProfileChanged, EventDataReferenceSpaceChangePending, EventDataSessionStateChanged, EventDataVisibilityMaskChangedKHR, applyHapticFeedback, attachSessionActionSets, beginFrame, beginSession, createActionSpace, createHandTrackerEXT, createReferenceSpace, createSession, createSpatialAnchorFromPerceptionAnchorMSFT, createSpatialAnchorMSFT, createSpatialAnchorSpaceMSFT, createSpatialGraphNodeSpaceMSFT, createSwapchain, createSwapchainAndroidSurfaceKHR, destroySession, endFrame, endSession, enumerateBoundSourcesForAction, enumerateColorSpacesFB, enumerateDisplayRefreshRatesFB, enumerateReferenceSpaces, enumerateSwapchainFormats, getActionStateBoolean, getActionStateFloat, getActionStatePose, getActionStateVector2f, getControllerModelKeyMSFT, getControllerModelPropertiesMSFT, getControllerModelStateMSFT, getCurrentInteractionProfile, getDisplayRefreshRateFB, getInputSourceLocalizedName, getReferenceSpaceBoundsRect, getVisibilityMaskKHR, loadControllerModelMSFT, locateViews, perfSettingsSetPerformanceLevelEXT, requestDisplayRefreshRateFB, requestExitSession, sessionBeginDebugUtilsLabelRegionEXT, sessionEndDebugUtilsLabelRegionEXT, sessionInsertDebugUtilsLabelEXT, setAndroidApplicationThreadKHR, setColorSpaceFB, xrSetInputDeviceActiveEXT, xrSetInputDeviceLocationEXT, xrSetInputDeviceStateBoolEXT, xrSetInputDeviceStateFloatEXT, xrSetInputDeviceStateVector2fEXT, stopHapticFeedback, syncActions, thermalGetTemperatureTrendEXT, tryGetPerceptionAnchorFromSpatialAnchorMSFT, waitFrame

An opaque type for representing pointers to XrSession handles

XrActionSet - Opaque handle to an action set

Description

Action sets are application-defined collections of actions. They are attached to a given Session with a attachSessionActionSets call. They are enabled or disabled by the application via syncActions 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 ActionSet handles they can be selectively enabled and disabled using a single function call.

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

Action sets are created by calling createActionSet:

See Also

ActiveActionSet, SessionActionSetsAttachInfo, createAction, createActionSet, destroyActionSet

An opaque type for representing pointers to XrActionSet handles

XrAction - Opaque handle to an action

Description

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

See Also

ActionSpaceCreateInfo, ActionStateGetInfo, ActionSuggestedBinding, ActionType, BoundSourcesForActionEnumerateInfo, HapticActionInfo, InteractionProfileAnalogThresholdVALVE, createAction, destroyAction

An opaque type for representing pointers to XrAction handles

XrSwapchain - Opaque handle to a swapchain object

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

See Also

CompositionLayerCubeKHR, SwapchainSubImage, acquireSwapchainImage, createSwapchain, createSwapchainAndroidSurfaceKHR, destroySwapchain, enumerateSwapchainFormats, enumerateSwapchainImages, releaseSwapchainImage, waitSwapchainImage

An opaque type for representing pointers to XrSwapchain handles

XrSpace - Opaque handle to a space

Description

Spaces are represented by Space handles, which the application creates and then uses in API calls. Whenever an application calls a function that returns coordinates, it provides an Space to specify the frame of reference in which those coordinates will be expressed. Similarly, when providing coordinates to a function, the application specifies which Space 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 locateSpace 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 locateSpace 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 Space for the runtime to use to position that layer over time. Composition layers whose Space 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.

See Also

ActionSpaceCreateInfo, CompositionLayerBaseHeader, CompositionLayerCubeKHR, CompositionLayerCylinderKHR, CompositionLayerEquirect2KHR, CompositionLayerEquirectKHR, CompositionLayerProjection, CompositionLayerQuad, HandJointsLocateInfoEXT, ReferenceSpaceCreateInfo, SpatialAnchorCreateInfoMSFT, ViewLocateInfo, createActionSpace, createHandMeshSpaceMSFT, createReferenceSpace, createSpatialAnchorSpaceMSFT, createSpatialGraphNodeSpaceMSFT, destroySpace, locateSpace, xrSetInputDeviceLocationEXT

An opaque type for representing pointers to XrSpace handles