CSS 绘画 API 第 1 级

1. 如果 name 是空字符串，则抛出一个 TypeError 并中止 所有这些步骤。

2. 令 paintDefinitionMap 为 PaintWorkletGlobalScope 的 绘制 定义映射。

3. 如果 paintDefinitionMap[name] 存在，则抛出一个 "InvalidModificationError" DOMException 并中止所有这些步骤。

4. 令 inputProperties 为空的 sequence<DOMString>。

5. 令 inputPropertiesIterable 为 Get(paintCtor, "inputProperties") 的结果。

6. 如果 inputPropertiesIterable 不是 undefined，则将 inputProperties 设置为 将 inputPropertiesIterable 转换 为 sequence<DOMString> 的结果。如果 抛出异常，则重新抛出该异常并中止所有这些步骤。

7. 过滤 inputProperties，使其仅包含受支持的 CSS 属性和自定义属性。

注： 输入属性 getter 提供的 CSS 属性列表既可以是自定义 CSS 属性，也可以是 原生 CSS 属性。

注： CSS 属性列表可以包含简写属性。

注： 为使绘制图像类具有向前兼容性， CSS 属性列表 还可以包含当前对用户代理无效的属性。例如 margin-bikeshed-property。

8. 令 inputArguments 为空的 sequence<DOMString>。

9. 令 inputArgumentsIterable 为 Get(paintCtor, "inputArguments") 的结果。

10. 如果 inputArgumentsIterable 不是 undefined，则将 inputArguments 设置为 将 inputArgumentsIterable 转换 为 sequence<DOMString> 的结果。如果 抛出异常，则重新抛出该异常并中止所有这些步骤。

11. 令 inputArgumentSyntaxes 为一个空列表。

12. 对 inputArguments 中的每个 item 执行 以下子步骤：

    1. 尝试从 item 中消费一个语法定义。 如果返回失败，则抛出一个 TypeError 并中止所有这些步骤。 否则，令 parsedSyntax 为返回的语法定义。

    2. 将 parsedSyntax 追加到 inputArgumentSyntaxes。

13. 令 contextOptionsValue 为 Get(paintCtor, "contextOptions") 的结果。

14. 令 paintRenderingContext2DSettings 为将 contextOptionsValue 转换 为 PaintRenderingContext2DSettings 的结果。 如果抛出异常，则重新抛出该异常并中止所有这些步骤。

    注： 将 paintRenderingContext2DSettings.alpha 设置为 false 允许用户代理 除执行“可见性”优化之外还对文本进行抗锯齿处理，例如，由于绘制图像是不透明的而不 绘制位于绘制图像后面的图像。

15. 如果 IsConstructor(paintCtor) 的结果为 false，则抛出一个 TypeError 并中止 所有这些步骤。

16. 令 prototype 为 Get(paintCtor, "prototype") 的结果。

17. 如果 Type(prototype) 的结果不是 Object，则抛出一个 TypeError 并 中止所有这些步骤。

18. 令 paintValue 为 Get(prototype, "paint") 的结果。

19. 令 paint 为将 paintValue 转换为 Function 回调函数类型的结果。重新抛出 转换过程中产生的任何异常。

20. 令 definition 为一个新的绘制定义，其：

    • 类构造函数为 paintCtor。

    • 绘制函数为 paint。

    • 构造函数有效标志 为 true。

    • 输入属性为 inputProperties。

    • PaintRenderingContext2DSettings 对象为 paintRenderingContext2DSettings。

21. 将 paintDefinitionMap[name] 设置为 definition。

22. 将一个任务加入队列以运行以下步骤：

    1. 令 documentPaintDefinitionMap 为关联文档的文档 绘制 定义映射。

    2. 令 documentDefinition 为一个新的文档 绘制定义，其：

       • 输入属性 为 inputProperties。

       • 输入 参数语法为 inputArgumentSyntaxes。

       • PaintRenderingContext2DSettings 对象为 paintRenderingContext2DSettings。

    3. 如果 documentPaintDefinitionMap[name] 存在，则运行以下步骤：

       1. 令 existingDocumentDefinition 为获取 documentPaintDefinitionMap[name] 的结果。

       2. 如果 existingDocumentDefinition 为 "invalid"，则中止所有 这些步骤。

       3. 如果 existingDocumentDefinition 和 documentDefinition 不等价（即输入 属性、输入 参数语法和PaintRenderingContext2DSettings 对象不同），则：

          将 documentPaintDefinitionMap[name] 设置为 "invalid"。

          向调试控制台记录一条错误，说明同一个类使用了不同的 inputProperties、inputArguments 或 paintRenderingContext2DSettings 进行注册。

    4. 否则，将 documentPaintDefinitionMap[name] 设置 为 documentDefinition。

