WebXR DOM オーバーレイモジュール

1. はじめに

1.1. 概要

2. HTML API 統合

このモジュールは、GlobalEventHandlers の定義に新しいイベント型を追加します。

2.1. onbeforexrselect

型が beforexrselect である XRSessionEvent は、入力ソースの targetRaySpace の -Z 軸が、入力デバイスの primary action が トリガーされた時点で DOM オーバーレイ要素と交差する場合、WebXR selectstart 入力イベントを生成する前に、DOM オーバーレイ要素上で配送されます。

partial interface mixin GlobalEventHandlers {
  attribute EventHandler onbeforexrselect;
};

このイベントは、型が beforexrselect である XRSessionEvent で、バブルし、キャンセル可能で、composed です。その target 要素は、targetRaySpace によって交差されている最上位イベントターゲットであり、DOM オーバーレイ要素の子孫または DOM オーバーレイ要素自体のいずれかです。

preventDefault() を呼び出してこのイベントをキャンセルすると、この primary action に対して入力ソースが通常生成する既定の WebXR 入力イベントが抑制されます。selectstart、 selectend、 および select イベントは、この インタラクションシーケンスに対して発火されません。

注: 将来の WebXR モジュールは、 このイベントのキャンセルによって影響を受ける追加のイベントまたは WebXR 入力依存データを定義する可能性があります。 たとえば、一時的な入力ソースのヒットテスト購読からの結果を抑制する場合などです。

このイベントおよびイベントハンドラーによって取られる処理は、DOM イベント処理に影響を与えず、 DOM イベント配送とも同期されません。ユーザーのアクションは別途、`"pointerdown"` などの 適切な DOM イベントを生成し、それらの DOM イベントは対応する beforexrselect イベントの前または後に発生し得ます。これは、 beforexrselect イベントがキャンセルされたかどうかに関係なく発生し、 XR 入力イベントハンドラーで実行される以後の処理とは独立しています。

注: このイベントは、ユーザーが DOM UI と インタラクションしている間に、アプリケーションが重複する XR 入力イベントを抑制する方法を提供します。これはバブルする イベントであるため、アプリケーションは適切なコンテナー要素にハンドラーを登録し、DOM オーバーレイの領域を XR 入力をブロックするものとして実質的にマークできます。これは DOM 要素の視覚的不透明度とは独立しています。 XR 入力イベントをブロックしない、テキスト説明などの非インタラクティブな不透明または半透明 DOM コンテンツを 表示することも可能です。

document.getElementById('button-container').addEventListener(
  'beforexrselect', ev => ev.preventDefault());

2.2. CSS 擬似クラス

:xr-overlay 擬似クラスは、 DOM Overlay を使用する没入型セッションの間、overlay element に一致しなければなりません。

overlay element は、backdrop root です。

注: DOM オーバーレイ要素またはその子孫に対する バックドロップフィルター効果は、AR カメラ画像（該当する場合）または没入型セッションの XRWebGLLayer に描画されるレンダリング済みコンテンツを変更しません。

オーバーレイ要素の祖先に対するスタッキングコンテキストがある場合、それらは没入型セッションの ディスプレイには描画されません。

注: overlay element 自体は、 `position: fixed` スタイルにより スタッキング コンテキストです。

注: マルチディスプレイシステムでは、UA は デスクトップモニターなどの別個のディスプレイ上に、オーバーレイ要素の祖先または兄弟ツリーの スタッキングコンテキストを描画してもよいです。

2.3. ユーザーエージェントレベルのスタイルシート既定値

overlay element に対するユーザーエージェントスタイルシート既定値は次のとおりです:

:xr-overlay {
    /* 透明な背景を強制する */
    background: rgba(0,0,0,0) !important;

    /* 子孫の包含ブロックとして機能する */
    contain: paint !important;

    /* 次のスタイル指定は :fullscreen と同一 */
    position: fixed !important;
    top: 0 !important;
    right: 0 !important;
    bottom: 0 !important;
    left: 0 !important;
    margin: 0 !important;
    box-sizing: border-box !important;
    min-width: 0 !important;
    max-width: none !important;
    min-height: 0 !important;
    max-height: none !important;
    width: 100% !important;
    height: 100% !important;
    transform: none !important;

    /* 意図的に !important ではない */
    object-fit: contain;
}

