[cairo] API Shakeup: cairo_begin_group, cairo_end_group, cairo_get_group

[Bill Spitzak]

Carl Worth wrote:

> 	void
> 	cairo_begin_pattern (cairo_t *cr);
> 
> 	void
> 	cairo_begin_pattern_with_format (cairo_t *cr, cairo_format_t format);

Is the purpose of the format so that you can choose whether alpha is 
stored or not? From a user's point of view it would help a lot if 
drawing an opaque rectangular image in the default format resulted in 
equal speed and efficiency as doing this.

> 	cairo_pattern_t *
> 	cairo_end_pattern (cairo_t *cr);
> 
> 	void
> 	cairo_end_pattern_to_source (cairo_t *cr);

Should there also be a method to send it to the mask?

> There reason I changed from "group" to "pattern" is that we are
> returning a cairo_pattern_t. Using the name "pattern" in the function
> names avoids the user having to learn an additional concept.

I like the name "pattern" much better. Even for your use #1. Also the 
term "group" is often used by higher-level scene graph api's and it 
might be best to avoid it here.

> Then, there's an interesting problem that shows up here. For all of
> the uses, but most particularly for (1) it's very convenient that the
> API does not require the user to provide a size for the intermediate
> surface, (since conceptually the user doesn't even have to be aware
> that any intermediate surface is present). (And I should mention that
> the current patch does the simplest and least efficient thing by just
> creating an intermediate surface that is the same size as the target).

 From the users point of view, the ideal api is that the pattern's size 
is the bounding box of all drawing done to it. This should include stuff 
drawn at negative coordiates or otherwise outside the target surface, 
otherwise the pattern cannot really be used for repeated fills or reused 
on other surfaces or transformations. A clear with no clip region should 
reset it back to the intial state of 0x0.

I would think this would not be impractical to implement. A program 
wanting maximum speed could first draw a rectangle of the size they want 
to avoid reallocations. There would be no problem with a silent clip to 
about 2K (for a present-day screen).

> 	void
> 	cairo_pattern_set_repeat_size (cairo_pattern_t *pattern,
> 				       double width, double height);

Actually I would like to repeat an arbitrary rectangle, not just a 
width+height. This rectangle should be allowed to go outside the area of 
memory used by the pattern, that area would be filled in the same way a 
non-repeating pattern fills area outside itself.