The XRSystem
interface's requestSession()
method returns a promise
which resolves to an XRSession
object through which you can manage the requested type of WebXR session.
While only one immersive VR session can be active at a time, multiple inline sessions can be in progress at once.
requestSession(mode)
requestSession(mode, options)
A Promise
that resolves with an XRSession
object if the device and user agent support the requested mode and features.
This method doesn't throw true exceptions; instead, it rejects the returned promise, passing into it a DOMException
whose name
is one of the following:
-
InvalidStateError
DOMException
-
Returned if the requested session mode is immersive-vr
but there is already an immersive VR session either currently active or in the process of being set up. There can only be one immersive VR session at a time.
-
NotSupportedError
DOMException
-
Returned if there is no WebXR-compatible device available, or the device does not support the specified sessionMode
; this can also be thrown if any of the required options are unsupported.
-
SecurityError
DOMException
-
Returned if permission to enter the specified XR mode is denied. This can happen for a number of reasons, which are covered in more detail in Permissions and security.
The following session features and reference spaces can be requested, either as optionalFeatures
or requiredFeatures
.
-
anchor
-
Enable use of XRAnchor
objects.
-
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.
-
depth-sensing
-
Enable the ability to obtain depth information using XRDepthInformation
objects.
-
dom-overlay
-
Enable allowing to specify a DOM overlay element that will be displayed to the user.
-
hand-tracking
-
Enable articulated hand pose information from hand-based input controllers (see XRHand
and XRInputSource.hand
).
-
hit-test
-
Enable hit testing features for performing hit tests against real world geometry.
-
layers
-
Enable the ability to create various layer types (other than XRProjectionLayer
).
-
light-estimation
-
Enable the ability to estimate environmental lighting conditions using XRLightEstimate
objects.
-
local
-
Enable 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.
-
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).
-
secondary-views
-
Enable XRView
objects to be secondary views. This can be used for first-person observer views used for video capture, or "quad views" where there are two views per eye, with differing resolution and fields of view.
-
unbounded
-
Enable 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.
-
viewer
-
Enable a tracking space whose native origin tracks the viewer's position and orientation.
Several session features and the various reference spaces have minimum security and privacy requirements, like asking for user consent and/or requiring the Feature-Policy
: xr-spatial-tracking
directive to be set. See also Permissions and security for more details.
The following example calls requestSession()
requesting an "immersive-vr"
session. If the Promise
resolves, it sets up a session and initiates the animation loop.
navigator.xr.requestSession("immersive-vr")
.then((xrSession) => {
xrSession.addEventListener('end', onXRSessionEnded);
xrSession.requestAnimationFrame(onXRAnimationFrame);
}).catch(function(error) {
console.warn("'immersive-vr' isn't supported, or an error occurred activating VR!");
});
The following example shows how to use both isSessionSupported()
and requestSession()
. First, it checks to see if WebXR is available by verifying the existence of navigator.xr
. Next, it calls isSessionSupported()
, passing it the desired session option before enabling controls for entering XR. Adding controls is a necessary step because entering XR requires a user action. Finally, the onButtonClicked()
method calls requestSession()
using the same session option passed to isSessionSupported()
.
if (navigator.xr) {
navigator.xr.isSessionSupported('immersive-vr')
.then((isSupported) => {
if (isSupported) {
immersiveButton.addEventListener('click', onButtonClicked);
immersiveButton.textContent = 'Enter XR';
immersiveButton.disabled = false;
} else {
console.log("WebXR doesn't support immersive-vr mode!");
}
});
} else {
console.log("WebXR is not available!");
}
function onButtonClicked() {
if (!xrSession) {
navigator.xr.requestSession('immersive-vr')
.then((session) => {
xrSession = session;
onSessionStarted(xrSession);
});
} else {
xrSession.end().then(() => xrSession = null);
}
}
Require an unbounded experience in which the user is able to freely move around their physical environment:
navigator.xr.requestSession('immersive-vr', { requiredFeatures: ['unbounded'] })
navigator.xr.requestSession("immersive-ar", {
optionalFeatures: ["dom-overlay"],
domOverlay: {
root: document.getElementById("xr-overlay")
}
}
Here, the caller is able to handle both CPU- and GPU-optimized usage, as well as both "luminance-alpha" and "float32" formats. The order indicates preference for CPU and "luminance-alpha":
navigator.xr.requestSession("immersive-ar", {
requiredFeatures: ["depth-sensing"],
depthSensing: {
usagePreference: ["cpu-optimized", "gpu-optimized"],
formatPreference: ["luminance-alpha", "float32"]
}
});