Add new public API cairo_surface_has_show_text_glyphs()

We added cairo_has_show_text_glyphs() before.  Since this is really a
surface property, should have the surface method too.  Like we added
cairo_surface_show_page()...

11 files changed, 65 insertions, 9 deletions

diff --git a/doc/public/cairo-sections.txt b/doc/public/cairo-sections.txt
index 0f9a4c64..622ca915 100644
--- a/doc/public/cairo-sections.txt
+++ b/doc/public/cairo-sections.txt
@@ -189,6 +189,7 @@ cairo_surface_set_user_data
 cairo_surface_get_user_data
 cairo_surface_copy_page
 cairo_surface_show_page
+cairo_surface_has_show_text_glyphs
 </SECTION>
 
 <SECTION>
diff --git a/doc/public/tmpl/cairo-surface.sgml b/doc/public/tmpl/cairo-surface.sgml
index 20a1d354..adc47bb2 100644
--- a/doc/public/tmpl/cairo-surface.sgml
+++ b/doc/public/tmpl/cairo-surface.sgml
@@ -250,3 +250,12 @@ cairo_<emphasis>backend</emphasis>_surface_create().
 @surface: 
 
 
+<!-- ##### FUNCTION cairo_surface_has_show_text_glyphs ##### -->
+<para>
+
+</para>
+
+@surface:
+@Returns:
+
+
diff --git a/src/cairo-analysis-surface.c b/src/cairo-analysis-surface.c
index e2c81898..c9f3e853 100644
--- a/src/cairo-analysis-surface.c
+++ b/src/cairo-analysis-surface.c
@@ -621,7 +621,7 @@ _cairo_analysis_surface_has_show_text_glyphs (void *abstract_surface)
 {
     cairo_analysis_surface_t *surface = abstract_surface;
 
-    return _cairo_surface_has_show_text_glyphs (surface->target);
+    return cairo_surface_has_show_text_glyphs (surface->target);
 }
 
 static cairo_int_status_t
