{"id":15019007,"url":"https://github.com/immersive-web/cardboard-vr-display","last_synced_at":"2025-04-05T18:12:19.783Z","repository":{"id":40395797,"uuid":"106752194","full_name":"immersive-web/cardboard-vr-display","owner":"immersive-web","description":"A JavaScript implementation of a WebVR 1.1 VRDisplay","archived":false,"fork":false,"pushed_at":"2021-05-06T20:53:28.000Z","size":13156,"stargazers_count":93,"open_issues_count":12,"forks_count":43,"subscribers_count":54,"default_branch":"main","last_synced_at":"2025-03-29T17:12:04.495Z","etag":null,"topics":["cardboard","polyfill","virtualreality","vr","vrdisplay","webvr"],"latest_commit_sha":null,"homepage":"https://immersive-web.github.io/cardboard-vr-display","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/immersive-web.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-10-12T22:35:23.000Z","updated_at":"2024-12-28T20:02:29.000Z","dependencies_parsed_at":"2022-09-06T08:10:44.873Z","dependency_job_id":null,"html_url":"https://github.com/immersive-web/cardboard-vr-display","commit_stats":null,"previous_names":[],"tags_count":67,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/immersive-web%2Fcardboard-vr-display","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/immersive-web%2Fcardboard-vr-display/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/immersive-web%2Fcardboard-vr-display/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/immersive-web%2Fcardboard-vr-display/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/immersive-web","download_url":"https://codeload.github.com/immersive-web/cardboard-vr-display/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247378152,"owners_count":20929297,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cardboard","polyfill","virtualreality","vr","vrdisplay","webvr"],"created_at":"2024-09-24T19:52:45.267Z","updated_at":"2025-04-05T18:12:19.753Z","avatar_url":"https://github.com/immersive-web.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# cardboard-vr-display\n\n[![Build Status](http://img.shields.io/travis/immersive-web/cardboard-vr-display.svg?style=flat-square)](https://travis-ci.org/immersive-web/cardboard-vr-display)\n[![Build Status](http://img.shields.io/npm/v/cardboard-vr-display.svg?style=flat-square)](https://www.npmjs.org/package/cardboard-vr-display)\n\nA JavaScript implementation of a [WebVR 1.1 VRDisplay][VRDisplay]. This is the magic\nbehind rendering distorted stereoscopic views for browsers that do not support the [WebVR API]\nwith the [webvr-polyfill].\n\nUnless you're building a WebVR wrapper, you probably want to use [webvr-polyfill] directly\nrather than this. This component **does not** polyfill interfaces like `VRFrameData` and\n`navigator.getVRDisplays`, and up to the consumer, although trivial (see examples).\n\n## How It Works\n\nAs of [1.0.4](https://github.com/immersive-web/cardboard-vr-display/tree/v1.0.4), `CardboardVRDisplay` uses [RelativeOrientationSensor] for orientation tracking,\nfalling back to [DeviceMotionEvents] using [sensor fusion and pose prediction][fusion].\n[RelativeOrientationSensor] is a new API ([read more about the new Sensors on the web][sensors])\nfirst implemented in Chrome M63. This API uses the new [Feature Policy] specification which allows\ndevelopers to selectively enable or disable browser features.\n\nIt can also render in stereo mode, and includes mesh-based\nlens distortion. This display also includes user interface elements in VR mode\nto make the VR experience more intuitive, including:\n\n* A gear icon to select your VR viewer.\n* A back button to exit VR mode.\n* An interstitial which only appears in portrait orientation, requesting you switch\n  into landscape orientation (if [orientation lock][ol] is not available).\n\n### iframes\n\nBy default, main frames and same-origin iframes have access to Sensor APIs,\nbut cross-origin iframes must specify feature policy and allow `gyroscope` and\n`accelerometer` features. If your experience is attempting to use the native\n[WebXR Device API] in an iframe, you'll have to specify that feature as well ([WebXR's\nfeature name may change](https://github.com/immersive-web/webxr/issues/308)). All of these features require HTTPS to function, except for `localhost`, where HTTP is allowed.\n\n```html\n\u003ciframe src=\"https://otherdomain.com\" allow=\"gyroscope; accelerometer; xr\"\u003e\u003c/iframe\u003e\n```\n\nWhile `devicemotion` is a fallback for Sensors, eventually `devicemotion` will be behind the same\nFeature Policy as Sensors and it is encouraged to adhere to these policies in the meantime.\nIf the Feature Policy for Sensors is denied, `CardboardVRDisplay` will **not** always attempt\nto fall back to `devicemotion`. Using Feature Policies now will guarantee a more future-proof experience.\n\n#### Caveats\n\n* On iOS, cross-origin iframes do not have access to the `devicemotion` events.\n  The `CardboardVRDisplay` however does respond to events passed in from a parent\n  frame via `postMessage`. See the [iframe example][iframe-example] to see how\n  the events must be formatted.\n* Chrome M63 supports Sensors, although not the corresponding Feature Policy [until Chrome M65][sensors-main-frame].\n  This results in Chrome M63/M64 only supporting Sensors in main frames, and these browsers\n  will fall back to using devicemotion if in iframes.\n* Using Sensors in a cross-origin iframe [requires the frame to be in focus](https://www.w3.org/TR/generic-sensor/#focused-area). In builds of Chrome prior to M69, this logic is [erroneously reversed](https://bugs.chromium.org/p/chromium/issues/detail?id=849501). If loading content via cross-origin iframe, you can disable Sensors, triggering the `devicemotion` fallback with this [hacky workaround](https://github.com/immersive-web/cardboard-vr-display/blob/c196e15a8c7ccf594fe6a5044fbdcb51cc2eff91/examples/index.html#L117-L124). More info in [#27](https://github.com/immersive-web/cardboard-vr-display/issues/27).\n\n### Magic Window\n\nIt is possible to have a magic window using a VRDisplay that isn't 100% width/height of the window, and can jump into fullscreen WebVR. See the [magic window][magicwindow-example] for usage.\n\n## Installation\n\n```\n$ npm install --save cardboard-vr-display\n```\n\n## Browser Support\n\nShould support most modern browsers (IE11 is missing a few, for example) and requires [ES5](https://kangax.github.io/compat-table/es5/) JavaScript support. If you want to support a non-ES5 browser, or browser lacking some DOM globals, you must use a transformation or provide polyfills to support older environments.\n\nGlobals required:\n\n* [`Promise`](https://caniuse.com/#feat=promises)\n* [`CustomEvent`](https://caniuse.com/#feat=customevent)\n* [`requestAnimationFrame`](https://caniuse.com/#feat=requestanimationframe)\n\nAdditionally, WebGL support, [`devicemotion`](https://caniuse.com/#feat=deviceorientation) events, and common browser globals (`window`, `navigator`, `document`) are also required in the environment.\n\n## Usage\n\n`cardboard-vr-display` exposes a constructor for a `CardboardVRDisplay` that takes\na single options configuration, detailed below. Check out [running the demo](#running-the-demo)\nto try the different options.\n\n```js\nimport CardboardVRDisplay from 'cardboard-vr-display';\n\n// Default options\nconst options = {\n  // Optionally inject custom Viewer parameters as an option. Each item\n  // in the array must be an object with the following properties; here is\n  // an example of the built in CardboardV2 viewer:\n  //\n  // {\n  //   id: 'CardboardV2',\n  //   label: 'Cardboard I/O 2015',\n  //   fov: 60,\n  //   interLensDistance: 0.064,\n  //   baselineLensDistance: 0.035,\n  //   screenLensDistance: 0.039,\n  //   distortionCoefficients: [0.34, 0.55],\n  //   inverseCoefficients: [-0.33836704, -0.18162185, 0.862655, -1.2462051,\n  //     1.0560602, -0.58208317, 0.21609078, -0.05444823, 0.009177956,\n  //     -9.904169E-4, 6.183535E-5, -1.6981803E-6]\n  // }\n  // Added in 1.0.12.\n  ADDITIONAL_VIEWERS: [],\n\n  // Select the viewer by ID. If unspecified, defaults to 'CardboardV1'.\n  // Added in 1.0.12.\n  DEFAULT_VIEWER: '',\n\n  // By default, on mobile, a wakelock is necessary to prevent the device's screen\n  // from turning off without user input. Disable if you're keeping the screen awake through\n  // other means on mobile. A wakelock is never used on desktop.\n  // Added in 1.0.3.\n  MOBILE_WAKE_LOCK: true,\n\n  // Whether or not CardboardVRDisplay is in debug mode. Logs extra\n  // messages. Added in 1.0.2.\n  DEBUG: false,\n\n  // The URL to JSON of DPDB information. By default, uses the data\n  // from https://github.com/WebVRRocks/webvr-polyfill-dpdb; if left\n  // falsy, then no attempt is made.\n  // Added in 1.0.1\n  DPDB_URL: 'https://dpdb.webvr.rocks/dpdb.json',\n\n  // Complementary filter coefficient. 0 for accelerometer, 1 for gyro.\n  K_FILTER: 0.98,\n\n  // How far into the future to predict during fast motion (in seconds).\n  PREDICTION_TIME_S: 0.040,\n\n  // Flag to disabled the UI in VR Mode.\n  CARDBOARD_UI_DISABLED: false,\n\n  // Flag to disable the instructions to rotate your device.\n  ROTATE_INSTRUCTIONS_DISABLED: false,\n\n  // Enable yaw panning only, disabling roll and pitch. This can be useful\n  // for panoramas with nothing interesting above or below.\n  YAW_ONLY: false,\n\n  // Scales the recommended buffer size reported by WebVR, which can improve\n  // performance.\n  // UPDATE(2016-05-03): Setting this to 0.5 by default since 1.0 does not\n  // perform well on many mobile devices.\n  BUFFER_SCALE: 0.5,\n\n  // Allow VRDisplay.submitFrame to change gl bindings, which is more\n  // efficient if the application code will re-bind its resources on the\n  // next frame anyway. This has been seen to cause rendering glitches with\n  // THREE.js.\n  // Dirty bindings include: gl.FRAMEBUFFER_BINDING, gl.CURRENT_PROGRAM,\n  // gl.ARRAY_BUFFER_BINDING, gl.ELEMENT_ARRAY_BUFFER_BINDING,\n  // and gl.TEXTURE_BINDING_2D for texture unit 0.\n  DIRTY_SUBMIT_FRAME_BINDINGS: false,\n};\n\nconst display = new CardboardVRDisplay(options);\n\nfunction MockVRFrameData () {\n  this.leftViewMatrix = new Float32Array(16);\n  this.rightViewMatrix = new Float32Array(16);\n  this.leftProjectionMatrix = new Float32Array(16);\n  this.rightProjectionMatrix = new Float32Array(16);\n  this.pose = null;\n};\n\nconst frame = new (window.VRFrameData || MockVRFrameData)();\n\ndisplay.isConnected; // true\ndisplay.getFrameData(frame);\n\nframe.rightViewMatrix; // Float32Array\nframe.pose; // { orientation, position }\n```\n\n## Development\n\n* `npm install`: installs the dependencies.\n* `npm run build`: builds the distributable.\n* `npm run watch`: watches `src/` for changes and rebuilds on change.\n\n### Releasing a new version\n\nFor 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.\n\n`npm version \u003csemverstring\u003e`\n\n## Running The Demo\n\nView the [example] to see a demo running the CardboardVRDisplay. This executes\na minimal WebVR 1.1 polyfill and parses query params to inject configuration parameters.\nView some premade links at [index.html]. For example, to set the buffer scale to 1.0\nand limit rotation to yaw, go to [https://immersive-web.github.io/cardboard-vr-display/examples/index.html?YAW_ONLY=true\u0026BUFFER_SCALE=1.0].\nView all config options at `src/options.js`.\n\n## License\n\nThis program is free software for both commercial and non-commercial use,\ndistributed under the [Apache 2.0 License](LICENSE).\n\n[VRDisplay]: https://immersive-web.github.io/webvr/spec/1.1/#interface-vrdisplay\n[WebVR API]: https://immersive-web.github.io/webvr/spec/1.1/\n[WebXR Device API]: https://immersive-web.github.io/webxr/spec/latest/\n[webvr-polyfill]: https://github.com/immersive-web/webvr-polyfill\n[example]: https://immersive-web.github.io/cardboard-vr-display/examples\n[iframe-example]: examples/iframe.html\n[magicwindow-example]: examples/magicwindow.html\n[index.html]: https://immersive-web.github.io/cardboard-vr-display\n[fusion]: http://smus.com/sensor-fusion-prediction-webvr/\n[ol]: https://www.w3.org/TR/screen-orientation/\n[sensors]: https://developers.google.com/web/updates/2017/09/sensors-for-the-web\n[DeviceMotionEvents]: https://developer.mozilla.org/en-US/docs/Web/API/DeviceMotionEvent\n[RelativeOrientationSensor]: https://www.w3.org/TR/orientation-sensor/#relativeorientationsensor-model\n[Feature Policy]: https://wicg.github.io/feature-policy/\n[sensors-main-frame]: https://developers.google.com/web/updates/2017/09/sensors-for-the-web#feature_policy_integration\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fimmersive-web%2Fcardboard-vr-display","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fimmersive-web%2Fcardboard-vr-display","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fimmersive-web%2Fcardboard-vr-display/lists"}