WebXR Device API Specification

The WebXR Device API provides web developers with access to the input and output capabilities of Virtual Reality (VR), Augmented Reality (AR), and Mixed Reality (MR) devices. It enables the development and hosting of immersive experiences directly in the browser.

Core Goals

• Capability Detection: Determine if XR capabilities are available on the user's device.
• Device Querying: Query specific XR device capabilities.
• Input Polling: Poll the state of the XR device and its associated input devices.
• High-Performance Rendering: Display imagery on the XR device at the appropriate frame rate.

Target Hardware

The API is designed to work across a wide range of hardware, including:

• ARCore-compatible devices and Android XR-compatible devices.
• Meta Quest (1, 2, and Pro).
• Microsoft HoloLens and Windows Mixed Reality headsets.
• HTC Vive and Magic Leap One.
• Samsung Galaxy XR.

WebXR involves sensors (cameras, accelerometers, etc.) that can generate sensitive real-world data. Developers should be aware of the following privacy risks:

• Sensitive Information: Includes user-configurable data like interpupillary distance (IPD) and sensor-based data like poses. While immersive sessions always expose some sensitive data for rendering, inline sessions may also expose it.
• Device Fingerprinting: Data unique to a device (e.g., raw IMU data or specific IPD values) can be used to identify users. User agents may anonymize data to mitigate this.
• User Profiling: Data that could signal demographic characteristics (race, gender, age) requires explicit consent. For example, IPD data can potentially be used to infer these characteristics.
• Private Browsing: WebXR does not generate persistent data or unique user identifiers, so it does not impose additional requirements for private browsing modes.

The WebXR Device API uses XRReferenceSpace to establish guarantees about motion and provide a coordinate system for retrieving XRViewerPose. Developers should select the least capable reference space that satisfies their experience's mobility needs to ensure maximum device compatibility (progressive enhancement).

Available XRReferenceSpaceType values:

• bounded-floor: For experiences where users move within a fixed, pre-defined boundary (e.g., VR painting, dance games).
• unbounded: For experiences where users move freely over large distances (e.g., campus tours). The origin may drift to maintain stability.
• local: An eye-level/seated experience. The origin is near the viewer's position at creation. Must be resilient to position changes.
• local-floor: A floor-level/standing experience. The origin is at floor level (y=0). Must be resilient to position changes.
• viewer: An origin always at the viewer's position/orientation. Used for non-tracking experiences (e.g., click-and-drag) or to track head-locked objects.

To successfully call XRRequestSession and create an XRSession, the following conditions must be met:

• Secure Context: The document must be a responsible document of a secure context.
• Same Origin: The currently focused area must belong to a document whose origin is the same origin-domain as the active document.
• Feature Policy: The document must be allowed to use all policy-controlled features associated with the sensor types used by the session (e.g., sensors for XRViewerPose, XRPose, or XRBoundedReferenceSpace).
• User Consent Requirements:
  • Required for bounded-floor or unbounded reference space types.
  • Required for local-floor reference space types if the floor level reflects the real-world location.
  • Required on devices with configurable interpupillary distance (IPD) if XRFrame.getViewerPose() returns XRView transforms that can compute the configured IPD.
  • Required if the user agent does not otherwise mitigate sensor fingerprinting threats via XRViewerPose or XRPose data.

If required consent is not obtained, the promise will be rejected with a SecurityError DOMException.

To render content to an XR device, you must create an XRWebGLLayer and set it as the session's baseLayer via xrSession.updateRenderState().

Depending on your app type, you must ensure WebGL context compatibility:

1. XR Enhanced (Progressive Enhancement): Call gl.makeXRCompatible() on your existing context. This may cause the context to be lost and recreated on a compatible graphics adapter. You must handle webglcontextlost and webglcontextrestored events.
2. XR Centric (Core XR App): Create the context with the { xrCompatible: true } flag to avoid the overhead of makeXRCompatible().

// Option 1: XR Enhanced
function setupWebGLLayer() {
  return gl.makeXRCompatible().then(() => {
    xrSession.updateRenderState({ baseLayer: new XRWebGLLayer(xrSession, gl) });
  });
}

// Handle context loss for XR Enhanced apps
glCanvas.addEventListener("webglcontextlost", (event) => {
  event.preventDefault();
});

glCanvas.addEventListener("webglcontextrestored", () => {
  loadSceneGraphics(gl);
});

// Option 2: XR Centric
let gl = glCanvas.getContext("webgl", { xrCompatible: true });