[cairo] API Shakeup: cairo_create and eliminating cairo_set_target_surface

[Carl Worth]

As we work through the rendering equation, we've just seen proposals
for how to handle source and shape. Now, this is a proposal for
dealing with target.

As discussed in earlier threads, the cairo_set_target_surface function
is poorly defined, and there are conflicting use cases for it. Since
this switches the target device, it would seem it must reset the CTM,
etc. However, one way in which we have used this function in existing
demos is for temporarily drawing to an intermediate surface, (for
grouping), and in this case the user does not want the CTM to change.

The second use case should now be handled well with the new
cairo_begin/end_group functions.

So, now we're left with the idea of resetting the CTM when changing
the target surface. I don't really like the idea of a function that
has such drastic side effects, (eg. the CTM should only change when
the user calls functions which have as their primary purpose to change
the CTM).

Another problem with re-targeting is the question of whether the
target surface is saved/restored.

To address these issues, I propose to change the API so that a single
cairo_t context cannot be re-targeted. Instead, the association of a
target surface must take place at the time of cairo_create:

	/* Create a new cairo context, targeting the given surface. */
	cairo_t *
	cairo_create (cairo_surface_t *target);

We previously had various convenience functions for backend-specific
versions of set_target. We can continue to provide similar convenience
functions as alternate constructors for the cairo_t context:

	/* Create a new cairo context, targeting an image. */
	cairo_t *
	cairo_create_for_image (cairo_format_t  format,
	                        int             width,
	                        int             height);

	/* Create a new cairo context, targeting the given image data. */
	cairo_t *
	cairo_create_for_image_data (char            *data,
	                             cairo_format_t  format,
	                             int             width,
	                             int             height,
	                             int             stride);

	/* Create a new cairo context, targeting the given Xlib	drawable */
	cairo_t *
	cairo_create_for_xlib (Display  *dpy,
	                       Drawable drawable,
                               int      width,
                               int      height,
	                       Visual   *visual,
	                       Colormap colormap);

	/* etc. */

Then, cairo_set_target_surface will be eliminated, and
cairo_current_target_surface will be renamed as cairo_get_target.

-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/553656c8/attachment.pgp