C Specification
xrLocateSpace provides the physical location of a space in a base space at a specified time, if currently known by the runtime.
// Provided by XR_VERSION_1_0
XrResult xrLocateSpace(
XrSpace space,
XrSpace baseSpace,
XrTime time,
XrSpaceLocation* location);
Parameters
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://registry.khronos.org/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
XrPosef::position
and XrPosef::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.
During tracking loss, the runtime should return a location with
XR_SPACE_LOCATION_POSITION_VALID_BIT
and
XR_SPACE_LOCATION_ORIENTATION_VALID_BIT
set and
XR_SPACE_LOCATION_POSITION_TRACKED_BIT
and
XR_SPACE_LOCATION_ORIENTATION_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 continue to make use of the runtime’s latest
knowledge of the world.
If an XrSpaceVelocity structure is chained to the
XrSpaceLocation::next
pointer, 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
XrSpaceLocation::next
pointer, 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);
See Also
Document Notes
For more information, 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.