XRSystem: requestSession() 方法

語法

requestSession(mode)
requestSession(mode, options)

引數

模式

一個 String，定義 XR 會話模式。支援的模式有：

• 實驗性 immersive-ar：會話的輸出將獲得對沉浸式裝置的獨佔訪問許可權，但渲染的內容將與真實世界環境混合。會話的 environmentBlendMode 指示用於混合內容的方法。
• immersive-vr：表示會話將在 VR 模式下使用沉浸式 XR 裝置顯示；它不打算疊加或整合到周圍環境中。如果可能，environmentBlendMode 預計為 opaque，但如果硬體需要，則可能為 additive。
• inline：輸出將內聯顯示在標準 HTML 文件的元素上下文中，而不是佔據完整的視覺空間。內聯會話可以以單聲道或立體聲模式呈現，並且可能有也可能沒有視口跟蹤。內聯會話不需要特殊硬體，並且應該在任何提供 WebXR API 支援的 使用者代理 上可用。

options 可選

一個用於配置 XRSession 的物件。如果未包含任何內容，裝置將對所有選項使用預設功能配置。

• requiredFeatures 可選：一個值陣列，返回的 XRSession *必須* 支援。請參閱下面的 會話功能。
• optionalFeatures 可選：一個值陣列，標識返回的 XRSession 可能支援的功能。請參閱下面的 會話功能。
• domOverlay 可選：一個物件，具有必需的 root 屬性，該屬性指定將顯示給使用者的 DOM 覆蓋層元素的內容。請參閱 下面的示例。
• depthSensing 可選：一個物件，具有兩個必需的屬性 usagePreference 和 dataFormatPreference，用於配置如何執行深度感應。請參閱 下面的示例。

返回值

一個 Promise，如果裝置和使用者代理支援請求的模式和功能，則會解析為 XRSession 物件。

異常

此方法不丟擲真正的異常；而是拒絕返回的 Promise，並將一個 DOMException 傳遞進去，其 name 是以下之一：

InvalidStateError DOMException

當請求的會話模式為 immersive-vr 但已有一個沉浸式 VR 會話當前處於活動狀態或正在設定中時返回。一次只能有一個沉浸式 VR 會話。

NotSupportedError DOMException

當沒有可用的 WebXR 相容裝置，或裝置不支援指定的 sessionMode 時返回；如果任何 *必需* 的選項不受支援，也可能丟擲此錯誤。

SecurityError DOMException

當進入指定 XR 模式的許可權被拒絕時返回。這可能由多種原因引起，詳見 許可權和安全。

會話功能

可以請求以下會話功能和參考空間，作為 optionalFeatures 或 requiredFeatures。

anchors

啟用 XRAnchor 物件的使用。

有界地板

類似於 local 型別，不同之處在於使用者不應超出由返回物件中的 boundsGeometry 給定的預定邊界。

depth-sensing

啟用使用 XRDepthInformation 物件獲取深度資訊的能力。

dom-overlay

啟用允許指定將顯示給使用者的 DOM 覆蓋層元素。

hand-tracking

啟用從基於手的輸入控制器獲取鉸接手部姿勢資訊（請參閱 XRHand 和 XRInputSource.hand）。

hit-test

啟用進行命中測試以與真實世界幾何形狀進行匹配的功能。

layers

啟用建立各種圖層型別（XRProjectionLayer 除外）的能力。

light-estimation

啟用使用 XRLightEstimate 物件估算環境光照條件的能力。

local

啟用一個跟蹤空間，其原生原點位於建立會話時視口位置附近。確切位置取決於底層平臺和實現。使用者不應超出其起始位置太多，並且跟蹤針對此用例進行了最佳化。

區域性地板

類似於 local 型別，不同之處在於起始位置放置在使用者可以安全站立的位置，其中 Y 軸的值在地面層為 0。如果不知道地面層，使用者代理 將估算地面層。如果估算的地面層非零，瀏覽器應將其四捨五入以避免 指紋識別（可能精確到最近的釐米）。

secondary-views

啟用 XRView 物件作為次要檢視。這可用於用於影片捕獲的第一人稱觀察者檢視，或“四檢視”，其中每隻眼睛有兩個檢視，解析度和視場角不同。

無界

啟用一個跟蹤空間，該空間允許使用者完全自由移動，可能距離其原點非常遠。使用者本身不被跟蹤；跟蹤針對使用者當前位置附近的穩定性進行了最佳化，因此原生原點可以根據需要進行漂移以適應該需求。

檢視器

啟用一個跟蹤空間，其原生原點跟蹤使用者的當前位置和方向。

安全

多個會話功能和各種參考空間都有最低安全和隱私要求，例如請求使用者同意和/或要求設定 Permissions-Policy：xr-spatial-tracking 指令。有關更多詳細資訊，請參閱 許可權和安全。

另請參閱 瞬時使用者啟用。

示例

建立沉浸式 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 是否可用。接下來，它呼叫 isSessionSupported()，並將期望的會話選項傳遞給它，然後再啟用進入 XR 的控制元件。新增控制元件是必要的步驟，因為進入 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"],
  },
});

規範

瀏覽器相容性