[cairo] The past, present and future of RGB16_565

[Chris Wilson]

Carl noted last night that we still haven't resolved the thorny issue
that RGB16_565 just has not died, and given the continued proliferation
of small low-powered devices it's not going away in the need future.

>From cairo's point of view we can already handle all image formats that
pixman can (internally anything that has a non-cairo_format_t format is
coerced into one of the simple types if required) so all we need is a
clean method of presenting the complexity of pixman in an elegant manner
consistent with the rest of the minimal interface.

The simplest (for us) method would be just to expose
_cairo_image_surface_create_for_pixman_image() and expect our users to
now have to learn (and bind) pixman as well, just in order to create a
cairo_image_surface_t!

The next step is then just to replace cairo_format_t with
pixman_format_code_t in a new
cairo_image_surface_create_with_pixman_format_for_data().

To quote:
* cworth shoots for winning the longest-function-name contest again...

But here we are still exposing a private API, and expecting our users to
bind a small part of pixman.

The idea I had last night was to introduce cairo_format_options_t, and
not introduce any new image creation routines. The usage I have in mind
would look something like:

format = cairo_format_options_create ();
cairo_format_options_set_red_mask (format, 0xff, 16);
cairo_format_options_set_green_mask (format, 0xff, 8);
cairo_format_options_set_blue_mask (format, 0xff, 0);
cairo_format_options_set_bits_per_pixel (format, 24);
cairo_image_surface_create (cairo_format_options_get_id (format),
                            width, height);
cairo_format_options_destroy (format);

By making it an opaque type we can safe-guard against future
requirements for HDR pixel-formats, or extension to un-premultiplied
sources etc.

Internally, I expect to currently just wrap _pixman_format_from_masks(),
throwing the usual errors for anything that isn't a suitable pixman
destination (though it won't be that difficult to make a read-only image
surface to hold pixman sources).

Implementation wise, upon a call to cairo_format_options_get_id() we
freeze the options, look up the masks in a hash table and retrieve an
identifier (just interning a copy of the options and using its index +
4096 [suitably large offset to distinguish from simple cairo_format_t,
though now we run the risk of collisions with cairo_content_t...]).
Then in the image create calls just reverse the process and get the
pixman_format_code_t and continue on through the normal code paths
without alteration. (In the future the options may be much more
expressive and could access alternate pixman image constructors...)

My only concern with this is that cairo_format_options_t cannot
guarantee to return the same id on different runs of the application.

In order to easily support tracing, I fancy also including
cairo_format_options_[to|from]_string() (Which for ease of use should be
interoperable with gstreamer?) And being complete I would expect
cairo_format_options_create_for_id() [which would work with the normal
cairo_format_t as well] and all the usual getters.

So... Is this scheme too ugly for words?

-ickle