[w3c/pointerlock] Add lock options to requestPointerLock (PR #99)

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 (https://bugs.webkit.org/show_bug.cgi?id=)
 * [ ] Chromium (https://bugs.chromium.org/p/chromium/issues/detail?id=)
 * [ ] Gecko (https://bugzilla.mozilla.org/show_bug.cgi?id=)


<!--
    This comment and the below content is programmatically generated.
    You may add a comma-separated list of anchors you'd like a
    direct link to below (e.g. #idl-serializers, #idl-sequence):

    Don't remove this comment or modify anything below this line.
    If you don't want a preview generated for this pull request,
    just replace the whole of this comment's content by "no preview"
    and remove what's below.
-->
***
<a href="https://pr-preview.s3.amazonaws.com/w3c/pointerlock/pull/99.html" title="Last updated on Jun 5, 2024, 9:19 PM UTC (29297ed)">Preview</a> | <a href="https://pr-preview.s3.amazonaws.com/w3c/pointerlock/99/4642646...29297ed.html" title="Last updated on Jun 5, 2024, 9:19 PM UTC (29297ed)">Diff</a>
You can view, comment on, or merge this pull request online at:

  https://github.com/w3c/pointerlock/pull/99

-- Commit Summary --

  * Introduce PointerLockOptions and return promise for requestPointerLock

-- File Changes --

    M index.html (661)

-- Patch Links --

https://github.com/w3c/pointerlock/pull/99.patch
https://github.com/w3c/pointerlock/pull/99.diff

-- 
Reply to this email directly or view it on GitHub:
https://github.com/w3c/pointerlock/pull/99
You are receiving this because you are subscribed to this thread.

Message ID: <w3c/pointerlock/pull/99@github.com>