[cairo] Deprecating CAIRO_FORMAT_RGB16_565

[Carl Worth]

Shortly before we released cairo 1.2.0 we received reports that cairo
was crashing when run against X servers with a 16-bit 565 visual,
(although cairo 1.0 had worked fine with this visual). To address this
problem we added a new public format: CAIRO_FORMAT_RGB16_565.

After the cairo 1.2.0 release we discovered a similar failure pattern,
(crashing with 1.2 though working with 1.0), with 24-bit visuals with
a BGR channel order instead of the RGB order that cairo uses. This has
been the last holdout of a set of bugs blocking a new 1.2.2
release. We recently fixed this bug[*], but without adding any new
public formats.

Meanwhile, Behdad has been doing some work to enable more compiler
warnings and chasing down the bugs that are exposed by them. One
interesting case is that adding -Wswitch-enum shows that the support
for RGB16_565 was incomplete. For example, cairo_surface_write_to_png
cannot work with a 16-bit format image, and there is missing support
in some xlib backend paths with unknown consequences.

That all seems quite dire, but then I noticed missing support from one
other critical function:

	cairo_image_surface_create

Here, we have an assertion check for a valid format, and the relevant
macro was not adjusted to allow for the new value. (Yes, the RGB16_565
addition was hasty and we obviously never tested this side of it.)

So the good news is that it has never been possible for a user to
manually create an RGB16_565 surface, so it's much harder for a user
to actually encounter the missing support for things like
cairo_surface_write_to_png.

And the recent work we did on fixing the BGR bug shows that we could
have added support for using the xlib backend without ever adding a
public 16-bit format.

So I'm inclined to deprecate the RGB16_565 format since it's never
been usable, nor was it necessary for fixing the one case for which
this feature was requested, (namely drawing with cairo's xlib backend
to an X server with a 16-bit visual).

Here's the documentation I plan to add now just before cairo 1.2.2 is
released:

 * @CAIRO_FORMAT_RGB16_565: This format value is deprecated. It has
 *   never been properly implemented in cairo and should not be used
 *   by applications. For example, any attempt to create an image
 *   surface with a format of CAIRO_FORMAT_RGB16_565 will fail. This
 *   format value was added as part of fixing cairo's xlib backend to
 *   work with X servers advertising a 16-bit, 565 visual. But as it
 *   turned out, adding this format to #cairo_format_t was not
 *   necessary, and was a mistake, (cairo's xlib backend can work fine
 *   with 16-bit visuals in the same way it works with BGR visuals
 *   without any BGR formats in #cairo_format_t). (Since 1.2)

-Carl

[*] Lots of details (more than you want most likely) on the BGR bug
are here:

  cairo doesn't work with a BGR X server visual (assertion failure:
  "Cairo does not yet support the requested image format")

  https://bugs.freedesktop.org/show_bug.cgi?id=7294
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
Url : http://lists.freedesktop.org/archives/cairo/attachments/20060807/55f1d09d/attachment.pgp