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

[Carl Worth]

Given the latest form of the simplified rendering equation:

	target = source IN shape OP target

When I introduced this form of the equation, I failed to explain that
both "source" and "shape" are patterns, while target is a
surface. With this understanding, I propose that the most fundamental
way to set the source should be:

	/* Set the source to the given pattern. */
	void
	cairo_set_source (cairo_t *cr, cairo_pattern_t *pattern)

This function would replace cairo_set_pattern which we have today.

Then, on top of this function, we could have several convenience
functions for setting the source from higher-level objects than
patterns. I propose that these functions should all share "set_source"
in their naming for improved clarity:

	/* Set the source by creating a pattern from the given surface. */
	void
	cairo_set_source_surface (cairo_t *cr, cairo_surface_t *surface);

	/* Set the source to be an opaque color everywhere. */
	void
	cairo_set_source_rgb (cairo_t *cr, double r, double g, double b);

	/* 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);

	/* Set the source to a pre-multiplied translucent color. */
	void
	cairo_set_source_rgba_premultiplied (cairo_t *cr,
					     double r, double g, double b,
					     double alpha);

This change renames set_rgb_color to set_source_rgb. The rationale for
this is to make it more clear to the user that setting a color really
involves modifying the source pattern, and not lodging a color into
the graphics state. This should avoid confusion about "where did my
color go" after calling something like cairo_set_source_surface. The
consistent use of cairo_set_surface should make this quite clear.

This change also removes the separate cairo_set_alpha function which
made similar confusion, (even among cairo developers and the
implementation itself), about whether it was modifying the source
pattern or whether it was a parameter within the graphics state. The
rendering equation does not allow a separate "alpha" parameter in the
graphics state, so the idea of specifying an alpha value really is
just part of the convenience function for creating a single-color
source pattern.

These two changes mean that the functions cairo_current_rgb_color and
cairo_current_alpha should also be eliminated. There are no such
parameters in the graphics state, so they can not be queried. (But
note that the source pattern will still be available via
cairo_get_source, so the "current color" can still be saved and reused
if necessary).

Finally, since this proposal now provides a functions to specify color
and alpha simultaneously, it was necessary to deal with the question
of pre-multiplied vs. non-pre-multiplied color representations. We
compromised by allowing both, while giving the non-premultiplied
version the shorter name. Allowing pre-multiplied colors does allow
the user to supply super-luminescent colors, (where color components
have values greater than alpha), which can be interesting.

-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/20050215/21a788f1/attachment.pgp