XRSession: updateRenderState() 方法

语法

updateRenderState()
updateRenderState(state)

参数

state 可选

一个可选对象，用于配置 XRRenderState。如果未提供，将使用默认配置。

• baseLayer 可选：一个 XRWebGLLayer 对象，WebXR 合成器将从中获取图像。默认情况下此值为 null。要指定其他（或多个）图层，请参阅 layers 选项。
• depthFar 可选：一个浮点值，指定从查看者到远裁剪面的距离（以米为单位），远裁剪面是与显示表面平行的平面，超出此平面将不再进行渲染。所有渲染将在 depthNear 和 depthFar 指定的距离之间进行。默认值为 1000 米（1 公里）。
• depthNear 可选：一个浮点值，表示从查看者到与显示表面平行的平面的距离（以米为单位），该平面被视为近裁剪面。此平面靠查看者一侧的场景将不会被渲染。默认值为 0.1 米（10 厘米）。
• inlineVerticalFieldOfView 可选：一个浮点值，表示为 inline XRSession 计算投影矩阵时使用的默认视场（以弧度为单位）。投影矩阵的计算还会考虑输出画布的 纵横比。此属性不得为沉浸式会话指定，因此对于沉浸式会话，默认值为 null。否则，默认值为 π * 0.5（π 值的一半）。
• layers 可选：一个有序的 XRLayer 对象数组，指定应呈现给 XR 设备的图层。设置 layers 会覆盖 baseLayer（如果存在），此时 baseLayer 的值为 null。图层的顺序是从“后到前”。有关图层的 alpha 混合，请参阅 XRCompositionLayer.blendTextureSourceAlpha 属性。

返回值

无（undefined）。

异常

InvalidStateError DOMException

在以下任何情况下抛出：

• XRSession 已结束，因此您无法更改其渲染状态。
• baseLayer 是由一个不同于调用 updateRenderState() 的 XRSession 创建的。
• 设置了 inlineVerticalFieldOfView 选项，但会话是沉浸式的，因此不允许使用此属性。

NotSupportedError DOMException

在以下任何情况下抛出：

• layers 选项在一个未创建 layers 功能的会话中使用。
• 同时指定了 baseLayer 和 layers 选项。

TypeError

如果 layers 选项包含重复的实例，则会抛出此异常。

示例

添加 baseLayer

此示例创建一个与沉浸式 XR 设备兼容的 WebGL 上下文，然后使用它创建一个 XRWebGLLayer。然后调用 updateRenderState() 方法来关联新的 XRWebGLLayer。

function onXRSessionStarted(xrSession) {
  let glCanvas = document.createElement("canvas");
  let gl = glCanvas.getContext("webgl", { xrCompatible: true });

  loadWebGLResources();

  xrSession.updateRenderState({
    baseLayer: new XRWebGLLayer(xrSession, gl),
  });
}

设置 layers 数组

要使用 WebXR 图层，XR 会话需要使用 layers 功能描述符创建（请参阅 XRSystem.requestSession()）。然后，您可以创建各种 WebXR 图层，例如

• XREquirectLayer
• XRCubeLayer
• XRCylinderLayer
• XRQuadLayer

其他图层，例如 XRProjectionLayer 或 XRWebGLLayer 也可用。

图层将按照 layers 数组中给出的顺序呈现，图层按“后到前”顺序给出。

const xrSession = navigator.xr.requestSession("immersive-ar", {
  optionalFeatures: ["layers"],
});

function onXRSessionStarted(xrSession) {
  const glCanvas = document.createElement("canvas");
  const gl = glCanvas.getContext("webgl", { xrCompatible: true });
  const xrGlBinding = new XRWebGLBinding(xrSession, gl);
  const projectionLayer = new XRWebGLLayer(xrSession, gl);
  const quadLayer = xrGlBinding.createQuadLayer({
    pixelWidth: 1024,
    pixelHeight: 1024,
  });

  xrSession.updateRenderState({
    layers: [projectionLayer, quadLayer],
  });
}

规范

浏览器兼容性

另见

• WebXR Device API
• XRRenderState
• XRSession.renderState