XRReferenceSpace

安全なコンテキスト用: この機能は一部またはすべての対応しているブラウザーにおいて、安全なコンテキスト (HTTPS) でのみ利用できます。

WebXR Device API の XRReferenceSpace インターフェイスは、指定された追跡の振る舞いを使用して、仮想世界内の特定の追跡対象のエンティティまたはオブジェクトの座標系を記述します。追跡の振る舞いは、選択した参照空間タイプによって定義されます。いくつかの異なる追跡の振る舞いのサポートを追加し、追跡対象オブジェクトと世界の別の場所との間のオフセット変換を記述する新しい参照空間を要求することにより、基本クラス XRSpace (en-US) を拡張します。

すべての参照空間（制限付き参照空間を除く）は、XRReferenceSpace タイプを使用して記述されます。制限付き空間は、XRBoundedReferenceSpace オブジェクトとして実装されます。これは、ビューアーが移動するのに「安全」な境界を確立できる特別な空間です。実世界のカメラで移動を追跡するシステムなど、ユーザーが物理的に動き回ることができる XR システムの場合、この境界は、物理的な障害によるものか、XR ハードウェアの制限によるものかにかかわらず、ユーザーが動き回ることができる領域の縁を確立します。ユーザーが物理的および仮想的な障害物と衝突しないようにするための境界の使用の詳細については、制限付き参照空間を使用したビューアーの保護 (en-US)の記事を参照してください。

プロパティ

XRSpace (en-US) から継承されたプロパティ（現時点では、ない）に加えて、XRReferenceSpace は EventTarget のプロパティも継承します。 XRReferenceSpace は、追加のプロパティを定義しません。

メソッド

親インターフェイスである XRSpace (en-US) から継承されたメソッド（現時点では、ない）に加えて、XRReferenceSpace は EventTarget からメソッドを継承します。 XRReferenceSpace は、次のメソッドも提供します。

getOffsetReferenceSpace(): メソッドを呼び出したものと同じ型（つまり、XRReferenceSpace または XRBoundedReferenceSpace）の新しい参照空間オブジェクトを作成して返します。新しい参照空間を使用して、メソッドが呼び出されたオブジェクトの参照空間から別の座標空間に座標を変換できます。これは、レンダリング中にオブジェクトを配置したり、3D 空間でビューアーの位置や向きを変更するときに必要な変換を実行したりするのに役立ちます。

イベント

XRSpace (en-US) または EventTarget オブジェクトに送信される可能性のある他のイベントに加えて、以下も XRReferenceSpace オブジェクトに適用されます。

reset

reset イベントは、ユーザーの環境または場所を基準にして追跡対象オブジェクトの原点で不連続性が発生したことをブラウザーが検出すると、XRReferenceSpace オブジェクトに送信されます。これは、例えば、ユーザーが XR デバイスを再調整した後や、追跡を失って回復した後にデバイスが原点を自動的に調整した場合に発生する可能性があります。

addEventListener() の使用に加えて、onreset (en-US) イベントハンドラープロパティを設定することにより、reset イベントハンドラーを確立できます。

参照空間タイプ

XRSession.requestReferenceSpace() によって返される参照空間は、XRReferenceSpace または XRBoundedReferenceSpace のいずれかです。以下の表の「インターフェイス」列は、各参照空間タイプ定数に対して2つの型のどちらが返されるかを示しています。

参照空間記述子

参照空間のタイプを以下の表に示します。それらのユースケースと、それらを実装するために使用されるインターフェイスについての簡単な情報が含まれています。

