Pointer Lock 2.0

The Element interface is extended to provide the ability to request the pointer be locked.

WebIDLpartial interface Element {
  Promise<undefined> requestPointerLock(optional PointerLockOptions options = {});
};

const lock_element = document.getElementById("lock_element");
const lock_button = document.getElementById("lock");
lock_button.addEventListener("click", async (event) => {
    try {
        await lock_element.requestPointerLock({ unadjustedMovement: true });
        console.log("successfully locked!");
    } catch (e) {
        console.log("lock failed with error: ", e);
    }
});

requestPointerLock(PointerLockOptions options) method

A parallel queue named as lock requests queue is used for queuing all requests. When requestPointerLock() is invoked, perform the following steps:

1. Let promise be a new promise.
2. When a window is in focus, if the this's shadow-including root is the active document of a browsing context (or has an ancestor browsing context) that is not in focus:
   1. Queue an element task on the user interaction task source, given this, to perform the following steps:
      1. Fire an event named pointerlockerror at this's node document.
      2. Reject promise with a "WrongDocumentError" DOMException.
   2. Return promise.
   Issue 93: Visibility state checks

   The spec should not allow hidden documents to request pointer lock.

   Additionally, should a document become hidden, it should release the pointer lock.

3. If the 'relevant global object does not have transient activation and the Document has not previously released a successful pointer lock with exitPointerLock():
   1. Queue an element task on the user interaction task source, given this, to perform the following steps:
      1. Fire an event named pointerlockerror at this's node document.
      2. Reject promise with a "NotAllowedError" DOMException.
   2. Return promise.
   Note
4. If this's node document's active sandboxing flag set has the sandboxed pointer lock browsing context flag set:
   1. Queue an element task on the user interaction task source, given this, to perform the following steps:
      1. Fire an event named pointerlockerror at this's node document.
      2. Reject promise with a "SecurityError" DOMException.
   2. Return promise.
5. If options["unadjustedMovement"] is true and the platform does not support unadjustedMovement:
   1. Queue an element task on the user interaction task source, given this, to perform the following steps:
      1. Fire an event named pointerlockerror at this's node document.
      2. Reject promise with a "NotSupportedError" DOMException.
   2. Return promise.
   Issue 90: Propose to add a static field to indicate whether `unadjustedMovement` is supported.

   In PR #49, PointerLockOptions is introduced. However, unadjustedMovement of PointerLockOptions might not be supported on all platforms. A static field could be useful to determine whether it is supported before directly using it in PointerLockOptions and get a not supported error.

6. Enqueue the following steps to the lock requests queue:
   1. If the user agent's pointer-lock target is an element whose shadow-including root is not equal to this's shadow-including root, then:
      1. Queue an element task on the user interaction task source, given this, to perform the following steps:
         1. Fire an event named pointerlockerror at this's node document.
         2. Reject promise with a "InvalidStateError" DOMException.
   2. If the user agent's pointer-lock target's shadow-including root is equal to this's shadow-including root and options are equivalent to the current pointer-lock options, then:
      1. Set pointer-lock target to this.
      2. Queue an element task on the user interaction task source, given this, to perform the following steps:
         1. Fire an event named pointerlockchange at this's node document.
         2. Resolve the promise.
   3. If pointer-lock target is null, or options is not equivalent to the current pointer-lock options, process the lock request and handle response upon fulfillment:
      1. If the lock request failed:
         1. Queue an element task on the user interaction task source, given this, to perform the following steps:
            1. Fire an event named pointerlockerror at this's node document.
            2. Reject promise with a "NotSupportedError" DOMException.
         Issue 91: When a subsequent requestPointerLock is rejected, should an already locked target exit lock state?

         In the PR #49's algorithm of requestPointerLock is currently missing the description for the scenario:
         When a subsequent request failed (for any possible reason), should an already locked target exit lock state?

      2. If the lock request succeed:
         1. Enter pointer lock state by performing the following:
            1. Set the user agent's pointer-lock target to this.
            2. Set the user agent's cursor position to the current system mouse location.
            3. Set the pointer-lock options to options.
         2. Queue an element task on the user interaction task source, given this, to perform the following steps:
            1. Fire an event named pointerlockchange at this's node document.
            2. Resolve the promise.
   Issue 96: lock requests queue processing is incomplete

   In the PR#49's algorithm of requestPointerLock is currently missing the description about how entries in lock requests queue are processed. Without an explicit text, we will leave open the incorrect (?) assumption that all entries will be synchronously dequeued at the end.

