Added support and tests for vrdisplaypointerrestricted events to the a-scene element with the possibility to disable the behavior (on by default)

Author: olga-microsoft

src/core/scene/a-scene.js

@@ -31,9 +31,11 @@ var warn = utils.debug('core:a-scene:warn');
  * @member {object} object3D - Root three.js Scene object.
  * @member {object} renderer
  * @member {bool} renderStarted
- * @member (object) effect - three.js VREffect
+ * @member {object} effect - three.js VREffect
  * @member {object} systems - Registered instantiated systems.
  * @member {number} time
+ * @member {bool} isCanvasPointerLockEnabled - true: set pointerlock on the canvas element in response to/
+ *         false: ignore vrdisplaypointerrestricted event.
  */
 module.exports.AScene = registerElement('a-scene', {
   prototype: Object.create(AEntity.prototype, {
@@ -56,6 +58,7 @@ module.exports.AScene = registerElement('a-scene', {
         this.systems = {};
         this.systemNames = [];
         this.time = 0;
+        this.isCanvasPointerLockEnabled = true;
         this.init();
       }
     },
@@ -119,6 +122,8 @@ module.exports.AScene = registerElement('a-scene', {
         this.enterVRBound = function () { self.enterVR(); };
         this.exitVRBound = function () { self.exitVR(); };
         this.exitVRTrueBound = function () { self.exitVR(true); };
+        this.pointerRestrictedBound = function () { self.pointerRestricted(); };
+        this.pointerUnrestrictedBound = function () { self.pointerUnrestricted(); };
 
         // Enter VR on `vrdisplayactivate` (e.g. putting on Rift headset).
         window.addEventListener('vrdisplayactivate', this.enterVRBound);
@@ -131,6 +136,14 @@ module.exports.AScene = registerElement('a-scene', {
 
         // Exit VR on `vrdisplaydisconnect` (e.g. unplugging Rift headset).
         window.addEventListener('vrdisplaydisconnect', this.exitVRTrueBound);
+
+        // Register for mouse restricted events while in VR
+        // (e.g. mouse no longer available on desktop 2D view)
+        window.addEventListener('vrdisplaypointerrestricted', this.pointerRestrictedBound);
+
+        // Register for mouse unrestricted events while in VR
+        // (e.g. mouse once again available on desktop 2D view)
+        window.addEventListener('vrdisplaypointerunrestricted', this.pointerUnrestrictedBound);
       },
       writable: window.debug
     },
@@ -178,6 +191,8 @@ module.exports.AScene = registerElement('a-scene', {
         window.removeEventListener('vrdisplaydeactivate', this.exitVRBound);
         window.removeEventListener('vrdisplayconnect', this.enterVRBound);
         window.removeEventListener('vrdisplaydisconnect', this.exitVRTrueBound);
+        window.removeEventListener('vrdisplaypointerrestricted', this.pointerRestrictedBound);
+        window.removeEventListener('vrdisplaypointerunrestricted', this.pointerUnrestrictedBound);
       }
     },
 
@@ -202,6 +217,16 @@ module.exports.AScene = registerElement('a-scene', {
       }
     },
 
+    /**
+     * For tests.
+     */
+    getPointerLockElement: {
+      value: function () {
+        return document.pointerLockElement;
+      },
+      writable: window.debug
+    },
+
     /**
      * For tests.
      */
@@ -317,6 +342,50 @@ module.exports.AScene = registerElement('a-scene', {
       writable: window.debug
     },
 
+    enableCanvasPointerLock: {
+      value: function () {
+        this.isCanvasPointerLockEnabled = true;
+      }
+    },
+
+    disableCanvasPointerLock: {
+      value: function () {
+        this.isCanvasPointerLockEnabled = false;
+      }
+    },
+
+    pointerRestricted: {
+      value: function () {
+        if (!this.isCanvasPointerLockEnabled) {
+          return;
+        }
+
+        if (this.canvas) {
+          var pointerLockElement = this.getPointerLockElement();
+          if (pointerLockElement && pointerLockElement !== this.canvas && document.exitPointerLock) {
+            // Recreate pointer lock on the canvas, if taken on another element.
+            document.exitPointerLock();
+          }
+
+          if (this.canvas.requestPointerLock) {
+            this.canvas.requestPointerLock();
+          }
+        }
+      }
+    },
+
+    pointerUnrestricted: {
+      value: function () {
+        if (!this.isCanvasPointerLockEnabled) {
+          return;
+        }
+        var pointerLockElement = this.getPointerLockElement();
+        if (pointerLockElement && pointerLockElement === this.canvas && document.exitPointerLock) {
+          document.exitPointerLock();
+        }
+      }
+    },
+
     /**
      * Handle `vrdisplaypresentchange` event for exiting VR through other means than
      * `<ESC>` key. For example, GearVR back button on Oculus Browser.

tests/core/scene/a-scene.test.js

@@ -403,6 +403,129 @@ suite('a-scene (without renderer)', function () {
     });
   });
 
+  suite('pointerRestricted', function () {
+    setup(function () {
+      var sceneEl = this.el;
+
+      // Stub canvas.
+      sceneEl.canvas = document.createElement('canvas');
+    });
+
+    test('requests pointerlock when restricted', function (done) {
+      var sceneEl = this.el;
+      var event;
+      var requestPointerLockSpy;
+
+      requestPointerLockSpy = this.sinon.spy(sceneEl.canvas, 'requestPointerLock');
+      event = new CustomEvent('vrdisplaypointerrestricted');
+      window.dispatchEvent(event);
+
+      process.nextTick(function () {
+        assert.ok(requestPointerLockSpy.called);
+        done();
+      });
+    });
+
+    test('ignores pointerlock if isCanvasPointerLockEnabled is false', function (done) {
+      var sceneEl = this.el;
+      var event;
+      var requestPointerLockSpy;
+
+      requestPointerLockSpy = this.sinon.spy(sceneEl.canvas, 'requestPointerLock');
+      sceneEl.disableCanvasPointerLock();
+      event = new CustomEvent('vrdisplaypointerrestricted');
+      window.dispatchEvent(event);
+
+      process.nextTick(function () {
+        assert.notOk(requestPointerLockSpy.called);
+        done();
+      });
+    });
+
+    test('exits pointerlock when unrestricted', function (done) {
+      var sceneEl = this.el;
+      var event;
+      var exitPointerLockSpy;
+
+      exitPointerLockSpy = this.sinon.spy(document, 'exitPointerLock');
+
+      event = new CustomEvent('vrdisplaypointerunrestricted');
+
+      this.sinon.stub(sceneEl, 'getPointerLockElement', function () {
+        return sceneEl.canvas;
+      });
+      window.dispatchEvent(event);
+
+      process.nextTick(function () {
+        assert.ok(exitPointerLockSpy.called);
+        done();
+      });
+    });
+
+    test('does not exit pointerlock when unrestricted on different locked element', function (done) {
+      var sceneEl = this.el;
+      var event;
+      var exitPointerLockSpy;
+
+      exitPointerLockSpy = this.sinon.spy(document, 'exitPointerLock');
+
+      event = new CustomEvent('vrdisplaypointerunrestricted');
+
+      this.sinon.stub(sceneEl, 'getPointerLockElement', function () {
+        // Mock that pointerlock is taken by the page itself,
+        // independently of the a-scene handler for vrdisplaypointerrestricted event
+        return document.createElement('canvas');
+      });
+      window.dispatchEvent(event);
+
+      process.nextTick(function () {
+        assert.notOk(exitPointerLockSpy.called);
+        done();
+      });
+    });
+
+    test('does not exit pointerlock when unrestricted if isCanvasPointerLockEnabled is false', function (done) {
+      var sceneEl = this.el;
+      var event;
+      var exitPointerLockSpy;
+
+      exitPointerLockSpy = this.sinon.spy(document, 'exitPointerLock');
+
+      event = new CustomEvent('vrdisplaypointerunrestricted');
+      sceneEl.disableCanvasPointerLock();
+      window.dispatchEvent(event);
+
+      process.nextTick(function () {
+        assert.notOk(exitPointerLockSpy.called);
+        done();
+      });
+    });
+
+    test('update existing pointerlock target when restricted', function (done) {
+      var sceneEl = this.el;
+      var event;
+      var exitPointerLockSpy;
+      var requestPointerLockSpy;
+
+      exitPointerLockSpy = this.sinon.spy(document, 'exitPointerLock');
+      requestPointerLockSpy = this.sinon.spy(sceneEl.canvas, 'requestPointerLock');
+      event = new CustomEvent('vrdisplaypointerrestricted');
+
+      this.sinon.stub(sceneEl, 'getPointerLockElement', function () {
+        // Mock that pointerlock is taken by the page itself,
+        // independently of the a-scene handler for vrdisplaypointerrestricted event
+        return document.createElement('canvas');
+      });
+      window.dispatchEvent(event);
+
+      process.nextTick(function () {
+        assert.ok(exitPointerLockSpy.called);
+        assert.ok(requestPointerLockSpy.called);
+        done();
+      });
+    });
+  });
+
   suite('system', function () {
     teardown(function () {
       delete components.test;