Export cairo_surface_{copy,show}_page

This patch adds cairo_surface_copy_page and cairo_surface_show_page
as public methods, leaving the previous cairo_show_page variants as
shorthands.  copy_page/show_page are specific to the surface, not
to the context, so they need to be surface methods.

TODO

@@ -27,11 +27,6 @@ Changes that add new API (API changes/removals will not be considered)
 	current path. We may also need to provide the coordinates of the
 	faces of every dash as well.
 
- • cairo_surface_show_page() and cairo_surface_copy_page()
-	how_page is a surface operation and should have been there instead of
-	cairo_show_page() from the beginning.  Same about copy_page().
-	Implement the right API now.
-
  • Polling API (cairo_get_serial and cairo_changed)
 
  • cairo_save/restore_path()

boilerplate/Makefile.win32

@@ -7,6 +7,10 @@ CFLAGS += -I../src
 
 SOURCES = \
 	cairo-boilerplate.c \
+	cairo-boilerplate-win32.c \
+	cairo-boilerplate-ps.c \
+	cairo-boilerplate-svg.c \
+	cairo-boilerplate-pdf.c \
 	xmalloc.c \
 	$(NULL)
 

boilerplate/cairo-boilerplate-test-surfaces.c

@@ -121,10 +121,7 @@ _cairo_boilerplate_test_paginated_surface_write_to_png (cairo_surface_t	*surface
     cairo_status_t status;
 
     /* show page first.  the automatic show_page is too late for us */
-    /* XXX use cairo_surface_show_page() when that's added */
-    cairo_t *cr = cairo_create (surface);
-    cairo_show_page (cr);
-    cairo_destroy (cr);
+    cairo_surface_show_page (surface);
 
     tpc = cairo_surface_get_user_data (surface, &test_paginated_closure_key);
 

src/cairo-gstate.c

@@ -1086,13 +1086,13 @@ BAIL:
 cairo_status_t
 _cairo_gstate_copy_page (cairo_gstate_t *gstate)
 {
-    return _cairo_surface_copy_page (gstate->target);
+    return cairo_surface_copy_page (gstate->target);
 }
 
 cairo_status_t
 _cairo_gstate_show_page (cairo_gstate_t *gstate)
 {
-    return _cairo_surface_show_page (gstate->target);
+    return cairo_surface_show_page (gstate->target);
 }
 
 static void

src/cairo-paginated-surface.c

@@ -376,14 +376,14 @@ _cairo_paginated_surface_copy_page (void *abstract_surface)
     surface->page_num++;
 
     /* XXX: It might make sense to add some suport here for calling
-     * _cairo_surface_copy_page on the target surface. It would be an
+     * cairo_surface_copy_page on the target surface. It would be an
      * optimization for the output, (so that PostScript could include
      * copypage, for example), but the interaction with image
      * fallbacks gets tricky. For now, we just let the target see a
      * show_page and we implement the copying by simply not destroying
      * the meta-surface. */
 
-    return _cairo_surface_show_page (surface->target);
+    return cairo_surface_show_page (surface->target);
 }
 
 static cairo_int_status_t
@@ -400,7 +400,7 @@ _cairo_paginated_surface_show_page (void *abstract_surface)
     if (status)
 	return status;
 
-    status = _cairo_surface_show_page (surface->target);
+    status = cairo_surface_show_page (surface->target);
     if (status)
 	return status;
 

src/cairo-surface.c

@@ -1585,8 +1585,19 @@ _cairo_surface_composite_trapezoids (cairo_operator_t		op,
 							  traps, num_traps);
 }
 
+/**
+ * cairo_surface_copy_page:
+ * @suface: a #cairo_surface_t
+ *
+ * Emits the current page for backends that support multiple pages,
+ * but doesn't clear it, so that the contents of the current page will
+ * be retained for the next page.  Use cairo_surface_show_page() if you
+ * want to get an empty page after the emission.
+ *
+ * Since: 1.6
+ */
 cairo_status_t