注： 输入属性列表应仅查找一次， 该类没有 动态更改其输入属性的机会。

注： 在本规范的未来版本中，作者可能能够 接收不同类型 的 RenderingContext。特别是，作者可能希望使用 WebGL 渲染上下文来渲染 3D 效果。设置 WebGL 渲染上下文以将 PaintSize 和 StylePropertyMap 作为输入存在一些复杂性。

1. 创建一个新的 PaintRenderingContext2D。

2. 设置位图尺寸为上下文的 输出位图，将 width 和 height 四舍五入后的值设置为该位图的尺寸。

3. 将 PaintRenderingContext2D 的 alpha 标志设置为 paintRenderingContext2DSettings 的 alpha。

4. 返回新的 PaintRenderingContext2D。

注意： 渲染上下文的初始状态在 设置位图尺寸算法中设置， 因为它调用了 重置渲染上下文为默认状态，并清除了 输出位图。

1. 令 paintFunction 为 box 上用户代理希望 绘制的 <paint()> 函数。

2. 令 name 为 paintFunction 的第一个参数。

3. 令 documentPaintDefinitionMap 为关联文档的文档绘制 定义映射。

4. 如果 documentPaintDefinitionMap[name] 不存在，则令 图像输出 为无效图像，并中止所有这些步骤。

5. 令 documentDefinition 为获取 documentPaintDefinitionMap[name] 的结果。

6. 如果 documentDefinition 为 "invalid"，则令图像输出为无效 图像，并中止所有这些步骤。

7. 令 inputArgumentSyntaxes 为 documentDefinition 的输入参数语法。

8. 令 inputArguments 为 paintFunction 中“绘制名称”参数 之后的所有参数所组成的列表。

9. 如果 inputArguments 与 inputArgumentSyntaxes 给出的已注册语法不匹配，则令 图像输出为无效 图像，并中止所有这些步骤。

   此步骤在以下情况下可能失败：

   // paint.js
   registerPaint('failing-argument-syntax', class {
       static get inputArguments() { return ['<length>']; }
       paint(ctx, size, styleMap, args) { /* 此处为绘制代码。 */ }
   });
   

   <style>
       .example-1 {
           background-image: paint(failing-argument-syntax, red);
       }
       .example-2 {
           background-image: paint(failing-argument-syntax, 1px, 2px);
       }
   </style>
   <div class=example-1></div>
   <div class=example-2></div>
   <script>
       CSS.paintWorklet.addModule('paint.js');
   </script>
   

   example-1 会产生无效图像，因为 "red" 与 已注册的语法不匹配。

   example-2 会产生无效图像，因为函数 参数过多。

10. 令 workletGlobalScope 为绘制 Worklet 的 全局作用域中的一个 PaintWorkletGlobalScope，并遵循 § 7.1 全局作用域选择中定义的规则。

    此时，给定绘制 Worklet， 用户代理可以另外创建 worklet 全局作用域。

11. 给定 name、 inputArguments、snappedConcreteObjectSize、workletGlobalScope， 运行调用绘制回调，并可选择并行执行。

    注： 如果用户代理在一个线程上调用绘制 回调并并行执行， 则它应选择一个可在该线程上使用的绘制 worklet 全局作用域。

1. 令 paintDefinitionMap 为 workletGlobalScope 的绘制定义映射。

2. 如果 paintDefinitionMap[name] 不存在，则运行 以下步骤：

   1. 将一个任务加入队列以运行以下步骤：

      1. 令 documentPaintDefinitionMap 为关联文档的文档 绘制定义映射。

      2. 将 documentPaintDefinitionMap[name] 设置为 "invalid"。

      3. 用户代理应向调试控制台记录一条错误，指出 某个 类并未在所有 PaintWorkletGlobalScope 中注册。

   2. 令图像输出为无效图像，并中止所有这些步骤。

   注： 这处理了可能存在某个绘制 worklet 全局作用域未 接收到针对 name 的 registerPaint(name, paintCtor) 的情况（但另一个全局作用域 接收到了）。在另一个全局作用域上调用的绘制回调可能成功，但 在后续帧调用绘制绘制图像时将不会成功。

