A polyfill and example code for building augmented reality (AR) and virtual reality (VR) applications using WebXR.
Clone or download
Latest commit 468a618 Jun 26, 2018

README.md

(deprecated, experimental) WebXR polyfill with examples

The API for "WebXR" implemented in this repository is based on a proposed draft proposal for WebXR we created as a starting point for discussing WebXR in the fall of 2017, to explore what it might mean to expand WebVR to include AR/MR capabilities.

We initially created this polyfill when the community group was calling the specification "WebVR", so using "WebXR" was not confusing. Now that the community group is working towards changing the name of the spec, this repo may be confusing to newcomers.

We're working to bring this repo's master branch in line with the community group's draft spec. But that work is not yet complete.

The WebVR community has shifted WebVR in this direction. The group is now called the Immersive Web Community Group and the WebVR specification has now become the WebXR Device API. You should consider that spec as ground-truth for WebXR, and it is what you will likely see appearing in browsers through the rest of 2018 and into 2019.

We will continue to experiment with extensions to, and new ideas for, WebXR in this library. Soon, we expect it to be integrated directly in our WebXR Viewer iOS app and no longer be included directly in any web pages.

WebXR library with examples

This repository holds an implementation of a non-compliant version of WebXR, along with sample code demonstrating how to use the API.

WARNING

THIS SOFTWARE IS NON-STANDARD AND PRERELEASE, IS NOT READY FOR PRODUCTION USE, AND WILL SOON HAVE BREAKING CHANGES.

NOTHING IN THIS REPO COMES WITH ANY WARRENTY WHATSOEVER. DO NOT USE IT FOR ANYTHING EXCEPT EXPERIMENTS.

There may be pieces of the library that are stubbed out and throw 'Not implemented' when called.

Running the examples

The master branch of this repo is automatically built and hosted at https://examples.webxrexperiments.com

The develop branch is hosted at https://develop.examples.webxrexperiments.com

Building and Running the examples

Clone this repo and then change directories into webxr-polyfill/

Install npm and then run the following:

npm install   # downloads webpack and an http server
npm start     # builds the polyfill in dist/webxr-polyfill.js and start the http server in the current directory

Using one of the supported browsers listed below, go to http://YOUR_HOST_NAME:8080/

Portable builds

To build the WebXR polyfill into a single file that you can use in a different codebase:

npm run build

The resulting file will be in dist/webxr-polyfill.js

Writing your own XR apps

The WebXR polyfill is not dependent on any external libraries, but examples/common.js has a handy base class, XRExampleBase, that wraps all of the boilerplate of starting a WebXR session and rendering into a WebGL layer using Three.js.

Look in examples/ar_simplest/index.html for an example of how to extend XRExampleBase and how to start up an app.

If you run these apps on Mozilla's ARKit based iOS app then they will use the class in polyfill/platform/ARKitWrapper.js to get pose and anchor data out of ARKit.

If you run these apps on Google's old ARCore backed experimental browser then they will use the class in polyfill/platform/ARCoreCameraRenderer.js to use data out of ARCore.

If you run these apps on desktop Firefox or Chrome with a WebVR 1.1 supported VR headset, the headset will be exposed as a WebXR XRDisplay.

If you run these apps on a device with no VR or AR tracking, the apps will use the 3dof orientation provided by Javascript orientation events.

Supported Displays

  • Flat Display (AR only, needs VR)
  • WebVR 1.1 HMD (VR only, needs AR)
  • Cardboard (NOT YET)
  • Hololens (NOT YET)

Supported Realities

  • Camera Reality (ARKit on Mozilla iOS Test App, WebARonARCore on Android, WebARonARKit on iOS, WebRTC video stream (PARTIAL))
  • Virtual Reality (Desktop Firefox with Vive and Rift, Daydream (NOT TESTED), GearVR (Not Tested), Edge with MS MR headsets (NOT TESTED))
  • Passthrough Reality (NOT YET)

Supported Browsers