CSS Painting API Level 1

1. Introduction

The paint stage of CSS is responsible for painting the background, content and highlight of a box based on that box’s size (as generated by the layout stage) and computed style.

This specification describes an API which allows developers to paint a part of a box in response to size / computed style changes with an additional <image> function.

Note: In a future version of the spec, support could be added for defining the clip, global alpha, filter on a portion of a box (for example on the background layers).

2. Paint Worklet

The paintWorklet attribute allows access to the Worklet responsible for all the classes which are related to painting.

The paintWorklet's worklet global scope type is PaintWorkletGlobalScope.

The paintWorklet's worklet destination type is "paintworklet".

partial namespace CSS {
    [SameObject] readonly attribute Worklet paintWorklet;
};

A PaintWorkletGlobalScope is a global execution context of the paintWorklet.

A PaintWorkletGlobalScope has a devicePixelRatio property which is identical to the Window.devicePixelRatio property.

[Global=(Worklet,PaintWorklet),Exposed=PaintWorklet]
interface PaintWorkletGlobalScope : WorkletGlobalScope {
    undefined registerPaint(DOMString name, VoidFunction paintCtor);
    readonly attribute unrestricted double devicePixelRatio;
};

The PaintRenderingContext2DSettings contains the settings for the rendering context associated with the paint canvas. The PaintRenderingContext2DSettings provides a supported subset of canvas rendering context 2D settings. In the future, it may be extended to support color management in paint canvas.

dictionary PaintRenderingContext2DSettings {
    boolean alpha = true;
};

class MyPaint {
    static get inputProperties() { return ['--foo']; }
    static get inputArguments() { return ['<color>']; }
    static get contextOptions() { return {alpha: true}; }

    paint(ctx, size, styleMap) {
        // Paint code goes here.
    }
}

3. Concepts

A paint definition is a struct which describes the information needed by the PaintWorkletGlobalScope about the author defined <image> (which can be referenced by the <paint()> function). It consists of:

• class constructor which is the class constructor.

• paint function which is the paint Function callback function type.

• constructor valid flag.

• input properties which is a list of DOMStrings.

• A PaintRenderingContext2DSettings object.

A document paint definition is a struct which describes the information needed by the document about the author defined <image> function (which can be referenced by the paint function). It consists of:

• A input properties which is a list of DOMStrings.

• A input argument syntaxes which is a list of syntax definitions.

• A PaintRenderingContext2DSettings object.

4. Registering Custom Paint

The document has a map of document paint definitions. Initially this map is empty; it is populated when registerPaint(name, paintCtor) is called.

A PaintWorkletGlobalScope has a map of paint definitions. Initially this map is empty; it is populated when registerPaint(name, paintCtor) is called.

A PaintWorkletGlobalScope has a map of paint class instances. Initially this map is empty; it is populated when draw a paint image is invoked by the user agent.

Instances of paint classes in the paint class instances map may be disposed and removed from the map by the user agent at any time. This may be done when a <paint()> function no longer is used, or the user agent needs to reclaim memory.

5. Paint Notation

paint() = paint( <ident>, <declaration-value>? )

The <paint()> function is an additional notation to be supported by the <image> type.

<style>
    .logo { background-image: paint(company-logo); }
    .chat-bubble { background-image: paint(chat-bubble, blue); }
</style>

For the cursor property, the <paint()> function should be treated as an invalid image and fallback to the next supported <image>.

At computed value time the <paint()> function does not need to match the grammar registered by registerPaint(). Instead this will result in an invalid image when the parsing occurs inside draw a paint image.

6. The 2D rendering context

[Exposed=PaintWorklet]
interface PaintRenderingContext2D {
};
PaintRenderingContext2D includes CanvasState;
PaintRenderingContext2D includes CanvasTransform;
PaintRenderingContext2D includes CanvasCompositing;
PaintRenderingContext2D includes CanvasImageSmoothing;
PaintRenderingContext2D includes CanvasFillStrokeStyles;
PaintRenderingContext2D includes CanvasShadowStyles;
PaintRenderingContext2D includes CanvasRect;
PaintRenderingContext2D includes CanvasDrawPath;
PaintRenderingContext2D includes CanvasDrawImage;
PaintRenderingContext2D includes CanvasPathDrawingStyles;
PaintRenderingContext2D includes CanvasPath;

Note: The PaintRenderingContext2D implements a subset of the CanvasRenderingContext2D API. Specifically it doesn’t implement the CanvasImageData, CanvasUserInterface, CanvasText, or CanvasTextDrawingStyles APIs.

A PaintRenderingContext2D object has a output bitmap. This is initialised when the object is created. The size of the output bitmap is the concrete object size of the object it is rendering to.

A PaintRenderingContext2D object also has an alpha flag, which can be set to true or false. Initially, when the context is created, its alpha flag must be set to true. When a PaintRenderingContext2D object has its alpha flag set to false, then its alpha channel must be fixed to 1.0 (fully opaque) for all pixels, and attempts to change the alpha component of any pixel must be silently ignored.

