WebXR Device API

Draft
This page is not complete.

This is an experimental technology
Check the Browser compatibility table carefully before using this in production.

The WebXR API is designed to support rendering 3D scenes to equipment that supports either virtual reality (VR) or augmented reality (AR), including both fully-immersive 3D headsets and mobile phones that support augmented reality using onboard graphics and the device camera or cameras.

WebXR provides the following key capabilities:

  • Find compatible VR or AR output devices
  • Render a 3D scene to the device at an appropriate frame rate
  • (Optionally) mirror the output to a 2D display
  • Create vectors representing the movements of input controls

WebXR Device API Concepts and usage

What is XR and WebXR

WebXR is an API to work with both Virtual Reality (VR) and Augmented Reality (AR) on the web. A typical XR device can have either 3 or 6 degrees of freedom and might or might not have an external positional sensor.

Sketch of a person in a chair with wearing goggles labelled "Head mounted display (HMD)" facing a monitor with a webcam labelled "Position sensor"

WebXR application lifecycle

Most applications using the WebXR Device API will follow a similar usage pattern:

  1. Check devise and UA compatibility with your WebXR experience
    1. Query navigator.xr.supportsSession() to determine whether the desired type of XR content is supported by the hardware and UA.
    2. If so, advertise the XR content to the user.
  2. Wait for the user to trigger user activation event
    Wait for the user to trigger a user activation event indicating they want to begin viewing XR content and within that event handler request an XRSession via navigator.xr.requestSession().
  3. Run the frame loop for the entire duration of the experience
    1. If the XRSession request succeeds, call XRSession.requestAnimationFrame() to schedule the first frame update to respond to XR input.
    2. Keep calling XRSession.requestAnimationFrame() within the callback for frame update to schedule the next frame update.
  4. End XR session or wait for the user to do it
    1. End the session yourself by calling XRSession.end() or wait for UA to do it.
    2. Respond to XRSession's end event.

WebXR Interfaces

XR
The gateway interface of WebXR API, which enables the creation of a XRSession.
XRSession
provides the means to interact with an AR/VR device, providing features such as polling the viewer space (viewer pose), getting information about the user's environment, and presenting imagery to the user.
XRRenderState
Contains interfaces for inspecting and configuring parameters that affect how the session's output is composited.
XRFrame
Represents a snapshot of the state of all of the tracked objects for a XRSession
XRSpace
The base class for classes that represent a virtual coordinate system with an origin that corresponds to a physical location. Spatial data in WebXR is always expressed in relationship to an instance of an XRSpace descendant at the time of a specific XRFrame.
XRReferenceSpace
A type of XRSpace used to retrieve information about the spatial relationship with the user's evironment. 
XRBoundedReferenceSpace
...
XRView
...
XRViewport
...
XRRigidTransform
...
XRPose
...
XRViewerPose
...
XRInputSource
...
XRWebGLLayer
...

WebXR extensions to other interfaces

The WebXR API extends the following APIs, adding the listed features.

Navigator.xr Read only
Represents the entry point into the WebXR API.

WebGL

Warning: These attributes are not stable.

WebGLContextAttributes.xrCompatible
Must be set to true when requesting WebGL context to use that context with WebXR.
WebGLRenderingContextBase.makeXRCompatible
Sets xrCompatible boolean after the WebGL context is created.

Specifications

Specification Status Comment
WebXR Device API Working Draft Initial definition.

Browser compatibility

Update compatibility data on GitHub
DesktopMobile
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidFirefox for AndroidOpera for AndroidSafari on iOSSamsung Internet
xr
Experimental
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
Experimental. Expect behavior to change in the future.
Experimental. Expect behavior to change in the future.

See also

Document Tags and Contributors

Contributors to this page: ExE-Boss, jpmedley, bershanskiy, Malvoz, mdnwebdocs-bot, Sheppy
Last updated by: ExE-Boss,