区域捕获

本文档中提出的裁剪机制 （cropTo）依赖于 裁剪会话目标，而不是 直接的节点引用。这有双重目的。

• 它允许一个 document 按另一个 document 中指定的坐标进行裁剪。

• 将 Element 标记为潜在裁剪目标，使用户代理能够避免 对所有其他元素执行不必要的工作，例如计算边界框以及跨进程发送此类坐标。

CropTarget 是一个有意为空的不透明标识符。其用途是作为输入传递给 cropTo。

WebIDL[Exposed=(Window,Worker), Serializable]
interface CropTarget {
  [Exposed=Window, SecureContext] static Promise<CropTarget> fromElement(Element element);
};

fromElement()

用受支持类型的 Element 调用 fromElement， 会将该 Element 与一个 CropTarget 关联。此 CropTarget 可用作 cropTo 的输入。我们将 有效 CropTarget 定义为在仍然 活动的 document 中调用 CropTarget.fromElement() 所返回的对象。

当用给定的 element 调用 fromElement 时，用户 代理以 element 作为输入 创建 CropTarget。 用户代理 MUST 返回一个 Promise p。 用户代理 MUST 只在它已完成与新 CropTarget 相关状态的所有必要内部传播之后， 才 resolve p；在此时，用户代理 MUST 准备好接收新的 CropTarget 作为 cropTo 的有效参数。

当克隆此前已对其调用过 fromElement 的 Element 时， 克隆不会与任何 CropTarget 关联。如果稍后对该克隆调用 fromElement， 则会为其分配一个新的 CropTarget。

注

关于生成 CropTarget 是否应通过调用类似 CropTarget.fromElement() 的异步方法来完成，还是通过一个接受 Element 作为输入的 CropTarget 构造函数来完成， 目前尚无共识。这在 议题 #17 中有进一步讨论。

要以 element 作为输入创建 CropTarget，运行以下步骤：

1. 令 cropTarget 为一个新的 CropTarget 类型对象。

2. 令 weakRef 为对 element 的弱引用。

   创建 cropTarget.[[Element]]， 并初始化为 weakRef。

   注

   cropTarget 保持对其所表示元素的弱引用。换句话说， cropTarget 不会阻止其元素被垃圾回收。

CropTarget 对象是可序列化的。给定 value、serialized 和布尔值 forStorage，其序列化 步骤为：

1. 如果 forStorage 为 true，则抛出一个新的 DOMException 对象， 其 name 属性 的值为 "DataCloneError"。

2. 将 serialized.[[CropTargetElement]] 设置为 value.[[Element]]。

给定 serialized 和 value，其反序列化 步骤为：

1. 将 value.[[Element]] 设置为 serialized.[[CropTargetElement]]。

回想一下，按照 [SCREEN-CAPTURE]，当调用 getDisplayMedia() 时， 它返回一个 Promise<MediaStream>， 并且此 MediaStream 包含 恰好一个视频轨道，其类型为 MediaStreamTrack。

我们规定，如果用户选择捕获一个 browser display-surface，用户 代理 MUST 将视频轨道实例化为 MediaStreamTrack， 或 MediaStreamTrack 的某个子类，并且 cropTo MUST 暴露在此轨道上。为简单起见，本文档假定用户代理使用一个名为 BrowserCaptureMediaStreamTrack 的子类。

该轨道 MUST 初始为未裁剪。

WebIDL[Exposed = Window]
interface BrowserCaptureMediaStreamTrack : MediaStreamTrack {
  Promise<undefined> cropTo(CropTarget? cropTarget);
  BrowserCaptureMediaStreamTrack clone();
};

cropTo()

对此方法的调用会指示用户代理开始/停止将视频轨道裁剪到 cropTarget.[[Element]] 的 边界客户端矩形。由于该轨道被限制在 display-surface 的可见视口内， 所捕获区域将是可见视口与元素边界客户端矩形的交集。 每当调用 cropTo 时， 用户代理 MUST 执行以下算法：

1. 如果 cropTarget 既不是有效 CropTarget，也不是 null， 则用户代理 MUST 返回一个以 UnknownError 拒绝的 Promise。

2. 令 p 为一个新的 Promise。

3. 并行运行以下步骤：

   1. 如果 cropTarget 既不是 undefined， 也不是有效 CropTarget， 则以 NotAllowedError 拒绝 p，并中止这些步骤。

   2. 如果 cropTarget 是 undefined 或有效 CropTarget， 则用户代理 MUST 根据 cropTarget 更新 this 视频轨道的 裁剪状态：

      • 如果 cropTarget 被设置为 undefined， 则用户代理 MUST 停止 裁剪。This 视频轨道恢复为 未裁剪状态。
      • 如果 cropTarget 是有效 CropTarget，则用户代理 MUST 开始将 this 视频轨道裁剪到 此 CropTarget 所引用元素的 轮廓。这意味着，对于轨道上产生的每个新帧， 用户代理都会计算属于该元素的像素的边界框，并将该帧裁剪到 此边界框的坐标。

   3. 将此方法调用之前的轨道状态称为 PRE-STATE， 并将此方法调用之后的状态称为 POST-STATE。用户代理 MUST 在能够保证不会再向应用交付任何根据 PRE-STATE 裁剪（或未裁剪）的帧，并且随后交付给应用的任何其他帧都将 因此按照 POST-STATE 或更后的状态裁剪（或未裁剪）时， resolve p。

      注

      cropTo promise 的 resolve 时机以及视频帧实际裁剪的时机， 可通过 JavaScript 中的 MediaStreamTrack 转换观察到。预期第一个新裁剪的视频帧会在 cropTo promise 被 resolve 之后立即入队到 MediaStreamTrack ReadableStream 上。

4. 返回 p。

clone()

当 BrowserCaptureMediaStreamTrack 被克隆时，用户代理 MUST 产生一个 初始为未裁剪的 轨道，而不管原始轨道的裁剪状态如何。