[cairo] API Shakeup: cairo_begin_group, cairo_end_group, cairo_get_group

[Bill Spitzak]

Carl Worth wrote:

> 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.

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.

Programs that want something non-temporary would do:

	...
	cairo_end(cr);
	pattern = cairo_get_source(cr);