注: これは Fullscreen API § 5.2 ユーザーエージェントレベルのスタイルシート既定値に基づくものであり、 オーバーレイ要素の背景を透明にする追加のスタイル指定を含みます。:xr-overlay のスタイル指定は、Fullscreen API の擬似クラスまたはスタイル指定に明示的には依存しないため、 ユーザーエージェントは Fullscreen API とは独立してこれを実装する柔軟性を持ちます。

注: Fullscreen API は現在、 `contain: paint` 規則を指定していませんが、これは典型的な UA の挙動と一致しており、 その仕様の将来の改訂で追加される予定です。

注: アプリケーションは、セッション中に UI 要素を条件付きでスタイル指定するために、インターフェイス要素の可視性の制御を含めて、:xr-overlay 擬似クラスを使用することが推奨されます。

2.4. Fullscreen API 統合

UA は DOM Overlay を [FULLSCREEN] API の特殊な場合として実装してもよいです。この場合、UA は 没入型セッションの間、アクティブな fullscreen 要素への変更を防止し、requestFullscreen 要求を拒否しなければなりません。

注: DOM Overlay API は、 セッション開始時にオーバーレイ要素を指定することを要求し、セッション中にアクティブなオーバーレイ要素を変更する 仕組みを提供しません。Fullscreen API を使用してアクティブなオーバーレイ要素を間接的に変更できる場合、 アプリケーションはプラットフォーム間で一貫性のない挙動になります。

DOM Overlay が Fullscreen API を通じて実装される場合、root 要素のスタッキングコンテキストは、没入型ディスプレイには描画されません。没入型ディスプレイに描画されるのは、 top layer 内の要素のスタッキングコンテキストのみであり、そこには overlay element も含まれます。

注: 既定では、fullscreen モードは不透明な黒の バックドロップを使用します。変更された描画規則により、このバックドロップを描画する必要がなくなり、 オーバーレイ要素の祖先または兄弟ツリーが透明なオーバーレイ要素を通して見えないようになります。

注: Fullscreen API に基づく実装を許可することは、主に、没入型セッション中にページの残りの部分が見えない 単一ディスプレイシステムを意図しています。マルチディスプレイシステムでは、技術的には、 デスクトップモニターなどの別個のディスプレイにページの残りの部分を表示しながら、オーバーレイ要素に Fullscreen API を 使用することができ、その場合 UA は、オーバーレイ要素の祖先または兄弟ツリーのスタッキングコンテキストを その別個のディスプレイ上に描画してもよいです。

あるいは、UA は [FULLSCREEN] API とは独立して DOM Overlay を実装してもよいです。この場合、overlay element は なお :xr-overlay 擬似クラスに一致しなければならず、この擬似クラスに対する § 2.3 ユーザーエージェントレベルのスタイルシート既定値を使用して 没入型ビュー内でスタイル指定されなければなりません。UA は、overlay element の外側にある要素に対して fullscreen API を使用することを 別途サポートしてもよいですが、これは DOM オーバーレイコンテンツの表示方法にいかなる影響も与えてはなりません。

注: DOM Overlay と Fullscreen API を 独立して処理することは、接続された VR ヘッドセットを持つデスクトップ PC などのマルチディスプレイシステムを サポートすることを意図しています。この場合、Fullscreen API は 2D モニター上のページコンテンツを制御するために 使用できます。たとえば、三人称レンダリングビューを持つ fullscreen canvas 要素を表示しながら、 DOM オーバーレイ要素と没入型コンテンツをヘッドセット内に別個に表示できます。

没入型セッションが、元々表示されていた Web ページとは別の出力デバイスを使用するマルチディスプレイシステムでは、 overlay element は、没入型ビューに表示されている間、 2D Web ページの一部として他のディスプレイ上で可視またはインタラクティブであってはなりません。UA は、 セッションの間、他のディスプレイ上のページ全体を非表示または無効化することを選択してもよいです。

注: DOM オーバーレイコンテンツを、 非インタラクティブなヘッドセットミラービューまたは同様の非 Web ページ UI の一部として表示することは問題ありません。 このマルチディスプレイ制限の意図は、オーバーレイ要素が同時に 2 か所に表示される場合に、 その表示の不整合や潜在的に混乱を招くインタラクションを避けることです。また、DOM 要素を 2 つの別々の ディスプレイに同時に表示することに関する実装上の課題も回避します。

