webxr-reference

WebXR API

The WebXR Device API lets you create augmented reality and virtual reality web sites by providing access to input and output capabilities of AR/VR hardware. As of early 2018, examples include Google’s Daydream, the Oculus Rift, the Samsung Gear VR, the HTC Vive, and Windows Mixed Reality headsets.

Concepts and Usage

Intro - TBD

What’s the X in XR mean?

There are many “___ reality” buzzwords flying around: virtual reality, augmented reality, mixed reality, etc.. It can be hard to keep track, even though there are many similarities between them. This API aims to provide foundational elements with which to do all of the above. Since the designers of the API don’t want to be limited to just one facet of AR, VR, or anything in between, the “X” in “XR” is not part of an acronym, but an algebraic variable of sorts to refer to whatever a web developer needs or wants it to be.

Immersive versus Non-immersive Sessions

There are two types of sessions: immersive sessions and non-immersive sessions.

Immersive session: An immersive presentation in which content is presented directly to the device. Entering an immersive session requires a user gesture.

Non-immersive session: A non-immersive presentation in which device tracking information is used to render content on a page. This is sometimes referred to as “magic window” mode. It enables the viewer to look around a scene by moving the device.

Frame of Reference Types

A frame of reference describes the space or stage in which AR/VR content will be created. Each frame of reference implies two facts that you need to be aware of when drawing content.

A frame of reference can be one of three types.

The "eye-level" and "stage" frames of reference are referred to as ‘room scale’ frames of reference.

Poses

Although the term pose sounds as though it might be referring to the viewer, it does not. A pose actually refers to a device, specifically it’s position and orientation in 3D space. A pose is represented by a matrix in the form of a Float32Array whose values are relative to the current coordinate system.

There are two types of poses in the WebXR Device API.

Device pose—The pose of the viewer, retrieved by calling XRFrame.getDevicePose().

Input pose—The pose of the input device, retrieved by calling XRFrame.getInputPose().

Matrices

Some WebXR objects return data in the form of matrices. WebXR matrices are always 4 by 4 and returned as 16 element Float32Arrays in column major order. They may be passed directly to WebGL’s uniformMatrix4fv() method, used to create an equivalent DOMMatrix, or used with a variety of third-party math libraries. Values in WebXR matrices are always given in meters.

Using the API

WebVR Device Interfaces

Device Enumeration

XR
Provides the means to query for attached AR/VR devices and receive events when device availability changes. A requested device is accessed through a returned `XRDevice` object.
XRDevice
Represents a single AR/VR hardware device and provides methods for obtaining an `XRSession` object

Sessions

XRSession
Provides the means to interact with an AR/VR device, providing features such as polling the device pose, getting information about the user's environment, and presenting imagery to the user.
XRSessionEvent
The event type passed to all of the `XRSession` events, specifically, `onblur`, `onfocus`, `onresetpose`, and `onend`.

Frame Loop

XRFrame
Provides all of the values needed to render a single frame of an AR/VR scene to the display represented by the `XRDevice` interface.

Coordinate Systems

XRCoordinateSystem
TBD
XRCoordinateSystemEvent
TBD
XRFrameOfReference
Provides information about the spatial point from which AR/VR measurements are made.
XRStageBounds
TBD
XRStageBoundsPoint
TBD

Views

XRView
Describes a single view into an AR/VR scene. Each view corresponds to a display or portion of a display used by a device to present imagery to the user.
XRViewport
Describes a viewport, or rectangular region, of a graphics surface.

Poses

XRDevicePose
Describes the position and orientation of an XRDevice relative to the XRCoordinateSystem it was queried with. It also describes the view and projection matrices that should be used by the application to render a frame of an AR/VR scene.

Input

XRInputSource
Returns information about the Web AR/VR control device being used. The control device is platform-specific and defines a primary action. A primary action is a trigger, touchpad, button, spoken command, or hand gesture that when performed produces selectstart, selectend, and select events.
XRInputPose
Returns information about the pose (position) of the input device in 3D space.

Layers

XRLayer
Defines a source of bitmap images and a description of how the image is to be rendered in the device. Do not use this interface directly. Rather use one of its subtypes. As of the first version of the [WebXR Device API](https://immersive-web.github.io/webxr/) only one subtype, `XRWebGLLayer` is supported.
XRWebGLLayer
An XRLayer subtype that allows WebGL to provide the bitmaps to be rendered to a device.

Canvas Rendering Context

XRPresentationContext
A wrapper object for the \{\{domxref("HTMLCanvasElement")\}\} object on which AR or VR content will be drawn. To retrieve an instance of this object, call `getContext()` on a canvas object with the value `'xrpresent'`.

Partial Interfaces

navigator.xr
Returns a new XR object.
WebGLRenderingContex.setCompatibleXRDevice()
Sets an XRDevice after a presentation context has been created.

Examples

Specifications

Latest

Browser Compatibility

See Browser Compatibility.

See Also

Glossary of AR/VR Terms