[cairo] API Shakeup: cairo_begin_group, cairo_end_group,
cairo_get_group
Owen Taylor
otaylor at redhat.com
Thu Feb 17 06:42:21 PST 2005
Bill Spitzak wrote:
> This may be crazy, but perhaps it should automatically set the source.
> Common usage would then be this:
>
> cairo_begin_source(cr);
> .. draw stuff here ..
> cairo_end(cr);
> cairo_paint(cr);
>
> The cairo_end() would actually change the source in the gstate. Between
> the begin/end the previous source would be in effect. (I also agree with
> some other posters that the word "create" is not needed, and that having
> the begin return void would make it impossible to access the surface
> until after it is done).
>
> For the mask it would be cairo_begin_mask(). (this is why the function
> is cairo_end() and not cairo_end_source(), because I wanted to enforce
> nesting of these). It may then know that only alpha needs to be stored,
> which seemed to be your reason for making a version that takes a format
> argument.
We had this idea, and were very happy with it for a short while. But
you can't do the same thing to get a mask because the shape isn't a
gstate element; rather it is consistently determined by the parameter
to the drawing operators. We considered various possibilities for
stashing a mask somewhere in the gstate, and having it only affect
cairo_mask(), but didn't like that much.
It also is useful in some cases to save a group and use it repeatedly
(a background element on multiple pages of a PDF document, say.)
So, in either of these cases, you have to save/restore to save
the current source, extract out the pattern from the source,
reference it, *then* destroy it once you you've used it somewhere
else. Which is decidely ugly.
What we could do to get almost the same convenience is to add:
void cairo_end_group_to_source (cairo_t *cr)
{
cairo_pattern_t *pattern = cairo_end_group (cr);
cairo_set_source (cr, pattern);
cairo_pattern_destroy (cr);
}
[ No, that isn't missing error checking ... we decided to
consistently return a magic singleton pattern on out of memory ]
Regards,
Owen
More information about the cairo
mailing list