[look-controls] Support Pointer Lock API.

docs/components/look-controls.md

@@ -10,7 +10,7 @@ examples: []
 The look-controls component:
 
 - Rotates the entity when we rotate a VR head-mounted display (HMD).
-- Rotates the entity when we click-drag mouse.
+- Rotates the entity when we move the mouse.
 - Rotates the entity when we touch-drag the touchscreen.
 
 ## Example
@@ -24,13 +24,16 @@ component](camera.md).
 
 ## Properties
 
-| Property         | Description                                                      | Default Value |
-|------------------|------------------------------------------------------------------|---------------|
-| enabled          | Whether look controls are enabled.                               | true          |
-| hmdEnabled       | Whether to use VR headset pose in VR mode.                       | true          |
-| reverseMouseDrag | Whether to reverse mouse drag.                                   | false         |
-| touchEnabled     | Whether to use touch controls in magic window mode.              | true          |
-| userHeight | Height offset to add to the camera when *not* in VR mode so the camera is not on ground level. The default camera that A-Frame injects or the `<a-camera>` primitive sets this to 1.6 meters. But note the default camera component alone (`<a-entity camera>`) defaults this to 0. | 0             |
+[pointer-lock-api]: https://developer.mozilla.org/docs/Web/API/Pointer_Lock_API
+
+| Property           | Description                                                      | Default Value |
+|--------------------|------------------------------------------------------------------|---------------|
+| enabled            | Whether look controls are enabled.                               | true          |
+| hmdEnabled         | Whether to use VR headset pose in VR mode.                       | true          |
+| reverseMouseDrag   | Whether to reverse mouse drag.                                   | false         |
+| touchEnabled       | Whether to use touch controls in magic window mode.              | true          |
+| pointerLockEnabled | Whether to hide the cursor using the [Pointer Lock API][pointer-lock-api]. | true |
+| userHeight         | Height offset to add to the camera when *not* in VR mode so the camera is not on ground level. The default camera that A-Frame injects or the `<a-camera>` primitive sets this to 1.6 meters. But note the default camera component alone (`<a-entity camera>`) defaults this to 0. | 0 |
 
 ## Customizing look-controls
 

src/components/look-controls.js

