XRSession.requestReferenceSpace()

Draft
This page is not complete.

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

refSpacePromise = xrSession.requestReferenceSpace(referenceSpaceType);

Parameters

type
A DOMString specifying the type of reference space for which an instance is to be returned. The string must be one of those found in the XRReferenceSpaceType enumerated type.

The reference space returned by XRSession.requestReferenceSpace() is either XRReferenceSpace or XRBoundedReferenceSpace. The "Interface" column in the table below indicates which is returned for each type.

XRReferenceSpaceType Description Interface
bounded-floor Similar to the local type, except the user is not expected to move outside a predetermined boundary, given by the boundsGeometry in the returned object. XRBoundedReferenceSpace
local

A 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, the local reference space tries to keep the origin stable relative to the environment.

XRReferenceSpace
local-floor Similar to the local 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 thet 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). XRReferenceSpace
unbounded A tracking space which allows the user total freedom of movement, possibly over extremely long distances from their origin point. Tracking is optimized for stability around the user's current position, so the native origin may drift over time. XRReferenceSpace
viewer A tracking space whose native origin tracks the viewer's position and orientation. This is used for spaces in which the user can physically move around, and is supported by all instances of XRSession. XRReferenceSpace

Return value

A Promise that resolves with an XRReferenceSpace object.

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 Status Comment
WebXR Device API
The definition of 'requestReferenceSpace()' in that specification.
Working Draft Initial definition.

Browser compatibility

Update compatibility data on GitHub
DesktopMobile
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidFirefox for AndroidOpera for AndroidSafari on iOSSamsung Internet
requestReferenceSpace()Chrome No support NoEdge No support NoFirefox No support NoIE No support NoOpera No support NoSafari No support NoWebView Android No support NoChrome Android No support NoFirefox Android No support NoOpera Android No support NoSafari iOS No support NoSamsung Internet Android No support No

Legend

No support  
No support