[cairo] API Shakeup: cairo_begin_group, cairo_end_group, cairo_get_group

[Owen Taylor]

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