[cairo] Pixel RGB Values...

[Carl Worth]

On Thu, 2009-07-09 at 12:07 +0100, Chris Wilson wrote:

> The first is a convenient method for direct access (prototyped in
> cairo-drm, and used to good effect):
> 
>   cairo_surface_t *
>   cairo_surface_map (cairo_surface_t *surface);
> 
>   void
>   cairo_surface_unmap (cairo_surface_t *surface,
>                        cairo_surface_t *image);

I do like the short name, but I'm a little bit concerned that the map
function returns a new *image* surface without ever mentioning the word
"image" in its function name. That's something I think we've avoided
doing elsewhere, (note that all the various surface_create functions
explicitly mention which sub-type of image they are creating).

"map_image" perhaps?

> In use, mapping a surface returns an image surface that you can use to
> manipulate pixels directly, and unmapping ensures that the changes are
> flushed to the backing surface. Internally this works just like
> acquire_dest_image()/release_dest_image() but with the extra caveat that
> the surface is exported and so we need to redirect rendering whilst the
> map is in effect. I like map/unmap (as used by pixel buffer objects in
> OpenGL), but alternative names used elsewhere include lock/unlock.
> (lock/unlock imply to me that any rendering to the original surface is
> disabled - a side-effect I don't like, but may be cause less confusion
> in the long run.)

If you don't disable rendering to the surface, then I'm not sure I
completely understand the semantics of your proposed map. You are saying
that rendering that I perform via cairo will be redirected to the mapped
image surface, but that changes I make via direct pixel access won't be
reflected to the underlying surface until the time of unmap? Is that it?

And maybe that's what we really want, but it seems oddly asymmetrix to
me.

> The second method I think we need is for efficient pixel upload. Already
> win32 has such a scheme, but it is of general use. My proposal here is:
> 
>   cairo_surface_t *
>   cairo_surface_create_similar_image (cairo_surface_t *target,
>                                       cairo_content_t content,
>                                       int width, int height);

We got really stuck on API the last time this idea came up, but the
above proposal looks great to me. It uses "similar" in a similar way as
the existing create_similar, (which is that "similar" means to do
something in a way that's as efficient as possible for the given
backend).

Like the existing create_similar, it uses an actual instance of a
surface rather than just naming the backend of interest, and that might
be annoying in some cases. For example, porting code that uses the
current cairo_quartz_image_surface_create to this new API might require
creating a dummy quartz surface here.

But we've already got a precedent for requiring such dummy surfaces in
the case of font metrics, for example. And for font metrics, the "dummy"
surface can actually hold necessary information, (such as antialiasing
mode). And perhaps here as well, being able to access the surface's
format/depth/etc. might also be important.

> That returns an image that has appropriate backing storage to enable
> efficient upload to the target surface. (This is the best name I've come
> up with since the last time this proposal stumbled due to not finding a
> good name... ;-) The tricky issue here is whether it should take a
> content or a format. When uploading pixel data you really want to avoid
> format conversion if possible, so maybe:
> 
>    typedef pixman_format_code_t cairo_wacky_format_t
>    cairo_surface_t *
>    cairo_surface_create_similar_image (cairo_surface_t *target,
>                                        cairo_wacky_format_t format,
>                                        int width, height);

I would imagine that this should accept a cairo_format_t first, and then
have a named-variation of the function to accept the extended format.
(Then we could use the same naming extension for
cairo_image_surface_create if that makes sense.)

That is, I think adding cairo_extended_format_t should be wholly
orthogonal to adding cairo_surface_create_similar_image.

-Carl

-------------- 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.cairographics.org/archives/cairo/attachments/20090722/8669fbf2/attachment.pgp