Subversion Repositories Scribus

Rev

Rev 14952 | Details | Compare with Previous | Last modification | View Log | RSS feed

Rev Author Line No. Line
14952 fschmid 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
18122 mrdocs 15
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
14952 fschmid 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 meta-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 meta-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 meta-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_bool_t
158
_cairo_surface_is_paginated (cairo_surface_t *surface);
159
 
160
cairo_private cairo_status_t
161
_cairo_paginated_surface_set_size (cairo_surface_t      *surface,
162
                                   int                   width,
163
                                   int                   height);
164
 
165
#endif /* CAIRO_PAGINATED_H */