[cairo] Cleaning up the PDF API

[Carl Worth]

On Mon, 16 May 2005 11:41:13 -0400, Kristian Høgsberg wrote:
> On Thu, 2005-05-12 at 15:50 -0700, Carl Worth wrote:
> > The interface in cairo-pdf.h needs a little bit of cleaning up. Some
> > of this we've discussed before. Here are the issues I see:
> > 
> > 1) cairo_pdf_surface_create should accept a "const char *filename"
> >    rather than a FILE*.
> 
> This change is still missing, I'll do that now.

Great. And thanks for taking care of the other issues.

I have one small comment one the new function:

	void
	cairo_pdf_surface_set_ppi (cairo_surface_t      *surface,
	                           double               x_ppi,
	                           double               y_ppi);

I think I was the one to come up with the name "pixels_per_inch" when
I conceived of it as a parameter for all surface types. But, now that
we're dealing with something that is specific to "print" backends, and
now that we're abbreviating it, I think we should use the standard
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);

> 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?

-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/20050516/029fed87/attachment.pgp