CSS 绘画 API 第一级

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

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

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

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

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

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

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

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

注意：CSS属性列表可能包含简写形式。

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

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

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

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

11. 令inputArgumentSyntaxes为空的列表。

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

    1. 尝试从item获取语法定义。 如果返回失败，抛出 TypeError 并中止所有这些步骤。 否则，将parsedSyntax设置为返回的语法定义。

    2. 将parsedSyntax附加到 inputArgumentSyntaxes。

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

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

    注意：将 paintRenderingContext2DSettings.alpha设置为false允许用户代理 除了进行"可见性"优化外，还可以对文本进行抗锯齿处理，例如，当绘画图像不透明时，不会在绘画图像后面绘制图像。

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

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

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

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

19. 将paintValue转换为函数的回调函数类型。重新抛出转换中的任何异常。

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]的get结果。

       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) { /* paint code here. */ }
   });
   

   <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 全局范围选择中的规则。

    用户代理可以在此时根据需要 创建一个工作全局范围。

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

    注意：如果用户代理在 调用绘画回调 时在并行线程上运行，它应选择可用于该线程的绘画工作全局范围。

1. 让 paintDefinitionMap 成为 workletGlobalScope 的 绘画定义 映射。

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

   1. 队列任务运行以下步骤：

      1. 让 documentPaintDefinitionMap 成为相关文档的 文档绘画定义 映射。

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

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

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

   注意： 这处理了可能有一个绘画工作全局范围没有收到 registerPaint(name, paintCtor) 的情况（然而另一个全局范围收到了）。在另一个全局范围上调用的绘画回调可能成功，但当调用 绘制一个绘画图像 时，在后续帧上不会成功。

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

4. 让 paintClassInstanceMap 成为 workletGlobalScope 的 绘画类实例 映射。

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

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

   2. 让 paintCtor 成为 definition 的 类构造函数。

   3. 让 paintInstance 成为通过 构造(paintCtor) 的结果。如果 构造抛出异常，设置 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 实际上被“隔离”。

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 的 paint function。

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

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

    注意：用户代理可以在其调试工具中为开发者提供工具，显示绘制类的开销。用户代理在适当情况下也可以显示 "无响应的脚本" 对话框。

13. 图像输出应从传递给方法的 renderingContext 中生成。

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

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