api: Extend cairo_antialias_t to include performace/quality hints

The existing API only described the method to be used for performing
rasterisation and unlike other API provided no opportunity for the user
to give a hint as to how to trade off performance against speed. So in
order to no be overly prescriptive, we extend the NONE/GRAY/SUBPIXEL
methods with FAST/GOOD/BEST hints and leave the backend to decide how
best to achieve those goals.

Signed-off-by: Chris Wilson <chris@chris-wilson.co.uk>

15 files changed, 79 insertions, 24 deletions

diff --git a/src/cairo-ft-font.c b/src/cairo-ft-font.c
index a0559466..9024463e 100644
--- a/src/cairo-ft-font.c
+++ b/src/cairo-ft-font.c
@@ -1266,6 +1266,7 @@ _render_glyph_outline (FT_Face                    face,
 	break;
 
     case CAIRO_ANTIALIAS_SUBPIXEL:
+    case CAIRO_ANTIALIAS_BEST:
 	switch (font_options->subpixel_order) {
 	    case CAIRO_SUBPIXEL_ORDER_DEFAULT:
 	    case CAIRO_SUBPIXEL_ORDER_RGB:
@@ -1299,6 +1300,8 @@ _render_glyph_outline (FT_Face                    face,
 
     case CAIRO_ANTIALIAS_DEFAULT:
     case CAIRO_ANTIALIAS_GRAY:
+    case CAIRO_ANTIALIAS_GOOD:
+    case CAIRO_ANTIALIAS_FAST:
 	render_mode = FT_RENDER_MODE_NORMAL;
     }
 
diff --git a/src/cairo-quartz-font.c b/src/cairo-quartz-font.c
index f529fc97..a50dc404 100644
--- a/src/cairo-quartz-font.c
+++ b/src/cairo-quartz-font.c
@@ -678,6 +678,7 @@ _cairo_quartz_init_glyph_surface (cairo_quartz_scaled_font_t *font,
 
 	switch (font->base.options.antialias) {
 	case CAIRO_ANTIALIAS_SUBPIXEL:
+	case CAIRO_ANTIALIAS_BEST:
 	    CGContextSetShouldAntialias (cgContext, TRUE);
 	    CGContextSetShouldSmoothFonts (cgContext, TRUE);
 	    if (CGContextSetAllowsFontSmoothingPtr &&
@@ -688,6 +689,8 @@ _cairo_quartz_init_glyph_surface (cairo_quartz_scaled_font_t *font,
 	    CGContextSetShouldAntialias (cgContext, FALSE);
 	    break;
 	case CAIRO_ANTIALIAS_GRAY:
+	case CAIRO_ANTIALIAS_GOOD:
+	case CAIRO_ANTIALIAS_FAST:
 	    CGContextSetShouldAntialias (cgContext, TRUE);
 	    CGContextSetShouldSmoothFonts (cgContext, FALSE);
 	    break;
diff --git a/src/cairo-script-surface.c b/src/cairo-script-surface.c
index f3e561bb..56e9d80a 100644
--- a/src/cairo-script-surface.c
+++ b/src/cairo-script-surface.c
@@ -362,7 +362,10 @@ _antialias_to_string (cairo_antialias_t antialias)
 	"ANTIALIAS_DEFAULT",	/* CAIRO_ANTIALIAS_DEFAULT */
 	"ANTIALIAS_NONE",	/* CAIRO_ANTIALIAS_NONE */
 	"ANTIALIAS_GRAY",	/* CAIRO_ANTIALIAS_GRAY */
-	"ANTIALIAS_SUBPIXEL"	/* CAIRO_ANTIALIAS_SUBPIXEL */
+	"ANTIALIAS_SUBPIXEL",	/* CAIRO_ANTIALIAS_SUBPIXEL */
+	"ANTIALIAS_FAST",	/* CAIRO_ANTIALIAS_FAST */
+	"ANTIALIAS_GOOD",	/* CAIRO_ANTIALIAS_GOOD */
+	"ANTIALIAS_BEST"	/* CAIRO_ANTIALIAS_BEST */
     };
     assert (antialias < ARRAY_LENGTH (names));
     return names[antialias];
diff --git a/src/cairo-surface-observer-private.h b/src/cairo-surface-observer-private.h
index d30a0e1e..a846a1c2 100644
--- a/src/cairo-surface-observer-private.h
+++ b/src/cairo-surface-observer-private.h
@@ -50,7 +50,7 @@ struct stat {
 #define NUM_OPERATORS (CAIRO_OPERATOR_HSL_LUMINOSITY+1)
 #define NUM_CAPS (CAIRO_LINE_CAP_SQUARE+1)
 #define NUM_JOINS (CAIRO_LINE_JOIN_BEVEL+1)
-#define NUM_ANTIALIAS (CAIRO_ANTIALIAS_SUBPIXEL+1)
+#define NUM_ANTIALIAS (CAIRO_ANTIALIAS_BEST+1)
 #define NUM_FILL_RULE (CAIRO_FILL_RULE_EVEN_ODD+1)
 
 struct extents {
diff --git a/src/cairo-surface-observer.c b/src/cairo-surface-observer.c
index 894509c7..75f2a46b 100644
--- a/src/cairo-surface-observer.c
+++ b/src/cairo-surface-observer.c
@@ -1533,7 +1533,10 @@ static const char *antialias_names[] = {
     "default",
     "none",
     "gray",
-    "subpixel"
+    "subpixel",
+    "fast",
+    "good",
+    "best"
 };
 static void
 print_antialias (cairo_output_stream_t *stream, unsigned int *array)
diff --git a/src/cairo-user-font.c b/src/cairo-user-font.c
index 522711d5..1b507fce 100644
--- a/src/cairo-user-font.c
+++ b/src/cairo-user-font.c
@@ -229,8 +229,11 @@ _cairo_user_scaled_glyph_init (void			 *abstract_font,
 	switch (scaled_font->base.options.antialias) {
 	default:
 	case CAIRO_ANTIALIAS_DEFAULT:
+	case CAIRO_ANTIALIAS_FAST:
+	case CAIRO_ANTIALIAS_GOOD:
 	case CAIRO_ANTIALIAS_GRAY:	format = CAIRO_FORMAT_A8;	break;
 	case CAIRO_ANTIALIAS_NONE:	format = CAIRO_FORMAT_A1;	break;
+	case CAIRO_ANTIALIAS_BEST:
 	case CAIRO_ANTIALIAS_SUBPIXEL:	format = CAIRO_FORMAT_ARGB32;	break;
 	}
 	surface = cairo_image_surface_create (format, width, height);
diff --git a/src/cairo-vg-surface.c b/src/cairo-vg-surface.c
index 392ed0bf..a2ea5476 100644
--- a/src/cairo-vg-surface.c
+++ b/src/cairo-vg-surface.c
@@ -658,9 +658,12 @@ _vg_rendering_quality_from_cairo (cairo_antialias_t aa)
     switch (aa) {
     case CAIRO_ANTIALIAS_DEFAULT:
     case CAIRO_ANTIALIAS_SUBPIXEL:
+    case CAIRO_ANTIALIAS_GOOD:
+    case CAIRO_ANTIALIAS_BEST:
 	return VG_RENDERING_QUALITY_BETTER;
 
     case CAIRO_ANTIALIAS_GRAY:
+    case CAIRO_ANTIALIAS_FAST:
 	return VG_RENDERING_QUALITY_FASTER;
 
     case CAIRO_ANTIALIAS_NONE:
@@ -1334,7 +1337,7 @@ _vg_surface_show_glyphs (void			*abstract_surface,
 			       op, source, &path,
 			       CAIRO_FILL_RULE_WINDING,
 			       CAIRO_GSTATE_TOLERANCE_DEFAULT,
-			       CAIRO_ANTIALIAS_SUBPIXEL,
+			       CAIRO_ANTIALIAS_DEFAULT,
 			       clip);
 BAIL:
     _cairo_path_fixed_fini (&path);
diff --git a/src/cairo-win32-font.c b/src/cairo-win32-font.c
index 1bd11040..18b837d5 100644
--- a/src/cairo-win32-font.c
+++ b/src/cairo-win32-font.c
@@ -342,9 +342,12 @@ _win32_scaled_font_create (LOGFONTW                   *logfont,
 	    f->quality = NONANTIALIASED_QUALITY;
 	    break;
 	case CAIRO_ANTIALIAS_GRAY:
+	case CAIRO_ANTIALIAS_FAST:
+	case CAIRO_ANTIALIAS_GOOD:
 	    f->quality = ANTIALIASED_QUALITY;
 	    break;
 	case CAIRO_ANTIALIAS_SUBPIXEL:
+	case CAIRO_ANTIALIAS_BEST:
 	    if (_have_cleartype_quality ())
 		f->quality = CLEARTYPE_QUALITY;
 	    else
diff --git a/src/cairo-xcb-surface-render.c b/src/cairo-xcb-surface-render.c
index d146fe95..2627837b 100644
--- a/src/cairo-xcb-surface-render.c
+++ b/src/cairo-xcb-surface-render.c
@@ -279,9 +279,12 @@ _cairo_xcb_surface_set_precision (cairo_xcb_surface_t	*surface,
     case CAIRO_ANTIALIAS_DEFAULT:
     case CAIRO_ANTIALIAS_GRAY:
     case CAIRO_ANTIALIAS_NONE:
+    case CAIRO_ANTIALIAS_FAST:
+    case CAIRO_ANTIALIAS_GOOD:
 	precision = XCB_RENDER_POLY_MODE_IMPRECISE;
 	break;
     case CAIRO_ANTIALIAS_SUBPIXEL:
+    case CAIRO_ANTIALIAS_BEST:
 	precision = XCB_RENDER_POLY_MODE_PRECISE;
 	break;
     }
diff --git a/src/cairo-xlib-surface.c b/src/cairo-xlib-surface.c
index 96d59932..e82de650 100644
--- a/src/cairo-xlib-surface.c
+++ b/src/cairo-xlib-surface.c
@@ -1097,8 +1097,11 @@ _cairo_xlib_surface_set_precision (cairo_xlib_display_t	*display,
     case CAIRO_ANTIALIAS_DEFAULT:
     case CAIRO_ANTIALIAS_GRAY:
     case CAIRO_ANTIALIAS_NONE:
+    case CAIRO_ANTIALIAS_FAST:
+    case CAIRO_ANTIALIAS_GOOD:
 	precision = PolyModeImprecise;
 	break;
+    case CAIRO_ANTIALIAS_BEST:
     case CAIRO_ANTIALIAS_SUBPIXEL:
 	precision = PolyModePrecise;
 	break;
@@ -2966,21 +2969,9 @@ _cairo_xlib_surface_composite_trapezoids (cairo_operator_t	op,
 	goto BAIL;
     }
 
-    switch (antialias) {
-    case CAIRO_ANTIALIAS_NONE:
-	pict_format =
-	    _cairo_xlib_display_get_xrender_format (display,
-						    CAIRO_FORMAT_A1);
-	break;
-    case CAIRO_ANTIALIAS_GRAY:
-    case CAIRO_ANTIALIAS_SUBPIXEL:
-    case CAIRO_ANTIALIAS_DEFAULT:
-    default:
-	pict_format =
-	    _cairo_xlib_display_get_xrender_format (display,
-						    CAIRO_FORMAT_A8);
-	break;
-    }
+    pict_format =
+	_cairo_xlib_display_get_xrender_format (display,
+						antialias == CAIRO_ANTIALIAS_NONE ?  CAIRO_FORMAT_A1 : CAIRO_FORMAT_A8);
 
     status = _cairo_xlib_surface_set_clip_region (dst, clip_region);
     if (unlikely (status))
diff --git a/src/cairo-xml-surface.c b/src/cairo-xml-surface.c
index f15a7677..40b6160a 100644
--- a/src/cairo-xml-surface.c
+++ b/src/cairo-xml-surface.c
@@ -158,10 +158,13 @@ static const char *
 _antialias_to_string (cairo_antialias_t antialias)
 {
     static const char *names[] = {
-	"ANTIALIAS_DEFAULT",	/* CAIRO_ANTIALIAS_DEFAULT */
-	"ANTIALIAS_NONE",	/* CAIRO_ANTIALIAS_NONE */
-	"ANTIALIAS_GRAY",	/* CAIRO_ANTIALIAS_GRAY */
-	"ANTIALIAS_SUBPIXEL"	/* CAIRO_ANTIALIAS_SUBPIXEL */
+	"DEFAULT",	/* CAIRO_ANTIALIAS_DEFAULT */
+	"NONE",         /* CAIRO_ANTIALIAS_NONE */
+	"GRAY",         /* CAIRO_ANTIALIAS_GRAY */
+	"SUBPIXEL",	/* CAIRO_ANTIALIAS_SUBPIXEL */
+	"FAST",         /* CAIRO_ANTIALIAS_FAST */
+	"GOOD",         /* CAIRO_ANTIALIAS_GOOD */
+	"BEST",         /* CAIRO_ANTIALIAS_BEST */
     };
     assert (antialias < ARRAY_LENGTH (names));
     return names[antialias];
diff --git a/src/cairo.h b/src/cairo.h
index 7a3a571f..710d9978 100644
--- a/src/cairo.h
+++ b/src/cairo.h
@@ -644,12 +644,35 @@ cairo_set_tolerance (cairo_t *cr, double tolerance);
  *  such as LCD panels
  *
  * Specifies the type of antialiasing to do when rendering text or shapes.
+ *
+ * As it is not necessarily clear from the above what advantages a particular
+ * antialias method provides, since 1.12, there is also a set of hints:
+ * @CAIRO_ANTIALIAS_FAST: Allow the backend to degrade raster quality for speed
+ * @CAIRO_ANTIALIAS_GOOD: A balance between speed and quality
+ * @CAIRO_ANTIALIAS_BEST: A high-fidelity, but potentially slow, raster mode
+ *
+ * These make no guarantee on how the backend will perform its rasterisation
+ * (if it even rasterises!), nor that they have any differing effect other
+ * than to enable some form of antialiasing. In the case of glyph rendering,
+ * @CAIRO_ANTIALIAS_FAST and @CAIRO_ANTIALIAS_GOOD will be mapped to
+ * @CAIRO_ANTIALIAS_GRAY, with @CAIRO_ANTALIAS_BEST being equivalent to
+ * @CAIRO_ANTIALIAS_SUBPIXEL.
+ *
+ * The interpretation of @CAIRO_ANTIALIAS_DEFAULT is left entirely up to
+ * the backend, typically this will be similar to @CAIRO_ANTIALIAS_GOOD.
  **/
 typedef enum _cairo_antialias {
     CAIRO_ANTIALIAS_DEFAULT,
+
+    /* method */
     CAIRO_ANTIALIAS_NONE,
     CAIRO_ANTIALIAS_GRAY,
-    CAIRO_ANTIALIAS_SUBPIXEL
+    CAIRO_ANTIALIAS_SUBPIXEL,
+
+    /* hints */
+    CAIRO_ANTIALIAS_FAST,
+    CAIRO_ANTIALIAS_GOOD,
+    CAIRO_ANTIALIAS_BEST
 } cairo_antialias_t;
 
 cairo_public void
diff --git a/util/cairo-gobject/cairo-gobject-enums.c b/util/cairo-gobject/cairo-gobject-enums.c
index 152bfd77..0a7c95d2 100644
--- a/util/cairo-gobject/cairo-gobject-enums.c
+++ b/util/cairo-gobject/cairo-gobject-enums.c
@@ -129,9 +129,15 @@ cairo_gobject_antialias_get_type (void)
    if (g_once_init_enter (&type_volatile)) {
       static const GEnumValue values[] = {
           { CAIRO_ANTIALIAS_DEFAULT, "CAIRO_ANTIALIAS_DEFAULT", "default" },
+
           { CAIRO_ANTIALIAS_NONE, "CAIRO_ANTIALIAS_NONE", "none" },
           { CAIRO_ANTIALIAS_GRAY, "CAIRO_ANTIALIAS_GRAY", "gray" },
           { CAIRO_ANTIALIAS_SUBPIXEL, "CAIRO_ANTIALIAS_SUBPIXEL", "subpixel" },
+
+          { CAIRO_ANTIALIAS_FAST, "CAIRO_ANTIALIAS_FAST", "fast" },
+          { CAIRO_ANTIALIAS_GOOD, "CAIRO_ANTIALIAS_GOOD", "good" },
+          { CAIRO_ANTIALIAS_BEST, "CAIRO_ANTIALIAS_BEST", "best" },
+
           { 0, NULL, NULL }
       };
       GType type = g_enum_register_static (g_intern_static_string ("cairo_antialias_t"), values);
diff --git a/util/cairo-script/cairo-script-operators.c b/util/cairo-script/cairo-script-operators.c
index 1ac5cb6f..36dbbb90 100644
--- a/util/cairo-script/cairo-script-operators.c
+++ b/util/cairo-script/cairo-script-operators.c
@@ -6597,6 +6597,9 @@ _integer_constants[] = {
     { "ANTIALIAS_NONE",		CAIRO_ANTIALIAS_NONE },
     { "ANTIALIAS_GRAY",		CAIRO_ANTIALIAS_GRAY },
     { "ANTIALIAS_SUBPIXEL",	CAIRO_ANTIALIAS_SUBPIXEL },
+    { "ANTIALIAS_FAST",		CAIRO_ANTIALIAS_FAST },
+    { "ANTIALIAS_GOOD",		CAIRO_ANTIALIAS_GOOD },
+    { "ANTIALIAS_BEST",		CAIRO_ANTIALIAS_BEST },
 
     { "LINE_CAP_BUTT",		CAIRO_LINE_CAP_BUTT },
     { "LINE_CAP_ROUND",		CAIRO_LINE_CAP_ROUND },
diff --git a/util/cairo-trace/trace.c b/util/cairo-trace/trace.c
index 1b42bed3..a6de76f1 100644
--- a/util/cairo-trace/trace.c
+++ b/util/cairo-trace/trace.c
@@ -2271,9 +2271,14 @@ _antialias_to_string (cairo_antialias_t antialias)
 #define f(name) case CAIRO_ANTIALIAS_ ## name: return "ANTIALIAS_" #name
     switch (antialias) {
 	f(DEFAULT);
+
 	f(NONE);
 	f(GRAY);
 	f(SUBPIXEL);
+
+	f(FAST);
+	f(GOOD);
+	f(BEST);
     };
 #undef f
     return "UNKNOWN_ANTIALIAS";