The size of the output bitmap 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 output bitmap 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 output bitmap repeatably while the visual viewport is being zoomed for example.

Whenever "currentColor" is used as a color in the PaintRenderingContext2D API, it is treated as opaque black.

registerPaint('currentcolor', class {
    paint(ctx, size) {
        ctx.fillStyle = 'currentColor';
        ctx.fillRect(0, 0, size.width, size.height);
    }
});

6.1. Drawing a CSSImageValue

The CanvasImageSource typedef is extended to also include the CSSImageValue type to be used as an image source.

For interfaces which use the CanvasDrawImage mixin:

• When a CanvasImageSource object represents an CSSImageValue, the result of invoking the value’s underlying image algorithm must be used as the source image for the purposes of drawImage.

Note: This should eventually be moved to the canvas section of the HTML specification. See Issue 819.

7. Drawing an image

If a <paint()> function image for a box is within the visual viewport, the user agent must display an image output from an invocation of the draw a paint image algorithm.

Note: The user agent doesn’t have to run draw a paint image each frame for a <paint()> function within the visual viewport. It can cache results, (potentially using additional invalidation steps) to display the correct image output.

Note: The user agent can optionally defer drawing images which are outside the visual viewport.

requestAnimationFrame(function() {
    element.styleMap.set('--custom-prop-invalidates-paint', 42);
});

The draw a paint image function is invoked by the user agent during the object size negotiation algorithm which is responsible for rendering an <image>, with snappedConcreteObjectSize defined as follows. Let concreteObjectSize be the concrete object size of the box. The snappedConcreteObjectSize is usually the same as the concreteObjectSize. However, the user agent may adjust the size such that it paints to pixel boundaries. If it does, the user agent should adjust the snappedConcreteObjectSize by the proportional change from its original size such that the <paint()> function can adjust the drawing accordingly.

For the purposes of the object size negotiation algorithm, the paint image has no natural dimensions.

Note: In a future version of the spec, the author could have the ability to specify the natural dimensions of the paint image. This will probably be exposed as a callback allowing the author to define static natural dimensions or dynamically updating the natural dimensions based on computed style and size changes.

The PaintSize object represents the size of the image that the author should draw. This is the snappedConcreteObjectSize given by the user agent.

Note: See CSS Images 3 § 4.4 Examples of CSS Object Sizing for examples on how the concrete object size is calculated.

The draw a paint image function may be speculatively invoked by the user agent at any point, with any snappedConcreteObjectSize. The resulting image is not displayed.

Note: User agents may use any heuristic to speculate a possible future value for snappedConcreteObjectSize, for example speculating that the size remains unchanged.

Note: Although the image is not displayed, it may still be cached, and subsequent invocations of <paint()> may use the cached image.

[Exposed=PaintWorklet]
interface PaintSize {
    readonly attribute double width;
    readonly attribute double height;
};

7.1. Global Scope Selection

When the user agent needs to select a PaintWorkletGlobalScope from the paint Worklet's global scopes list it must:

• Select from at least two PaintWorkletGlobalScopes, unless the user agent is under memory constraints.

• Not re-use the same PaintWorkletGlobalScope more than 1000 times in a row.

  Note: The 1000 limit was picked as a high upper bound, this limit may improve (downwards) over time.

Note: These rules exist to ensure that authors do not rely on being able to store state on the global object or non-regeneratable state on the class. See the discussion in the worklets specification about code idempotence.

8. Examples

8.1. Example 1: Colored Circle

The example below makes use of the fact that <paint()> functions are able to be animated. E.g. when the textarea is focused in the example below, the --circle-color property will transition from deepskyblue to purple.

This ability isn’t limited to just transitions, it also applies to CSS animations, and the Web Animations API.

<!DOCTYPE html>
<style>
  #example {
    --circle-color: deepskyblue;

    background-image: paint(circle);
    font-family: sans-serif;
    font-size: 36px;
    transition: --circle-color 1s;
  }

  #example:focus {
    --circle-color: purple;
  }
</style>

<textarea id="example">
  CSS is awesome.
</textarea>

<script>
    CSS.registerProperty({
      name: '--circle-color',
      syntax: '<color>',
      initialValue: 'black',
      inherits: false
    });
    CSS.paintWorklet.addModule('circle.js');
</script>

// circle.js
registerPaint('circle', class {
  static get inputProperties() { return ['--circle-color']; }
  paint(ctx, geom, properties) {
    // Change the fill color.
    const color = properties.get('--circle-color');
    ctx.fillStyle = color.cssText;

    // Determine the center point and radius.
    const x = geom.width / 2;
    const y = geom.height / 2;
    const radius = Math.min(x, y);

    // Draw the circle \o/
    ctx.beginPath();
    ctx.arc(x, y, radius, 0, 2 * Math.PI, false);
    ctx.fill();
  }
});

8.2. Example 2: Image Placeholder

It is possible for an author to use paint to draw a placeholder image while an image is being loaded.

<!DOCTYPE html>
<style>
#example {
    --image: url('#someUrlWhichIsLoading');
    background-image: paint(image-with-placeholder);
}
</style>

