[cairo] Cleaning up the PDF API

[Kristian Høgsberg]

On Mon, 2005-05-16 at 09:05 -0700, Carl Worth wrote:
...

> term of DPI. So I suggest the following function instead:
> 
> 	void
> 	cairo_pdf_surface_set_dpi (cairo_surface_t      *surface,
> 	                           double               x_dpi,
> 	                           double               y_dpi);

OK.

> > No, this is different.  The cairo_destroy_func_t passed in here is
> > called when cairo_surface_finish() is called on the surface.  It's
> > responsible for e.g. flushing out any buffers and fclose()'ing FILE's at
> > the time we know that no more output will be going to the stream.  The
> > actual destruction of the surface may occur much later (because of e.g.
> > garbage collection taking place at a later time).
> 
> So currently we have a two-stage destruction process for stream-based
> PDF surfaces that the user has to understand. As a surface goes from
> active to destroy it passes through two transitions:
> 
> active -> finished
> 	Call destroy notifier set in cairo_pdf_surface_create_for_stream
> finished -> destroyed
> 	Call destroy notifier set in cairo_set_user_data
> 
> The question I have is why the distinction between these two stages
> would be useful to the user? (eg. to the point where callbacks are
> needed for each stage separately). And if it is useful, then why don't
> other surface types also need a similar distinction?

We do have this two phases destruction on all surfaces.  It's just that
in the stream based case, the underlying resource that we destroy going
from active to finished is user supplied and we don't know how to
destroy it - thus the callback.  For the image backend, we know how to
free the data, for the file based pdf backend, we know how to close the
file.  However, if the user provides us with some opaque void pointer,
we have to ask the user to destroy that for us.

cheers,
Kristian