[cairo] API Shakeup: cairo_surface_finish, cairo_surface_flush, cairo_finish, cairo_flush

[Carl Worth]

Kristian has already proposed the cairo_surface_set_user_data as a
means for associating external data with a surface along with a
destroy notifier, (called when the last reference to the surface is
dropped).

What is still missing is a way to instruct cairo to finish up all
activity related to a surface, (eg. write a PDF trailer), so that the
user can close/free external resources associated with that surface
(eg. a FILE*), with deterministic timing.

The proposal we came up with to address this is:

	void
	cairo_surface_finish (cairo_surface_t *surface);

A related need is the ability to instruct cairo to flush any pending
drawing operations to the surface:

	void
	cairo_surface_flush (cairo_surface_t *surface);

We had talked about adding convenience functions on the cairo_t* for
the target surface, (cairo_finish? cairo_flush?), but I'm now
disinclined to add them. Now that we have well-defined semantics for
non-referencing getters, these operations are quite trivial for the
user to call directly:

	cairo_surface_flush (cairo_get_target (cr));

And I think adding a convenience function for something so easy does
more harm than good, (it adds API, which means more for the user to
learn).

I'm now tempted to go through the API looking for similarly gratuitous
convenience functions that should be removed.

-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/20050222/8fed7f97/attachment.pgp