ポインターロック 2.0

Element インターフェイスは、ポインタのロックを要求する機能を拡張して提供します。

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) メソッド

lock requests queue という名前の 並列キュー が全てのリクエストをキューイングするために使われます。requestPointerLock() が呼び出されると、次の手順を実行します：

1. promise を 新しい promise とする。
2. window が フォーカス 状態で、this の shadow-including root が アクティブドキュメント である ブラウジングコンテキスト（またはフォーカスされていない 祖先 ブラウジングコンテキスト）の場合：
   1. 要素タスクをキューに追加し、ユーザーインタラクションタスクソース 上で、this を与えて、次の手順を実行する：
      1. イベントを発火し、名前は pointerlockerror、対象は this の ノードドキュメント。
      2. Reject（却下） promise に "WrongDocumentError" DOMException を与える。
   2. promise を返す。
   Issue 93: Visibility state checks

   この仕様では、非表示ドキュメントからのポインタロック要求を許可すべきではありません。

   さらに、ドキュメントが非表示になった場合はポインタロックを解除するべきです。

3. 「関連するグローバルオブジェクト」が一時的なアクティベーションを持たず、 Document が過去に exitPointerLock() で ポインタロックを正常に解除していない場合：
   1. 要素タスクをキューに追加し、ユーザーインタラクションタスクソース 上で、this を与えて、次の手順を実行する：
      1. イベントを発火し、名前は pointerlockerror、対象は this の ノードドキュメント。
      2. Reject（却下） promise に "NotAllowedError" DOMException を与える。
   2. promise を返す。
   注
4. this の ノードドキュメント の active sandboxing flag set に sandboxed pointer lock browsing context flag が設定されている場合：
   1. 要素タスクをキューに追加し、ユーザーインタラクションタスクソース 上で、this を与えて、次の手順を実行する：
      1. イベントを発火し、名前は pointerlockerror、対象は this の ノードドキュメント。
      2. Reject（却下） promise に "SecurityError" DOMException を与える。
   2. promise を返す。
5. options["unadjustedMovement"] が true で、 プラットフォームが unadjustedMovement をサポートしていない場合：
   1. 要素タスクをキューに追加し、ユーザーインタラクションタスクソース 上で、this を与えて、次の手順を実行する：
      1. イベントを発火し、名前は pointerlockerror、対象は this の ノードドキュメント。
      2. Reject（却下） promise に "NotSupportedError" DOMException を与える。
   2. promise を返す。
   Issue 90: `unadjustedMovement` がサポートされているかどうかを示す静的フィールドを追加する提案

   PR #49 で PointerLockOptions が導入されましたが、PointerLockOptions の unadjustedMovement は全てのプラットフォームでサポートされるとは限りません。事前にサポート有無を判定できる静的フィールドがあれば、直接 PointerLockOptions を使う前に未サポートエラーを避けられるでしょう。

6. lock requests queue に次の手順をエンキューする：
   1. ユーザーエージェントの pointer-lock target が、その shadow-including root が this の shadow-including root と異なる要素である場合：
      1. 要素タスクをキューに追加し、ユーザーインタラクションタスクソース 上で、this を与えて、次の手順を実行する：
         1. イベントを発火し、名前は pointerlockerror 、対象は this の ノードドキュメント。
         2. Reject（却下） promise に "InvalidStateError" DOMException を与える。
   2. ユーザーエージェントの pointer-lock target の shadow-including root が this の shadow-including root と等しく、options が現在の pointer-lock options と同じ場合：
      1. pointer-lock target を this に設定する。
      2. 要素タスクをキューに追加し、ユーザーインタラクションタスクソース 上で、this を与えて、次の手順を実行する：
         1. イベントを発火し、名前は pointerlockchange 、対象は this の ノードドキュメント。
         2. Resolve（解決） promise を解決する。
   3. pointer-lock target が null または options が現在の pointer-lock options と同等でない場合、ロックリクエストを処理し、完了時に応答を処理する：
      1. ロックリクエストが失敗した場合：
         1. 要素タスクをキューに追加し、ユーザーインタラクションタスクソース 上で、this を与えて、次の手順を実行する：
            1. イベントを発火し、名前は pointerlockerror 、対象は this の ノードドキュメント。
            2. Reject（却下） promise に "NotSupportedError" DOMException を与える。
         Issue 91: 後続の requestPointerLock が拒否された場合、すでにロックされているターゲットはロック解除すべきか？

         PR #49 の requestPointerLock のアルゴリズムは、 次のシナリオの記述が欠落しています：
         後続リクエストが何らかの理由で失敗した場合、すでにロックされているターゲットはロック状態を解除すべきか？

      2. ロックリクエストが成功した場合：
         1. ポインタロック状態に入り、次を行う：
            1. ユーザーエージェントの pointer-lock target を this に設定。
            2. ユーザーエージェントの cursor position を 現在のシステムマウス位置に設定。
            3. pointer-lock options を options に設定。
         2. 要素タスクをキューに追加し、ユーザーインタラクションタスクソース 上で、this を与えて、次の手順を実行する：
            1. イベントを発火し、名前は pointerlockchange 、対象は this の ノードドキュメント。
            2. Resolve（解決） promise を解決する。
   Issue 96: lock requests queue の処理が未完成

   PR#49 の requestPointerLock アルゴリズムは、lock requests queue のエントリがどのように処理されるかの記述がまだありません。 明示的な記述がなければ、すべてのエントリが同期的に最後にデキューされるという誤った仮定が残ることになります。

