C Specification

xrLocateSpace provides the physical relationship of a space relative to a base space at a specified time, if currently known by the runtime.

XrResult xrLocateSpace(
    XrSpace                                     space,
    XrSpace                                     baseSpace,
    XrTime                                      time,
    XrSpaceRelation*                            relation);

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 relation should be provided.

  • relation provides a relation which transforms coordinates from baseSpace to space.

Description

For a time in the past, the runtime should relate 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 relate 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 ../../openxr.html#prediction-time-limits. For values of time outside this range, xrLocateSpace may return a relation with no position and XR_SPACE_RELATION_POSITION_VALID_BIT unset.

Some devices improve their understanding of the world as the device is used. The relation 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_RELATION_POSITION_VALID_BIT but it can clear XR_SPACE_RELATION_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 space and baseSpace relate (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 relation with no position and XR_SPACE_RELATION_POSITION_VALID_BIT unset.

The runtime must return a relation with both XR_SPACE_RELATION_POSITION_VALID_BIT and XR_SPACE_RELATION_POSITION_TRACKED_BIT set when relating 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 relation in this case is the difference in the two spaces' application-specified transforms relative to that common entity.

The runtime should return a relation with XR_SPACE_RELATION_POSITION_VALID_BIT set and XR_SPACE_RELATION_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.

Valid Usage (Implicit)

  • space must be a valid XrSpace handle

  • baseSpace must be a valid XrSpace handle

  • relation must be a pointer to an XrSpaceRelation 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_INSTANCE_LOST

  • XR_ERROR_SESSION_LOST

  • XR_ERROR_RUNTIME_FAILURE

  • XR_ERROR_HANDLE_INVALID

  • XR_ERROR_VALIDATION_FAILURE

See Also

XrSpace, XrSpaceRelation, XrSpaceRelationFlagBits, XrTime

Document Notes

For more information, see the OpenXR Specification at URL

https://www.khronos.org/registry/openxr/specs/1.0-extensions/html/xrspec.html#xrLocateSpace

This page is extracted from the OpenXR Specification. Fixes and changes should be made to the Specification, not directly.

Copyright

Copyright (c) 2014-2019 Khronos Group. This work is licensed under a Creative Commons Attribution 4.0 International License.