[cairo] API Shakeup: cairo_begin_group, cairo_end_group, cairo_get_group

[Carl Worth]

Once the new cairo_paint operator is in place, we have a simple
proposal for allowing the user to temporarily redirect drawing
operations to a group, (similar to the concept of a group in SVG or
PDF). This makes many operations simple which would otherwise require
creating a temporary surface, drawing to it, using it as the source in
painting to the original surface, and then destroying the intermediate
surface.

This kind of idea has been proposed in the past, and I think we've got
a better plan than anything we've had before. The anticipated common
usage model is:

	cairo_begin_group (cr);
	/* Draw to the group */
	cairo_end_group (cr);

	cairo_set_source (cr, cairo_get_group (cr));
	cairo_paint (cr);

Though we have also planned the API so that using a group as a mask
will be about as easy.

Groups can be nested arbitrarily.

The initial implementation for this support will likely be an
intermediate surface that starts off at the size of the bounds of the
first drawing operation and grows by doubling as needed. A later
implementation is expected to use meta surfaces so that groups are
completely vectorial, rather than suffering from early rasterization.

Here is the proposed API:

	/* Begin rendering to a new group. While rendering to a group,
	   drawing operations are applied to the group, not the target
	   surface. A group is conceptually a new surface, (supporting
	   color and alpha), with the same device-space origin as the
	   target surface. Within the group, there are no implicit
	   changes to the graphics state, (eg. the same CTM is in
	   effect).

	   cairo_begin_group calls cairo_save so that any changes to
	   the graphics state made within the group will not be
	   visible outside of the group.
	*/

	void
	cairo_begin_group (cairo_t *cr);

	/* Like cairo_begin_group, but with the ability to express the
	   format of the group. This is particularly useful when using
	   a group to construct an alpha mask, which can be done more
	   efficiently by using an alpha-only format.
	*/

	void
	cairo_begin_group_with_format (cairo_t *cr, cairo_format_t format);

	/* Signal to cairo the end of drawing operations for a group.

	   cairo_end_group calls cairo_restore so that any changes to
	   the graphics state made within the group will not be
	   visible outside of the group.

	   After calling cairo_end_group, the contents drawn to the
	   group are available by calling cairo_get_group.
	*/

	void
	cairo_end_group (cairo_t *cr);

	/* Get the most recently completed group. */

	cairo_pattern_t *
	cairo_get_group (cairo_t *cr);

-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/a4324cda/attachment.pgp