0,0 → 1,165 |
/* cairo - a vector graphics library with display and print output |
* |
* Copyright © 2005 Red Hat, Inc |
* |
* This library is free software; you can redistribute it and/or |
* modify it either under the terms of the GNU Lesser General Public |
* License version 2.1 as published by the Free Software Foundation |
* (the "LGPL") or, at your option, under the terms of the Mozilla |
* Public License Version 1.1 (the "MPL"). If you do not alter this |
* notice, a recipient may use your version of this file under either |
* the MPL or the LGPL. |
* |
* You should have received a copy of the LGPL along with this library |
* in the file COPYING-LGPL-2.1; if not, write to the Free Software |
* Foundation, Inc., 51 Franklin Street, Suite 500, Boston, MA 02110-1335, USA |
* You should have received a copy of the MPL along with this library |
* in the file COPYING-MPL-1.1 |
* |
* The contents of this file are subject to the Mozilla Public License |
* Version 1.1 (the "License"); you may not use this file except in |
* compliance with the License. You may obtain a copy of the License at |
* http://www.mozilla.org/MPL/ |
* |
* This software is distributed on an "AS IS" basis, WITHOUT WARRANTY |
* OF ANY KIND, either express or implied. See the LGPL or the MPL for |
* the specific language governing rights and limitations. |
* |
* The Original Code is the cairo graphics library. |
* |
* The Initial Developer of the Original Code is Red Hat, Inc. |
* |
* Contributor(s): |
* Carl Worth <cworth@cworth.org> |
*/ |
|
#ifndef CAIRO_PAGINATED_H |
#define CAIRO_PAGINATED_H |
|
#include "cairoint.h" |
|
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_warn 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); |
|
/* Optional. Specifies the smallest box that encloses all objects |
* on the page. Will be called at the end of the ANALYZE phase but |
* before the mode is changed to RENDER. |
*/ |
cairo_warn cairo_int_status_t |
(*set_bounding_box) (void *surface, |
cairo_box_t *bbox); |
|
/* Optional. Indicates whether the page requires fallback images. |
* Will be called at the end of the ANALYZE phase but before the |
* mode is changed to RENDER. |
*/ |
cairo_warn cairo_int_status_t |
(*set_fallback_images_required) (void *surface, |
cairo_bool_t fallbacks_required); |
|
cairo_bool_t |
(*supports_fine_grained_fallbacks) (void *surface); |
}; |
|
/* A #cairo_paginated_surface_t 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). |
* |
* To use the paginated surface, you'll first need to create your |
* 'real' surface using _cairo_surface_init() and the standard |
* #cairo_surface_backend_t. Then you also call |
* _cairo_paginated_surface_create which takes its own, much simpler, |
* #cairo_paginated_surface_backend_t. You are free to return the result |
* of _cairo_paginated_surface_create() from your public |
* cairo_<foo>_surface_create(). The paginated backend will be careful |
* to not let the user see that they really got a "wrapped" |
* surface. See test-paginated-surface.c for a fairly minimal example |
* of a paginated-using surface. That should be a reasonable example |
* to follow. |
* |
* What the paginated surface does is first save all drawing |
* operations for a page into a recording-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 not %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 recording-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_bounding_box() to provide the target surface with the |
* tight bounding box of the page. |
* |
* 5. Calls set_paginated_mode() with an argument of %CAIRO_PAGINATED_MODE_RENDER |
* |
* 6. Replays a subset of the recording-surface operations to the target surface |
* |
* 7. Calls set_paginated_mode() with an argument of %CAIRO_PAGINATED_MODE_FALLBACK |
* |
* 8. 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 three separate |
* stages, (ANALYZE, RENDER and FALLBACK). 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. The FALLBACK phase allows the surface |
* to distinguish fallback images from native rendering in case they |
* need to be handled as a special case. |
* |
* Note: The paginated surface layer assumes that the target surface |
* is "blank" by default at the beginning of each page, without any |
* need for an explicit erase operation, (as opposed to an image |
* surface, for example, which might have uninitialized content |
* originally). As such, it optimizes away CLEAR operations that |
* happen at the beginning of each page---the target surface will not |
* even see these operations. |
*/ |
cairo_private cairo_surface_t * |
_cairo_paginated_surface_create (cairo_surface_t *target, |
cairo_content_t content, |
const cairo_paginated_surface_backend_t *backend); |
|
cairo_private cairo_surface_t * |
_cairo_paginated_surface_get_target (cairo_surface_t *surface); |
|
cairo_private cairo_bool_t |
_cairo_surface_is_paginated (cairo_surface_t *surface); |
|
cairo_private cairo_status_t |
_cairo_paginated_surface_set_size (cairo_surface_t *surface, |
int width, |
int height); |
|
#endif /* CAIRO_PAGINATED_H */ |