[cairo] Integrating the new Pixman - and offer and questions

[David Hill]

Hi all,


I would like to help with the effort to integrate the new pixmap into
Cairo. I have been looking at this for a few days now and I see how much
there is to be done. I think that with some guidance from the list that
some of the more troublesome issues can be handled.

To start the flow of information, let me raise the issue of Cairo
supported depths. Please bear with me as I reiterate facts that most of
you know – I am new here, and this also gives you guys a chance to
correct any poor assumptions I have.


There has been some reluctance in the past to support all the depths
that pixman could support, primarily (I believe) because these depths
were not supported in an optimized manner (though they did work). Now
with the nifty new pixman, we have the promise 35 bit depth formats with
some level of optimization.


The core of Cairo supports/exposes a few fairly standard depths:


typedef enum _cairo_format {
CAIRO_FORMAT_ARGB32,
CAIRO_FORMAT_RGB24,
CAIRO_FORMAT_A8,
CAIRO_FORMAT_A1
/* The value of 4 is reserved by a deprecated enum value.
* The next format added must have an explicit value of 5.
CAIRO_FORMAT_RGB16_565 = 4,
*/
} cairo_format_t;

Leaving out RGB16 for a moment these make sense because they are
primarily used by the backends to map to known depths in the backends.
And of course – not all backends support even these four formats
properly, and not all platforms are RGB.


To start with, I would argue that there is one format that is missing –
and that is CAIRO_FORMAT_NATIVE. On a number of platforms, particularly
mobile devices, the native, working bit depth is something other than
RGB24. Providing a means of specifying “use whatever works best” for
your non-alpha, RGB surface (which actually could be BGR, but thats a
nit). This would allow for operations on your image with the fewest
depth conversions along the way in the display path. This is especially
true if I am just creating a single surface to scribble on. On most
platforms this might even mean CAIRO_FORMAT_NATIVE == CAIRO_FORMAT_RGB24.


Taking this a step forward – even ARGB32 and RGB24 are perhaps too
restrictive as they might require final conversion on a BGR platform. Do
we want to consider two more values like CAIRO_FORMAT_COLOR, and
CAIRO_FORMAT_COLOR_ALPHA which would be aliases to the backend to map
the format to something logical ?


But where do we need really need to specify the depth and layout of the
surface ? The only case I can think of is with the image backend, and in
this case, where I, the consumer of Cairo have, or want, image data in a
particular format. I want this data in a particular format for any of a
number of reasons, in my case, usually mapping a screen frame buffer
into a cairo surface, but also because I may get a variety of image data
formats from other sources, like reading from a png. With this in mind,
it seems to me that we need yet another cairo_format_t,
CAIRO_FORMAT_CUSTOM (unless we really want to remap all of the pixman
supported formats – ick).


So what would be the normal usage ? I ask the destination backend for a
CAIRO_FORMAT_NATIVE, assuming I just want a page to scribble on without
preserving the alpha channel. If I want to add in other images, or
create masks, I may create a number of image surfaces using data I have,
and pixman does the right thing when blasting those images on top of my
destination.


But – we have one more thing to consider here ABI. As much as I would
like to, we can't just rewrite Cairo like pixman was. We need to
preserve – and probably extend.


So what I am proposing to do ?


First add CAIRO_FORMAT_NATIVE to cairo_format_t.


CAIRO_FORMAT_NATIVE would be a compile time choice for some of the
backends (like image), an alias for other backends, and perhaps a run
time choice for some like Xlib.


Second, support _cairo_image_surface_create_with_masks, (renamed so it
is in the proper namespace, with a copy of the old name passing to the
new one for ABI) with the note that it will error out if a depth is
specified that is not supported/enumerated by pixman ( ie 12-12-12 or
16-16-16). Add CAIRO_FORMAT_CUSTOM to cairo_format_t.


31 of the current 35 pixman supported depths would result in a
CAIRO_FORMAT_CUSTOM.


The backends need to handle CAIRO_FORMAT_CUSTOM as an error case, and
probably need to better handle the error case when they don't support A1
or A8. (Question – should they try to match to the nearest supported
depth – I can't think of a use case here).


Note: this will not fix all of the bugs I have heard reported for the
Xlib backend, as there are some odd depths out there – the Xlib backend
may need to hunt for a supported depth/visual match.


Third, add CAIRO_FORMAT_COLOR, and CAIRO_FORMAT_COLOR_ALPHA to
cairo_format_t. These would need to be supported by the backends – to
start with as aliases to CAIRO_FORMAT_ARGB32 and CAIRO_FORMAT_RGB24, and
later as the backend maintainers choice, perhaps to more appropriate
platform values.

One thought though, I am not sure I can see a difference between my
proposed CAIRO_FORMAT_NATIVE and CAIRO_FORMAT_COLOR, so maybe they
should be combined. Other thoughts out there ?


thanks in advance for comments and critiques,

Dave