3. WebXR Device API 統合

このモジュールは、XRSessionInit および XRSession の定義を拡張し、XRInputSource イベントの挙動を変更します。

3.1. XRSessionInit

このモジュールは、文字列 dom-overlay を、 immersive sessions 用の requiredFeatures または optionalFeatures シーケンスで使用する新しい有効なfeature descriptorとして導入します。

デバイスは、没入型セッションの間、ユーザーが DOM コンテンツを見てインタラクションする方法を 提供する場合、DOM オーバーレイ機能をcapable of supportingします。

注: 実装上の選択肢には、 ハンドヘルド AR デバイス上の fullscreen オーバーレイ、または VR もしくは AR ヘッドセット向けの 空間内の浮遊矩形が含まれます。

DOM コンテンツは、最上位のコンテンツレイヤーであるかのように合成されなければなりません。これは XRWebGLLayer からのコンテンツ、または AR デバイスのパススルーカメラからの画像によって遮蔽されてはなりません。 アプリケーションは通常の CSS 規則を使用して、DOM オーバーレイ自体の内部におけるコンテンツの透明度と 2D 配置を制御できます。

DOM オーバーレイは、セッションの開始時からユーザーに自動的に可視でなければならず、 それを可視にするためにユーザーがボタンを押したり他の手動操作を行ったりする必要があってはなりません。

注: コンテンツ要素が間接的にしか見えない場合、 たとえば、セッション中に通常見えない別個の 2D モニター上のコンテンツを見るために、ユーザーが ヘッドセットを外したり、パススルーカメラを手動で有効にしたりする必要がある場合、デバイスは DOM オーバーレイを サポートすると主張すべきではありません。ただし、ユーザーが DOM オーバーレイコンテンツを表示する物理的な タッチスクリーンデバイスを携帯している没入型 CAVE システムは、有効な実装です。

XRSessionInit 辞書は、新しい domOverlay メンバーを追加することによって拡張されます。これは XRSessionInit の任意メンバーですが、既定のオーバーレイ要素が存在しないため、DOM オーバーレイ機能を使用する場合は 指定しなければなりません。

partial dictionary XRSessionInit {
  XRDOMOverlayInit? domOverlay;
};

DOM オーバーレイ機能が必須機能であるにもかかわらず、アプリケーションが domOverlay メンバーを供給しなかった場合、UA はこれを未解決の必須機能として扱い、requestSession() promise を NotSupportedError で拒否しなければなりません。任意機能として要求された場合、UA は機能要求を無視し、DOM オーバーレイを有効にしてはなりません。

注: UA は、DOM オーバーレイが有効にならなかった理由を説明する 開発者コンソールメッセージなどのローカル警告を出してもよいです。

3.2. XRSession

このモジュールは XRSession インターフェイスを拡張し、DOM オーバーレイ機能の現在の状態を反映する 新しい読み取り専用属性を追加します。

partial interface XRSession {
  readonly attribute XRDOMOverlayState? domOverlayState;
};

domOverlayState 属性は、dom-overlay 機能がサポートされていない、または有効になっていない場合、null でなければなりません。

この機能が有効である場合、属性値は存在しなければなりません。

注: アプリケーションは、domOverlayState の存在を確認することで、たとえば任意機能として要求した場合に、DOM オーバーレイ機能が有効で動作していることを 検証できます。

注: DOM オーバーレイは、 たとえばユーザーエージェントが固定された向きまたは位置に配置し、ユーザーの移動後にそれがユーザーの視野外に 出てしまう場合など、一時的にユーザーから見えなくなることがあります。この間も domOverlayState 属性は設定されたままです。

セッションが可視の DOM オーバーレイとともにアクティブである間、UA はこれを rendering opportunity として扱い、DOM コンテンツのアニメーションに適した速度で Window の requestAnimationFrame() コールバックを実行しなければなりません。これらは、requestAnimationFrame() コールバックが XRWebGLLayer コンテンツの描画に使用される場合とは異なる時刻および頻度で実行されてもよいです。

3.3. XRInputSource

XRInputSource が、その primary action に対応するプラットフォーム固有のアクションを開始するとき、 UA は、このアクションが primary action として扱われるかどうかを決定するために、入力処理を開始する前に次の手順を 実行しなければなりません:

