Web/API/XRSession/requestReferenceSpace

Draft This page is not complete.

Secure contextThis 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 of the two types is returned for each reference space type constant..

Reference space descriptors

The types of reference space are listed in the table below, with brief information about their use cases and which interface is used to implement them.

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 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).	`XRReferenceSpace`
`unbounded`	A 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.	`XRReferenceSpace`
`viewer`	A 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 of `XRSession`, 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.	`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 APIThe definition of 'requestReferenceSpace()' in that specification.	Working Draft	Initial definition.

Browser compatibility

Update compatibility data on GitHub

	Desktop						Mobile
	Chrome	Edge	Firefox	Internet Explorer	Opera	Safari	Android webview	Chrome for Android	Firefox for Android	Opera for Android	Safari on iOS	Samsung Internet
`requestReferenceSpace()`	Chrome Full support 79	Edge Full support 79	Firefox No support No	IE No support No	Opera No support No	Safari No support No	WebView Android No support No	Chrome Android Full support 79	Firefox Android No support No	Opera Android No support No	Safari iOS No support No	Samsung Internet Android Full support 11.2

Legend

Full support: Full support
No support: No support

XRSession.requestReferenceSpace() by Mozilla Contributors is licensed under CC-BY-SA 2.5.