src/cairo-paginated-private.h

   1 /* cairo - a vector graphics library with display and print output
   2  *
   3  * Copyright © 2005 Red Hat, Inc
   4  *
   5  * This library is free software; you can redistribute it and/or
   6  * modify it either under the terms of the GNU Lesser General Public
   7  * License version 2.1 as published by the Free Software Foundation
   8  * (the "LGPL") or, at your option, under the terms of the Mozilla
   9  * Public License Version 1.1 (the "MPL"). If you do not alter this
  10  * notice, a recipient may use your version of this file under either
  11  * the MPL or the LGPL.
  12  *
  13  * You should have received a copy of the LGPL along with this library
  14  * in the file COPYING-LGPL-2.1; if not, write to the Free Software
  15  * Foundation, Inc., 51 Franklin Street, Suite 500, Boston, MA 02110-1335, USA
  16  * You should have received a copy of the MPL along with this library
  17  * in the file COPYING-MPL-1.1
  18  *
  19  * The contents of this file are subject to the Mozilla Public License
  20  * Version 1.1 (the "License"); you may not use this file except in
  21  * compliance with the License. You may obtain a copy of the License at
  22  * http://www.mozilla.org/MPL/
  23  *
  24  * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY
  25  * OF ANY KIND, either express or implied. See the LGPL or the MPL for
  26  * the specific language governing rights and limitations.
  27  *
  28  * The Original Code is the cairo graphics library.
  29  *
  30  * The Initial Developer of the Original Code is Red Hat, Inc.
  31  *
  32  * Contributor(s):
  33  *      Carl Worth <cworth@cworth.org>
  34  */
  35
  36 #ifndef CAIRO_PAGINATED_H
  37 #define CAIRO_PAGINATED_H
  38
  39 #include "cairoint.h"
  40
  41 struct _cairo_paginated_surface_backend {
  42     /* Optional. Will be called once for each page.
  43      *
  44      * Note: With respect to the order of drawing operations as seen
  45      * by the target, this call will occur before any drawing
  46      * operations for the relevant page. However, with respect to the
  47      * function calls as made by the user, this call will be *after*
  48      * any drawing operations for the page, (that is, it will occur
  49      * during the user's call to cairo_show_page or cairo_copy_page).
  50      */
  51     cairo_warn cairo_int_status_t
  52     (*start_page)               (void                   *surface);
  53
  54     /* Required. Will be called twice for each page, once with an
  55      * argument of CAIRO_PAGINATED_MODE_ANALYZE and once with
  56      * CAIRO_PAGINATED_MODE_RENDER. See more details in the
  57      * documentation for _cairo_paginated_surface_create below.
  58      */
  59     void
  60     (*set_paginated_mode)       (void                   *surface,
  61                                  cairo_paginated_mode_t  mode);
  62
  63     /* Optional. Specifies the smallest box that encloses all objects
  64      * on the page. Will be called at the end of the ANALYZE phase but
  65      * before the mode is changed to RENDER.
  66      */
  67     cairo_warn cairo_int_status_t
  68     (*set_bounding_box) (void           *surface,
  69                          cairo_box_t    *bbox);
  70
  71     /* Optional. Indicates whether the page requires fallback images.
  72      * Will be called at the end of the ANALYZE phase but before the
  73      * mode is changed to RENDER.
  74      */
  75     cairo_warn cairo_int_status_t
  76     (*set_fallback_images_required) (void           *surface,
  77                                      cairo_bool_t    fallbacks_required);
  78
  79     cairo_bool_t
  80     (*supports_fine_grained_fallbacks) (void                *surface);
  81 };
  82
  83 /* A #cairo_paginated_surface_t provides a very convenient wrapper that
  84  * is well-suited for doing the analysis common to most surfaces that
  85  * have paginated output, (that is, things directed at printers, or
  86  * for saving content in files such as PostScript or PDF files).
  87  *
  88  * To use the paginated surface, you'll first need to create your
  89  * 'real' surface using _cairo_surface_init() and the standard
  90  * #cairo_surface_backend_t. Then you also call
  91  * _cairo_paginated_surface_create which takes its own, much simpler,
  92  * #cairo_paginated_surface_backend_t. You are free to return the result
  93  * of _cairo_paginated_surface_create() from your public
  94  * cairo_<foo>_surface_create(). The paginated backend will be careful
  95  * to not let the user see that they really got a "wrapped"
  96  * surface. See test-paginated-surface.c for a fairly minimal example
  97  * of a paginated-using surface. That should be a reasonable example
  98  * to follow.
  99  *
 100  * What the paginated surface does is first save all drawing
 101  * operations for a page into a recording-surface. Then when the user calls
 102  * cairo_show_page(), the paginated surface performs the following
 103  * sequence of operations (using the backend functions passed to
 104  * cairo_paginated_surface_create()):
 105  *
 106  * 1. Calls start_page() (if not %NULL). At this point, it is appropriate
 107  *    for the target to emit any page-specific header information into
 108  *    its output.
 109  *
 110  * 2. Calls set_paginated_mode() with an argument of %CAIRO_PAGINATED_MODE_ANALYZE
 111  *
 112  * 3. Replays the recording-surface to the target surface, (with an
 113  *    analysis surface inserted between which watches the return value
 114  *    from each operation). This analysis stage is used to decide which
 115  *    operations will require fallbacks.
 116  *
 117  * 4. Calls set_bounding_box() to provide the target surface with the
 118  *    tight bounding box of the page.
 119  *
 120  * 5. Calls set_paginated_mode() with an argument of %CAIRO_PAGINATED_MODE_RENDER
 121  *
 122  * 6. Replays a subset of the recording-surface operations to the target surface
 123  *
 124  * 7. Calls set_paginated_mode() with an argument of %CAIRO_PAGINATED_MODE_FALLBACK
 125  *
 126  * 8. Replays the remaining operations to an image surface, sets an
 127  *    appropriate clip on the target, then paints the resulting image
 128  *    surface to the target.
 129  *
 130  * So, the target will see drawing operations during three separate
 131  * stages, (ANALYZE, RENDER and FALLBACK). During the ANALYZE phase
 132  * the target should not actually perform any rendering, (for example,
 133  * if performing output to a file, no output should be generated
 134  * during this stage). Instead the drawing functions simply need to
 135  * return %CAIRO_STATUS_SUCCESS or %CAIRO_INT_STATUS_UNSUPPORTED to
 136  * indicate whether rendering would be supported. And it should do
 137  * this as quickly as possible. The FALLBACK phase allows the surface
 138  * to distinguish fallback images from native rendering in case they
 139  * need to be handled as a special case.
 140  *
 141  * Note: The paginated surface layer assumes that the target surface
 142  * is "blank" by default at the beginning of each page, without any
 143  * need for an explicit erase operation, (as opposed to an image
 144  * surface, for example, which might have uninitialized content
 145  * originally). As such, it optimizes away CLEAR operations that
 146  * happen at the beginning of each page---the target surface will not
 147  * even see these operations.
 148  */
 149 cairo_private cairo_surface_t *
 150 _cairo_paginated_surface_create (cairo_surface_t                                *target,
 151                                  cairo_content_t                                 content,
 152                                  const cairo_paginated_surface_backend_t        *backend);
 153
 154 cairo_private cairo_surface_t *
 155 _cairo_paginated_surface_get_target (cairo_surface_t *surface);
 156
 157 cairo_private cairo_surface_t *
 158 _cairo_paginated_surface_get_recording (cairo_surface_t *surface);
 159
 160 cairo_private cairo_bool_t
 161 _cairo_surface_is_paginated (cairo_surface_t *surface);
 162
 163 cairo_private cairo_status_t
 164 _cairo_paginated_surface_set_size (cairo_surface_t      *surface,
 165                                    int                   width,
 166                                    int                   height);
 167
 168 #endif /* CAIRO_PAGINATED_H */