[cairo] Separating Cairo from stdio.h

[Carl Worth]

On Mon, 1 Nov 2004 09:58:06 -0800, Ned Konz wrote:
> The routines cairo_ps_surface_create() and cairo_png_surface_create() (and 
> their corresponding set_target routines) assume that FILEs exist. However, I 
> can see using these in systems without stdio.h or using them to create 
> Postscript or PNG data in memory buffers or into a socket stream (perhaps in 
> systems where you can't make FILEs out of socket handles).

I appreciate you keeping us honest here. I did hesitate a bit before
adding that stdio dependence to the public header, and I've been
expecting a message like this eventually.

[I'll merge in a reply to Keith's reply here as well.]

On Mon, 01 Nov 2004 12:11:52 -0800, Keith Packard wrote:
KP> However, I would prefer to avoid creating a new file abstraction unless 
KP> there are significant platforms for which the standard C library cannot be 
KP> used.

I agree with this. I'd like to build on existing abstractions whenever
possible. And stdio does seem fairly reasonable--allowing portability
better than a raw file handle in many situations. But do let us know if
we were wrong on that point for the PS backend.

KP> > In cairo_png_surface.c I see that the file is just being passed to libpng, 
KP> > which lets its users use other I/O routines at runtime using 
KP> > png_set_???_fn(), and also lets you compile libpng using the PNG_NO_STDIO 
KP> > define and just create PNG structures in buffers.
KP> 
KP> In this case, exposing the functionality of the PNG library does seem like 
KP> a reasonable request.  If there is an abstract PNG object which can 
KP> represent the stream, we could create a lower-level cairo API that plugged 
KP> in there instead of at the FILE level.

Ah, indeed we did fail to take advantage of this in libpng. So, we could
make a new cairo_png_surface_create function accepting an initialized
png_struct*. That would allow the user access to the IO and
error-handling capabilities in libpng.

KP> Naming, as always, would probably be the hardest part of this
KP> particular change.

Indeed.

> And then rename the existing cairo_png_surface_create() as:
> 
> cairo_surface_t *cairo_png_surface_create_for_file(FILE* file, cairo_format_t
> format, int width, int height);
> 
> Or if there are lots of users of cairo_png_surface_create() etc. then we could 
> just make up new names.

I'm not *too* concerned about changing the names at this point. I've
already got a bunch of other changes planned (many noted in cairo.h
already). One of the things already on my list for this week is to come
up with a Great Renaming Proposal for cairo in preparation for a 1.0
release next spring.

I think the above name for the current function seems reasonable, and
then the new function could use the current name:

	cairo_surface_t *
	cairo_png_surface_create (png_struct *png, cairo_format_t format,
				  int width, int height);

The we could rename the current cairo_set_target_png to
cairo_set_target_png_file and put in a new cairo_set_target_png.

That naming isn't perfect since set_target_png_file would be a
convenience function for set_target_png, and so far we've managed to
always give the convenience functions shorter names. I suppose we could
switch things around, dropping "for_file" and adding "for_png_struct" or
"for_libpng" or something. Naming is a pain. Feedback is welcome.

Oh, and libpng does have a separate png_info* but I think the cairo PNG
backend should create that itself to reduce confusion about which
libpng initialization calls the user is responsible for.

-Carl