Skip to content

Latest commit

 

History

History
121 lines (85 loc) · 5.83 KB

README.md

File metadata and controls

121 lines (85 loc) · 5.83 KB
Raw

WebXR Polyfill

Build Status Build Status

A JavaScript implementation of the WebXR Device API. This polyfill allows developers to write against the latest specification, providing support when run on browsers that implement the WebVR 1.1 spec, or no WebVR/WebXR support at all.

⚠️ The WebXR Device API is still in flux ⚠️

The polyfill will be updated to track changes in the spec, and may introduce breaking changes in the polyfill's 1.0.x releases until the spec stabilizes.

If you are writing code against the WebVR 1.1 spec, use webvr-polyfill, which supports browsers with the 1.0 spec, or no implementation at all. It is recommended to write your code targeting the WebXR Device API spec however and use this polyfill as browsers begin to implement the latest changes.

The minimal input controls currently supported by WebXR is polyfilled here as well, using the Gamepad API.

Setup

Installing

Download the build at build/webxr-polyfill.js and include it as a script tag, or use a CDN. You can also use the minified file in the same location as webxr-polyfill.min.js.

  <script src='webxr-polyfill.js'></script>
  <!-- or use a link to a CDN -->
  <script src='https://cdn.jsdelivr.net/npm/webxr-polyfill@latest/build/webxr-polyfill.js'></script>

Or if you're using a build tool like browserify or webpack, install it via npm.

$ npm install --save webxr-polyfill

Using

The webxr-polyfill exposes a single constructor, WebXRPolyfill that takes an object for configuration. See full configuration options at API.

Be sure to instantiate the polyfill before calling any of your XR code! The polyfill needs to patch the API if it does not exist so your content code can assume that the WebXR API will just work.

If using script tags, a WebXRPolyfill global constructor will exist.

var polyfill = new WebXRPolyfill();

In a modular ES6 world, import and instantiate the constructor similarly.

import WebXRPolyfill from 'webxr-polyfill';
const polyfill = new WebXRPolyfill();

API

new WebXRPolyfill(global, config)

Takes a global object (usually window), as well as a config object with the following options:

  • webvr: Whether or not there should be an attempt to fall back to a WebVR 1.1 VRDisplay. (default: true).
  • cardboard: Whether or not there should be an attempt to fall back to a JavaScript implementation of the WebXR API only on mobile. (default: true)

Browser Support

There are 3 builds provided: build/webxr-polyfill.js, an ES5 transpiled build, its minified counterpart build/webxr-polyfill.min.js, and an untranspiled ES Modules version build/webxr-polyfill.module.js. If using the transpiled ES5 build, its up to developers to decide which browser features to polyfill based on their support, as no extra polyfills are included. Some browser features this library uses include:

  • TypedArrays
  • Object.assign
  • Promise
  • Symbol
  • Map
  • Array#includes

Check the .babelrc configuration and ensure the polyfill runs in whatever browsers you choose to support.

Polyfilling Rules

  • If 'xr' in navigator === false:
    • WebXR classes (e.g. XRDevice, XRSession) will be added to the global
    • navigator.xr will be polyfilled.
    • If the platform has a VRDisplay from the WebVR 1.1 spec available:
      • navigator.xr.requestDevice() will return a polyfilled XRDevice wrapping the VRDisplay.
    • If the platform does not have a VRDisplay, config.cardboard === true, and on mobile:
      • navigator.xr.requestDevice() will return a polyfilled XRDevice based on CardboardVRDisplay.
    • If WebGLRenderingContext.prototype.setCompatibleXRDevice is not a function:
      • Polyfill all WebGLRenderingContext.prototype.setCompatibleXRDevice and a creation attribute for { compatibleXrDevice }.
      • Polyfills HTMLCanvasElement.prototype.getContext to support a xrpresent type. Returns a polyfilled XRPresentationContext used for mirroring and magic window.
  • If 'xr' in navigator === true, config.cardboard === true and on mobile:
    • Overwrite navigator.xr.requestDevice so that a native XRDevice is returned if it exists, and if not, return a polyfilled XRDevice based on CardboardVRDisplay.

In the future, when the WebXR API is implemented on a platform but inconsistent with spec (due to new spec changes or inconsistencies), the polyfill will attempt to patch these differences without overwriting the native behavior.

Not supported/Caveats

  • A lot of objects should only be used in the frame they were retrieved; don't save and access a XRDevice's poseModelMatrix in a frame other than when it was created.
  • XRWebGLLayer.multiview
  • XRWebGLLayer.framebufferScaleFactor and XRWebGLLayer.requestViewportScaling()

License

This program is free software for both commercial and non-commercial use, distributed under the Apache 2.0 License.