CanvasFilters
This specification has been incorporated into WHATWG HTML
Canvas Filters is a specification for a filter attribute that takes a list of filter operations similar to the CSS Image filter function.
- Editors
- Markus Stange
- Tobias Schneider
- Tantek Çelik
- Feedback
- Please send feedback on CanvasFilters to whatwg@whatwg.org
Per CC0, to the extent possible under law, the editors have waived all copyright and related or neighboring rights to this work. In addition, as of 2024-04-18, the editors have made this specification available under the Open Web Foundation Agreement Version 1.0.
Background:
Bugs:
- https://bugzilla.mozilla.org/show_bug.cgi?id=927892
- https://bugzilla.mozilla.org/show_bug.cgi?id=1152918
- https://code.google.com/p/chromium/issues/detail?id=501642
Contents
Basic Examples
Using a CSS shorthand
<canvas id="canvas"></canvas>
var canvas = document.getElementById("canvas");
var ctx = canvas.getContext("2d");
ctx.filter = "blur(5px)";
ctx.font = "48px serif";
ctx.strokeText("Hello world", 50, 100);
Using a SVG reference
<canvas id="canvas"></canvas>
<svg>
<defs>
<filter id="blur" x="0" y="0">
<feGaussianBlur in="SourceGraphic" stdDeviation="5" />
</filter>
</defs>
</svg>
var canvas = document.getElementById("canvas");
var ctx = canvas.getContext("2d");
ctx.filter = "url(#blur)";
ctx.font = "48px serif";
ctx.strokeText("Hello world", 50, 100);
IDL addition
[Constructor(),
Constructor(unsigned long width, unsigned long height),
Exposed=(Window,Worker)]
interface CanvasRenderingContext2D {
// ...
// filter
attribute DOMString filter; // (default "none")
}
Filter
The value of the filter attribute is part of the canvas drawing state.
All drawing operations are affected by the filter.
context . filter [ = value ] Returns the current filter. Can be set, to change the filter. Values that cannot be parsed are ignored.
When the context is created, the filter attribute initially must be set to "none".
On getting, must return the value that it was last successfully set to. The value must not be re-serialized.
On setting, if the new value is "none" (not "", null nor undefined), filters must be disabled for the context. Otherwise, the value must be parsed as a CSS <filter-function-list> value. If the value cannot be parsed as a CSS <filter-function-list> value, where using property-independent style sheet syntax like 'inherit' or 'initial' is considered an invalid value, then it must be ignored, and the attribute must retain its previous value. [filter-effects]
All drawing operations are affected by the filter attribute.
Coordinates in filters are interpreted as 1px = 1 SVG user space unit = 1 canvas coordinate space unit. Filter coordinates are not affected by the current transformation matrix. The current transformation matrix only affects the input to the filter, filters are applied in device space (XXX "device space" is apparently not defined on https://html.spec.whatwg.org/multipage/scripting.html , how should we say this? I think they refer to the same concept as "the bitmap's coordinate space". The SVG spec uses "the parent's coordinate space" or "viewport coordinate space").
When a filter value defines lengths using percentages, 'em' or 'ex' units (Issue: What about 'larger' or 'smaller' ... ?) keywords, these must be interpreted relative to the computed value of the 'font-size' property of the font style source object of the canvas at the time that the attribute is set, if it is an element. If the computed values are undefined for a particular case (e.g. because the font style source object is not an element or is not being rendered), then the relative keywords must be interpreted relative to the normal-weight 10px sans-serif default.
If the filter refers to an SVG filter in an external resource document, and that document hasn't finished loading when the filtered drawing operation is invoked, nothing gets drawn. Issue: This behavior should be the same as if trying to draw text using a web font that is not fully loaded at that point. It doesn't seem to be defined in the spec tho.
Issue: Should changes to a referenced SVG filter be respected during the next drawing operation? Or does the filter attribute need to be set again for those changes to take effect?
...
Issue: Maybe the shadow drawing algorithm should mention in step 1 that the "source image for which a shadow is being created" is already the output of the filter, if a filter is set. Alternatively (or additionally) we should insert an extra step between step 1 and 2 of the drawing model where image A, as produced by step 1, is used as the input for the filter, drawing its output into image B which is then proceeded with in step 2.
Test Suite
A test suite for CanvasFilters is TBD.
References
- [filter-effects] Filters working draft at https://hg.fxtf.org/drafts/raw-file/default/filters/Publish.html