diff --git a/src/cairo-gstate.c b/src/cairo-gstate.c
index 2db9b367..29807709 100644
--- a/src/cairo-gstate.c
+++ b/src/cairo-gstate.c
@@ -1525,7 +1525,7 @@ _cairo_gstate_glyph_extents (cairo_gstate_t *gstate,
 cairo_bool_t
 _cairo_gstate_has_show_text_glyphs (cairo_gstate_t *gstate)
 {
-    return _cairo_surface_has_show_text_glyphs (gstate->target);
+    return cairo_surface_has_show_text_glyphs (gstate->target);
 }
 
 cairo_status_t
diff --git a/src/cairo-paginated-surface.c b/src/cairo-paginated-surface.c
index 248edb41..2640a8bf 100644
--- a/src/cairo-paginated-surface.c
+++ b/src/cairo-paginated-surface.c
@@ -609,7 +609,7 @@ _cairo_paginated_surface_has_show_text_glyphs (void *abstract_surface)
 {
     cairo_paginated_surface_t *surface = abstract_surface;
 
-    return _cairo_surface_has_show_text_glyphs (surface->target);
+    return cairo_surface_has_show_text_glyphs (surface->target);
 }
 
 static cairo_int_status_t
diff --git a/src/cairo-surface.c b/src/cairo-surface.c
index 1d95ca47..db920a35 100644
--- a/src/cairo-surface.c
+++ b/src/cairo-surface.c
@@ -1738,6 +1738,9 @@ _cairo_surface_composite_trapezoids (cairo_operator_t		op,
  * be retained for the next page.  Use cairo_surface_show_page() if you
  * want to get an empty page after the emission.
  *
+ * There is a convenience function for this that takes a #cairo_t,
+ * namely cairo_copy_page().
+ *
  * Since: 1.6
  */
 void
@@ -1772,6 +1775,9 @@ slim_hidden_def (cairo_surface_copy_page);
  * Emits and clears the current page for backends that support multiple
  * pages.  Use cairo_surface_copy_page() if you don't want to clear the page.
  *
+ * There is a convenience function for this that takes a #cairo_t,
+ * namely cairo_show_page().
+ *
  * Since: 1.6
  **/
 void
@@ -2141,14 +2147,50 @@ _cairo_surface_get_extents (cairo_surface_t         *surface,
     return status;
 }
 
+/**
+ * cairo_surface_has_show_text_glyphs:
+ * @surface: a #cairo_surface_t
+ *
+ * Returns whether the surface supports
+ * sophisticated cairo_show_text_glyphs() operations.  That is,
+ * whether it actually uses the provided text and cluster data
+ * to a cairo_show_text_glyphs() call.
+ *
+ * Note: Even if this function returns %FALSE, a
+ * cairo_show_text_glyphs() operation targeted at @surface will
+ * still succeed.  It just will
+ * act like a cairo_show_glyphs() operation.  Users can use this
+ * function to avoid computing UTF-8 text and cluster mapping if the
+ * target surface does not use it.
+ *
+ * There is a convenience function for this that takes a #cairo_t,
+ * namely cairo_has_show_text_glyphs().
+ *
+ * Return value: %TRUE if @surface supports
+ *               cairo_show_text_glyphs(), %FALSE otherwise
+ *
+ * Since: 1.8
+ **/
 cairo_bool_t
-_cairo_surface_has_show_text_glyphs (cairo_surface_t	    *surface)
+cairo_surface_has_show_text_glyphs (cairo_surface_t	    *surface)
 {
+    cairo_status_t status_ignored;
+
+    if (surface->status)
+	return FALSE;
+
+    if (surface->finished) {
+	status_ignored = _cairo_surface_set_error (surface,
+						   CAIRO_STATUS_SURFACE_FINISHED);
+	return FALSE;
+    }
+
     if (surface->backend->has_show_text_glyphs)
 	return surface->backend->has_show_text_glyphs (surface);
     else
 	return surface->backend->show_text_glyphs != NULL;
 }
+slim_hidden_def (cairo_surface_has_show_text_glyphs);
 
 /* Note: the backends may modify the contents of the glyph array as long as
  * they do not return %CAIRO_INT_STATUS_UNSUPPORTED. This makes it possible to
diff --git a/src/cairo.c b/src/cairo.c
index a533a7bd..2ff64700 100644
--- a/src/cairo.c
+++ b/src/cairo.c
@@ -3227,6 +3227,9 @@ cairo_show_glyphs (cairo_t *cr, const cairo_glyph_t *glyphs, int num_glyphs)
  * function to avoid computing UTF-8 text and cluster mapping if the
  * target surface does not use it.
  *
+ * This is a convenience function that simply calls
+ * cairo_surface_has_show_text_glyphs() on @cr's target.
+ *
  * Return value: %TRUE if the target surface of @cr supports
  *               cairo_show_text_glyphs(), %FALSE otherwise
  *
diff --git a/src/cairo.h b/src/cairo.h
index 52a34e94..77bfe281 100644
--- a/src/cairo.h
+++ b/src/cairo.h
@@ -1981,6 +1981,9 @@ cairo_surface_copy_page (cairo_surface_t *surface);
 cairo_public void
 cairo_surface_show_page (cairo_surface_t *surface);
 
+cairo_public cairo_bool_t
+cairo_surface_has_show_text_glyphs (cairo_surface_t *surface);
+
 /* Image-surface functions */
 
 /**
diff --git a/src/cairoint.h b/src/cairoint.h
index a6c9e3fa..4b903535 100644
--- a/src/cairoint.h
+++ b/src/cairoint.h
@@ -1752,9 +1752,6 @@ _cairo_surface_fill (cairo_surface_t	*surface,
 		     double		 tolerance,
 		     cairo_antialias_t	 antialias);
 
-cairo_private cairo_bool_t
-_cairo_surface_has_show_text_glyphs (cairo_surface_t	    *surface);
-
 cairo_private cairo_status_t
 _cairo_surface_show_text_glyphs (cairo_surface_t	    *surface,
 				 cairo_operator_t	     op,
@@ -2454,6 +2451,7 @@ slim_hidden_proto (cairo_surface_get_content);
 slim_hidden_proto (cairo_surface_get_device_offset);
 slim_hidden_proto (cairo_surface_get_font_options);
 slim_hidden_proto (cairo_surface_get_type);
+slim_hidden_proto (cairo_surface_has_show_text_glyphs);
 slim_hidden_proto (cairo_surface_mark_dirty_rectangle);
 slim_hidden_proto_no_warn (cairo_surface_reference);
 slim_hidden_proto (cairo_surface_set_device_offset);
diff --git a/src/test-meta-surface.c b/src/test-meta-surface.c
index 5425c0c8..4d56e1b7 100644
--- a/src/test-meta-surface.c
+++ b/src/test-meta-surface.c
@@ -260,7 +260,7 @@ _test_meta_surface_has_show_text_glyphs (void *abstract_surface)
 {
     test_meta_surface_t *surface = abstract_surface;
 
-    return _cairo_surface_has_show_text_glyphs (surface->meta);
+    return cairo_surface_has_show_text_glyphs (surface->meta);
 }
 
 static cairo_int_status_t
diff --git a/src/test-paginated-surface.c b/src/test-paginated-surface.c
index 48c73082..5d86986c 100644
--- a/src/test-paginated-surface.c
+++ b/src/test-paginated-surface.c
@@ -237,7 +237,7 @@ _test_paginated_surface_has_show_text_glyphs (void *abstract_surface)
 {
     test_paginated_surface_t *surface = abstract_surface;
 
-    return _cairo_surface_has_show_text_glyphs (surface->target);
+    return cairo_surface_has_show_text_glyphs (surface->target);
 }
 
 static cairo_int_status_t