[css-paint-api] first rough version of paint level 1.

Author: bfgeek

css-paint-api/Overview.bs

@@ -9,3 +9,215 @@ Editor: Shane Stephens, shanestephens@google.com
 Editor: Ian Kilpatrick, ikilpatrick@chromium.org
 Editor: Dean Jackson, dino@apple.com
 </pre>
+
+Introduction {#intro}
+=====================
+
+The paint stage of CSS is responsible for painting the background, content and highlight of an element based on that element'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 element in response to geometry / computed style changes.
+
+Issue: Currently this spec doesn't provide any mechanism for setting clip, opacity, filter, etc. on either the context, background of an element. This would be nice to have.
+
+Paint Invalidation {#paint-invalidation}
+==================================
+
+At any point in time the output of a paint callback for an element may be either <dfn>paint-valid</dfn> or <dfn>paint-invalid</dfn>.
+
+Issue: Describe output in a nicer way. This could be pixels, or a display list type object.
+
+If the output is <a>paint-invalid</a> and the output should not be used for rendering, and can be safely disposed.
+
+Invoking the paint callback will cause the output to become <a>paint-valid</a>.
+
+The output of a paint callback will become <a>paint-invalid</a> when:
+ * The geometry of an element/fragment (as determined by layout) changes.
+ * The computed style of a property that the paint callback has registered a dependency on has changed.
+
+Output which is <a>paint-valid</a> does not provide a guarantee that the paint callback is not invoked. Browsers may choose to invoke all callbacks every frame for simplicity.
+Thus to ensure cross-browser compatibility paint callbacks should be idempotent.
+
+Output which is <a>paint-invalid</a> are not necessarily invoked on the current frame.
+For example if the element is outside the current viewport, the browser may choose to only invoke the callback when it appears in the viewport.
+
+Issue: This describes everything in terms of element which is incorrect. Callbacks should be at the fragment level.
+
+Issue: Describe what happens if a callback doesn't hit a frame timing boundary. I.e. just renders a transparent image instead?
+
+Issue: Should paint callbacks support partial area invalidation?
+       For example if the paint callback just invalidates 1/4 of the actual element, should we provide an API to just update that area?
+       This may be expensive for memory/computation for display list based implementations.
+
+Registering Custom Paint {#registering-custom-paint}
+====================================================
+
+<pre class='idl'>
+interface PaintGlobalScope {
+    // TODO once we have a spec for separate script execution contexts, make this inherit.
+    // A PaintGlobalScope is inside of a 'worker', so not in the main script execution context.
+    // A PaintGlobalScope and by extension custom paint callbacks don't have access to things like the DOM, XHRs, etc.
+};
+
+interface CanvasRenderingContext2d {
+    // TODO link to actual CanvasRenderingContext2d.
+};
+
+interface Geometry {
+    readonly attribute double width;
+    readonly attribute double height;
+};
+
+interface InputProperties {
+    // Similar to ComputedStyle, but only includes properties listed in 'dependencies'.
+    // Eventually provide typed access to properties instead of string based access.
+};
+
+callback PaintCallback = void (CanvasRenderingContext2d context, Geometry geometry, InputProperties inputProperties);
+
+dictionary VisualOverflowRectDict {
+    float? top;
+    float? bottom;
+    float? left;
+    float? right;
+};
+
+dictionary PaintDescriptor {
+    DOMString name;
+    PaintCallback paintCallback;
+    sequence&lt;DOMString&gt; dependencies;
+    DOMString contextType;
+    VisualOverflowRectDict visualOverflowRect;
+};
+
+partial interface PaintGlobalScope {
+      long registerPaint(PaintDescriptor paint);
+      void unregisterPaint(long hookID);
+};
+</pre>
+
+:   <dfn dict-member for=PaintDescriptor>name</dfn>
+::  The name of the custom paint being defined. Any valid <<ident>> can be a custom paint name.
+
+:   <dfn dict-member for=PaintDescriptor>paintCallback</dfn>
+::  The custom paint callback.
+
+Issue: This should probably be a class instead.
+
+:   <dfn dict-member for=PaintDescriptor>dependencies</dfn>
+::  The list of CSS properties (custom or native) which are provided to the custom paint callback. In addition when any of these properties changes, an element will become <a>paint-invalid</a>.
+
+:   <dfn dict-member for=PaintDescriptor>contextType</dfn>
+::  The type of context to provide for paint. Providing the "2d" will result in a <a href=''>CanvasRenderingContext2d</a>.
+
+Issue: We probably won't support any others initially. Remove this?
+
+:   <dfn dict-member for=PaintDescriptor>visualOverflowRect</dfn>
+::  The amount of additional canvas to provide for drawing for the fragment.
+    This additional canvas can be used for drawing outside the box determined by layout for achieving overflow effects like box-shadow.
+
+Issue: This is not how CSS works. We probably need an additional callback to provide the visual overflow rect based on the InputProperties.
+       This is another argument for making the API class based.
+
+:   <dfn method for=PaintGlobalScope>registerPaint(<var>paint</var>)</dfn>
+::  Registers a paint callback.
+
+:   <dfn method for=PaintGlobalScope>unregisterPaint(<var>hookID</var>)</dfn>
+::  Unregisters a paint callback based on the ID given by <a>registerPaint()</a>.
+
+:   <dfn argument for=PaintCallback>context</dfn>
+::  The paint callback is passed a new <a href=''>CanvasRenderingContext2d</a> each time it is invoked. Implicitly this means that there is no stored data, or state on the rendering context.
+    For example you can't setup a clip on the context, and expect the same clip to be applied next time the function is called.
+
+    Several methods will be modified from the current CanvasRenderingContext2d. For example:
+     * The <a href=''>canvas</a> accessor will throw a <a href=''>InvalidAccessError</a> as the context doesn't have a parent <a href=''>HTMLCanvasElement</a>.
+     * <a href=''>getImageData()</a> and similar pixel data accessors will be no-ops.
+     * <a href=''>addHitRegion()</a>, <a href=''>removeHitRegion()</a>, <a href=''>clearHitRegions()</a> will be no-ops.
+     * <a href=''>drawFocusIfNeeded()</a> will be a no-op.
+
+Note: The litmus test used for deciding above was: methods should become no-ops if they can, otherwise throw an error if they'd require an IDL change.
+
+Issue: We should probably create a new interface for CanvasRenderingContext2d and use IDL mixins (like CanvasPathMethods) to share common interfaces.
+
+:   <dfn argument for=PaintCallback>geometry</dfn>
+::  The geometry information for the callback.
+
+Issue: Decide what is needed here (in level 1). Obviously we need the width/height of the fragment.
+       If we are going down the fragment route do we need continuation data? I.e. what edge is shared etc.
+       Do we need children position data?
+       Should make sure we don't rabbit hole too much on this, provide what we think is useful for v1, iterate in v2.
+
+:   <dfn argument for=PaintCallback>inputProperties</dfn>
+::  Similar to <a href=''>ComputedStyle</a>, but only includes properties listed in dependencies.
+
+Issue: No way for image data to appear here yet. Everything string based.
+       For example if you load the image data via. url('http://example.com/image.png') how does this appear in the paint callback?
+       I think the answer to this is to provide this information in the Typed CSS Value OM.
+       Will need access to a loaded bit, width, height, and a way to render into rendering context.
+
+Issue: Should VisualOverflowRectDict just be based on longs instead? Do floats make sense?
+
+Using Custom Paint {#using-custom-paint}
+========================================
+
+The <<image-or-paint>> type extends the <<image>> type to allow the <<paint()>> function.
+
+<pre class="prod"><dfn>&lt;image-or-paint&gt;</dfn> = <<image>> | <<paint()>></pre>
+
+Issue: Should this just replace the <<image>> type instead? I don't think so as it'll mean that we can custom paint the cursor. Which I don't think we want.
+
+The <<paint()>> function will lookup to see if there has been a paint callback registered with the same name.
+If it has the output of the paint callback should appear in the appropriate place.
+If there is no paint callback registered, the function output should be replaced with a transparent image, as if nothing was there.
+
+Issue: Word-smith this better.
+
+<pre class='prod'>
+    <dfn>paint()</dfn> = paint( <<ident>> )
+</pre>
+
+Issue: Change 'background-image', 'border-image' and 'content' to accept <<image-or-paint>> or <<paint()>>.
+
+Examples {#examples}
+====================
+
+Example 1: A colored circle. {#example-1}
+----------------------------------------
+
+<pre class='lang-javascript'>
+// Inside PaintGlobalScope.
+this.registerPaint({
+    name: 'circle',
+    dependencies: ['--circle-color'],
+    contextType: '2d',
+    paintCallback: function(ctx, geom, properties) {
+        // Change the fill color.
+        var color = properties['--circle-color'];
+        ctx.fillStyle = color;
+
+        // Determine the center point and radius.
+        var x = geom.width / 2;
+        var y = geom.height / 2;
+        var radius = Math.min(x, y);
+
+        // Draw the circle \o/
+        ctx.beginPath();
+        ctx.arc(x, y, radius, 0, 2 * Math.PI, false);
+        ctx.fill();
+    }
+});
+</pre>
+
+<pre class='lang-markup'>
+&lt;div id="myElement"&gt;
+    CSS is awesome.
+&lt;/div&gt;
+
+&lt;style&gt;
+#myElement {
+    --circle-color: red;
+    background-image: paint(circle);
+}
+&lt;/style&gt;
+</pre>
+
+Issue: How to do conic-gradient as a use-case?