WebXR 平面检测模块

const session = await navigator.xr.requestSession("immersive-ar", {
  requiredFeatures: ["plane-detection"]
});

enum XRPlaneOrientation {
    "horizontal",
    "vertical"
};

[Exposed=Window]
interface XRPlane {
    [SameObject] readonly attribute XRSpace planeSpace;

    readonly attribute FrozenArray<DOMPointReadOnly> polygon;
    readonly attribute XRPlaneOrientation? orientation;
    readonly attribute DOMHighResTimeStamp lastChangedTime;
    readonly attribute DOMString? semanticLabel;
};

[Exposed=Window]
interface XRPlaneSet {
  readonly setlike<XRPlane>;
};

partial interface XRFrame {
  readonly attribute XRPlaneSet detectedPlanes;
};

partial interface XRSession {
  Promise<undefined> initiateRoomCapture();
};

调用此方法时，用户代理必须运行以下步骤：

1. 令 session 为此对象

2. 令 promise 为在 session 的相关领域中创建的新 Promise。

3. 如果 session 的 ended 值为 `true`，则使用一个“InvalidStateError” DOMException 拒绝 promise，并返回 promise。

4. 如果房间捕获已完成为 `true`，则使用一个“InvalidStateError” DOMException 拒绝 promise， 并返回 promise。

5. 如果 plane-detection 功能描述符未被包含在 session 的XR 设备针对 session 的模式的已启用功能列表中，则使用一个“NotSupportedError” DOMException 拒绝 promise，并返回 promise。

6. 如果 session 的 XR 设备不支持手动捕获，或者 XRSystem 确定不需要进行房间捕获：

   1. 将 session 的房间捕获已完成设置为 `true`。

   2. 兑现 promise。

   3. 返回 promise。

7. 排入一个任务以执行以下步骤：

   1. 调用 session 的 XR 设备的房间捕获方法，等待其结果，并将该结果 赋给 result。

   2. 运行以下步骤：

      如果 result 为 `true`：

      兑现 promise

      否则：

      使用一个“OperationError” DOMException 拒绝 promise

   3. 将 session 的房间捕获已完成设置为 `true`。

8. 返回 promise。

为了为 frame 更新 平面，用户代理必须运行以下步骤：

1. 令 session 为 frame 的会话。

2. 令 device 为 session 的XR 设备。

3. 如果 plane-detection 功能描述符未被包含在 device 针对 session 的模式的已启用功能列表中，则中止这些步骤。

4. 令 trackedPlanes 为调用 device 的原生平面检测能力，以获取 frame 的时间所对应时刻的已跟踪 平面后得到的结果。

5. 对 trackedPlanes 中的每个 native plane，运行：

   1. 如有需要，将 native plane 视为未出现在 trackedPlanes 中，并继续处理下一个条目。有关可用于判断是否应以这种方式忽略条目的标准， 请参阅§ 6 隐私与安全考量。

   2. 如果 session 的已跟踪平面集合包含一个 与 native plane 对应的对象 plane，则以 plane、native plane 和 frame 调用更新平面对象算法，并继续处理 下一个条目。

   3. 令 plane 为使用 native plane 和 frame 调用创建平面对象 算法得到的结果。

   4. 将 plane 添加到 session 的已跟踪平面集合中。

6. 从 session 的已跟踪 平面集合中移除在本算法调用期间既未创建也未更新的每个对象。

7. 将 frame 的 detectedPlanes 设置为已跟踪平面集合。

为了根据原生平面对象 native plane 和 XRFrame frame 创建平面 对象，用户代理必须运行以下步骤：

1. 令 result 为 XRPlane 的新实例。

2. 将 result 的原生实体设置为 native plane。

3. 将 result 的 planeSpace 设置为一个新的 XRSpace 对象；创建该对象时，将会话设置为 frame 的 session， 并将原生原点设置为跟踪 native plane 的 原生原点。

4. 以 result、native plane 和 frame 调用更新平面对象算法。

5. 返回 result。

以这种方式创建的平面对象 result 被称为与传入的原生平面 对象 native plane 对应。

为了使用原生平面对象 native plane 和 XRFrame frame 更新平面 对象 plane，用户代理必须运行以下步骤：

1. 将 plane 的帧设置为 frame。

2. 如果底层系统将 native plane 分类为垂直方向，则将 plane 的 orientation 设置为 "vertical"。 否则，如果底层系统将 native plane 分类为水平方向，则将 plane 的 orientation 设置为 "horizontal"。 否则，将 plane 的 orientation 设置为 null。

3. 将 plane 的 polygon 设置为表示 native plane 多边形的新顶点数组，并执行所有必要的转换， 以处理原生平面多边形表示方式的差异。

4. 将 plane 的 semanticLabel 设置为包含语义标签的新字符串。

5. 如有需要，按照§ 6 隐私与安全考量中的描述，降低 plane 的 polygon 的细节级别。

6. 将 plane 的 lastChangedTime 设置为时间。

// `planes` 将跟踪应用已知的所有检测到的平面，
// 以及它们更新时的时间戳。最初，这是一个空映射。
const planes = Map();

function onXRFrame(timestamp, frame) {
  const detectedPlanes = frame.detectedPlanes;

  // 首先，检查我们之前知道的平面中是否有任何平面已不再被跟踪：
  for (const [plane, timestamp] of planes) {
    if(!detectedPlanes.has(plane)) {
      // 处理已移除的平面——`plane` 存在于上一帧中，
      // 但现在已不再被跟踪。

      // 我们知道该平面已不存在，因此将其从映射中移除：
      planes.delete(plane);
    }
  }

  // 接下来，处理所有仍在跟踪的平面。
  // 其中既包括我们之前见过的已跟踪平面（可能已更新），
  // 也包括新平面。
  detectedPlanes.forEach(plane => {
    if (planes.has(plane)) {
      // 处理之前见过的平面：

      if(plane.lastChangedTime > planes.get(plane)) {
        // 处理之前见过且已更新的平面。
        // 这意味着该平面的某个属性与之前不同——
        // 最有可能是多边形发生了变化。

        ... // 渲染平面或为渲染准备平面等。

        // 更新我们更新该平面的时间：
        planes.set(plane, plane.lastChangedTime);
      } else {
        // 处理之前见过但未在当前帧中更新的平面。
        // 请注意，平面相对于其他某个空间的姿态可能已发生变化。
      }
    } else {
      // 处理新平面。

      // 设置我们更新该平面的时间：
      planes.set(plane, plane.lastChangedTime);
    }

    // 无论之前是否见过该平面，
    // 也无论其是否已更新，其姿态都可能已发生变化：
    const planePose = frame.getPose(plane.planeSpace, xrReferenceSpace);
  });

  frame.session.requestAnimationFrame(onXRFrame);
}