[whatwg] Proposal: Add CanvasRenderingContext2D.setDash()/.getDash()/.dashOffset for dashed stroking

[Chris Jones]

Most 2d graphics libraries support stroking paths with a "dash pattern" of on/off strokes.  Canvas should have it for completeness.  Because SVG already offers a facility for dashed stroking, adding it to canvas is not expected to be a big burden on implementors who have also implemented SVG.  It's quite nontrivial for authors to implement this functionality on top of canvas, and those implementations are not likely to be performant. 

The concrete proposal is

  interface CanvasRenderingContext2D {
    //...
    void setDash(sequence<Number>);  // array of on/off dash lengths
    sequence<Number> getDash();      // return the current dash array, freshly allocated
    attribute Number dashOffset;     // default 0; offset within dash pattern to begin stroking
    //...
  };

setDash() sets the dash array, getDash() gets the current dash array.  The interpretation of the dash array is the analogue of the SVG "stroke-dasharray" property[1]: the array specifies a sequence of alternating dashes and gaps.  The numbers are distances in the canvas userspace at the time of stroking.  The |dashOffset| specifies an offset into the dash pattern at which stroking should begin, and has the same unit as the elements of |dash|.  It's the analogue of the SVG "stroke-dashoffset" property.  The precise semantics of stroking a dashed path are defined to be the same as in SVG.  The dash array and offset are saved and restored along with other canvas rendering state.

Note: a similar spec has been implemented in Gecko as |mozDash/mozDashOffset|[2], however with mozDash as a sequence attribute, which  Cameron McCormack pointed out is forbidden by WebIDL[3].  In the API above, the attribute is converted into explicit setDash()/getDash() methods.  Mozilla will update Gecko's implementation once the proposal here stabilizes.

Cheers,
Chris

[1] http://www.w3.org/TR/SVG11/painting.html#StrokeProperties
[2] https://bugzilla.mozilla.org/show_bug.cgi?id=662038
[3] https://bugzilla.mozilla.org/show_bug.cgi?id=683051