7. promise を返す。

注

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

onpointerlockchange 属性

イベントハンドラーIDL属性であり、 pointerlockchange イベント用です。

onpointerlockerror 属性

イベントハンドラーIDL属性であり、 pointerlockerror イベント用です。

exitPointerLock() メソッド

1. ユーザーエージェントの pointer-lock target が null の場合、何もせず return する。
2. pointer-lock target の shadow-including root が this の node document と等しくない場合、return する。
3. Exit pointer lock をユーザーエージェントの pointer-lock target で実行する。

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

pointerLockElement

ポインタがロックされている間、マウスイベントのターゲットとなる要素を retargeting した結果を返します。この結果と this 要素が同じツリー内にある場合はその要素を、そうでなければ null を返します。

ロックが保留中またはポインタがロック解除されている場合は null を返します。

例 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>

注

この例では、shadow-root 要素は シャドウルート インスタンスを表す架空の要素です。

#canvas1 がターゲットの場合、document.pointerLockElement は #host1 を返し、root1.pointerLockElement は #canvas1 を返します。retargeting で #canvas1 を #root2 に対して retarget すると #host1 になりますが、#host1 は #root2 と同じツリー内にないため、root2.pointerLockElement は null になります。

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

movementX 属性

movementY 属性

movementX および movementY 属性は、ポインタの位置変化量を提供しなければならない。これは、screenX および screenY の値が2つの連続した mousemove イベント eNow および ePrevious 間で保存されていて、その差分 movementX = eNow.screenX - ePrevious.screenX を取った場合と同様である。

movementX および movementY は、mousemove および pointermove 以外のすべてのマウスイベントでは0でなければならない。すべての移動データは mousemove イベントを通じて届けられるものとし、任意の2つのマウスイベント earlierEvent と currentEvent の間で currentEvent.screenX - earlierEvent.screenX の値が、それらの間に発生した全ての movementX の合計と等しくなる。ただし、ポインタが ユーザーエージェント の画面端でクリップされ screenX が更新できない場合を除く。

movementX および movementY は、pointer lock の状態にかかわらず更新されなければならない。

ロック解除時、システムカーソルは ユーザーエージェント ウィンドウを出入りできる。その際、ユーザーエージェント がOSのマウス移動イベントのターゲットでなかった場合、最新のポインタ位置は ユーザーエージェント で不明となり、 movementX / movementY は算出できず、0に設定されなければならない。

ポインタロックが有効なとき、clientX、clientY、screenX、screenY は、ポインタロックに入った時点からポインタが全く動いていないかのように一定値を保持しなければならない。しかし movementX および movementY は、ロック解除時と同様にポインタの位置変化量を提供し続けなければならない。マウスが一方向へ継続して動かされた場合、movementX および movementY の値に制限はない。マウスカーソルの概念がなくなり、ウィンドウ外や画面端で制限されることもない。

movementX および movementY の未初期化時の値は 0 でなければならない。

マウス入力が中断された場合（たとえば、マウスカーソルがウィンドウを離れて別の場所から再び入る場合など）に、大きな movement 値が出てはならない。ユーザーエージェント がOSからのマウス入力データの受信にギャップを経験した場合、次に生成される mousemove イベントの movementX および movementY は 0 に設定されなければならない。たとえば、ユーザーエージェント がウィンドウシステムAPIでマウス離脱イベントを受信した場合などである。例外として、マウスキャプチャによりカーソルがウィンドウ外に出ても ユーザーエージェント がマウスイベントを受け取り続けることができる場合がある。

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

movementX メンバー

movementY メンバー

movementX および movementY の各メンバーは、それぞれ MouseEvent の対応するメンバーを初期化するために使用されます。

デフォルト解除ジェスチャーは常に利用可能でなければならず、ポインターロックの解除を ユーザーエージェントの pointer-lock target で行うことができなければならない。

pointer-lock target が 切断されるか、ユーザーエージェント・ウィンドウ・タブのいずれかがフォーカスを失った場合、ポインタロックは解除されなければならない。アクティブドキュメント内の要素間や、ブラウジングコンテキスト間でフォーカスを移動しても、pointer lock は解除されない。例えば、キーボード操作でフレームやiframeの内容間でフォーカスを移動しても解除されない。

フルスクリーン［FULLSCREEN］が開始または終了した際、ユーザーエージェントのグラフィカルユーザーインターフェース操作にポインターが必要な場合、デフォルト解除ジェスチャーによって両方を解除した場合、またはウィンドウやタブのフォーカスが失われた場合を除き、ポインターロックは解除してはならない。

非規範的と明記されたセクションだけでなく、この仕様書のすべての執筆ガイドライン、図、例、注記も非規範的です。それ以外はすべて規範的です。

この仕様は、ひとつの製品、すなわち本仕様に含まれるインターフェースを実装するユーザーエージェントに適用される適合性基準を定義します。