Merge remote-tracking branch 'upstream/master'

Author: wilddamon

README.markdown

@@ -1,6 +1,6 @@
 ### [CSS-TAG Houdini Task Force](https://wiki.css-houdini.org/) Specifications
 
-This is the repository containing all the CSS/TAG Houdini Task Force specifications.
+This is the repository containing all the [CSS/TAG Houdini Task Force specifications](https://drafts.css-houdini.org/).
 
 In addition to this git repository, a Mercurial mirror is maintained at `https://hg.css-houdini.org/drafts`, if for whatever reason you prefer Mercurial.
 

css-paint-api/Overview.bs

@@ -24,6 +24,8 @@ urlPrefix: https://heycam.github.io/webidl/; type: dfn;
         url: throw; text: thrown
 urlPrefix: https://html.spec.whatwg.org/multipage/scripting.html; type: dfn;
     text: reset the rendering context to its default state
+    text: scratch bitmap
+    text: set bitmap dimensions
 urlPrefix: http://www.ecma-international.org/ecma-262/6.0/#sec-; type: dfn;
     text: Construct
     text: IsArray
@@ -68,26 +70,26 @@ Registering Custom Paint {#registering-custom-paint}
 <pre class='idl'>
 callback VoidFunction = void ();
 
-interface PaintWorkletGlobalScope : WorkletGlobalScope {
+partial interface RenderWorkletGlobalScope {
     void registerPaint(DOMString name, VoidFunction paintCtor);
     void unregisterPaint(DOMString name);
 };
 </pre>
 
-A {{PaintWorkletGlobalScope}} has a map of <b>name to paint instance map</b>. Initially this map is empty; it is populated when {{registerPaint(name, paintCtor)}} is called.
+The {{RenderWorkletGlobalScope}} has a map of <b>name to paint instance map</b>. Initially this map is empty; it is populated when {{registerPaint(name, paintCtor)}} is called.
 
 <div class='note'>
     Note: This is how the class should look.
     <pre class='idl'>
         callback interface PaintClass {
             readonly attribute sequence&lt;DOMString&gt; inputProperties;
-            void paint(PaintRenderingContext2d ctx, Geometry geom, StylePropertyMap inputProperties);
+            void paint(PaintRenderingContext2D ctx, Geometry geom, StylePropertyMap inputProperties);
             void overflow(StylePropertyMap inputProperties);
         };
     </pre>
 </div>
 
-When the <dfn method for=PaintWorkletGlobalScope>registerPaint(<var>name</var>, <var>paintCtor</var>)</dfn> method is called, the user agent <em>must</em> run the following steps:
+When the <dfn method for=RenderWorkletGlobalScope>registerPaint(<var>name</var>, <var>paintCtor</var>)</dfn> method is 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>NotSupportedError</a> and abort all these steps.
     2. If the |name| exists as a key in the <b>name to paint instance map</b>, <a>throw</a> a <a>NotSupportedError</a> and abort all these steps.
     3. If the result of <a>IsConstructor</a>(argument=|paintCtor|) is false, <a>throw</a> a <a>NotSupportedError</a> and abort all these steps.
@@ -98,7 +100,7 @@ When the <dfn method for=PaintWorkletGlobalScope>registerPaint(<var>name</var>,
     8. If the result of <a>IsArray</a>(argument=|inputProperties|) is false, <a>throw</a> a <a>NotSupportedError</a> and abort all these steps.
     9. Add the key-value pair (|name| - |inputProperties|) to the <b>paint name to input properties map</b> of the associated <a>document</a>.
     10. Let <var>paintInstance</var> be the result of <a>Construct</a>(|paintCtor|).
-    11. Add the key-value pair (|name| - |paintInstance|) to the <b>name to paint instance map</b> of the {{PaintWorkletGlobalScope}}.
+    11. Add the key-value pair (|name| - |paintInstance|) to the <b>name to paint instance map</b> of the {{RenderWorkletGlobalScope}}.
 
 Note: The list of CSS properties provided by the input properties getter can either be custom or native CSS properties.
 
@@ -110,9 +112,9 @@ Note: In a future version of the spec, the author may be able to set an option t
 
 Issue(w3c/css-houdini-drafts#31): Allow author to specify the intrinsic size.
 
-When the <dfn method for=PaintWorkletGlobalScope>unregisterPaint(<var>name</var>)</dfn> method is called, the user agent <em>must</em> run the following steps:
+When the <dfn method for=RenderWorkletGlobalScope>unregisterPaint(<var>name</var>)</dfn> method is called, the user agent <em>must</em> run the following steps:
     1. Remove the key-value pair associated with the |name| key in the <b>paint name to input properties map</b> of the associated <a>document</a>.
-    2. Remove the key-value pair associated with the |name| key in the <b>name to paint instance map</b> of the {{PaintWorkletGlobalScope}}.
+    2. Remove the key-value pair associated with the |name| key in the <b>name to paint instance map</b> of the {{RenderWorkletGlobalScope}}.
 
 Paint Notation {#paint-notation}
 ================================
@@ -131,22 +133,70 @@ Issue(w3c/css-houdini-drafts#33): What to do about cursor.
 
 Issue: How do we do things like conic-gradient? I.e. paint functions which accept arguments as inputs?
 
-Drawing an image {#drawing-an-image}
-====================================
+The 2D rendering context {#2d-rendering-context}
+================================================
 
 <pre class='idl'>
-interface PaintRenderingContext2d {
-    // TODO link to actual CanvasRenderingContext2d.
+[Exposed=Worklet]
+interface PaintRenderingContext2D {
 };
+PaintRenderingContext2D implements CanvasState;
+PaintRenderingContext2D implements CanvasTransform;
+PaintRenderingContext2D implements CanvasCompositing;
+PaintRenderingContext2D implements CanvasImageSmoothing;
+PaintRenderingContext2D implements CanvasFillStrokeStyles;
+PaintRenderingContext2D implements CanvasShadowStyles;
+PaintRenderingContext2D implements CanvasRect;
+PaintRenderingContext2D implements CanvasDrawPath;
+PaintRenderingContext2D implements CanvasText;
+PaintRenderingContext2D implements CanvasDrawImage;
+PaintRenderingContext2D implements CanvasPathDrawingStyles;
+PaintRenderingContext2D implements CanvasTextDrawingStyles;
+PaintRenderingContext2D implements CanvasPath;
+</pre>
+
+Note: The {{PaintRenderingContext2D}} implements a subset of the {{CanvasRenderingContext2D}} API.
+    Specifically it doesn't implement the {{CanvasHitRegion}}, {{CanvasImageData}} or
+    {{CanvasUserInterface}} APIs.
+
+A {{PaintRenderingContext2D}} object has a <a>scratch bitmap</a>. This is initialised when the
+object is created. The size of the <a>scratch bitmap</a> is the size of the fragment it is rendering
+plus the size specified by the overflow method.
+
+The logical origin (0,0) is not necessarily placed at the origin of the <a>scratch bitmap</a>. If
+the fragment which is being painted has an associated overflow, the logical origin is placed at
+(overflow-left,overflow-top) of the <a>scratch bitmap</a>.
+
+Issue: Add image explaining origin vs. logical origin.
+
+The size of the <a>scratch bitmap</a> does not necessarily represent the size of the actual bitmap
+that the user agent will use internally or during rendering. For example, if the visual viewport is
+zoomed the user agent may internally use bitmaps which correspond to the number of device pixels in
+the coordinate space, so that the resulting rendering is of high quality.
+
+Additionally the user agent may record the sequence of drawing operations which have been applied to
+the <a>scratch bitmap</a> such that the user agent can subsequently draw onto a device bitmap at the
+correct resolution. This also allows user agents to re-use the same output of the <a>scratch
+bitmap</a> repeatably while the visual viewport is being zoomed for example.
+
+When the user agent is to <dfn>create a {{PaintRenderingContext2D}} object</dfn> for a given
+|width|, |height| and |overflowOffset| it <em>must</em> run the following steps:
+    1. Create a new {{PaintRenderingContext2D}}.
+    2. <a>Set bitmap dimensions</a> for the context's <a>scratch bitmap</a> to |width| and |height|.
+    3. Set the logical origin of the <a>scratch bitmap</a> to |overflowOffset|.
+    4. Return the new {{PaintRenderingContext2D}}.
 
+Drawing an image {#drawing-an-image}
+====================================
+
+<pre class='idl'>
+[Exposed=Worklet]
 interface Geometry {
     readonly attribute double width;
     readonly attribute double height;
 };
 </pre>
 
-Issue: Create a new interface which uses IDL mixins to share methods with CanvasRenderingContext2d.
-
 If a <<paint()>> function for a fragment is <a>paint-invalid</a> and the fragment is within the visual viewport,
 then user agent <em>must</em> <a>draw an image</a> for the current frame.
 
@@ -169,23 +219,18 @@ When the user agent wants to <dfn>draw an image</dfn> of a <<paint()>> for a <va
     6. Let <var>overflow</var> be the result <a>invoke a method on a class inside a Worklet</a> given "overflow" as the <em>methodPropertyKey</em> and [|styleMap|] as the <em>arguments</em> with the following options:
         - To <a>create a worklet global scope</a> the user agent will:
 
-            Return a new {{PaintWorkletGlobalScope}}.
+            Return a new {{RenderWorkletGlobalScope}}.
         - To <a>lookup a class instance on a worklet global scope</a> given a |workletGlobalScope|, the user agent will:
 
             Return the result of looking up |name| on the |workletGlobalScope|'s <b>name to paint instance map</b>.
 
         Note: User agents may have to compute overflow before entering their paint phase in order to determine which fragments to paint (overflow changes what could be seen on the output device).
             User agents may opt into running the steps up to this point, to determine overflow, then continuing later to determine the drawn image for the fragments which need painting.
 
-    7. Let <var>renderingContext</var> be a new {{PaintRenderingContext2d}}.
-
-        The backing size of the |renderingContext| must be the size of the |fragment| plus the size specified by |overflow|.
-
-        The user agent must ensure to <a>reset the rendering context to its default state</a>.
-
-        The origin of the |renderingContext| must be offset by the left, top size specified by |overflow|.
-
-        Note: (0,0) is the top-left of the |fragment|, (-offsetLeft,-offsetTop) is the top-left of the |overflow|.
+    7. Let <var>renderingContext</var> be the result of <a>create a {{PaintRenderingContext2D}} object</a> given:
+        - "overflowOffset" - The logical offset for the <a>scratch bitmap</a> specified by |overflow|.
+        - "width" - The width of the |fragment| plus the additional width specified by |overflow|.
+        - "height" - The height of the |fragment| plus the additional height specified by |overflow|.
 
         Note: The |renderingContext| must not be re-used between invocations of paint. Implicitly this means that there is no stored data, or state on the |renderingContext| between invocations.
             For example you can't setup a clip on the context, and expect the same clip to be applied next time the paint method is called.
@@ -199,7 +244,7 @@ When the user agent wants to <dfn>draw an image</dfn> of a <<paint()>> for a <va
     9. To produce the image output, <a>invoke a method on a class inside a Worklet</a> given "paint" as the <em>methodPropertyKey</em> and [|renderingContext|, |geometry|, |styleMap|] as the <em>arguments</em> with the following options:
         - To <a>create a worklet global scope</a> the user agent will:
 
-            Return a new {{PaintWorkletGlobalScope}}.
+            Return a new {{RenderWorkletGlobalScope}}.
         - To <a>lookup a class instance on a worklet global scope</a> given a |workletGlobalScope|, the user agent will:
 
             Return the result of looking up |name| on the |workletGlobalScope|'s <b>name to paint instance map</b>.
@@ -234,7 +279,7 @@ Example 1: A colored circle. {#example-1}
 -----------------------------------------
 
 <pre class='lang-javascript'>
-// Inside PaintWorkletGlobalScope.
+// Inside RenderWorkletGlobalScope.
 registerPaint('circle', class {
     static get inputProperties() { return ['--circle-color']; }
     paint(ctx, geom, properties) {

css-typed-om/Overview.bs

@@ -41,7 +41,7 @@ Issue: is it possible to amalgamate this API with value objects once they're spe
 <pre class='idl'>
 interface StyleValue {
   attribute DOMString cssString;
-  static (StyleValue or sequence&ltStyleValue>)? parse(DOMString property, DOMString cssText);
+  static (StyleValue or sequence&lt;StyleValue>)? parse(DOMString property, DOMString cssText);
 };
 </pre>
 
@@ -355,7 +355,7 @@ Issue: What happens if the provided DOMString or LengthValue for (e.g.) a Simple
 
 <pre class='idl'>
 [Constructor(),
- Constructor(sequence&lt;TransformComponent>)]
+ Constructor(sequence&lt;TransformComponent> transforms)]
 interface TransformValue : StyleValue {
   iterable&lt;TransformComponent>;
   Matrix asMatrix();

worklets/Overview.bs

@@ -271,6 +271,25 @@ it must run the following steps:
 
 Note: It is up to the user agent to select a appropriate {{WorkletGlobalScope}} to invoke the method in.
 
+Rendering Worklet {#rendering-worklet}
+--------------------------------------
+
+The {{renderWorklet}} attribute allows access to the {{Worklet}} responsible for all the classes
+which are related to rendering.
+
+<pre class='idl'>
+partial interface Window {
+    [SameObject] readonly attribute Worklet renderWorklet;
+};
+</pre>
+
+The {{RenderWorkletGlobalScope}} is the global execution context of the {{renderWorklet}}.
+
+<pre class='idl'>
+interface RenderWorkletGlobalScope : WorkletGlobalScope {
+};
+</pre>
+
 Examples {#examples}
 ====================