注: 実質的に、beforexrselect イベントをキャンセルすると XR 入力 select イベントが抑制され、このアクションに対して selectstart、 selectend、 または select のいずれも生成されません。一時的な 入力ソースについては、inputsourceschange イベントは引き続き生成されますが、beforexrselect イベントをキャンセルすると、そのアクションは二次的な指入力と同様に auxiliary action として扱われます。

4. 初期化

アプリケーションは、domOverlay 辞書を通じて DOM オーバーレイの構成を提供しなければなりません。

dictionary XRDOMOverlayInit {
  required Element root;
};

root 属性は、DOM オーバーレイの内容としてユーザーに表示される overlay element を指定します。これは必須属性であり、 既定値はありません。

let uiElement = document.getElementById('ui');
navigator.xr.requestSession('immersive-ar', {
    optionalFeatures: ['dom-overlay'],
    domOverlay: { root: uiElement } }).then((session) => {
    // session.domOverlayState.type is now set if supported,
    // or is null if the feature is not supported.
  }
}

アクティブな間、DOM オーバーレイ要素は、UA が提供する DOM オーバーレイ矩形の寸法を満たすように 自動的にリサイズされます。その背景色は、セッションの間、自動的に透明としてスタイル指定されます。

注: UA は、DOM オーバーレイ要素をスタイル指定するために Fullscreen API § 5.2 ユーザーエージェントレベルのスタイルシート既定値を使用し、背景を透明に設定するために background-color: rgba(0,0,0,0) !important; を含む追加規則を加えてもよいです。

セッションがアクティブになると、domOverlayState 属性は DOM オーバーレイに関する情報を提供します。

enum XRDOMOverlayType {
  "screen",
  "floating",
  "head-locked"
};

dictionary XRDOMOverlayState {
  XRDOMOverlayType type; 
};

ユーザーエージェントは、DOM オーバーレイがどのように表示されているかを示すように type を設定しなければなりません。その値は、セッションの間、変更されないままでなければなりません。

• screen のオーバーレイ型は、DOM オーバーレイ要素が、 たとえばハンドヘルド AR のようなスクリーンベースのデバイスに対して、物理スクリーン全体を覆うことを示します。 その視覚的範囲は、XRViewport （複数の場合も含む）の視覚的範囲と一致しなければなりません。これは XRWebGLLayer レンダリングに使用されるものです。単眼表示では、これは単一のビューポートです。立体視表示スクリーンは 2 つのビューポートを提供することになり、その場合 DOM オーバーレイは物理スクリーン位置に一致する Z 位置でレンダリングされ、両眼ビューで同一に見えなければなりません。

• floating のオーバーレイ型は、DOM オーバーレイが 空間内の浮遊矩形として現れることを示します。この矩形のワールド空間内での初期位置は UA に委ねられ、UA はセッション中にこれを移動して視界内に保つか、ユーザーによる手動配置を サポートしてもよいです。

• head-locked のオーバーレイ型は、DOM オーバーレイがユーザーの頭部の動きに一貫して追従し、ヘルメット型ヘッドアップディスプレイに似た形で 表示されることを示します。

注: ユーザーの視点からは、"floating" オーバーレイは現実世界の位置に固定されているかのようにレンダリングされると静止しているように知覚され、 このスタイルは VR におけるインタラクティブ表示面として一般的な選択です。"head-locked" オーバーレイは 頭部回転に合わせて動き、固定された現実世界の位置を持ちません。

注: この仕様の将来のバージョンでは、 たとえば浮遊オーバーレイのワールド空間内の現在位置など、オーバーレイ状態に追加の属性が加えられる可能性があります。

5. クロスオリジンコンテンツに対するイベント処理

ユーザーエージェントは、DOM オーバーレイ要素内に入れ子にされた HTMLIFrameElement などのクロスオリジンコンテンツとのユーザーインタラクションに対して、ポーズまたは gamepad 入力状態を 提供してはなりません。

ユーザーエージェントは、たとえば通常そのコンテンツによって受信される DOM イベントをブロックすることにより、 またはクロスオリジンコンテンツをまったく読み込まず表示しないことにより、 クロスオリジンコンテンツとのユーザーインタラクションを防止して、この要件を満たしてもよいです。

