[cairo] API shakeup: png function names

[Kristian Høgsberg]

Owen Taylor wrote:
> On Mon, 2005-04-04 at 11:07 -0700, Bill Spitzak wrote:
> 
>>How about "cairo_image_surface_create_from_png" (replace "for" with 
>>"from")? I'm also wondering why the word "image" is in there, since this 
>>returns a surface, and I don't see how it could return any other type of 
>>surface than an "image" one. How about shortening it to 
>>"cairo_surface_create_from_png"?
> 
> 
> Subclasses of CairoSurface can have specific operations on them, 
> like cairo_xlib_surface_set_size().  
> 
> cairo_image_surface_create_for_png() is thus a constructor for 
> CairoImageSurface... currently constructors for <foo> are
> foo_<create>_<blah>.
> 
> Related to that, I'd like to see the *width, *height out parameters
> vanish from the signature, to be replaced with getters on
> cairo_surface() or cairo_image_surface() (*). Some surfaces don't
> necessarily have a size ... that's why it *might* belong to 
> cairo_image_surface(). 

I'd prefer that too, those getters would be useful in other situations.

> On the other hand, many surfaces do have a size, so putting them on
> CairoSurface and returning -1 to mean "unknown" might be simpler.
> 
> Regards,
> 						Owen
> 
> (*) Why? Multiple return values don't bind well in all languages,
>     and they make the function signature less obvious and harder
>     to remember.
> 
> P.S. - _from_png() would also be considerably more natural to me 
>        as well.

And to me as well, that's what I had in my original proposal, with this 
explanation:

"The other surface constructors all reference and use the passed in 
resources throughout the lifetime (actually from creation to finish) of 
the surface.  In this case the png file is only used for initializing 
the contents of the surface.  When the constructor returns, file can be 
closed immediately.  I think 'from' implies this fairly well."

but Carl preferred "for" for consistency:

"Should this be "for_png" instead of "from_png". They seem close enough
to be arbitrary to me, and if they are, I'm sure to always get them
wrong."

cheers,
Kristian