[cairo] API Shakeup: cairo_mask

[Carl Worth]

In a previous message, I made the observation (and proposal) that
all drawing operations use the same rendering equation and differ only
in how the shape is computed.

The one operator that is obviously missing from the existing list,
(cairo_paint, cairo_fill, cairo_stroke, cairo_show_text,
cairo_show_glyphs), is an operator which allows the user to set the
shape directly.

Since the shape operand to the rendering equation is a pattern, (as is
source), I propose a new drawing operator that allows the user to
invoke the rendering equation with an explicit pattern for the shape:

	/* Paint using the provided pattern as a masking shape. */
	void
	cairo_mask (cairo_t *cr, cairo_pattern_t *pattern);

It will probably make sense to also add convenience functions for
masking with a surface, (to parallel the existing function for setting
source from a surface):

	/* Paint using the provided surface as a masking shape. */
	void
	cairo_mask_surface (cairo_t *cr, cairo_surface_t *surface);

And, it likely makes sense to also provide an easy way to get a
constant alpha mask for the common operation of blending a surface,
(eg. for fade in/out):

	/* Paint using the provided surface as a masking shape. */
	void
	cairo_mask_alpha (cairo_t *cr, double alpha);

-Carl
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
Url : http://lists.freedesktop.org/archives/cairo/attachments/20050215/d4fd46d9/attachment.pgp