7. Return promise.

Note

WebIDLpartial interface Document {
  attribute EventHandler onpointerlockchange;
  attribute EventHandler onpointerlockerror;
  undefined exitPointerLock();
};

onpointerlockchange attribute

An event handler idl attribute for pointerlockchange events.

onpointerlockerror attribute

An event handler idl attribute for pointerlockerror events.

exitPointerLock() method

1. If the user agent's pointer-lock target is null, then return.
2. If pointer-lock target's shadow-including rootis not equal to this's node document, return.
3. Exit pointer lock with the user agent's pointer-lock target.

WebIDLpartial interface mixin DocumentOrShadowRoot {
  readonly attribute Element? pointerLockElement;
};

pointerLockElement

While the pointer is locked, returns the result of retargeting the element, which is the target for mouse events, against this element if the result and this element are in the same tree, otherwise returns null.

Returns null if lock is pending or if pointer is unlocked.

Example 2

<body>
  <div id="host1">
    <shadow-root id="root1">
      <canvas id="canvas1"></canvas>
    </shadow-root>
  </div>
  <div id="host2">
    <shadow-root id="root2">
      <canvas id="canvas2"></canvas>
    </shadow-root>
  </div>
</body>

Note

The example uses fictional shadow-root element to denote a shadow root instance.

If #canvas1 is the target, document.pointerLockElement returns #host1, and root1.pointerLockElement returns #canvas1. The result of retargeting #canvas1 against #root2 is #host1, but as #host1 is not in the same tree as #root2, null will be returned for root2.pointerLockElement.

WebIDLpartial interface MouseEvent {
  readonly attribute double movementX;
  readonly attribute double movementY;
};

movementX attribute

movementY attribute

The attributes movementX and movementY must provide the change in position of the pointer, as if the values of screenX, screenY, were stored between two subsequent mousemove events eNow and ePrevious and the difference taken movementX = eNow.screenX - ePrevious.screenX.

movementX and movementY must be zero for all mouse events except mousemove. All motion data must be delivered via mousemove events such that between any two mouse events earlierEvent and currentEvent the value of currentEvent.screenX - earlierEvent.screenX is equivalent to the sum of all movementX in the events after earlierEvent, with the exception of when screenX can not be updated because the pointer is clipped by the user agent screen boundaries.

movementX and movementY must be updated regardless of pointer lock state.

When unlocked, the system cursor can exit and re-enter the user agent window. If it does so and the user agent was not the target of operating system mouse move events then the most recent pointer position will be unknown to the user agent and movementX / movementY can not be computed and must be set to zero.

When pointer lock is enabled clientX, clientY, screenX, and screenY must hold constant values as if the pointer did not move at all once pointer lock was entered. But movementX and movementY must continue to provide the change in position of the pointer as when the pointer is unlocked. There will be no limit to movementX and movementY values if the mouse is continuously moved in a single direction. The concept of the mouse cursor will have been removed, and it will not move off the window or be clamped by a screen edge.

The un-initialized value of movementX and movementY must be 0.

Large movement values must not appear in situations when mouse input is interupted, such as the mouse cursor leaving the window and then re-entering at another location. If a user agent experiences a gap in receiving mouse input data from the operating system then the next generated mousemove event must have movementX and movementY set to 0. These gaps may appear for example when the user agent receives a mouse leaving event at the window system API. As an exception mouse capture may allow the user agent to continue receiving mouse events when the cursor moves outside the window.

WebIDLpartial dictionary MouseEventInit {
  double movementX = 0;
  double movementY = 0;
};

movementX member

movementY member

The members movementX and movementY are used to initialize respective members of MouseEvent.

A default unlock gesture must always be available that will exit pointer lock with the user agent's pointer-lock target.

Pointer lock must be exited if the pointer-lock target becomes disconnected, or the user agent, window, or tab loses focus. Moving focus between elements of active document, including between browsing contexts , does not exit pointer lock. E.g. using the keyboard to move focus between contents of frames or iframes will not exit.

Pointer lock must not be exited when fullscreen [FULLSCREEN] is entered or exited unless the pointer is required to enable interaction with the user agent graphical user interface, the default unlock gesture was used to exit both fullscreen and pointer lock, or window or tab focus was lost.

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

This specification defines conformance criteria that apply to a single product: the user agent that implements the interfaces that it contains.