3. 令 definition 为获取 paintDefinitionMap[name] 的结果。

4. 令 paintClassInstanceMap 为 workletGlobalScope 的绘制类实例 映射。

5. 令 paintInstance 为获取 paintClassInstanceMap[|name]| 的结果。如果 paintInstance 为 null，则运行以下 步骤：

   1. 如果 definition 上的构造函数有效标志 为 false，则令图像输出为无效图像，并中止所有这些步骤。

   2. 令 paintCtor 为 definition 上的类构造函数。

   3. 令 paintInstance 为 Construct(paintCtor) 的结果。

      如果 construct 抛出异常， 则将 definition 的构造函数有效标志设置为 false， 令图像输出为无效图像，并中止所有这些 步骤。

   4. 将 paintClassInstanceMap[name] 设置为 paintInstance。

6. 令 inputProperties 为 definition 的输入属性。

7. 令 styleMap 为一个新的 StylePropertyMapReadOnly， 其中仅填充 inputProperties 中所列属性的计算值。

8. 令 renderingContext 为在给定以下内容的情况下创建 PaintRenderingContext2D 对象的结果：

   • "width" - 由 snappedConcreteObjectSize 给出的宽度。

   • "height" - 由 snappedConcreteObjectSize 给出的高度。

   • "paintRenderingContext2DSettings" - 由 definition 给出的PaintRenderingContext2DSettings 对象。

   注： renderingContext 不会在各次绘制调用 之间复用。这隐含地 意味着各次调用之间 renderingContext 上不存在存储的数据或状态。 例如，你不能在上下文上设置裁剪区域，然后期望下次调用绘制方法时 应用相同的裁剪区域。

   注： 这还隐含地意味着 在绘制方法完成后，renderingContext 实际上已被“失效”。 作者代码可以保留对 renderingContext 的引用 并 调用其方法，但这不会对当前图像或后续 图像产生任何影响。

9. 令 paintSize 为一个新的 PaintSize， 并使用 snappedConcreteObjectSize 定义的宽度和高度对其进行初始化。

10. 在此阶段，如果 paintSize、styleMap、inputArguments 与上一次调用中的对应值等价，则用户代理可以复用上一次调用的图像。 如果是这样，则令图像 输出为该缓存图像，并中止所有这些步骤。

    在下面的示例中，div-1 和 div-2 都具有绘制 函数，并且其 JavaScript 参数等价。用户代理可以缓存一次调用的结果 并将其用于这两个元素。

    // paint.js
    registerPaint('simple', class {
        paint(ctx, size) {
            ctx.fillStyle = 'green';
            ctx.fillRect(0, 0, size.width, size.height);
        }
    });
    

    <style>
        .div-1 {
            width: 50px;
            height: 50px;
            background-image: paint(simple);
        }
        .div-2 {
            width: 100px;
            height: 100px;
    
            background-size: 50% 50%;
            background-image: paint(simple);
        }
    </style>
    <div class=div-1></div>
    <div class=div-2></div>
    <script>
        CSS.paintWorklet.addModule('paint.js');
    </script>
    

11. 令 paintFunctionCallback 为 definition 的绘制 函数。

12. 使用参数 «renderingContext, paintSize, styleMap, inputArguments» 调用 paintFunctionCallback，并将 paintInstance 作为回调 this 值。

    如果 paintFunctionCallback 未能在可接受的时间内完成（由 用户代理确定，即它是“长时间运行的脚本”），则用户代理可以终止 脚本，令图像输出为无效图像，并中止所有这些步骤。

    注： 用户代理可以在其 调试工具中提供工具，以向作者显示 其绘制类的开销有多大。在适当情况下，用户代理还可以显示“无响应脚本” 对话框。

13. 图像输出将由传递给该方法的 renderingContext 生成。

    如果抛出异常，则令图像输出为无效图像。

注： 生成图像的内容并非设计为 可访问的。作者可以通过标准无障碍 API 传达 任何有用的信息。