[whatwg] proposal: Add support for masking to canvas

[Rik Cabanier]

All,

the canvas API does not have a convenient way of supporting masking today.
There is some support with the compositing operators but it requires quite
a bit of work on the author's part as well as a temporary canvas. In
addition, there is no way to implement a luminosity mask without reading
the pixels and doing the math yourself.

I was thinking of proposing the following new API calls for the 2d canvas
context:

enum CanvasMaskType { luminosity, alpha};
void maskImage(image, sx, sy, sw, sh, dx, dy, dw, dh, maskType, invert,
clipToMask);
void resetMask();


'maskImage' will set the mask in the current graphics state which makes it
subject to save/restore. parameters:

image = HTMLImageElement or HTMLCanvasElement or HTMLVideoElement.

Points to set of pixels that will be used as the mask source


sx, sy, etc = describes what portions of the source and destination canvas
to target. (This is similar to drawImage [1])

maskType = sets what type of mask.

luminosity = (default) use the luma value of the pixel

alpha = just look at the alpha channel. ignore the color channel

invert = boolean. (default = false) invert the mask values

clipToMask = boolean (default = true) the area outside of the mask pixels
clipped away. If false, that area is not affected by the mask.

'maskImage' will set the mask in the current graphics state which makes it
subject to save/restore.


'resetMask' will remove the mask from the current graphics state.

Some people told me that maskImage is taking too many parameters and that a
dictionary would be better.

What do people think? Is this useful enough to add to the API?

Rik

1:
http://www.w3.org/html/wg/drafts/2dcontext/html5_canvas/#dom-context-2d-drawimage