README

WebVR UI

A javascript library allowing easily to create the Enter VR button a WebVR site. It will automatically detect the support in the browser and show correct messages to the user. The intention for the library is to create an easy way to make a button solving as many of the common use cases of WebVR as possible, and show some best practices for how to work with WebVR.

The library also supports adding a Enter Fullscreen link that allows entering a mode where on desktop you can use the mouse to drag around, and on mobile rotate the camera based on the gyroscope without rendering in stereoscopic mode (also known as Magic Window)

Examples

Basic usage Shows how to simply add a button with the default styling to a site using three.js (source)
A-Frame usage Shows how to use the library with A-Frame (source)
Styling options Shows how customize the styling through options (source)
Custom DOM Shows how to use the library with a custom DOM for the button A-Frame (source)

Library Usage

Include WebVR UI

Get the library either by cloning, downloading or installing through npm npm install webvr-ui

Include the ES5 transpiled library in a script tag

<script src="/webvr-ui/build/webvr-ui.min.js"></script>

or include it in your ES2015 code

import * as webvrui from 'webvr-ui';

The constructor for the button needs the dom element of the WebGL canvas. To use it together with the THREE.WebGLRenderer, do something like this

var renderer = new THREE.WebGLRenderer();

var options = {}
var enterVR = new webvrui.EnterVRButton(renderer.domElement, options);
document.body.appendChild(enterVR.domElement);

A-Frame

To use the button in A-Frame, include the library as above, and add webvr-ui to the scene.

<a-scene webvr-ui>
    ...
</a-scene>

This will disable the default UI and add a Enter VR button to the document DOM. All the styling and text options bellow are also available.

Options

These are the supported options in EnterVRButton. All options are optional.

Styling

color: Set the text and icon color (default: rgb(80,168,252))
background: Set the background color, set to false for no background (default: false)
corners: Choose the corner radius. Can either be 'square' or 'round' or a number representing pixel radius (default: 'square')
disabledOpacity: The opacity of the button when disabled (default: 0.5)
domElement: Provide a DOM element to use instead of default build in DOM. See Custom DOM example for more details how to use.
injectCSS: Set to false to disable CSS injection of button style (default: true)

Text

textEnterVRTitle: The text in the button prompting to begin presenting (default: 'ENTER VR')
textExitVRTitle: The text in the button prompting to begin presenting (default: 'EXIT VR')
textVRNotFoundTitle: The text in the button when there is no VR headset found (default: 'VR NOT FOUND')

Function Hooks

beforeEnter():Promise: Function called right before entering VR. Must return a Promise. Gives the opportunity to provide custom messaging or other changes before the experience is presented.
beforeExit():Promise: Function called right before exiting VR. Must return a promise. Gives the opportunity to update UI or other changes before the presentation is exited.
onRequestStateChange(state):boolean: A function called before state is changed, use to intercept entering or exiting VR for example. Return true to continue with default behavior, or false to stop the default behavior.

Events

The following events will be broadcasted by EnterVRButton, and can be subscribed to using the function .on([event]) on the button.

ready Event called when VR support is first detected, the VRDisplay is provided as the first parameter.
enter Event called when user enters VR, the VRDisplay is provided as the first parameter.
exit Event called when user exits VR, the VRDisplay is provided as the first parameter.
error Event called when an error occurs, i.e. VR is not supported, an Error is provided as the first parameter.
hide Event called when button is hidden
show Event called when button is shown

Functions

These are some of the functions that can be called on the EnterVRButton

setTitle(title) Change the text in the button.
setTooltip(tooltip) Change the hover tooltip of the button.
show() / hide() Change the visibility of the button.
disable() / enable() Change the disabled state of the button.
getVRDisplay():Promise Returns a Promise returning the VRDisplay associated to the button.
isPresenting():boolean: Returns true if the canvas associated to the button is presenting in fullscreen or VR mode.
requestEnterVR():Promise: Requests to start presenting. Must be called from a user action (read more)
requestEnterFullscreen():Promise: Requests to enter fullscreen mode if its supported in the browser.
requestExit():Promise: Request exiting presentation mode.

Development

To run the example, install dependencies

npm install

and start the watcher and server (available on localhost:3000/examples/basic.html)

npm start

To build the transpiled es5 version of the library, run

npm run build

and the library will be build to build/webvr-ui.js

Usage no npm install needed!