paint-brush
Web Fundamentals: WebVR APIby@mozilla
915 reads
915 reads

Web Fundamentals: WebVR API

by Mozilla ContributorsMay 11th, 2020
Read on Terminal Reader
Read this story w/o Javascript
tldt arrow

Too Long; Didn't Read

WebVR API is replaced by WebXR API. Some browsers might still support it, but it may have already been removed from the relevant web standards. Avoid using it, and update existing code if possible; see the compatibility table at the bottom of this page to guide your decision. WebVR was never ratified as a standard, was implemented and enabled by default in very few browsers and supported a small number of devices. It's features can be used to perform VR device capability tests, for example can it return position information.
featured image - Web Fundamentals: WebVR API
Mozilla Contributors HackerNoon profile picture
Deprecated
This feature is no longer recommended. Though some browsers might still support it, it may have already been removed from the relevant web standards, may be in the process of being dropped, or may only be kept for compatibility purposes. Avoid using it, and update existing code if possible; see the compatibility table at the bottom of this page to guide your decision. Be aware that this feature may cease to work at any time.
Note: WebVR API is replaced by WebXR API. WebVR was never ratified as a standard, was implemented and enabled by default in very few browsers and supported a small number of devices.

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

Concepts and usage

Any VR devices attached to your computer will be returned by the

Navigator.getVRDisplays()
method; each one will be represented by a
VRDisplay
object.

VRDisplay
is the central interface in the WebVR API — via its properties and methods you can access functionality to:

  • Retrieve useful information to allow us to identify the display,
    what capabilities it has, controllers associated with it, and more.
  • Retrieve
    frame data
    for each frame of content you you want to present in a display, and submit those frames for display at a consistent rate.
  • Start and stop presenting to the display.

A typical (simple) WebVR app would work like so:

In addition, WebVR 1.1 adds a number of events on the

Window
object to allow JavaScript to respond to changes to the status of the display.

Note: You can find a lot more out about how the API works in our Using the WebVR API and WebVR Concepts articles.

Using controllers: Combining WebVR with the Gamepad API

Many WebVR hardware setups feature controllers that go along with the headset. These can be used in WebVR apps via the Gamepad API, and specifically the Gamepad Extensions API that adds API features for accessing controller pose, haptic actuators, and more.

Note: Our Using VR controllers with WebVR article explains the basics of how to use VR controllers with WebVR apps.

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

Returns the

VRDisplay.displayId
of the associated
VRDisplay
— the VRDisplay that the gamepad is controlling the displayed scene of.

Navigator


Navigator.activeVRDisplays

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 events

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).

Window.onvrdisplayconnect

Represents an event handler that will run when a compatible VR display has been connected to the computer (when the

vrdisplayconnect
event fires).

Window.onvrdisplaydisconnect

Represents an event handler that will run when a compatible VR display has been disconnected from the computer (when the

vrdisplaydisconnect
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).

Examples

You can find a number of examples at these locations:

Specifications

Browser compatibility

Navigator.getVRDisplays

See also

  • vr.mozilla.org — The main Mozilla landing pad for WebVR, with demos, utilities, and other information.
  • A-Frame — Open source web framework for building VR experiences.
  • webvr.info — Up-to-date information about WebVR, browser setup, and community.
  • threejs-vr-boilerplate — A useful starter template for writing WebVR apps into.
  • Web VR polyfill — JavaScript implementation of WebVR.
  • Supermedium — A pure WebVR browser to easily access the best WebVR content.
  • WebVR Directory — List of quality WebVR sites.

Credits