[cairo] Cleaning up the PDF API

[Carl Worth]

> > On Mon, 16 May 2005 19:23:42 -0400, Owen Taylor wrote:
> > 
> > I'd prefer it if functionality intended uniquely for language binding
> > authors could be done in separate functions.
> 
> Pass NULL if you don't want the destroy function.

Yeah, yeah. Obviously not the same in terms of how much the user has
to figure out to be able to get to this.

> > > It's quite awkward if the language binding author has to insert code
> > > into the binding for cairo_surface_finish() that checks to see if 
> > > the surface is a PDF surface they created, and if so, frees the
> > > InputStream.
> > 
> > But why would the language binding author ever do that? If the user is
> > creating the InputStream to pass into createFromPDF, shouldn't the
> > user being doing any flush, close, free operations needed on that
> > stream?
>  
> I think it makes sense for language bindings to implement the
> filename version using the stream API, so they get native IO
> errors.

That seems like a perfectly legitimate thing for a binding author to
do. But that's also a very straightforward situation. If the binding
author opens a file in cairo_pdf_surface_create, then obviously, the
author also needs to close it. Doing so in cairo_surface_finish is
very straightforward. The interaction between cairo functions that the
binding author has to understand is not complex. The extra data needed
can be stored in user_data or in some binding-specific wrapper. AND,
this case doesn't even show up in a more strict one-to-one binding
approach that you also advocated.

> It doesn't seem particularly useful to me for the image data, or 
> native surface constructors. Just the stream case. And for the 
> stream case,  "I'm done, you can close the stream" is a very natural
> part of what a stream is.

Maybe I'm still missing something, but I still don't get it.

When we first added a FILE* interface for PDF (or PS) surfaces, people
rightly complained that there was no way to know when it was safe to
flush and close the file. So we added cairo_surface_finish to allow
the user to explicitly force that condition, (eg. "Be done, so I can
close the stream".).

With that in place, the surface is only finished on an explicit user
action, (cairo_surface_finish), or asynchronously when the surface is
destroyed, (for which we already have user_data callbacks). The
argument above makes it sound like the user can't know when the
surface is going to be finished, which just isn't the case. (Or if it
were, perhaps we could just use always use this callback and drop the
cairo_surface_finish call --- not that I would actually prefer that
approach).

-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/47dc8db1/attachment.pgp