@@ -21,6 +21,7 @@ module.exports.Component = registerComponent('look-controls', {
     enabled: {default: true},
     touchEnabled: {default: true},
     hmdEnabled: {default: true},
+    pointerLockEnabled: {default: true},
     reverseMouseDrag: {default: false},
     userHeight: {default: 1.6}
   },
@@ -38,6 +39,7 @@ module.exports.Component = registerComponent('look-controls', {
     this.rotation = {};
     this.deltaRotation = {};
     this.savedPose = null;
+    this.pointerLocked = false;
     this.setupMouseControls();
     this.bindMethods();
 
@@ -61,6 +63,12 @@ module.exports.Component = registerComponent('look-controls', {
       this.pitchObject.rotation.set(0, 0, 0);
       this.yawObject.rotation.set(0, 0, 0);
     }
+
+    if (oldData && !data.pointerLockEnabled !== oldData.pointerLockEnabled) {
+      this.removeEventListeners();
+      this.addEventListeners();
+      if (this.pointerLocked) { document.exitPointerLock(); }
+    }
   },
 
   tick: function (t) {
@@ -91,6 +99,8 @@ module.exports.Component = registerComponent('look-controls', {
     this.onTouchEnd = bind(this.onTouchEnd, this);
     this.onEnterVR = bind(this.onEnterVR, this);
     this.onExitVR = bind(this.onExitVR, this);
+    this.onPointerLockChange = bind(this.onPointerLockChange, this);
+    this.onPointerLockError = bind(this.onPointerLockError, this);
   },
 
  /**
@@ -130,6 +140,13 @@ module.exports.Component = registerComponent('look-controls', {
     // sceneEl events.
     sceneEl.addEventListener('enter-vr', this.onEnterVR);
     sceneEl.addEventListener('exit-vr', this.onExitVR);
+
+    // Pointer Lock events.
+    if (this.data.pointerLockEnabled) {
+      document.addEventListener('pointerlockchange', this.onPointerLockChange, false);
+      document.addEventListener('mozpointerlockchange', this.onPointerLockChange, false);
+      document.addEventListener('pointerlockerror', this.onPointerLockError, false);
+    }
   },
 
   /**
@@ -143,18 +160,22 @@ module.exports.Component = registerComponent('look-controls', {
 
     // Mouse events.
     canvasEl.removeEventListener('mousedown', this.onMouseDown);
-    canvasEl.removeEventListener('mousemove', this.onMouseMove);
-    canvasEl.removeEventListener('mouseup', this.onMouseUp);
-    canvasEl.removeEventListener('mouseout', this.onMouseUp);
+    window.removeEventListener('mousemove', this.onMouseMove);
+    window.removeEventListener('mouseup', this.onMouseUp);
 
     // Touch events.
     canvasEl.removeEventListener('touchstart', this.onTouchStart);
-    canvasEl.removeEventListener('touchmove', this.onTouchMove);
-    canvasEl.removeEventListener('touchend', this.onTouchEnd);
+    window.removeEventListener('touchmove', this.onTouchMove);
+    window.removeEventListener('touchend', this.onTouchEnd);
 
     // sceneEl events.
     sceneEl.removeEventListener('enter-vr', this.onEnterVR);
     sceneEl.removeEventListener('exit-vr', this.onExitVR);
+
+    // Pointer Lock events.
+    document.removeEventListener('pointerlockchange', this.onPointerLockChange, false);
+    document.removeEventListener('mozpointerlockchange', this.onPointerLockChange, false);
+    document.removeEventListener('pointerlockerror', this.onPointerLockError, false);
   },
 
   /**
@@ -242,7 +263,7 @@ module.exports.Component = registerComponent('look-controls', {
     var movementY;
 
     // Not dragging or not enabled.
-    if (!this.mouseDown || !this.data.enabled) { return; }
+    if (!this.data.enabled || (!this.mouseDown && !this.pointerLocked)) { return; }
 
      // Calculate delta.
     movementX = event.movementX || event.mozMovementX;
@@ -266,9 +287,21 @@ module.exports.Component = registerComponent('look-controls', {
     if (!this.data.enabled) { return; }
     // Handle only primary button.
     if (evt.button !== 0) { return; }
+
+    var sceneEl = this.el.sceneEl;
+    var canvasEl = sceneEl && sceneEl.canvas;
+
     this.mouseDown = true;
     this.previousMouseEvent = evt;
     document.body.classList.add(GRABBING_CLASS);
+
+    if (this.data.pointerLockEnabled && !this.pointerLocked) {
+      if (canvasEl.requestPointerLock) {
+        canvasEl.requestPointerLock();
+      } else if (canvasEl.mozRequestPointerLock) {
+        canvasEl.mozRequestPointerLock();
+      }
+    }
   },
 
   /**
@@ -334,6 +367,20 @@ module.exports.Component = registerComponent('look-controls', {
     this.previousHMDPosition.set(0, 0, 0);
   },
 
+  /**
+   * Update Pointer Lock state.
+   */
+  onPointerLockChange: function () {
+    this.pointerLocked = !!(document.pointerLockElement || document.mozPointerLockElement);
+  },
+
+  /**
+   * Recover from Pointer Lock error.
+   */
+  onPointerLockError: function () {
+    this.pointerLocked = false;
+  },
+
   /**
    * Toggle the feature of showing/hiding the grab cursor.
    */

tests/components/look-controls.test.js

@@ -60,6 +60,42 @@ suite('look-controls', function () {
       });
       window.dispatchEvent(new Event('mouseup'));
     });
+
+    test('requests pointer lock on mousedown', function (done) {
+      var canvasEl = this.sceneEl.canvas;
+
+      var requestPointerLock = this.sinon.spy(canvasEl, 'requestPointerLock');
+
+      process.nextTick(function () {
+        assert.ok(requestPointerLock.called);
+        document.body.classList.remove(GRABBING_CLASS);
+        done();
+      });
+
+      var event = new Event('mousedown');
+      event.button = 0;
+      canvasEl.dispatchEvent(event);
+    });
+
+    test('does not request pointer lock when option is disabled', function (done) {
+      var sceneEl = this.sceneEl;
+      var canvasEl = sceneEl.canvas;
+      var cameraEl = sceneEl.camera.el;
+
+      var requestPointerLock = this.sinon.spy(canvasEl, 'requestPointerLock');
+
+      cameraEl.setAttribute('look-controls', {pointerLockEnabled: false});
+
+      process.nextTick(function () {
+        assert.notOk(requestPointerLock.called);
+        document.body.classList.remove(GRABBING_CLASS);
+        done();
+      });
+
+      var event = new Event('mousedown');
+      event.button = 0;
+      canvasEl.dispatchEvent(event);
+    });
   });
 
   suite('saveCameraPose', function () {