-_cairo_surface_copy_page (cairo_surface_t *surface)
+cairo_surface_copy_page (cairo_surface_t *surface)
 {
     assert (! surface->is_snapshot);
 
@@ -1602,9 +1613,20 @@ _cairo_surface_copy_page (cairo_surface_t *surface)
 
     return surface->backend->copy_page (surface);
 }
+slim_hidden_def (cairo_surface_copy_page);
+
+/**
+ * cairo_surface_show_page:
+ * @surface: a #cairo_Surface_t
+ *
+ * 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.
+ *
+ * Since: 1.6
+ **/
 
 cairo_status_t
-_cairo_surface_show_page (cairo_surface_t *surface)
+cairo_surface_show_page (cairo_surface_t *surface)
 {
     assert (! surface->is_snapshot);
 
@@ -1620,6 +1642,7 @@ _cairo_surface_show_page (cairo_surface_t *surface)
 
     return surface->backend->show_page (surface);
 }
+slim_hidden_def (cairo_surface_show_page);
 
 /**
  * _cairo_surface_get_current_clip_serial:

src/cairo-svg-surface.c

@@ -991,7 +991,7 @@ _cairo_svg_surface_emit_meta_surface (cairo_svg_document_t *document,
 	return status;
     }
 
-    status = _cairo_surface_show_page (paginated_surface);
+    status = cairo_surface_show_page (paginated_surface);
     if (status) {
 	cairo_surface_destroy (&meta->base);
 	return status;

src/cairo.c

@@ -2107,6 +2107,9 @@ slim_hidden_def(cairo_fill_preserve);
  * doesn't clear it, so, the contents of the current page will be retained
  * for the next page too.  Use cairo_show_page() if you want to get an
  * empty page after the emission.
+ *
+ * This is a convenience function that simply calls
+ * cairo_surface_copy_page() on @cr's target.
  **/
 void
 cairo_copy_page (cairo_t *cr)
@@ -2127,6 +2130,9 @@ cairo_copy_page (cairo_t *cr)
  *
  * Emits and clears the current page for backends that support multiple
  * pages.  Use cairo_copy_page() if you don't want to clear the page.
+ *
+ * This is a convenience function that simply calls
+ * cairo_surface_show_page() on @cr's target.
  **/
 void
 cairo_show_page (cairo_t *cr)

src/cairo.h

@@ -1535,6 +1535,12 @@ cairo_surface_set_fallback_resolution (cairo_surface_t	*surface,
 				       double		 x_pixels_per_inch,
 				       double		 y_pixels_per_inch);
 
+cairo_public cairo_status_t
+cairo_surface_copy_page (cairo_surface_t *surface);
+
+cairo_public cairo_status_t
+cairo_surface_show_page (cairo_surface_t *surface);
+
 /* Image-surface functions */
 
 /**

src/cairoint.h

@@ -1828,12 +1828,6 @@ _cairo_surface_composite_trapezoids (cairo_operator_t	op,
 				     cairo_trapezoid_t	*traps,
 				     int		ntraps);
 
-cairo_private cairo_status_t
-_cairo_surface_copy_page (cairo_surface_t *surface);
-
-cairo_private cairo_status_t
-_cairo_surface_show_page (cairo_surface_t *surface);
-
 cairo_private cairo_status_t
 _cairo_surface_acquire_source_image (cairo_surface_t         *surface,
 				     cairo_image_surface_t  **image_out,
@@ -2455,6 +2449,8 @@ slim_hidden_proto (cairo_surface_mark_dirty_rectangle);
 slim_hidden_proto_no_warn (cairo_surface_reference);
 slim_hidden_proto (cairo_surface_set_device_offset);
 slim_hidden_proto (cairo_surface_set_fallback_resolution);
+slim_hidden_proto (cairo_surface_copy_page);
+slim_hidden_proto (cairo_surface_show_page);
 slim_hidden_proto (cairo_surface_status);
 slim_hidden_proto (cairo_version_string);