XRReferenceSpaceType	説明	インターフェイス
`bounded-floor`	`local` タイプと同様ですが、返されたオブジェクトの `boundsGeometry` によって指定された所定の境界の外にユーザーが移動することは想定されていません。	`XRBoundedReferenceSpace`
`local`	セッションが作成されたときのネイティブの原点がビューアーの位置の近くにある追跡空間。正確な位置は、基盤となるプラットフォームと実装によって異なります。ユーザーは、開始位置を超えて移動することはあまり想定されておらず、この使用例に合わせて追跡が最適化されています。 6 自由度（6DoF）追跡のデバイスの場合、`local` 参照空間は、環境に対して原点を安定させようとします。	`XRReferenceSpace`
`local-floor`	`local` タイプと同様ですが、開始位置は、ビューアーが立つことができる安全な場所に配置され、y 軸の値は床レベルで 0 です。その床レベルがわからない場合、ユーザーエージェントは床レベルを推定します。推定床レベルがゼロ以外の場合、ブラウザーはフィンガープリントを回避するような方法で丸めることが期待されます（最も近いセンチメートルまで）。	`XRReferenceSpace`
`unbounded`	おそらく原点から非常に長い距離にわたって、ユーザーが自由に移動できる追跡空間。ビューアーはまったく追跡されません。追跡は、ユーザーの現在位置周辺の安定性のために最適化されているため、ネイティブの原点は、そのニーズに対応するために必要に応じてドリフトする可能性があります。	`XRReferenceSpace`
`viewer`	ネイティブの原点がビューアーの位置と向きを追跡する追跡空間。これは、ユーザーが物理的に移動できる環境で使用し、没入型（immersive）とインライン（inline）の両方の `XRSession` (en-US) のすべてのインスタンスをサポートしますが、インラインセッションで最も役立ちます。ビューアーと入力の間の距離を決定するとき、またはオフセット空間を操作するときに特に役立ちます。そうでない場合、通常、他の参照空間タイプの1つがより頻繁に使用されます。	`XRReferenceSpace`

使用上の注意

XRReferenceSpace の作成

XRReferenceSpace を取得する必要がある状況は2つあります。 1つ目は、シーンを設定し、XRSession (en-US) の期間中、世界に対するユーザーの視点を表す参照空間を取得する必要がある場合です。これを行うには、XRSession (en-US) のメソッド requestReferenceSpace() を呼び出して、取得する参照空間タイプを指定します。

xrSession.requestReferenceSpace("local").then((refSpace) => {
  xrReferenceSpace = refSpace;
  /* ... */
});

新しい参照空間を取得する必要があるもう1つの状況は、原点を新しい位置に移動する必要がある場合です。これは通常、例えば、あなたのプロジェクトで、ユーザーが XR デバイスを介して接続されていないキーボード、マウス、タッチパッド、ゲームコントローラーなどの入力デバイスを使用して環境内を移動できる場合に行われます。原点は通常、空間内のユーザーの位置であるため、原点を変更して、ユーザーの移動と方向の変更を反映する必要があります。

ユーザーの世界のビューを移動または回転するには、その視点を表すために使用される XRReferenceSpace を変更する必要があります。ただし、XRReferenceSpace は不変であるため、代わりに、変更された視点を表す新しい参照空間を作成する必要があります。これは、getOffsetReferenceSpace() メソッドを使用して簡単に実行できます。

let offsetTransform = new XRRigidTransform({x: 2, y: 0, z: 1},
                                           {x: 0, y: 1, z: 0, w: 1});
xrReferenceSpace = xrReferenceSpace.getOffsetReferenceSpace(offsetTransform);

これにより、XRReferenceSpace を新しいものに置き換えます。その原点と向きは、新しい原点を現在の原点に対して (2, 0, 1) に配置するように調整し、前の世界の向きに対してビューアーを真上に向けるように空間を向ける単位クォータニオンを指定して回転します。

ジオメトリー

XRReferenceSpace のネイティブ原点は、+X が右側、+Y が上向き、+Z が「後方」またはユーザーに向かっていると見なされるように常に構成されています。

仕様

仕様	状態	コメント
WebXR Device API XRReferenceSpace の定義	草案	初期定義

ブラウザーの互換性

BCD tables only load in the browser