index.md

title	short-title	slug	l10n
XRReferenceSpace: reset イベント	reset	Web/API/XRReferenceSpace/reset_event	sourceCommit 89c435da452257b944b403cc9e45036fcb22590e

{{APIRef("WebXR Device API")}}{{SecureContext_Header}}

reset イベントは、ネイティブの原点または実際の原点のいずれかで不連続が検出されると {{domxref("XRReferenceSpace")}} オブジェクトに送信され、参照空間を使用して方向付けられたオブジェクトの位置または方向がジャンプします。 これは、ユーザーが XR 機器を較正または再較正する場合、または機器がユーザーの追跡を失った後に原点を自動的に変更してから再び取得する場合によく見られます。

{{domxref("XRBoundedReferenceSpace")}} オブジェクトの場合、{{domxref("XRBoundedReferenceSpace.boundsGeometry", "boundsGeometry")}} が変更されたときに reset イベントを発生させることもあります。

いずれの場合も、イベントは、新しい原点を利用する WebXR アニメーションフレームが実行される前に送信されます。

このイベントはキャンセルできません。

構文

このイベント名を {{domxref("EventTarget.addEventListener", "addEventListener()")}} などのメソッドで使用するか、イベントハンドラープロパティを設定するかしてください。

addEventListener("reset", (event) => {});

onreset = (event) => {};

イベント型

{{domxref("XRReferenceSpaceEvent")}} です。 {{domxref("Event")}} を継承しています。

イベントプロパティ

以下に挙げたプロパティに加えて、親インターフェイスである {{domxref("Event")}} のプロパティが利用できます。

• {{domxref("XRReferenceSpaceEvent.referenceSpace", "referenceSpace")}} {{ReadOnlyInline}}
  • : イベントを生成した参照空間を示す {{domxref("XRReferenceSpace")}} です。
• {{domxref("XRReferenceSpaceEvent.transform", "transform")}} {{ReadOnlyInline}}
  • : イベント前の座標系を基準にして定義された、イベント後の指定された referenceSpace のネイティブの原点の位置と向きを示す {{domxref("XRRigidTransform")}} オブジェクト。

解説

reset イベントは、参照空間の原点を変更し、イベントの {{domxref("XRReferenceSpaceEvent.transform", "transform")}} プロパティで示されるように移動および回転することにより、座標系がリセットまたは再構成されたことを示します。 イベントは、アニメーションフレームのコールバックが実行されて保留中のフレームがレンダリングされる前に送信され、これらのコールバックで更新された座標系が使用可能であることを確認します。

リセットが発生する理由はいくつかあります。 それらの間で最も一般的なものは次のとおりです。

• ユーザーが、顔の向きおよびハンドコントローラーがユーザーの実際の位置および顔の向きと同期するようにヘッドセット自体の再較正を要求するなどして、手動で座標系をリセットしました。 これは主に、local または local-floor の参照空間の問題です。
• bounded-floor 参照空間では、ユーザーが参照空間の境界を出て新しい参照空間に入る場合、座標系をリセットできます（ゲーム内のあるレベルから別のレベルに横断する場合など、各レベルは独自の座標系を持つ独自のマップです）。
• 追跡システムは一時的にユーザーを見失い、その後再びユーザーを取り戻しましたが、最後に知られた位置のすぐ近くを離れるのに十分な距離を移動した後になってからでした。 主に unbounded 参照空間の問題です。
• ユーザーは、unbounded 参照空間にいて、開始位置（参照空間の原点）から十分に離れているため、浮動小数点またはその他の形式の誤差またはドリフトが問題になります。 このため座標系は、ユーザーの現在の位置またはその近くの新しい原点でリセットされます。
• WebXR インフラストラクチャーまたはハードウェアドライバーは、機器が一時的に追跡を失い、ハードウェアとソフトウェアの位置と方向が同期していないことを検出しました。

Note

参照空間が以前の原点の追跡を取り戻すことができる場合、reset イベントは発生しません。 これは、原点が強制的に再配置されていないことを意味します。 このイベントは、追跡喪失から回復するために原点を再配置する必要がある場合にのみ発生します。

手動リセット

VR ヘッドセットを使用したことがある人なら、起動したときに正面を向いているのに、ヘッドセットは空や床を見ていると勘違いしたり、ハンドコントローラーをまっすぐ前に向けているのに、どこか上や右に向けていると勘違いしたりしたことがあるでしょう。このような場合、通常はどこかのボタンを押し続けると、世界が機器の現在の向きに再同期されます。 これは、ヘッドセットの向きに基づいた 1 つまたは複数の参照空間に reset イベントを送信することで機能します。

不連続性の処理

ビューアーの位置のジャンプは、{{domxref("XRPose")}} の論理値プロパティ {{domxref("XRPose.emulatedPosition", "emulatedPosition")}} を監視することで処理できます。 ビューアーの位置のジャンプが、emulatedPosition が true から false に切り替わるのと同時に起こった場合、ビューアーは追跡を回復し、新しい位置は以前にエミュレートされた値からの補正を表します。 これは、サイトまたはアプリが、（XR 機器が移動を導入するために使用するユーザーの物理的な移動ではなく）ビューアーの位置や向きを明示的に変更することによる空間内のモーションをシミュレートしない場合に一般的に望ましい振る舞いです。

ただし、そのような「テレポート」が使用されている場合は、追跡を回復した後に、追加の潜在的に不快なジャンプが発生する可能性があり、実際にはユーザーの位置をジャンプしないようにする必要があります。 これを許可する代わりに、 {{domxref("XRReferenceSpace.getOffsetReferenceSpace", "getOffsetReferenceSpace()")}} を呼び出す前に計算されたテレポーテーションオフセットに emulatedPosition を統合して、更新された実際の原点が前のフレームからビューアーの位置がジャンプした隔たりによって調整された新しい参照空間を作成できます。 このようにして、ユーザーの位置を 2 回ではなく 1 回だけ変更します。

不連続の大きさの効果

不連続が十分に小さく、機器が同じ追跡領域内で追跡を取り戻せる場合、reset イベントは発生しません。 また、ユーザーの近くで空間の安定性を維持するために、時間の経過とともにネイティブの原点に小さな調整を加えるため、unbounded 参照空間で発生することもありません。 大きな不連続のみがリセットをトリガーします。

例

reset イベントのハンドラーを追加するには、2 つの方法のいずれかを使用できます。 まず、次のように {{domxref("EventTarget.addEventListener", "addEventListener()")}} メソッドを使用できます。

viewerRefSpace.addEventListener("reset", (event) => {
  /* リセットに関連するタスクを実行 */
});

2 番目のオプションは、次のように XRReferenceSpace オブジェクトの onreset イベントハンドラープロパティを設定することです。

viewerRefSpace.onreset = (event) => {
  /* リセットに関連するタスクを実行 */
};

仕様書

{{Specifications}}

ブラウザーの互換性

{{Compat}}