ユーザーエージェントが DOM オーバーレイ内のクロスオリジンコンテンツとのインタラクションをサポートし、 かつ入力ソースの targetRaySpace が最上位 イベントターゲットとしてクロスオリジンコンテンツと交差する場合、UA は WebXR Device API § 13.4.3 Limiting データ調整を有効にし、その入力ソースに関連付けられた XRSpace に対して、limit boolean を true として扱ってpopulate the pose しなければなりません。さらに、ポーズが制限されている間、UA はこの入力ソースの gamepad データを 更新してはなりません。

注: この方法でポーズが制限されている間、 アプリケーションはコントローラーまたはそのターゲティングレイのポーズ更新を受け取りません。UA は、 インタラクションを可能にするために必要に応じて、ポインターレイまたはその他の適切な視覚化を描画する責任を負います。

注: gamepad データの更新を制限することは、 クロスオリジンコンテンツとのインタラクションからアプリケーションへの情報漏えいを避けることを意図しています。 たとえば、入力ソースの primary action が、あるトリガーしきい値で primary action が発生するアナログトリガーを使用する場合、対応するイベントがブロックされていても、 アプリケーションはトリガー値から、ユーザーが primary action を開始および終了した時点を推測できます。 別の例として、DOM コンテンツでのテキスト入力にトラックパッドまたはジョイスティックを使用するデバイスでは、 軸値を読み取ることで、アプリケーションが入力されているテキストを推測できる場合があります。

primary action がクロスオリジンコンテンツ内で終了する場合、UA は primary action をキャンセルされたものとして扱い、select イベントを送信してはなりません。UA は、 ポーズを制限されたものとして扱うことにより、クロスオリジンコンテンツに入る前の最後に利用可能だったポーズを使用して selectend イベントを送信しなければなりません。

入力が transient input source であり、かつ transient action がクロスオリジンコンテンツ内で開始する場合、ユーザーエージェントは、 入力位置がクロスオリジンコンテンツの外に移動するまで、adding the input source を 遅延しなければなりません。transient action がまだクロスオリジンコンテンツ内にある間に 終了する場合、一時的な入力ソースはまったく追加されません。

注: screen モードの 入力を使用するハンドヘルド AR デバイスでは、これは、クロスオリジンコンテンツ内に留まるタッチが入力ソースまたは 関連する XR 入力イベントを作成しないことを意味します。ドラッグ移動がクロスオリジンコンテンツ内で開始する場合、 入力ソースは、タッチ位置がクロスオリジンコンテンツから離れた位置で作成され、通常どおりキャンセル可能な beforexrselect イベントを発行します。

6. セキュリティ、プライバシー、および快適性に関する考慮事項

6.1. 保護された機能

DOM オーバーレイ自体は、新しい機微情報を導入しません。しかし、既存の技術を組み合わせるため、 この組み合わせが予期しないインタラクションにつながらないようにすることが重要です。

このモジュールの主要な設計目標は、DOM オーバーレイが可能な限り 2D コンテンツの既存のセマンティクスに従うことでした。 具体的には、クロスオリジン埋め込みコンテンツに関連する情報フローは、2D ページ上で iframe を使用する場合と 類似しているべきです。たとえば、2D ページはクロスオリジンコンテンツを iframe に埋め込み、その iframe を 透明な要素で覆うことができます。その場合、ページは引き続きマウス移動情報を受け取りますが、 クロスオリジンコンテンツは覆われた領域内の入力イベントを受け取りません。DOM オーバーレイでは、 XR 入力イベントデータはマウス移動データと同様に扱われます。クロスオリジンコンテンツが存在しない場合、 またはクロスオリジンコンテンツが入力を受信していない場合、ポーズは外側のページで引き続き利用可能ですが、 クロスオリジンコンテンツとインタラクションしているときは制限（ブロック）されます。

クロスオリジンコンテンツは、クリックジャッキング脅威に対して潜在的に脆弱です。UA は、 iframe が DOM オーバーレイで使用される場合、Content Security Policy 3 § 6.1.5 frame-src などの緩和策を引き続き適用しなければなりません。UA は、特定の脅威に対処するために必要であれば、 DOM オーバーレイ内のクロスオリジンコンテンツに特化した追加の制限を実装してもよいです。

変更点

2021年8月31日の最初の公開作業草案からの変更点

7. 謝辞

次の個人が WebXR DOM Overlay 仕様の設計に貢献しました:

• Brandon Jones (Google)

• Nell Waliczek (Amazon [2018年までは Microsoft])