[css-paint-api] Introduce css paint image definition concept.

Author: bfgeek

css-paint-api/Overview.bs

@@ -27,18 +27,20 @@ urlPrefix: https://html.spec.whatwg.org/multipage/scripting.html; type: dfn;
     text: scratch bitmap
     text: set bitmap dimensions
 urlPrefix: http://www.ecma-international.org/ecma-262/6.0/#sec-; type: dfn;
+    text: constructor
     text: Construct
     text: IsArray
     text: IsCallable
     text: IsConstructor
     text: HasProperty
     url: get-o-p; text: Get
+    url: terms-and-definitions-function; text: function
 </pre>
 
 Introduction {#intro}
 =====================
 
-The paint stage of CSS is responsible for painting the background, content and highlight of an
+The paint stage of CSS is responsible for painting the background, content and highlight of a
 box based on that box's geometry (as generated by the layout stage) and computed style.
 
 This specification describes an API which allows developers to paint a part of an box in
@@ -113,11 +115,25 @@ interface PaintWorkletGlobalScope : WorkletGlobalScope {
     </pre>
 </div>
 
+Concepts {#concepts}
+====================
+
+A <dfn>paint image definition</dfn> describes an author defined <<image>> which can be referenced by
+the <<paint()>> function. It consists of:
+
+ - A <dfn>paint image name</dfn>
+
+ - A <dfn>class constructor</dfn> which is the class <a>constructor</a>
+
+ - A <dfn>paint function</dfn> which is the paint <a>function</a> callback
+
+ - A <dfn>class constructor valid flag</dfn>
+
 Registering Custom Paint {#registering-custom-paint}
 ====================================================
 
-The {{PaintWorkletGlobalScope}} has a <dfn>paint name to constructor map</dfn>. Initially this map
-is empty; it is populated when {{registerPaint(name, paintCtor)}} is called.
+The {{PaintWorkletGlobalScope}} has a <dfn>paint name to paint image definition map</dfn>. Initially
+this map is empty; it is populated when {{registerPaint(name, paintCtor)}} is called.
 
 The {{PaintWorkletGlobalScope}} has a <dfn>paint name to instance map</dfn>. Initially this map is
 empty; it is populated when <a>draw a paint image</a> is invoked by the user agent.
@@ -131,25 +147,56 @@ called, the user agent <em>must</em> run the following steps:
     1. If the |name| is not a valid <<ident>>, <a>throw</a> a <a>TypeError</a> and abort all these
         steps.
 
-    2. If the |name| exists as a key in the <a>paint name to constructor map</a>, <a>throw</a> a
-        <a>NotSupportedError</a> and abort all these steps.
+    2. If the |name| exists as a key in the <a>paint name to paint image definition map</a>,
+        <a>throw</a> a <a>NotSupportedError</a> and abort all these steps.
+
+    3. Let |inputProperties| be the result of <a>Get</a>(O=|paintCtor|, P="inputProperties").
+
+    4. If |inputProperties| is not undefined, and the result of <a>IsArray</a>(argument=
+        |inputProperties|) is false, <a>throw</a> a <a>TypeError</a> and abort all these steps.
+
+        1. Let |len| be the result of <a>ToLength</a>(<a>Get</a>(O=|inputProperties|, P="length")).
+
+        2. Let |idx| be 0.
+
+        3. Repeat while |idx| < |len|
+
+            1. Let |item| be the result of <a>Get</a>(O=|inputProperties|, |idx|).
 
-    3. If the result of <a>IsConstructor</a>(argument=|paintCtor|) is false, <a>throw</a> a
+            2. If the result of <a>Type</a>(|item|) is not String, <a>throw</a> a <a>TypeError</a>
+                and abort all these steps.
+
+            3. TODO prefixed behaviour
+
+       If |inputProperties| is undefined, let |inputProperties| be a new empty array.
+
+    5. If the result of <a>IsConstructor</a>(argument=|paintCtor|) is false, <a>throw</a> a
         <a>TypeError</a> and abort all these steps.
 
-    4. Let |prototype| be the result of <a>Get</a>(O=|paintCtor|, P="prototype").
+    6. Let |prototype| be the result of <a>Get</a>(O=|paintCtor|, P="prototype").
 
-    5. If the result of <a>IsCallable</a>(argument=<a>Get</a>(O=|prototype|, P="paint")) is false,
+    7. If the result of <a>Type</a>(argument=|prototype|) is not Object, <a>throw</a> a
+        <a>TypeError</a> and abort all these steps.
+
+    8. If the result of <a>IsCallable</a>(argument=<a>Get</a>(O=|prototype|, P="paint")) is false,
         <a>throw</a> a <a>TypeError</a> and abort all these steps.
 
-    6. Let |inputProperties| be the result of <a>Get</a>(O=|paintCtor|, P="inputProperties").
+    9. Let |definition| be a new <a>paint image definition</a> with:
 
-    7. If |inputProperties| is not undefined, and the result of <a>IsArray</a>(argument=
-        |inputProperties|) is false, <a>throw</a> a <a>TypeError</a> and abort all these steps.
+        - <a>paint image name</a> being |name|
+ 
+        - <a>class constructor</a> being |constructor|
+
+        - <a>paint function</a> being |paint|
 
-    8. Add the key-value pair (|name| - |inputProperties|) to the <a>paint name to input properties
+        - <a>class constructor valid flag</a> being true
+    
+    10. Add the key-value pair (|name| - |inputProperties|) to the <a>paint name to input properties
         map</a> of the associated <a>document</a>.
 
+    11. Add the key-value pair (|name| - |definition|) to the <a>paint name to paint image
+        definition map</a> of the associated <a>document</a>.
+
 Note: The list of CSS properties provided by the input properties getter can either be custom or
     native CSS properties.
 
@@ -298,25 +345,34 @@ following steps:
             select or create. It may use a single {{PaintWorkletGlobalScope}} or multiple and
             randomly assign between them.
 
-    5. If no paint constructor exists on |workletGlobalScope|'s <a>paint name to constructor map</a>
-        with key |name|, the resulting image output will be an <a>invalid image</a> and the user
-        agent must abort all these steps.
+    5. Let |definition| be the result of looking up |name| on the |workletGlobalScope|'s <a>paint
+        name to paint image definition map</a>.
+
+        If |definition| does not exist, let the image output be an <a>invalid image</a> and abort
+        all these steps.
 
     6. Let |paintInstance| be the result of looking up |name| on |workletGlobalScope|'s <a>paint
         name to instance map</a>. If |paintInstance| is null run the following substeps:
-        1. Let |paintCtor| be the result of looking up |name| on <a>paint name to constructor
-            map</a>.
 
-        2. Let |paintInstance| be the result of <a>Construct</a>(|paintCtor|).
+        1. If the <a>class constructor valid flag</a> on |definition| is false, let the image output
+            be an <a>invalid image</a> and abort all these steps.
+
+        2. Let |paintCtor| be the <a>class constructor</a> on |definition|.
 
-        3. Add the key-value pair (|name| - |paintInstance|) to the <a>paint name to instance
+        3. Let |paintInstance| be the result of <a>Construct</a>(|paintCtor|).
+
+            If <a>Construct</a> throws an exception, set the |definition|'s <a>constructor valid
+            flag</a> to false, let the image output be an <a>invalid image</a> and abort all these
+            steps.
+
+        4. Add the key-value pair (|name| - |paintInstance|) to the <a>paint name to instance
             map</a> of the |workletGlobalScope|.
 
     7. Let |inputProperties| be the result of looking up |name| on the associated <a>document</a>'s
         <a>paint name to input properties map</a>.
 
-    8. Let |styleMap| be a new {{StylePropertyMap}} populated with <em>only</em> the <a>computed
-        value</a>'s for properties listed in |inputProperties|.
+    8. Let |styleMap| be a new {{StylePropertyMapReadOnly}} populated with <em>only</em> the
+        <a>computed value</a>'s for properties listed in |inputProperties|.
 
     9. Let |renderingContext| be the result of <a>create a PaintRenderingContext2D object</a> given:
         - "width" - The width given by |concreteObjectSize|.
@@ -340,7 +396,7 @@ following steps:
 
     12. The image output is to be produced from the |renderingContext| given to the method.
 
-        If an exception is <a>thrown</a> the resulting image output will be an <a>invalid image</a>.
+        If an exception is <a>thrown</a> the let the image output be an <a>invalid image</a>.
 
     13. Set the <a>paint valid flag</a> for the |paintFunction| to <a>paint-valid</a>.
 
@@ -423,17 +479,22 @@ document.registerProperty({
 registerPaint('circle', class {
     static get inputProperties() { return ['--image']; }
     paint(ctx, geom, properties) {
-        // This relies on a TypedOM image object which doesn't exist yet.
         const img = properties.get('--image');
-        if (img.loaded) {
-            // The image is loaded! Draw the image.
-            ctx.drawImage(img.data, 0, 0, geom.width, geom.height);
-        } else if (img.invalid) {
-            // The image is invalid (e.g. it didn't load), draw a sad face.
-            drawSadFace(ctx);
-        } else {
-            // The image is loading, draw some mountains.
-            drawMountains(ctx);
+
+        switch (img.state) {
+            case 'ready':
+                // The image is loaded! Draw the image.
+                ctx.drawImage(img, 0, 0, geom.width, geom.height);
+                break;
+            case 'pending':
+                // The image is loading, draw some mountains.
+                drawMountains(ctx);
+                break;
+            case 'invalid':
+            default:
+                // The image is invalid (e.g. it didn't load), draw a sad face.
+                drawSadFace(ctx);
+                break;
         }
     }
 });
@@ -442,7 +503,7 @@ registerPaint('circle', class {
 Example 3: Conic-gradient {#example-3}
 --------------------------------------
 
-Issue: Add conic-gradient as a use case.
+Issue: Add conic-gradient as a use case once we have function arguments.
 
 Example 4: Different color based on geometry {#example-4}
 ---------------------------------------------------------