Use WebVR today, on mobile or desktop, without requiring a special browser build.
npm install tamu-webvr-polyfillwebvr-polyfill.min.js.
html
`
$3
If you're using a build tool like [browserify] or [webpack], install it via [npm].
`
$ npm install --save webvr-polyfill
`
Using
Instructions for using versions >=0.10.0. For <=0.9.x versions, see 0.9.40 tag.
The webvr-polyfill exposes a single constructor, WebVRPolyfill that takes an
object for configuration. See full configuration options at src/config.js.
Be sure to instantiate the polyfill before calling any of your VR code! The
polyfill needs to patch the API if it does not exist so your content code can
assume that the WebVR API will just work.
If using script tags, a WebVRPolyfill global constructor will exist.
`js
var polyfill = new WebVRPolyfill();
`
In a modular ES6 world, import and instantiate the constructor similarly.
`js
import WebVRPolyfill from 'webvr-polyfill';
const polyfill = new WebVRPolyfill();
`
Here's an example of querying displays and setting up controls based on
environment. Remember, you'll still need to provide controls and code
to support a desktop-like experience if no native VRDisplays are found,
as the CardboardVRDisplay is only on mobile. See the example.
`js
// Polyfill always provides us with navigator.getVRDisplays
navigator.getVRDisplays().then(displays => {
// If we have a native VRDisplay, or if the polyfill
// provided us with a CardboardVRDisplay, use it
if (displays.length) {
vrDisplay = displays[0];
controls = new THREE.VRControls(camera);
vrDisplay.requestAnimationFrame(animate);
} else {
// If we don't have a VRDisplay, we're probably on
// a desktop environment, so set up desktop-oriented controls
controls = new THREE.OrbitControls(camera);
requestAnimationFrame(animate);
}
});
`
$3
There are some concerns and caveats when embedding polyfilled WebVR content inside iframes. More information is documented in the cardboard-vr-display README.
Goals
The polyfill's goal is to provide a library so that developers can create
content targeting the WebVR API without worrying about what browsers and devices
their users have in a world of growing, but fragmented support.
The three main components of the polyfill are:
* Injects a WebVR 1.1 JavaScript implementation if one does not exist
* Patches browsers that have an incomplete or inconsistent implementation of the API
* Provide a synthesized [CardboardVRDisplay] on mobile when WebVR is not supported, or if it does have native support but no native VRDisplays and PROVIDE_MOBILE_VRDISPLAY is true (default).
Performance
Performance is critical for VR. If you find your application is too sluggish,
consider tweaking some of the above parameters. In particular, keeping
BUFFER_SCALE at 0.5 (the default) will likely help a lot.
Developing
If you're interested in developing and contributing on the polyfill itself, you'll need to
have [npm] installed and familiarize yourself with some commands below. For full list
of commands available, see package.json scripts.
`
$ git clone git@github.com:immersive-web/webvr-polyfill.git
$ cd webvr-polyfill/
Install dependencies
$ npm install
Build uncompressed JS file
$ npm run build
Run tests
$ npm test
Watch src/* directory and auto-rebuild on changes
$ npm watch
`
$3
Right now there are some unit tests in the configuration and logic for how things get polyfilled.
Be sure to run tests before submitting any PRs, and bonus points for having new tests!
`
$ npm test
`
Due to the nature of the polyfill, be also sure to test the examples with your changes where appropriate.
$3
For maintainers only, to cut a new release for npm, use the [npm version] command. The preversion, version and postversion npm scripts will run tests, build, add built files and tag to git, push to github, and publish the new npm version.
npm version