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"],
  },
});

规范

浏览器兼容性