This PR replaces #49 originally started by @NavidZ.

The goal of this change is to allow application to access unadjusted mouse movement data while in Pointer Lock. This is a highly requested feature from partners in the gaming space. This change adds a PointerLockOptions object as a parameter to the requestPointerLock() method. The PointerLockOptions object currently only has one useful member which is the boolean unadjustedMovement. Also, to properly return error information and make it easier for developers to implement the requestPointerLock method was changed to return a promise.

The existing Pointer Lock API returns the mouse movement that the platforms give Chrome. By default all platforms include some form of mouse acceleration in the movement information they give Chrome. Mouse acceleration is the artificial increase of velocity when the mouse is moving fast. This is useful in normal use of the pointer when a user is trying to move the mouse across the screen. However, it also makes aiming in first person perspective games very difficult. To solve this problem we are adding an option to get that unadjusted movement data when requesting pointer lock.

With Pointer Lock options now available, applications need the ability to change those options while keeping the lock. This proves difficult using the previous API which fired changed or error events on the document to indicate the result of the request. Particularly troublesome was that the error event gave no reason. To solve this problem for developers a Promise workflow is being introduced. Now when requesting a change the developers can get actionable error information on rejected requests.

Example:

try {
  await element.requestPointerLock({ unadjustedMovement: true });
  console.log(“pointer lock acquired”);
} catch (error) {
  console.log(`Failed to acquire pointer lock due to ${error}`);
}

Closes #36

The following tasks have been completed:

• Modified Web platform tests (link to pull request)

Implementation commitment:

• WebKit Add unadjustedMovement option to requestPointerLock WebKit/WebKit#17525
• Chromium (https://bugs.chromium.org/p/chromium/issues/detail?id=982379)
• Gecko (https://bugzilla.mozilla.org/show_bug.cgi?id=)

Preview | Diff