[cairo] API Shakeup: cairo_begin_group, cairo_end_group, cairo_get_group

[Carl Worth]

On Thu, 16 Jun 2005 14:35:09 -0700, Bill Spitzak wrote:
> 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.

Here, the format is intended to specify one of three different modes
for what the pattern will store:

	Color only
	Alpha only
	Color and alpha

The existing cairo_format_t is not the right way to specify this
information as it is overspecific, (describing bits per channel and
channel order as well).

There's an outstanding TODO item regarding splitting uses of
cairo_format_t into two separate things specifying either bit-layout
or surface capability.

There are still some unanswered questions about how that should work,
(see cairo/TODO), but cairo_begin_pattern certainly places more
emphasis on the need to answer them.

> > 	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 isn't a mask in the graphics state to send it to.

Instead, the mask, (or "shape" which is the general term we decided to
use), is always an explicit or implicit parameter to one of cairo's
drawing operations. The drawing operation with an explicit pattern for
the shape is cairo_mask which can be used with cairo_end_pattern as follows:

	pattern = cairo_end_pattern (cr);
	cairo_mask (cr, pattern);
	cairo_pattern_destroy (pattern);

It would be possible to add a convenience function for this, but I'm
hesitant to for the following reasons:

1) I don't know what to name it. cairo_end_pattern_to_mask is wrong
   since this behaves so much differently than
   cairo_end_pattern_to_source.

2) It just feels wrong.

   This might be because I'd like to limit the number of drawing
   operations provided to the user to make things easier to
   understand. Right now we have the following 7 operations:

	cairo_fill
	cairo_stroke
	cairo_paint
	cairo_paint_with_alpha
	cairo_mask
	cairo_show_glyphs
	cairo_show_text

   But it's not just that, since cairo_paint_with_alpha is also a
   convenience function, so the same logic would argue for its removal
   but I don't want to do that.

   No, I think what I object to is that this new convenience function,
   (cairo_end_pattern_<whatever>), would be performing drawing as a
   side effect. That seems wrong for a graphics library such as cairo
   where drawing operations should be primary.

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

That sounds like a pretty good way to set the default size.

> I would think this would not be impractical to implement.

No, it wouldn't. And now that I've looked over Kristian's meta-surface
stuff, I think I'll go back and try doing cairo_begin_pattern with
that instead.

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

Using a rectangle seems reasonable. So we could have a rectangle in
pattern space. 	There's still the somewhat unresolved question of the
timing for locking the pattern-space/user-space transform, (see
cairo/test/source-surface-scale-paint), so this will give us a bit
more motivation to resolve that.

-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/20050623/1f2dfa1e/attachment.pgp