XRSystem：requestSession() 方法

mode

一个String，定义 XR 会话模式。支持的模式有

• 实验性 immersive-ar：会话的输出将获得对沉浸式设备的独占访问权限，但呈现的内容将与真实世界环境混合。会话的environmentBlendMode指示用于混合内容的方法。
• immersive-vr：表示呈现的会话将使用沉浸式 XR 设备以 VR 模式显示；它不打算覆盖或集成到周围环境中。如果硬件允许，environmentBlendMode 预计为 opaque，但如果硬件需要，它也可能是 additive。
• inline：输出在标准 HTML 文档中元素的上下文中内联呈现，而不是占据整个视觉空间。内联会话可以以单声道或立体声模式呈现，并且可能或可能没有查看器跟踪可用。内联会话不需要特殊硬件，应该在提供 WebXR API 支持的任何用户代理上可用。

options 可选

一个用于配置XRSession的对象。如果没有包含任何配置，则设备将为所有选项使用默认功能配置。

• requiredFeatures 可选：返回的XRSession必须支持的值数组。请参见下面的会话功能。
• optionalFeatures 可选：标识返回的XRSession可能选择支持的功能的值数组。请参见下面的会话功能。
• domOverlay 可选：一个对象，它具有一个必需的 root 属性，该属性指定将显示给用户的 DOM 覆盖元素作为 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对象的用法。

bounded-floor

类似于 local 类型，但用户预计不会超出预定的边界，该边界由返回对象中的boundsGeometry 给出。

depth-sensing

启用使用XRDepthInformation对象获取深度信息的能力。

dom-overlay

启用允许指定将显示给用户的 DOM 覆盖元素。

hand-tracking

启用来自基于手的输入控制器的手部姿势信息（请参见XRHand和XRInputSource.hand）。

hit-test

启用命中测试功能，以对真实世界几何体执行命中测试。

layers

启用创建各种图层类型的能力（除 XRProjectionLayer 之外）。

光线估计

启用使用 XRLightEstimate 对象估计环境光照条件的能力。

本地

启用一个跟踪空间，其原生原点位于会话创建时靠近查看器位置的位置。确切位置取决于底层平台和实现。用户预计不会在他们的起始位置之外移动太多，如果有的话，跟踪针对此用例进行了优化。

本地地板

与 local 类型类似，只是起始位置位于查看器可以安全站立的位置，其中 y 轴的值在地板级别为 0。如果不知道地板级别，则 用户代理 将估计地板级别。如果估计的地板级别非零，则浏览器预计会以一种避免 指纹识别 的方式将其四舍五入（可能四舍五入到最接近的厘米）。

辅助视图

启用 XRView 对象作为辅助视图。这可以用于用于视频捕获的第一人称观察者视图，或者“四视图”，其中每个眼睛有两个视图，具有不同的分辨率和视野。

无界

启用一个跟踪空间，该空间允许用户完全自由移动，可能从他们的原点移动极长距离。查看器根本没有被跟踪；跟踪针对用户当前位置周围的稳定性进行了优化，因此原生原点可能会根据需要漂移以满足该需求。

查看器

启用一个跟踪空间，其原生原点跟踪查看器的位置和方向。

一些会话功能和各种参考空间具有最低的安全和隐私要求，例如要求用户同意和/或要求 Permissions-Policy: xr-spatial-tracking 指令被设置。有关更多详细信息，另请参阅 权限和安全。

另请参阅 短暂用户激活。

以下示例调用 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!",
    );
  });

以下示例展示了如何使用 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"],
});

在这里，调用者能够处理 CPU 和 GPU 优化的使用，以及“亮度-alpha”和“float32”格式。顺序表示对 CPU 和“亮度-alpha”的偏好

navigator.xr.requestSession("immersive-ar", {
  requiredFeatures: ["depth-sensing"],
  depthSensing: {
    usagePreference: ["cpu-optimized", "gpu-optimized"],
    dataFormatPreference: ["luminance-alpha", "float32"],
  },
});