Add CAIRO_INTERNAL_FORMAT_RGB16_565 and prefer it over deprecated CAIRO_FORMAT_RGB16_565

Also clarify the documentation for cairo_internal_format_t

src/cairo-image-surface.c

@@ -131,7 +131,7 @@ _cairo_image_surface_create_for_pixman_image (pixman_image_t *pixman_image,
 
 /* Try to recover a cairo_format_t from a pixman_format
  * by looking at the bpp and masks values. */
-static cairo_format_t
+static cairo_internal_format_t
 _cairo_format_from_pixman_format (pixman_format_t *pixman_format)
 {
     unsigned int bpp, am, rm, gm, bm;
@@ -167,7 +167,7 @@ _cairo_format_from_pixman_format (pixman_format_t *pixman_format)
 	    rm == 0xf800 &&
 	    gm == 0x07e0 &&
 	    bm == 0x001f)
-	    return CAIRO_FORMAT_RGB16_565;
+	    return CAIRO_INTERNAL_FORMAT_RGB16_565;
 	break;
     case 8:
 	if (am == 0xff &&
@@ -560,7 +560,7 @@ _cairo_content_from_format (cairo_format_t format)
     case CAIRO_INTERNAL_FORMAT_ABGR32:
 	return CAIRO_CONTENT_COLOR_ALPHA;
     case CAIRO_FORMAT_RGB24:
-    case CAIRO_FORMAT_RGB16_565:
+    case CAIRO_INTERNAL_FORMAT_RGB16_565:
     case CAIRO_INTERNAL_FORMAT_BGR24:
 	return CAIRO_CONTENT_COLOR;
     case CAIRO_FORMAT_A8:

src/cairoint.h

@@ -308,33 +308,43 @@ typedef enum cairo_internal_surface_type {
     CAIRO_INTERNAL_SURFACE_TYPE_TEST_PAGINATED
 } cairo_internal_surface_type_t;
 
-/* For xlib fallbacks, we use image surfaces with formats that match
- * the visual of the X server. There are a couple of common X server
- * visuals for which we do not have corresponding public
- * cairo_format_t values, since we do not plan on always guaranteeing
- * that cairo will be able to draw to these formats.
+/* For xlib fallbacks, we need image surfaces with formats that match
+ * the visual of the X server. There are a few common X server visuals
+ * for which we do not have corresponding public cairo_format_t
+ * values, since we do not plan on always guaranteeing that cairo will
+ * be able to draw to these formats.
  *
- * So, currently pixman does provide support for these formats. It's
- * possible that in the future we will change the implementation to
- * instead convert to a supported format. This would allow us to be
- * able to simplify pixman to handle fewer formats.
+ * Currently pixman does advertise support for these formats, (with an
+ * interface to construct a format from a set of masks---but pixman
+ * may not actually have code to support any arbitrary set of
+ * maskes). So we lodge a cairo_internal_format_t in the internal
+ * cairo image surface to indicate what's going on. The value isn't
+ * actually used for much, since it is the set of pixman masks that
+ * control the rendering.
  *
- * The RGB16_565 case could probably have been handled this same way,
- * (and in fact we could still change it to do so, and maybe just
- * leave the value in the enum but deprecate it entirely). We can't
- * drop the value since it did appear in cairo 1.2.0 so it might
- * appear in code, (particularly bindings which are thorough about
- * things like that). But we did neglect to update CAIRO_FORMAT_VALID
- * for 1.2 so we know that no functional code is out there relying on
- * being able to create an image surface with a 565 format, (which is
- * good since things like write_to_png are missing support for the 565
- * format.
+ * But even though the value isn't used, it's still useful to maintain
+ * this list, as it indicates to use visual formats that have been
+ * encountered in practice. We can take advantage of this for future
+ * rewrites of pixman that might support a limited set of formats
+ * instead of general mask-based rendering, (or at least optimized
+ * rendering for a limited set of formats).
+ *
+ * Another approach that could be taken here is to convert the data at
+ * the time of the fallback to a supported format. This is similar to
+ * what needs to be done to support PseudoColor visuals, for example.
  *
  * NOTE: The implementation of CAIRO_FORMAT_VALID *must* *not*
- * consider these internal formats as valid. */
+ * consider these internal formats as valid.
+ *
+ * NOTE: When adding a value to this list, be sure to add it to
+ * _cairo_format_from_pixman_format, (which is probably the assert
+ * failure you're wanting to eliminate), but also don't forget to add
+ * it to cairo_content_from_format.
+ */
 typedef enum cairo_internal_format {
     CAIRO_INTERNAL_FORMAT_ABGR32 = 0x1000,
-    CAIRO_INTERNAL_FORMAT_BGR24
+    CAIRO_INTERNAL_FORMAT_BGR24,
+    CAIRO_INTERNAL_FORMAT_RGB16_565
 } cairo_internal_format_t;
 
 typedef enum cairo_direction {