[cairo] get_image() / set_image() virtual functions

[Owen Taylor]

[ Summary of a conversation from #cairo, between myself, Carl, and 
  Kristian ]

Currently, cairo_surface_backend_t has:

    cairo_image_surface_t *
    (*get_image)                (void                   *surface);

    cairo_status_t
    (*set_image)                (void                   *surface,
                                 cairo_image_surface_t  *image);

This is used in two places:

 1) To implement fallbacks in cairo_surface.c.

 2) In _cairo_pattern_get_image(), a helper function for
    surface.create_pattern() used by glitz and the image 
    backend.

    I think this usage broken, and it should be something 
    like _cairo_pattern_get_surface() and possibly return
    a native surface.

There's also a potential use case ... to implement a generic PNG writer
function.

For the fallback case, the above has a couple of problems.

 - It gets the *entire* surface

 - It always returns a cairo_image_surface_t. A backend might
   already have a pixman_image_t (the win32 backend wraps
   DIB's in pixman_image_t), and not want to create another
   cairo_image_surface_t.

I think the above might be replaced with something more along the lines
of what I have in the Win32 backend.

static cairo_status_t
_clone_subimage (cairo_win32_surface_t  *surface,
                 cairo_rectangle_t      *rect,
                 cairo_win32_surface_t **subimage_out);

static cairo_status_t
_end_subimage (cairo_win32_surface_t  *surface,
                cairo_rectangle_t      *rect,
                cairo_win32_surface_t  *subimage)

The rect argument in the _clone_subimage is in/out ... on in it is the
area that the calling code is interested in, on return it is the actual
area of the returned surface (As I have it, always smaller than the
requested area, since the backend checks for clipping. though making it
potentially bigger might be useful in other cases.)
_clone_subimage() can store NULL in subimage_out

The end_subimage takes the surface/rect returned from _clone_subimage()
puts it back, and frees the subimage. The two functins have to be called
paired ... a difference from get_image() which is used sometimes paired,
and sometimes not. 

You'd probably want slightly different naming. Maybe something like
begin_image_fallback()/end_image_fallback().

To avoid having to return cairo_image_surface_t, we could add another
virtual function to the surface interface: get_pixman_image() 
to return a pixman_image_t. That would be useful in a number of places
where we to identify surfaces that can be used "like" an image
surface, without having to actually *be* an image surface.

The PNG writer use case seems distinct ... probably we should have a
separate get_image() for that. That sort of get_image() needs to be able
to fail if the surface can't be gotten as an image (for instance if it's
a PDF surface.)

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/20050121/d4156b79/attachment.pgp