MDN wants to talk to developers like you: https://qsurvey.mozilla.com/s3/8d22564490d8

Draft
This page is not complete.

The WebVR API documentation is currently being updated to cover the v1.0 spec, therefore some of this information will be out of date. Contact chrisdavidmills if you have any questions about this work.

This is an experimental technology
Because this technology's specification has not stabilized, check the compatibility table for usage in various browsers. Also note that the syntax and behavior of an experimental technology is subject to change in future versions of browsers as the specification changes.

WebVR provides support for exposing virtual reality devices — for example head-mounted displays like the Oculus Rift — to web apps, enabling developers to translate position and movement information from the display into movement around a 3D scene. This has numerous very interesting applications, from virtual product tours and interactive training apps to super immersive first person games.

Concepts and usage

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

Any VR devices attached to your computer will be returned by the Navigator.getVRDisplays() method. This returns an array of objects to represent the attached devices, which inherit from the general VRDevice object — generally a head mounted display will have two devices — the head mounted display itself, represented by HMDVRDevice, and a position sensor camera that keeps track of your head position, represented by PositionSensorVRDevice.

The PositionSensorVRDevice object contains the getState() method, which returns a VRPositionState object — this represents the sensor’s state at a given timestamp, and includes properties containing useful data such as current velocity, acceleration, and orientation, useful for updating the rendering of a scene on each frame according to the movement of the VR head mounted display.

The HMDVRDevice.getEyeParameters() method returns a VREyeParameters object, which can be used to return field of view information — how much of the scene the head mounted display can see. The VREyeParameters.currentFieldOfView returns a VRFieldOfView object that contains 4 angles describing the current view from a center point. You can also change the field of view using HMDVRDevice.setFieldOfView().

WebVR Interfaces

VRDisplay
Represents any VR device supported by this API. It includes generic information such as device IDs and descriptions, as well as methods for starting to present a VR scene, retrieving eye parameters and display capabilities, and other important functionality.
VRDisplayCapabilities
Describes the capabilities of a VRDisplay — it's features can be used to perform VR device capability tests, for example can it return position information.
VRDisplayEvent
Represents the event object of WebVR-related events (see the window object extensions listed below).
VRFrameData
Represents all the information needed to render a single frame of a VR scene; constructed by VRDisplay.getFrameData().
VRPose
Represents the position state at a given timestamp (which includes orientation, position, velocity, and acceleration.)
VREyeParameters
Provides access to all the information required to correctly render a scene for each given eye, including field of view information.
VRFieldOfView
Represents a field of view defined by 4 different degree values describing the view from a center point.
VRLayerInit
Represents a layer to be presented in a VRDisplay.
VRStageParameters
Represents the values describing the the stage area for devices that support room-scale experiences.

Extensions to other interfaces

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

Gamepad

Gamepad.displayId Read only
Returns the VRDisplay.displayId of the associated VRDisplay — the VRDisplay that the gamepad is controlling the displayed scene of.
Navigator.activeVRDisplays Read only
Returns an array containing every VRDisplay object that is currently presenting (VRDisplay.ispresenting is true).
Navigator.getVRDisplays()
Returns a promise that resolves to an array of VRDisplay objects representing any available VR displays connected to the computer.

Window

Window.onvrdisplayconnected
Represents an event handler that will run when a compatible VR display has been connected to the computer (when the vrdisplayconnected event fires).
Window.onvrdisplaydisconnected
Represents an event handler that will run when a compatible VR display has been disconnected from the computer (when the vrdisplaydisconnected event fires).
Window.onvrdisplayactivate
Represents an event handler that will run when a display is able to be presented to (when the vrdisplayactivate event fires), for example if an HMD has been moved to bring it out of standby, or woken up by being put on.
Window.onvrdisplaydeactivate
Represents an event handler that will run when a display can no longer be presented to (when the vrdisplaydeactivate event fires), for example if an HMD has gone into standby or sleep mode due to a period of inactivity.
Window.onvrdisplayblur
Represents an event handler that will run when presentation to a display has been paused for some reason by the browser, OS, or VR hardware (when the vrdisplayblur event fires) — for example, while the user is interacting with a system menu or browser, to prevent tracking or loss of experience.
Window.onvrdisplayfocus
Represents an event handler that will run when presentation to a display has resumed after being blurred (when the vrdisplayfocus event fires).
Window.onvrdisplaypresentchange
represents an event handler that will run when the presenting state of a VR display changes — i.e. goes from presenting to not presenting, or vice versa (when the vrdisplaypresentchange event fires).

Examples

You can find a number of examples at these locations:

Specifications

Specification Status Comment
Unknown Unknown Initial definition

Browser compatibility

Feature Chrome Chromium Edge Firefox (Gecko) Internet Explorer Opera Safari (WebKit)
Basic support (Yes) (Yes) (Yes) 55 (55) No support No support No support
Feature Android Edge Firefox Mobile (Gecko) IE Phone Opera Mobile Safari Mobile Chrome for Android Samsung Internet for GearVR
Basic support No support No support 55.0 (55) No support No support No support (Yes) (Yes)
 

See also

  • A-Frame — Open source web framework for building VR experiences.
  • MozVR team — Demos, and useful utilities
  • webvr.info — Up-to-date information about WebVR, browser setup, and community.
  • MozVr.com — Demos, downloads, and other resources from the Mozilla VR team.
  • threejs-vr-boilerplate — A useful starter template for writing WebVR apps into.

Document Tags and Contributors

 Last updated by: chrisdavidmills,