XRSystem: requestSession() メソッド
Experimental: これは実験的な機能です。
本番で使用する前にブラウザー互換性一覧表をチェックしてください。
安全なコンテキスト用: この機能は一部またはすべての対応しているブラウザーにおいて、安全なコンテキスト (HTTPS) でのみ利用できます。
XRSystem
インターフェイスの requestSession()
メソッドは、プロミス (Promise
) を返します。このプロミスは XRSession
オブジェクトに解決し、リクエストされた型の WebXR セッションを管理します。
一度にアクティブにできる没入型 VR セッションは 1 つだけですが、複数のインラインセッションを同時に進行することができます。
構文
requestSession(mode)
requestSession(mode, options)
引数
mode
-
文字列 (
String
) で、 XR セッションモードを定義します。対応しているモードは次の通りです。-
Experimental
immersive-ar
: セッションの出力は没入型端末に独占的にアクセスされますが、レンダリングされたコンテンツは現実の環境と混合されます。 このセッションのenvironmentBlendMode
は、コンテンツを混合するために使用するメソッドを示します。 -
immersive-vr
: このレンダリングセッションは VR モードの没入型 XR 端末を使用して表示されます。周囲の環境に重ねたり統合したりすることは意図していません。environmentBlendMode
は可能な限りopaque
であることが期待されますが、ハードウェアが要求される場合はadditive
であるかもしれません。 inline
: 出力は、視覚空間全体を占めるのではなく、標準 HTML 文書内の要素のコンテキスト内でインライン表示されます。インラインセッションはモノラルまたはステレオモードで表示することができ、ビューアートラッキングを利用できる場合とできない場合があります。インラインセッションは特別なハードウェアを要求されず、 WebXR API を対応しているユーザーエージェントであれば利用できるはずです。
-
Experimental
options
省略可-
XRSession
を構成するためのオブジェクト。何も含まれない場合、端末はすべてのオプションに対して既定の機能構成を使用します。requiredFeatures
省略可: 返されたXRSession
が対応しなければならない値の配列。対応しなければならない値の配列。下記のセッション機能を参照ください。optionalFeatures
省略可: 返されたXRSession
がオプションで対応している機能を表す値の配列。下記のセッション機能を参照ください。domOverlay
省略可: DOM オーバーレイのコンテンツとしてユーザーに表示されるオーバーレイ要素を指定するroot
プロパティが要求されるオブジェクトです。下記の例を参照してください。depthSensing
省略可: 2 つの必須プロパティusagePreference
とdataFormatPreference
を持つオブジェクトで、深度測定の実行方法を設定します。下記の例を参照してください。
返値
例外
このメソッドは実際には例外を発生させません。代わりに、name
が以下のいずれかである DOMException
を渡して、返されたプロミスを拒否します。
InvalidStateError
DOMException
-
リクエストされたセッションモードが
immersive-vr
であるにもかかわらず、すでに没入型 VR セッションがアクティブであるか、設定する途中である場合に返されます。没入型 VR セッションは一度に一つしか存在できません。 NotSupportedError
DOMException
-
利用できる WebXR 互換の端末がないか、端末が指定した
sessionMode
に対応していない場合に返されます。必須オプションに未対応の場合にも発生します。 SecurityError
DOMException
-
指定した XR モードに入る権限が拒否された場合に返されます。これはいくつかの理由で起こる可能性があり、権限とセキュリティで詳しく述べられています。
セッション機能
以下のセッション機能と参照空間を optionalFeatures
または requiredFeatures
としてリクエストすることができます。
anchors
-
XRAnchor
オブジェクトの仕様を有効にします。 bounded-floor
-
local
型と似ていますが、返すオブジェクトのboundsGeometry
で指定された境界の外にユーザーが移動することはありません。 depth-sensing
-
XRDepthInformation
オブジェクトを使用して深度情報を取得する機能を有効にします。 dom-overlay
-
ユーザーに表示される DOM オーバーレイ要素を指定します。
hand-tracking
-
ハンドベースの入力コントローラー(
XRHand
およびXRInputSource.hand
を参照)からの多関節ハンドポーズ情報を有効にします。 hit-test
-
実際の形状に対するヒットテストを実行するためのヒットテスト機能を有効にします。
layers
-
様々なレイヤー型(
XRProjectionLayer
以外)を作成する機能を有効にします。 light-estimation
-
XRLightEstimate
オブジェクトを使用して環境照明条件を推定する機能を有効にします。 local
-
セッションが作成された時点でのビューアーの位置の近くに原点があるトラッキング空間を有効にします。正確な位置は基盤と実装に依存します。ユーザーは開始位置から大きく移動することはまったく期待されておらず、トラッキングはこの用途に最適化されています。
local-floor
-
local
型と似ていますが、開始位置は視聴者が安全に立てる場所に指定され、y軸の値は床の高さを0とします。床面がわからない場合、ユーザーエージェントは床面を推定します。推定された床面が 0 でない場合、ブラウザーはフィンガープリンティングを避けるために、(おそらく最も近いセンチメートル単位に)丸めることが期待されます。 secondary-views
-
XRView
オブジェクトをセカンダリビューにすることができます。これは、動画キャプチャに使用するファーストパーソンオブザーバービューや、解像度と視野角が異なる、片目につき 2 つのビューがある「クワッドビュー」に使用することができます。 unbounded
-
ユーザーが完全に自由に動けるようなトラッキング空間を有効にし、場合によっては原点から非常に長い距離を移動できるようにします。ビューアーはまったくトラッキングされません。トラッキングはユーザーの現在位置を中心に安定するようにオプティマイザー指定されるため、ネイティブの原点は必要に応じてドリフトします。
viewer
-
ネイティブ原点が視聴者の位置と方向を追跡するトラッキング空間を有効にします。
セキュリティ
いくつかのセッション機能と様々な参照空間には、ユーザーの同意を要求したり、 Permissions-Policy
を要求するなど、最小限のセキュリティとプライバシーの要件があります。 xr-spatial-tracking
ディレクティブを設定する必要があります。詳しくは権限とセキュリティも参照してください。
セッション機能 | ユーザー同意の要件 | 権限ポリシーの要件 |
---|---|---|
bounded-floor |
常に必要 | xr-spatial-tracking |
depth-sensing |
— | xr-spatial-tracking |
hand-tracking |
常に必要 | — |
hit-test |
— | xr-spatial-tracking |
local |
インラインセッションでは常に必要 | xr-spatial-tracking |
local-floor |
常に必要 | xr-spatial-tracking |
unbounded |
常に必要 | xr-spatial-tracking |
viewer |
常に必要 | — |
ユーザーによる一時的な有効化も参照してください。
例
没入型 VR セッションの作成
次の例では requestSession()
を呼び出して、 "immersive-vr"
セッションをリクエストしています。 Promise
が解決されると、セッションを設定し、アニメーションループを開始します。
navigator.xr
.requestSession("immersive-vr")
.then((xrSession) => {
xrSession.addEventListener("end", onXRSessionEnded);
// Do necessary session setup here.
// Begin the session's animation loop.
xrSession.requestAnimationFrame(onXRAnimationFrame);
})
.catch((error) => {
// "immersive-vr" sessions are not supported
console.error(
"'immersive-vr' isn't supported, or an error occurred activating VR!",
);
});
WebXR の対応の確認と VR モード開始ボタンの使用
次の例では、isSessionSupported()
と requestSession()
の両方を使用する方法を示します。最初に、 navigator.xr
の存在を確認することで WebXR が利用できるかどうかを調べます。次に、 XR に入るための制御ができるように、希望のセッションオプションを渡して isSessionSupported()
を呼び出します。XRに入るにはユーザー操作が要求されるので、制御を追加するのは必要な段階です。最後に、onButtonClicked()
メソッドは isSessionSupported()
に渡すのと同じセッションオプションを使用して requestSession()
を呼び出します。
if (navigator.xr) {
navigator.xr.isSessionSupported("immersive-vr").then((isSupported) => {
if (isSupported) {
immersiveButton.addEventListener("click", onButtonClicked);
immersiveButton.textContent = "Enter XR";
immersiveButton.disabled = false;
} else {
console.error("WebXR doesn't support immersive-vr mode!");
}
});
} else {
console.error("WebXR is not available!");
}
function onButtonClicked() {
if (!xrSession) {
navigator.xr.requestSession("immersive-vr").then((session) => {
xrSession = session;
// onSessionStarted() not shown for reasons of brevity and clarity.
onSessionStarted(xrSession);
});
} else {
// Button is a toggle button.
xrSession.end().then(() => (xrSession = null));
}
}
要求された機能を持つセッションのリクエスト
ユーザーが物理的環境を自由に移動できるような、縛られない使い勝手を要求します。
navigator.xr.requestSession("immersive-vr", {
requiredFeatures: ["unbounded"],
});
DOM オーバーレイによるセッションのリクエスト
navigator.xr.requestSession("immersive-ar", {
optionalFeatures: ["dom-overlay"],
domOverlay: {
root: document.getElementById("xr-overlay"),
},
});
深度測定セッションのリクエスト
ここでは、呼び出し側は CPU と GPU の両方のオプティマイザー、および "luminance-alpha" と "float32" の両方の形式を処理することができます。順序は CPU と "luminance-alpha" の環境設定を推奨することを示します。
navigator.xr.requestSession("immersive-ar", {
requiredFeatures: ["depth-sensing"],
depthSensing: {
usagePreference: ["cpu-optimized", "gpu-optimized"],
dataFormatPreference: ["luminance-alpha", "float32"],
},
});
仕様書
Specification |
---|
WebXR Device API # dom-xrsystem-requestsession |
ブラウザーの互換性
BCD tables only load in the browser