<div id="example"></div>

<script>
    CSS.registerProperty({
        name: '--image',
        syntax: '<image> | none',
        initialValue: 'none',
    });
    CSS.paintWorklet.addModule('image-placeholder.js');
</script>

// image-placeholder.js
registerPaint('image-with-placeholder', class {
    static get inputProperties() { return ['--image']; }
    paint(ctx, geom, properties) {
        const img = properties.get('--image');

        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;
        }
    }
});

8.3. Example 3: Arcs

<!DOCTYPE html>
<style>
#example {
  width: 200px;
  height: 200px;

  background-image:
    paint(arc, purple, 0.4turn, 0.8turn, 40px, 15px),
    paint(arc, blue, -20deg, 170deg, 30px, 20px),
    paint(arc, red, 45deg, 220deg, 50px, 10px);
}
</style>

<div id="example"></div>

<script>
    CSS.paintWorklet.addModule('arc.js');
</script>

// arc.js
registerPaint('arc', class {
  static get inputArguments() {
    return [
      '<color>',
      '<angle>',  // startAngle
      '<angle>',  // endAngle
      '<length>', // radius
      '<length>', // lineWidth
    ];
  }

  paint(ctx, geom, _, args) {
    ctx.strokeStyle = args[0].cssText;

    // Determine the center point.
    const x = geom.width / 2;
    const y = geom.height / 2;

    // Convert the start and end angles to radians.
    const startAngle = this.convertAngle(args[1]) - Math.PI / 2;
    const endAngle = this.convertAngle(args[2]) - Math.PI / 2;

    // Convert the radius and lineWidth to px.
    const radius = this.convertLength(args[3]);
    const lineWidth = this.convertLength(args[4]);

    ctx.lineWidth = lineWidth;

    ctx.beginPath();
    ctx.arc(x, y, radius, startAngle, endAngle, false);
    ctx.stroke();
  }

  convertAngle(angle) {
    switch (angle.unit) {
      case 'deg':
        return angle.value * Math.PI / 180;
      case 'rad':
        return angle.value;
      case 'grad':
        return angle.value * Math.PI / 200;
      case 'turn':
        return angle.value * Math.PI / 0.5;
      default:
        throw Error(`Unknown angle unit: ${angle.unit}`);
    }
  }

  convertLength(length) {
    switch (length.type) {
      case 'px':
        return length.value;
      default:
        throw Error(`Unkown length type: ${length.type}`);
    }
  }
});

8.4. Example 4: Different Colors (based on size)

<h1>
    Heading 1
</h1>
<h1>
    Another heading
</h1>

<style>
h1 {
    background-image: paint(heading-color);
}
</style>

<script>
    CSS.paintWorklet.addModule('heading-color.js');
</script>

// heading-color.js
registerPaint('heading-color', class {
    static get inputProperties() { return []; }
    paint(ctx, geom, properties) {
        // Select a color based on the width and height of the image.
        const width = geom.width;
        const height = geom.height;
        const color = colorArray[(width * height) % colorArray.length];

        // Draw just a solid image.
        ctx.fillStyle = color;
        ctx.fillRect(0, 0, width, height);
    }
});

8.5. Example 5: Drawing outside an element’s area

It is possible to draw outside an element’s area by using the border-image property.

<style>
#overdraw {
    --border-width: 10;

    border-style: solid;
    border-width: calc(var(--border-width) * 1px);

    border-image-source: paint(overdraw);
    border-image-slice: 0 fill;
    border-image-outset: calc(var(--border-width) * 1px);

    width: 200px;
    height: 200px;
}
</style>
<div id="overdraw"></div>
<script>
    CSS.paintWorklet.addModule('overdraw.js');
</script>

// overdraw.js
registerPaint('overdraw', class {
    static get inputProperties() { return ['--border-width']; }
    paint(ctx, geom, properties) {
        const borderWidth = parseInt(properties.get('--border-width'));
        ctx.shadowColor = 'rgba(0,0,0,0.25)';
        ctx.shadowBlur = borderWidth;

        ctx.fillStyle = 'rgba(255, 255, 255, 1)';
        ctx.fillRect(borderWidth,
                     borderWidth,
                     geom.width - 2 * borderWidth,
                     geom.height - 2 * borderWidth);
    }
});

9. Security Considerations

There are no known security issues introduced by these features.

10. Privacy Considerations

• The timing of paint callbacks can be used as a high-bandwidth channel for detecting "visited" state for links. (details) This is not a fundamentally new privacy leak, as visited state leaks from many interactions, but absent any further mitigations, this is a particularly high-bandwidth channel of the information.

  No official mitigations are planned at this time, as this privacy leak needs to be addressed more directly to fix all such channels.

11. Changes

Changes since the 9 August 2018 CR publication:

• Filtered the list of input properties to a paint worklet to be only known or custom properties.

• Added alpha flag to PaintRenderingContext2D to control whether the rendering surface is forced opaque or allows transparency.

• Fix definition for the size of the output bitmap:

  The size of the output bitmap is the concrete object size of the object it is rendering to size of the fragment it is rendering .