XRSession: requestReferenceSpace() method
Limited availability
This feature is not Baseline because it does not work in some of the most widely-used browsers.
Experimental: This is an experimental technology
Check the Browser compatibility table carefully before using this in production.
Secure context: This feature is available only in secure contexts (HTTPS), in some or all supporting browsers.
The requestReferenceSpace()
method of the
XRSession
interface returns a promise
that resolves with
an instance of either XRReferenceSpace
or XRBoundedReferenceSpace
as appropriate given the type of reference
space requested.
Syntax
requestReferenceSpace(referenceSpaceType)
Parameters
type
-
A string specifying the type of reference space for which an instance is to be returned. The string must be one of the values below.
Return value
A Promise
that resolves with an XRReferenceSpace
object.
The types of reference space are listed below, with brief information about their use cases and which interface is used to implement them.
bounded-floor
-
An
XRBoundedReferenceSpace
similar to thelocal
type, except the user is not expected to move outside a predetermined boundary, given by theboundsGeometry
in the returned object. local
-
An
XRReferenceSpace
tracking space whose native origin is located near the viewer's position at the time the session was created. The exact position depends on the underlying platform and implementation. The user isn't expected to move much if at all beyond their starting position, and tracking is optimized for this use case. For devices with six degrees of freedom (6DoF) tracking, thelocal
reference space tries to keep the origin stable relative to the environment. local-floor
-
An
XRReferenceSpace
similar to thelocal
type, except the starting position is placed in a safe location for the viewer to stand, where the value of the y axis is 0 at floor level. If that floor level isn't known, the user agent will estimate the floor level. If the estimated floor level is non-zero, the browser is expected to round it such a way as to avoid fingerprinting (likely to the nearest centimeter). unbounded
-
An
XRReferenceSpace
tracking space which allows the user total freedom of movement, possibly over extremely long distances from their origin point. The viewer isn't tracked at all; tracking is optimized for stability around the user's current position, so the native origin may drift as needed to accommodate that need. viewer
-
An
XRReferenceSpace
tracking space whose native origin tracks the viewer's position and orientation. This is used for environments in which the user can physically move around, and is supported by all instances ofXRSession
, both immersive and inline, though it's most useful for inline sessions. It's particularly useful when determining the distance between the viewer and an input, or when working with offset spaces. Otherwise, typically, one of the other reference space types will be used more often.
Exceptions
Rather than throwing true exceptions, requestReferenceSpace()
rejects the
returned promise with a DOMException
whose name is found in the list
below:
NotSupportedError
-
The requested reference space is not supported.
Specifications
Specification |
---|
WebXR Device API # dom-xrsession-requestreferencespace |
Browser compatibility
BCD tables only load in the browser