[css-paint-api] Update EXPLAINER.md to include inputArguments and paint efficiency.

Author: bfgeek

css-paint-api/EXPLAINER.md

@@ -21,6 +21,37 @@ This means that the memory and cpu usage of the page would go down, the renderin
 have to keep in memory the additional DOM nodes, in addition to performing style-recalc, layout,
 painting for all these additional divs.
 
+### Efficiency Gains ###
+
+Providing a "hook" into the rendering engine allows for efficiency gains which are difficult to
+achieve with current APIs.
+
+#### Invalidation ####
+
+As the CSS paint API Invalidation is based off style changes, this check can occur in the same pass
+as the rest of the box tree. For example:
+
+```css
+my-button {
+    --property-which-invalidates-paint: no-hover;
+}
+
+my-button:hover {
+    --property-which-invalidates-paint: hover;
+}
+```
+
+To achieve the same effect with current APIs you have to rebuild the engines invalidation logic
+which is potentially less efficient.
+
+#### Painting ####
+
+Once a box has been invalidated, a rendering engine isn't required to paint it that frame. For
+example some rendering engines just paint what is visible within the "visual viewport". This means
+that only a smaller amount of work is needed to be done.
+
+A naive implementation with existing APIs may try and paint everything within the document.
+
 ### Extensibility of CSS ###
 
 We believe that allowing developers to extend CSS is good for the ecosystem. As an example if a
@@ -87,11 +118,15 @@ The `paint` function is your callback into the browsers paint phase in the rende
  - `size`, the size of the area in which you should paint.
  - `style`, the computed style of the element which are you currently painting.
  
-The `style` is a Typed-OM style map. It will _only_ contain the CSS properties that you listed under the static `inputProperties` accessor.
+The `style` is a Typed-OM style map. It will _only_ contain the CSS properties that you listed under
+the static `inputProperties` accessor.
 
-This is to allow the engine to cache results of your paint class. For example if `--some-other-property` changes the user-agent knows that this doesn't affect your paint class, and can re-use the stored result.
+This is to allow the engine to cache results of your paint class. For example if
+`--some-other-property` changes the user-agent knows that this doesn't affect your paint class, and
+can re-use the stored result.
 
-The only time when your paint class _must_ be called is when the element it is painting into is within the viewport, and the size or CSS input properties have changed.
+The only time when your paint class _must_ be called is when the element it is painting into is
+within the viewport, and the size or CSS input properties have changed.
 
 Why classes?
 ------------
@@ -127,7 +162,8 @@ class BorderRectPainter extends RectPainter {
 registerPaint('border-rect', BorderRectPainter);
 ```
 
-Classes also give the developer a specific point in time to perform pre-initialization work. As an example:
+Classes also give the developer a specific point in time to perform pre-initialization work. As an
+example:
 
 ```js
 registerPaint('lots-of-paths', class {
@@ -146,14 +182,18 @@ registerPaint('lots-of-paths', class {
 });
 ```
 
-In this example `performPathPreInit` is doing CPU intensive work which should only be done once. Without classes this would typically be done when the script is first run, instead this is performed when the class instance is first created (which may be much later in time).
+In this example `performPathPreInit` is doing CPU intensive work which should only be done once.
+Without classes this would typically be done when the script is first run, instead this is performed
+when the class instance is first created (which may be much later in time).
 
 Drawing Images
 --------------
 
-The API works in conjunction with the [CSS Properties and Values](https://drafts.css-houdini.org/css-properties-values-api/) proposal and the [CSS Typed OM](https://drafts.css-houdini.org/css-typed-om/) proposal.
+The API works in conjunction with the [CSS Properties and Values](https://drafts.css-houdini.org/css-properties-values-api/)
+proposal and the [CSS Typed OM](https://drafts.css-houdini.org/css-typed-om/) proposal.
 
-Using the Properties and Values `registerProperty` method, developers can create a custom CSS property with the `<image>` type. E.g.
+Using the Properties and Values `registerProperty` method, developers can create a custom CSS
+property with the `<image>` type. E.g.
 
 ```js
 registerProperty({
@@ -162,7 +202,8 @@ registerProperty({
 });
 ```
 
-This tells the rendering engine to treat the CSS property `--profile-image` as an image; and as a result the style engine will parse and begin loading that image.
+This tells the rendering engine to treat the CSS property `--profile-image` as an image; and as a
+result the style engine will parse and begin loading that image.
 
 You can then directly draw this image from within your paint method:
 
@@ -200,7 +241,35 @@ The above example would be used in CSS by:
 }
 ```
 
-Paint Efficiency
-----------------
+Paint Arguments
+---------------
+
+It is also possible with this API to have additional arguments to the `paint()` function, for
+example:
+
+```js
+registerPaint('circle-args', class {
+  static inputArguments = ['<color>'];
+
+  paint(ctx, size, _, args) {
+    const color = args[0].cssText;
+    ctx.fillStyle = color;
 
-TODO
+    const x = size.width / 2;
+    const y = size.height / 2;
+    const radius = Math.min(x, y);
+
+    ctx.beginPath();
+    ctx.arc(x, y, radius, 0, 2 * Math.PI, false);
+    ctx.fill();
+  }
+});
+```
+
+```js
+my-element {
+  background:
+    paint(circle-args, red) center/50% no-repeat,
+    paint(cirlce-args, blue);
+}
+```