CanvasRoundRect

Proposal to add roundRect() to Path2D.

Abstract

Roundrects are everywhere, a single call in Path2D to create a round rect can be accelerated as it lets the underlying platform know of the intent to draw a round rect, as opposed to merely composing a round rect from a series of individual paths.

Description

Follow http://dev.w3.org/csswg/css-backgrounds/#border-radius the rules for css border radius.

Motivation

• Speed. TODO - Add some perf measurements against either native skia, or a patch against blink showing the perf increase.
• Ease of use.
• TODO find examples of roundrect in other apis.
  • Cocoa
  • Skia
• This feature can be polyfilled, see this fork of canvas-5-polyfill. The polyfill in action.

WebIDL

The specification would add the following methods to CanvasPathMethods, which mean they would appear in Path2D and CanvasRenderingContext2D.

interface CanvasPathMethods {
    ...
    [RaisesException] void roundRect(unrestricted float x, unrestricted float y, unrestricted float width, unrestricted float height,
        unrestricted float rh, unrestricted float rv);
    [RaisesException] void roundRect(unrestricted float x, unrestricted float y, unrestricted float width, unrestricted float height,
        unrestricted float rtl, unrestricted float rtr, unrestricted float rbr, unrestricted float rbl);
    [RaisesException] void roundRect(unrestricted float x, unrestricted float y, unrestricted float width, unrestricted float height,
        unrestricted float rtlh, unrestricted float rtlv,
        unrestricted float rtrh, unrestricted float rtrv,
        unrestricted float rbrh, unrestricted float rbrv,
        unrestricted float rblh, unrestricted float rblv);
    ...
};

Details

The values of x, y, width and height describe the rectangle. All the other parameters describe the radii of the corners for the path of the round rect. Each method must create a new subpath containing just the components of the round rect, and must then mark the subpath as closed.

 roundRect(x, y, width, height, radius, rh, rv);

Adds the path of the round rect to the current path. Every corner will have a horizontal radius of 'rh and a verical radius of 'rv'. If rv is omitted, user agents must act as if it had the same value as rh.

 roundRect(x, y, width, height, rtl, rtr, rbr, rbl);

Adds the path of the round rect to the current path with a radius given for each corner going in a clockwise direction starting from the top-left corner. The radii given are rtl: top-left, rtr: top-right, rbr: bottom-right, rbl: bottom left.

 roundRect(x, y, width, height, rtlh, rtlv, rtrh, rtrv, rbrh, rbrv, rblh, rblv);

Adds the path of the round rect to the current path with a radius given for each corner, both horizontal and vertical dimension, going in a clockwise direction starting from the top-left corner. The radii given are rtlh: top-left-horizontal, rtlv: top-left-vertical, rtrh: top-right-horizontal, rtrv: top-right-vertical, rbrh: bottom-right-horizontal, rbrv: bottom-right-veritcal, rblh: bottom-left-horizontal, rblv: bottom-left-vertical.

Negative values for any radius must cause the implementation to throw an IndexSizeError exception.

Corner curves must not overlap: When the sum of any two adjacent border radii exceeds the size of the border box, the implementation must throw an IndexSizeError exception.

Open Questions

• Should these calls be RaisesException? Alternatively they could do nothing for invalid inputs, i.e. negative radii.
• Should the spec text use horizontal and vertical like the CSS spec, or stick to x and y?
• Should the overlap be an error that raises an exception, or should we reduce radii until everything works like the CSS spec does it?
• Should these be methods on CanvasPathMethods or only on Path2D?