Add lock options to requestPointerLock

[alvinjiooo]

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

[alvinjiooo]

Due to the IPR issue in #49 , I created this duplicate PR to bypass the CI issue.

Hi @james-howard, for some reasons I couldn't add you as reviewers at this PR, I add you here to notify that we create this dup PR for #49 .

[scheib]

Thank you for the all the work on this @alvinjiooo, and earlier editors @NavidZ and @jameshollyergoogle, and all the reviewers.

[mustaqahmed]

I am approving the PR based on the following points:

• On May 6 2024 @marcoscaceres called a virtual meeting to help us resolve the remaining comments in the original PR (Add lock options to requestPointerLock #49). The meeting was attended by @alvinjiooo, @james-howard, @marcoscaceres, @mustaqahmed, @nondebug and @scheib. We agreed that landing the PR makes the spec better match the implementations, and decided to land it after adding & linking new spec issues for the remaining TODOs there.
• I approved the original PR after @alvinjiooo addressed the remaining TODOs there.
• The original PR has been blocked by an "ipr" check for a while because @NavidZ is no longer a participant of WebApps WG. We didn't find a way to resolve this blocker quickly.
• To bypass the "ipr" check, @alvinjiooo created this PR and I closed Add lock options to requestPointerLock #49.
• Just now, I confirmed by local diffing that Add lock options to requestPointerLock #49 and Add lock options to requestPointerLock #99 match exactly, so my approval there logically carries over to this PR.

---

I second @scheib in thanking everyone for their patience with #49 (which was about to become ~5 years old 😞), especially @NavidZ, @jameshollyergoogle, @alvinjiooo, @domenic and @marcoscaceres.

[mustaqahmed]

At this point, I am in favor of landing this PR and move the discussion to open issues as we agreed already. Any objections? FYI @marcoscaceres who was the last reviewer of the original PR #49.

[mustaqahmed]

Landing now but please continue the discussion in linked or new issues.