[cairo] [API] cairo_surface_create_similar_image() + mime-surface

[Paolo Bonzini]

>  cairo_surface_t *
>  cairo_mime_surface_create (const char *mime_type,
>  			   cairo_mime_format_func_t mime_format_func,
>  			   cairo_mime_decode_func_t mime_decode_func);
>  which is passed a function to lazily set the format (or NULL) and a
>  function to lazily decode the image data (or NULL if you really want
>  to  ;) .

... and what is cairo_mime_format_func_t?

>  3. Decode:
>  typedef cairo_status_t
>  (*cairo_mime_decode_func_t) (cairo_surface_t *mime_surface,
>  			     cairo_surface_t *image,
>  			     cairo_rectangle_t *roi);
>  
>  If we need the pixel data (i.e. the mime-type is not supported by the
>  target backend) then we obviously need to decode the data. The image is
>  created for the target surface using
>  cairo_surface_create_similar_image() and the decoder must at least fill
>  the Region-Of-Interest (and update roi with the region actually filled).
>  [This currently is unused, but added for when acquire_source_image()
>  gains roi support.]

It could also be possible for the mime_decode_func to set a roi smaller
than the requested region.  acquire_source_image would use transparent
for anything outside the returned roi.  When more data arrives from the
network, the application can force a repaint, acquire_source_image is
then called again (if needed) and the mime_decode_func is called with
the roi corresponding to not-yet-decoded data.  Not sure if it is needed
to add a new status code like CAIRO_INCOMPLETE_DATA (probably yes) and
how much it would screw up existing clients (probably not much, since
only mime_surface-aware clients would be affected, and this is a new API).

Paolo