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.
See Also
XrActionSpaceCreateInfo, XrBodyJointsLocateInfoFB, XrCompositionLayerBaseHeader, XrCompositionLayerCubeKHR, XrCompositionLayerCylinderKHR, XrCompositionLayerEquirect2KHR, XrCompositionLayerEquirectKHR, XrCompositionLayerPassthroughFB, XrCompositionLayerPassthroughHTC, XrCompositionLayerProjection, XrCompositionLayerQuad, XrEventDataSpaceEraseCompleteFB, XrEventDataSpaceSaveCompleteFB, XrEventDataSpaceSetStatusCompleteFB, XrEventDataSpatialAnchorCreateCompleteFB, XrEyeGazesInfoFB, XrGeometryInstanceCreateInfoFB, XrGeometryInstanceTransformFB, XrHandJointsLocateInfoEXT, XrPassthroughMeshTransformInfoHTC, XrPlaneDetectorBeginInfoEXT, XrPlaneDetectorGetInfoEXT, XrReferenceSpaceCreateInfo, XrSceneBoundsMSFT, XrSceneComponentsLocateInfoMSFT, XrSpaceEraseInfoFB, XrSpaceListSaveInfoFB, XrSpaceQueryResultFB, XrSpaceSaveInfoFB, XrSpaceShareInfoFB, XrSpatialAnchorCreateInfoFB, XrSpatialAnchorCreateInfoHTC, XrSpatialAnchorCreateInfoMSFT, XrSpatialGraphStaticNodeBindingCreateInfoMSFT, XrViewLocateInfo, XrVirtualKeyboardInputInfoMETA, XrVirtualKeyboardLocationInfoMETA, XrVirtualKeyboardSpaceCreateInfoMETA, xrCreateActionSpace, xrCreateHandMeshSpaceMSFT, xrCreateKeyboardSpaceFB, xrCreateMarkerSpaceML, xrCreateMarkerSpaceVARJO, xrCreateReferenceSpace, xrCreateSpaceFromCoordinateFrameUIDML, xrCreateSpatialAnchorHTC, xrCreateSpatialAnchorSpaceMSFT, xrCreateSpatialGraphNodeSpaceMSFT, xrCreateVirtualKeyboardSpaceMETA, xrDestroySpace, xrEnumerateSpaceSupportedComponentsFB, xrGetSpaceBoundary2DFB, xrGetSpaceBoundingBox2DFB, xrGetSpaceBoundingBox3DFB, xrGetSpaceComponentStatusFB, xrGetSpaceContainerFB, xrGetSpaceRoomLayoutFB, xrGetSpaceSemanticLabelsFB, xrGetSpaceTriangleMeshMETA, xrGetSpaceUuidFB, xrGetSpatialAnchorNameHTC, xrLocateSpace, xrSetInputDeviceLocationEXT, xrSetSpaceComponentStatusFB
Document Notes
For more information, see the OpenXR Specification
This page is extracted from the OpenXR Specification. Fixes and changes should be made to the Specification, not directly.
Copyright
Copyright 2014-2024, The Khronos Group Inc.
This work is licensed under a Creative Commons Attribution 4.0 International License.