[cairo] Cleaning up the PDF API

[Owen Taylor]

On Mon, 2005-05-16 at 16:54 -0700, Carl Worth wrote:
> On Mon, 16 May 2005 19:23:42 -0400, Owen Taylor wrote:
> > The destroy function is there principally for language bindings. 
> 
> That sets off a red flag for me. The cairo_pdf_surface_create_for_stream 
> function is also there for users, (and even fairly trivial programs
> might have to use it instead of cairo_pdf_surface_create---think
> support for "-" to mean "write to stdout).
> 
> 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.

> > For, the language binding implementing:
> >  
> >  createFromPDF (InputStream stream)
> > 
> > suggested in the language binding appendix, say.
> > 
> > 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?

Well, part of it is plain old memory management. Yes, you can
do that with user data, but since the stream is *done* at finish
time, it's a bit more natural to close it then.

And as I mentioned in:

 http://cairographics.org/manual/bindings-streams.html
 
I think it makes sense for language bindings to implement the
filename version using the stream API, so they get native IO
errors.

> > Not only that, there is no conceptual reason that the language binding
> > couldn't hand off the object they created to some C code that
> > actually calls finish().
> 
> Would we perhaps want some other way to register a finish-time
> callback in addition to a destroy-time callback? I don't know, but at
> least that would be an API addition, so a decision much easier to make
> after we gain more experience.

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.

Regards,
						Owen

-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
Url : http://lists.freedesktop.org/archives/cairo/attachments/20050516/68e19acc/attachment.pgp