[cairo] API Shakeup: cairo_begin_group, cairo_end_group,
cairo_get_group
Carl Worth
cworth at cworth.org
Tue Feb 15 19:41:59 PST 2005
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
More information about the cairo
mailing list