Add a start_page function to the paginated_surface_backend.

This allows for any surface using the paginated_surface backend to
easily do stuff at the beginning of each page, (such as writing out
any per-page header necessary).

This replaces some of the per-page state tracking that the PS surface
was doing, (though it still has some left for its optimization of
CLEAR on a blank page).

1 files changed, 58 insertions, 2 deletions

diff --git a/src/cairo-paginated-surface-private.h b/src/cairo-paginated-surface-private.h
index 42cb9eff0..c18cb3c14 100644
--- a/src/cairo-paginated-surface-private.h
+++ b/src/cairo-paginated-surface-private.h
@@ -44,11 +44,67 @@ typedef enum {
 } cairo_paginated_mode_t;
 
 typedef struct _cairo_paginated_surface_backend {
+    /* Optional. Will be called once for each page.
+     *
+     * NOTE: With respect to the order of drawing operations as seen
+     * by the target, this call will occur before any drawing
+     * operations for the relevant page. However, with respect to the
+     * function calls as made by the user, this call will be *after*
+     * any drawing operations for the page, (that is, it will occur
+     * during the user's call to cairo_show_page or cairo_copy_page).
+     */
+    cairo_int_status_t
+    (*start_page)		(void			*surface);
+
+    /* Required. Will be called twice for each page, once with an
+     * argument of CAIRO_PAGINATED_MODE_ANALYZE and once with
+     * CAIRO_PAGINATED_MODE_RENDER. See more details in the
+     * documentation for _cairo_paginated_surface_create below.
+     */
     void
-    (*set_paginated_mode)	 (void				*surface,
-				  cairo_paginated_mode_t	 mode);
+    (*set_paginated_mode)	(void			*surface,
+				 cairo_paginated_mode_t	 mode);
 } cairo_paginated_surface_backend_t;
 
+/* A cairo_paginated_surface provides a very convenient wrapper that
+ * is well-suited for doing the analysis common to most surfaces that
+ * have paginated output, (that is, things directed at printers, or
+ * for saving content in files such as PostScript or PDF files).
+ *
+ * What the paginated surface does is first save all drawing
+ * operations for a page into a meta-surface. Then when the user calls
+ * cairo_show_page, the paginated surface performs the following
+ * sequence of operations (using the backend functions passed to
+ * cairo_paginated_surface_create):
+ *
+ * 1. Calls start_page (if non NULL). At this point, it is appropriate
+ *    for the target to emit any page-specific header information into
+ *    its output.
+ *
+ * 2. Calls set_paginated_mode with an argument of CAIRO_PAGINATED_MODE_ANALYZE
+ *
+ * 3. Replays the meta-surface to the target surface, (with an
+ *    analysis surface inserted between which watches the return value
+ *    from each operation). This analysis stage is used to decide which
+ *    operations will require fallbacks.
+ *
+ * 4. Calls set_paginated_mode with an argument of CAIRO_PAGINATED_MODE_RENDER
+ *
+ * 5. Replays a subset of the meta-surface operations to the target surface
+ *
+ * 6. Replays the remaining operations to an image surface, sets an
+ *    appropriate clip on the target, then paints the resulting image
+ *    surface to the target.
+ *
+ * So, the target will see drawing operations during two separate
+ * stages, (ANALYZE and RENDER). During the ANALYZE phase the target
+ * should not actually perform any rendering, (for example, if
+ * performing output to a file, no output should be generated during
+ * this stage). Instead the drawing functions simply need to return
+ * CAIRO_STATUS_SUCCESS or CAIRO_INT_STATUS_UNSUPPORTED to indicate
+ * whether rendering would be supported. And it should do this as
+ * quickly as possible.
+ */
 cairo_private cairo_surface_t *
 _cairo_paginated_surface_create (cairo_surface_t				*target,
 				 cairo_content_t				 content,