[cairo] API Shakeup: Eliminating cairo_show_surface

[Carl Worth]

Given the latest simplified rendering equation:

	target = source IN shape OP target

and give that source can only be modified by a cairo_set_source
function, we can now turn our attention to how the user sets shape.

I propose that the distinguishing feature of each drawing operator is
the method of selecting shape. For some drawing operators, shape is
computed based on a single parameter, while for other operators, shape
is computed based on some elements of the graphics state. For example:

	cairo_paint (cr);		- Uses infinite shape

	cairo_fill (cr);		- Computes shape by filling path

	cairo_stroke (cr);		- Computes shape by stroking path

	cairo_show_text (cr, text);	- Computes shape for given text

	cairo_show_glyphs (cr, glyphs);	- Computes shape for given glyphs

There is very satisfying consistency here. Each drawing operator
determines how the shape is computed but otherwise behaves
identically.

We have had one function defined for a while which behaves quite
differently: cairo_show_surface. This function did not set shape, but
instead set source, and did so only temporarily. In light of the above
set of consistent operators, I propose eliminating cairo_show_surface.

The actual operation of displaying a surface is still quite simple. It
consists of:

	cairo_set_source_surface (cr, surface);
	cairo_paint (cr);

And if someone wants the behavior of the old cairo_show_surface, they
can wrap those two calls in cairo_save/restore. But I don't think we
want a convenience function for that sequence of four calls since the
result is a drawing operator which acts nothing like any of the
others.

-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/20050216/6f969eda/attachment.pgp