[cairo] API Shakeup: Making set_source consistent, (renaming cairo_set_rgb_color and cairo_set_pattern, eliminating cairo_set_alpha)

[Carl Worth]

On Tue, 15 Feb 2005 19:01:04 -0500, Carl Worth wrote:
> 	/* Set the source to be a translucent color everywhere. */
> 	void
> 	cairo_set_source_rgba (cairo_t *cr,
> 			       double r, double g, double b,
> 			       double alpha);

I went to implement this thinking it would be primarily just a name
change. But, doing it right means eliminating cairo_set_alpha as well
as cairo_get_rgb_color, and I wondered if that might cause any
problems. (For example, it would no longer be possible to change to a
translucent version of the current color without already knowing what
that color was).

So, I did a little survey of calls to cairo_set_alpha in all the C
programs on my hard drive. I found several hundred calls to
cairo_set_alpha, and in something like 98% of the cases,
cairo_set_alpha was called immediately before or after
cairo_set_rgb_color. So all that code will be trivial to port to the
new cairo_set_source_rgba.

What of the other uses? That's where the interesting stuff is.

I found about 10 calls to cairo_set_alpha just before a call to
cairo_show_surface. So those can be replaced by the new
cairo_paint_alpha.

There were 2 or 3 calls to cairo_set_alpha before calling into a
function that did a bunch of drawing, (eg. drawing an SVG image). This
is an interesting case, because the code is broken in general. The
intent was to draw the SVG image (for example) with some additional
translucence. But using cairo_set_alpha for this only works if the
drawing code never called cairo_set_alpha itself. So, this code really
needs to use a temporary surface, which the new cairo_begin_group code
will make much easier.

Finally, I found 2 calls that did something similar to what I was
originally worried about, changing to a translucent version of the
current color. Interestingly enough, in both cases the same function
had previously set and drawn with the opaque version of the color. So,
the color was easily available in the source code, so these uses
should also be trivial to port.

So, porting away from cairo_set_alpha might be interesting in a few
cases, but I think the improved coherence of the rendering model is
worth it.

It's possible that someone still wants to do what I initially
imagined, and such a user will be responsible for hanging on to the
color of interest and passing it around, rather than having a slot in
the cairo graphics state for lodging a "current color".

-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/20050328/4b69eecf/attachment.pgp