[cairo] cairo_win32_surface_create api change

[Carl Worth]

On Mon, 5 Dec 2005 12:14:46 -0800, Stuart Parmenter wrote:
> Here's another patch that adds a 2nd api and will keep the old api
> around but have it call the new one if it can.  It attempts to get the
> width and height from the clip box of the HDC and will use that unless
> it fails to get it or the clip box is a null region.

That certainly looks a lot cleaner to me. Not breaking the API is
important.

Now, at the risk of exposing a lot of ignorance on my part, but in
light of the fact that the debate has stalled, I'll continue:

It's still not obvious to me how broken cairo_win32_create is. Under
what circumstances does the HDC clip box not give the correct size for
the surface? I can imagine that if we're in the middle of something
like an expose event, the HDC clip box might be some small subset of
the full surface, but in this case, it seems we'd then want the
generated surface to also be that smaller size [*].

I can see that capturing this size up front is important, particularly
as some operations within cairo itself change the clip box, so that
looks like a good bug fix in the current patch.

But is it just that we're afraid that the user might be doing
something weird with the clip box? In that case, instead of
"deprecating" cairo_win32_surface_create, might it make sense to
simply document the dependence on the hdc clip box and then say
something to the effect that if you're doing something weird with the
clip box then you should use cairo_win32_surface_create_with_size
instead?

-Carl

PS. The documentation for cairo_win32_surface_create should be in
gtk-doc style inside cairo-win32-surface.c. If we do decide to
deprecate the function, (which I'm trying to avoid), we will need to
establish some policy for what to do with deprecated functions. (One
idea I've had is to hide them in cairo-deprecated.h or some such which
would be included by cairo.h, or we could extend that scheme to have
cairo-win32.h include cairo-win32-deprecated.h).

[*] In this case there might still be a remaining bug in that the
offset of the clip box should be passed to
cairo_surface_set_device_offset, but that's just an implementation
bug, not an API issue.
-------------- 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/20051207/e0fa45d2/attachment.pgp