1 /* -*- Mode: c; tab-width: 8; c-basic-offset: 4; indent-tabs-mode: t; -*- */
2 /* cairo - a vector graphics library with display and print output
4 * Copyright © 2002 University of Southern California
5 * Copyright © 2005 Red Hat, Inc.
7 * This library is free software; you can redistribute it and/or
8 * modify it either under the terms of the GNU Lesser General Public
9 * License version 2.1 as published by the Free Software Foundation
10 * (the "LGPL") or, at your option, under the terms of the Mozilla
11 * Public License Version 1.1 (the "MPL"). If you do not alter this
12 * notice, a recipient may use your version of this file under either
13 * the MPL or the LGPL.
15 * You should have received a copy of the LGPL along with this library
16 * in the file COPYING-LGPL-2.1; if not, write to the Free Software
17 * Foundation, Inc., 51 Franklin Street, Suite 500, Boston, MA 02110-1335, USA
18 * You should have received a copy of the MPL along with this library
19 * in the file COPYING-MPL-1.1
21 * The contents of this file are subject to the Mozilla Public License
22 * Version 1.1 (the "License"); you may not use this file except in
23 * compliance with the License. You may obtain a copy of the License at
24 * http://www.mozilla.org/MPL/
26 * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY
27 * OF ANY KIND, either express or implied. See the LGPL or the MPL for
28 * the specific language governing rights and limitations.
30 * The Original Code is the cairo graphics library.
32 * The Initial Developer of the Original Code is University of Southern
36 * Carl D. Worth <cworth@cworth.org>
41 #include "cairo-array-private.h"
42 #include "cairo-clip-inline.h"
43 #include "cairo-clip-private.h"
44 #include "cairo-damage-private.h"
45 #include "cairo-device-private.h"
46 #include "cairo-error-private.h"
47 #include "cairo-list-inline.h"
48 #include "cairo-image-surface-inline.h"
49 #include "cairo-recording-surface-private.h"
50 #include "cairo-region-private.h"
51 #include "cairo-surface-inline.h"
52 #include "cairo-tee-surface-private.h"
55 * SECTION:cairo-surface
56 * @Title: cairo_surface_t
57 * @Short_Description: Base class for surfaces
58 * @See_Also: #cairo_t, #cairo_pattern_t
60 * #cairo_surface_t is the abstract type representing all different drawing
61 * targets that cairo can render to. The actual drawings are
62 * performed using a cairo <firstterm>context</firstterm>.
64 * A cairo surface is created by using <firstterm>backend</firstterm>-specific
65 * constructors, typically of the form
66 * <function>cairo_<emphasis>backend</emphasis>_surface_create(<!-- -->)</function>.
68 * Most surface types allow accessing the surface without using Cairo
69 * functions. If you do this, keep in mind that it is mandatory that you call
70 * cairo_surface_flush() before reading from or writing to the surface and that
71 * you must use cairo_surface_mark_dirty() after modifying it.
73 * <title>Directly modifying an image surface</title>
76 * modify_image_surface (cairo_surface_t *surface)
78 * unsigned char *data;
79 * int width, height, stride;
81 * // flush to ensure all writing to the image was done
82 * cairo_surface_flush (surface);
85 * data = cairo_image_surface_get_data (surface);
86 * width = cairo_image_surface_get_width (surface);
87 * height = cairo_image_surface_get_height (surface);
88 * stride = cairo_image_surface_get_stride (surface);
89 * modify_image_data (data, width, height, stride);
91 * // mark the image dirty so Cairo clears its caches.
92 * cairo_surface_mark_dirty (surface);
96 * Note that for other surface types it might be necessary to acquire the
97 * surface's device first. See cairo_device_acquire() for a discussion of
101 #define DEFINE_NIL_SURFACE(status, name) \
102 const cairo_surface_t name = { \
103 NULL, /* backend */ \
105 CAIRO_SURFACE_TYPE_IMAGE, /* type */ \
106 CAIRO_CONTENT_COLOR, /* content */ \
107 CAIRO_REFERENCE_COUNT_INVALID, /* ref_count */ \
108 status, /* status */ \
112 FALSE, /* _finishing */ \
113 FALSE, /* finished */ \
114 TRUE, /* is_clear */ \
115 FALSE, /* has_font_options */ \
116 FALSE, /* owns_device */ \
117 { 0, 0, 0, NULL, }, /* user_data */ \
118 { 0, 0, 0, NULL, }, /* mime_data */ \
119 { 1.0, 0.0, 0.0, 1.0, 0.0, 0.0 }, /* device_transform */ \
120 { 1.0, 0.0, 0.0, 1.0, 0.0, 0.0 }, /* device_transform_inverse */ \
121 { NULL, NULL }, /* device_transform_observers */ \
122 0.0, /* x_resolution */ \
123 0.0, /* y_resolution */ \
124 0.0, /* x_fallback_resolution */ \
125 0.0, /* y_fallback_resolution */ \
126 NULL, /* snapshot_of */ \
127 NULL, /* snapshot_detach */ \
128 { NULL, NULL }, /* snapshots */ \
129 { NULL, NULL }, /* snapshot */ \
130 { CAIRO_ANTIALIAS_DEFAULT, /* antialias */ \
131 CAIRO_SUBPIXEL_ORDER_DEFAULT, /* subpixel_order */ \
132 CAIRO_LCD_FILTER_DEFAULT, /* lcd_filter */ \
133 CAIRO_HINT_STYLE_DEFAULT, /* hint_style */ \
134 CAIRO_HINT_METRICS_DEFAULT, /* hint_metrics */ \
135 CAIRO_ROUND_GLYPH_POS_DEFAULT /* round_glyph_positions */ \
136 } /* font_options */ \
139 /* XXX error object! */
141 static DEFINE_NIL_SURFACE(CAIRO_STATUS_NO_MEMORY
, _cairo_surface_nil
);
142 static DEFINE_NIL_SURFACE(CAIRO_STATUS_SURFACE_TYPE_MISMATCH
, _cairo_surface_nil_surface_type_mismatch
);
143 static DEFINE_NIL_SURFACE(CAIRO_STATUS_INVALID_STATUS
, _cairo_surface_nil_invalid_status
);
144 static DEFINE_NIL_SURFACE(CAIRO_STATUS_INVALID_CONTENT
, _cairo_surface_nil_invalid_content
);
145 static DEFINE_NIL_SURFACE(CAIRO_STATUS_INVALID_FORMAT
, _cairo_surface_nil_invalid_format
);
146 static DEFINE_NIL_SURFACE(CAIRO_STATUS_INVALID_VISUAL
, _cairo_surface_nil_invalid_visual
);
147 static DEFINE_NIL_SURFACE(CAIRO_STATUS_FILE_NOT_FOUND
, _cairo_surface_nil_file_not_found
);
148 static DEFINE_NIL_SURFACE(CAIRO_STATUS_TEMP_FILE_ERROR
, _cairo_surface_nil_temp_file_error
);
149 static DEFINE_NIL_SURFACE(CAIRO_STATUS_READ_ERROR
, _cairo_surface_nil_read_error
);
150 static DEFINE_NIL_SURFACE(CAIRO_STATUS_WRITE_ERROR
, _cairo_surface_nil_write_error
);
151 static DEFINE_NIL_SURFACE(CAIRO_STATUS_INVALID_STRIDE
, _cairo_surface_nil_invalid_stride
);
152 static DEFINE_NIL_SURFACE(CAIRO_STATUS_INVALID_SIZE
, _cairo_surface_nil_invalid_size
);
153 static DEFINE_NIL_SURFACE(CAIRO_STATUS_DEVICE_TYPE_MISMATCH
, _cairo_surface_nil_device_type_mismatch
);
154 static DEFINE_NIL_SURFACE(CAIRO_STATUS_DEVICE_ERROR
, _cairo_surface_nil_device_error
);
156 static DEFINE_NIL_SURFACE(CAIRO_INT_STATUS_UNSUPPORTED
, _cairo_surface_nil_unsupported
);
157 static DEFINE_NIL_SURFACE(CAIRO_INT_STATUS_NOTHING_TO_DO
, _cairo_surface_nil_nothing_to_do
);
159 static void _cairo_surface_finish_snapshots (cairo_surface_t
*surface
);
160 static void _cairo_surface_finish (cairo_surface_t
*surface
);
163 * _cairo_surface_set_error:
164 * @surface: a surface
165 * @status: a status value indicating an error
167 * Atomically sets surface->status to @status and calls _cairo_error;
168 * Does nothing if status is %CAIRO_STATUS_SUCCESS or any of the internal
171 * All assignments of an error status to surface->status should happen
172 * through _cairo_surface_set_error(). Note that due to the nature of
173 * the atomic operation, it is not safe to call this function on the
176 * The purpose of this function is to allow the user to set a
177 * breakpoint in _cairo_error() to generate a stack trace for when the
178 * user causes cairo to detect an error.
180 * Return value: the error status.
183 _cairo_surface_set_error (cairo_surface_t
*surface
,
184 cairo_int_status_t status
)
186 /* NOTHING_TO_DO is magic. We use it to break out of the inner-most
187 * surface function, but anything higher just sees "success".
189 if (status
== CAIRO_INT_STATUS_NOTHING_TO_DO
)
190 status
= CAIRO_INT_STATUS_SUCCESS
;
192 if (status
== CAIRO_INT_STATUS_SUCCESS
||
193 status
>= (int)CAIRO_INT_STATUS_LAST_STATUS
)
196 /* Don't overwrite an existing error. This preserves the first
197 * error, which is the most significant. */
198 _cairo_status_set_error (&surface
->status
, (cairo_status_t
)status
);
200 return _cairo_error (status
);
204 * cairo_surface_get_type:
205 * @surface: a #cairo_surface_t
207 * This function returns the type of the backend used to create
208 * a surface. See #cairo_surface_type_t for available types.
210 * Return value: The type of @surface.
215 cairo_surface_get_type (cairo_surface_t
*surface
)
217 /* We don't use surface->backend->type here so that some of the
218 * special "wrapper" surfaces such as cairo_paginated_surface_t
219 * can override surface->type with the type of the "child"
221 return surface
->type
;
225 * cairo_surface_get_content:
226 * @surface: a #cairo_surface_t
228 * This function returns the content type of @surface which indicates
229 * whether the surface contains color and/or alpha information. See
232 * Return value: The content type of @surface.
237 cairo_surface_get_content (cairo_surface_t
*surface
)
239 return surface
->content
;
243 * cairo_surface_status:
244 * @surface: a #cairo_surface_t
246 * Checks whether an error has previously occurred for this
249 * Return value: %CAIRO_STATUS_SUCCESS, %CAIRO_STATUS_NULL_POINTER,
250 * %CAIRO_STATUS_NO_MEMORY, %CAIRO_STATUS_READ_ERROR,
251 * %CAIRO_STATUS_INVALID_CONTENT, %CAIRO_STATUS_INVALID_FORMAT, or
252 * %CAIRO_STATUS_INVALID_VISUAL.
257 cairo_surface_status (cairo_surface_t
*surface
)
259 return surface
->status
;
261 slim_hidden_def (cairo_surface_status
);
264 _cairo_surface_allocate_unique_id (void)
266 static cairo_atomic_int_t unique_id
;
269 if (++unique_id
== 0)
273 cairo_atomic_int_t old
, id
;
276 old
= _cairo_atomic_uint_get (&unique_id
);
280 } while (! _cairo_atomic_uint_cmpxchg (&unique_id
, old
, id
));
287 * cairo_surface_get_device:
288 * @surface: a #cairo_surface_t
290 * This function returns the device for a @surface.
291 * See #cairo_device_t.
293 * Return value: The device for @surface or %NULL if the surface does
294 * not have an associated device.
299 cairo_surface_get_device (cairo_surface_t
*surface
)
301 if (unlikely (surface
->status
))
302 return _cairo_device_create_in_error (surface
->status
);
304 return surface
->device
;
308 _cairo_surface_has_snapshots (cairo_surface_t
*surface
)
310 return ! cairo_list_is_empty (&surface
->snapshots
);
314 _cairo_surface_has_mime_data (cairo_surface_t
*surface
)
316 return surface
->mime_data
.num_elements
!= 0;
320 _cairo_surface_detach_mime_data (cairo_surface_t
*surface
)
322 if (! _cairo_surface_has_mime_data (surface
))
325 _cairo_user_data_array_fini (&surface
->mime_data
);
326 _cairo_user_data_array_init (&surface
->mime_data
);
330 _cairo_surface_detach_snapshots (cairo_surface_t
*surface
)
332 while (_cairo_surface_has_snapshots (surface
)) {
333 _cairo_surface_detach_snapshot (cairo_list_first_entry (&surface
->snapshots
,
340 _cairo_surface_detach_snapshot (cairo_surface_t
*snapshot
)
342 assert (snapshot
->snapshot_of
!= NULL
);
344 snapshot
->snapshot_of
= NULL
;
345 cairo_list_del (&snapshot
->snapshot
);
347 if (snapshot
->snapshot_detach
!= NULL
)
348 snapshot
->snapshot_detach (snapshot
);
350 cairo_surface_destroy (snapshot
);
354 _cairo_surface_attach_snapshot (cairo_surface_t
*surface
,
355 cairo_surface_t
*snapshot
,
356 cairo_surface_func_t detach_func
)
358 assert (surface
!= snapshot
);
359 assert (snapshot
->snapshot_of
!= surface
);
361 cairo_surface_reference (snapshot
);
363 if (snapshot
->snapshot_of
!= NULL
)
364 _cairo_surface_detach_snapshot (snapshot
);
366 snapshot
->snapshot_of
= surface
;
367 snapshot
->snapshot_detach
= detach_func
;
369 cairo_list_add (&snapshot
->snapshot
, &surface
->snapshots
);
371 assert (_cairo_surface_has_snapshot (surface
, snapshot
->backend
) == snapshot
);
375 _cairo_surface_has_snapshot (cairo_surface_t
*surface
,
376 const cairo_surface_backend_t
*backend
)
378 cairo_surface_t
*snapshot
;
380 cairo_list_foreach_entry (snapshot
, cairo_surface_t
,
381 &surface
->snapshots
, snapshot
)
383 if (snapshot
->backend
== backend
)
391 _cairo_surface_begin_modification (cairo_surface_t
*surface
)
393 assert (surface
->status
== CAIRO_STATUS_SUCCESS
);
394 assert (! surface
->finished
);
396 return _cairo_surface_flush (surface
, 1);
400 _cairo_surface_init (cairo_surface_t
*surface
,
401 const cairo_surface_backend_t
*backend
,
402 cairo_device_t
*device
,
403 cairo_content_t content
)
405 CAIRO_MUTEX_INITIALIZE ();
407 surface
->backend
= backend
;
408 surface
->device
= cairo_device_reference (device
);
409 surface
->content
= content
;
410 surface
->type
= backend
->type
;
412 CAIRO_REFERENCE_COUNT_INIT (&surface
->ref_count
, 1);
413 surface
->status
= CAIRO_STATUS_SUCCESS
;
414 surface
->unique_id
= _cairo_surface_allocate_unique_id ();
415 surface
->finished
= FALSE
;
416 surface
->_finishing
= FALSE
;
417 surface
->is_clear
= FALSE
;
419 surface
->damage
= NULL
;
420 surface
->owns_device
= (device
!= NULL
);
422 _cairo_user_data_array_init (&surface
->user_data
);
423 _cairo_user_data_array_init (&surface
->mime_data
);
425 cairo_matrix_init_identity (&surface
->device_transform
);
426 cairo_matrix_init_identity (&surface
->device_transform_inverse
);
427 cairo_list_init (&surface
->device_transform_observers
);
429 surface
->x_resolution
= CAIRO_SURFACE_RESOLUTION_DEFAULT
;
430 surface
->y_resolution
= CAIRO_SURFACE_RESOLUTION_DEFAULT
;
432 surface
->x_fallback_resolution
= CAIRO_SURFACE_FALLBACK_RESOLUTION_DEFAULT
;
433 surface
->y_fallback_resolution
= CAIRO_SURFACE_FALLBACK_RESOLUTION_DEFAULT
;
435 cairo_list_init (&surface
->snapshots
);
436 surface
->snapshot_of
= NULL
;
438 surface
->has_font_options
= FALSE
;
442 _cairo_surface_copy_similar_properties (cairo_surface_t
*surface
,
443 cairo_surface_t
*other
)
445 if (other
->has_font_options
|| other
->backend
!= surface
->backend
) {
446 cairo_font_options_t options
;
448 cairo_surface_get_font_options (other
, &options
);
449 _cairo_surface_set_font_options (surface
, &options
);
452 cairo_surface_set_fallback_resolution (surface
,
453 other
->x_fallback_resolution
,
454 other
->y_fallback_resolution
);
458 * cairo_surface_create_similar:
459 * @other: an existing surface used to select the backend of the new surface
460 * @content: the content for the new surface
461 * @width: width of the new surface, (in device-space units)
462 * @height: height of the new surface (in device-space units)
464 * Create a new surface that is as compatible as possible with an
465 * existing surface. For example the new surface will have the same
466 * fallback resolution and font options as @other. Generally, the new
467 * surface will also use the same backend as @other, unless that is
468 * not possible for some reason. The type of the returned surface may
469 * be examined with cairo_surface_get_type().
471 * Initially the surface contents are all 0 (transparent if contents
472 * have transparency, black otherwise.)
474 * Use cairo_surface_create_similar_image() if you need an image surface
475 * which can be painted quickly to the target surface.
477 * Return value: a pointer to the newly allocated surface. The caller
478 * owns the surface and should call cairo_surface_destroy() when done
481 * This function always returns a valid pointer, but it will return a
482 * pointer to a "nil" surface if @other is already in an error state
483 * or any other error occurs.
488 cairo_surface_create_similar (cairo_surface_t
*other
,
489 cairo_content_t content
,
493 cairo_surface_t
*surface
;
494 cairo_status_t status
;
495 cairo_solid_pattern_t pattern
;
497 if (unlikely (other
->status
))
498 return _cairo_surface_create_in_error (other
->status
);
499 if (unlikely (other
->finished
))
500 return _cairo_surface_create_in_error (CAIRO_STATUS_SURFACE_FINISHED
);
501 if (unlikely (width
< 0 || height
< 0))
502 return _cairo_surface_create_in_error (CAIRO_STATUS_INVALID_SIZE
);
504 if (unlikely (! CAIRO_CONTENT_VALID (content
)))
505 return _cairo_surface_create_in_error (CAIRO_STATUS_INVALID_CONTENT
);
507 if (unlikely (other
->status
))
508 return _cairo_surface_create_in_error (other
->status
);
510 /* We inherit the device scale, so create a larger surface */
511 width
= width
* other
->device_transform
.xx
;
512 height
= height
* other
->device_transform
.yy
;
515 if (other
->backend
->create_similar
)
516 surface
= other
->backend
->create_similar (other
, content
, width
, height
);
518 surface
= cairo_surface_create_similar_image (other
,
519 _cairo_format_from_content (content
),
522 if (unlikely (surface
->status
))
525 _cairo_surface_copy_similar_properties (surface
, other
);
526 cairo_surface_set_device_scale (surface
,
527 other
->device_transform
.xx
,
528 other
->device_transform
.yy
);
530 if (unlikely (surface
->status
))
533 _cairo_pattern_init_solid (&pattern
, CAIRO_COLOR_TRANSPARENT
);
534 status
= _cairo_surface_paint (surface
,
535 CAIRO_OPERATOR_CLEAR
,
536 &pattern
.base
, NULL
);
537 if (unlikely (status
)) {
538 cairo_surface_destroy (surface
);
539 surface
= _cairo_surface_create_in_error (status
);
542 assert (surface
->is_clear
);
548 * cairo_surface_create_similar_image:
549 * @other: an existing surface used to select the preference of the new surface
550 * @format: the format for the new surface
551 * @width: width of the new surface, (in device-space units)
552 * @height: height of the new surface (in device-space units)
554 * Create a new image surface that is as compatible as possible for uploading
555 * to and the use in conjunction with an existing surface. However, this surface
556 * can still be used like any normal image surface.
558 * Initially the surface contents are all 0 (transparent if contents
559 * have transparency, black otherwise.)
561 * Use cairo_surface_create_similar() if you don't need an image surface.
563 * Return value: a pointer to the newly allocated image surface. The caller
564 * owns the surface and should call cairo_surface_destroy() when done
567 * This function always returns a valid pointer, but it will return a
568 * pointer to a "nil" surface if @other is already in an error state
569 * or any other error occurs.
574 cairo_surface_create_similar_image (cairo_surface_t
*other
,
575 cairo_format_t format
,
579 cairo_surface_t
*image
;
581 if (unlikely (other
->status
))
582 return _cairo_surface_create_in_error (other
->status
);
583 if (unlikely (other
->finished
))
584 return _cairo_surface_create_in_error (CAIRO_STATUS_SURFACE_FINISHED
);
586 if (unlikely (width
< 0 || height
< 0))
587 return _cairo_surface_create_in_error (CAIRO_STATUS_INVALID_SIZE
);
588 if (unlikely (! CAIRO_FORMAT_VALID (format
)))
589 return _cairo_surface_create_in_error (CAIRO_STATUS_INVALID_FORMAT
);
592 if (other
->backend
->create_similar_image
)
593 image
= other
->backend
->create_similar_image (other
,
594 format
, width
, height
);
596 image
= cairo_image_surface_create (format
, width
, height
);
598 assert (image
->is_clear
);
602 slim_hidden_def (cairo_surface_create_similar_image
);
605 * _cairo_surface_map_to_image:
606 * @surface: an existing surface used to extract the image from
607 * @extents: limit the extraction to an rectangular region
609 * Returns an image surface that is the most efficient mechanism for
610 * modifying the backing store of the target surface. The region
611 * retrieved is limited to @extents.
613 * Note, the use of the original surface as a target or source whilst
614 * it is mapped is undefined. The result of mapping the surface
615 * multiple times is undefined. Calling cairo_surface_destroy() or
616 * cairo_surface_finish() on the resulting image surface results in
617 * undefined behavior. Changing the device transform of the image
618 * surface or of @surface before the image surface is unmapped results
619 * in undefined behavior.
621 * Assumes that @surface is valid (CAIRO_STATUS_SUCCESS,
624 * Return value: a pointer to the newly allocated image surface. The
625 * caller must use _cairo_surface_unmap_image() to destroy this image
628 * This function always returns a valid pointer, but it will return a
629 * pointer to a "nil" surface if @other is already in an error state
630 * or any other error occurs.
632 * The returned image might have a %CAIRO_FORMAT_INVALID format.
634 cairo_image_surface_t
*
635 _cairo_surface_map_to_image (cairo_surface_t
*surface
,
636 const cairo_rectangle_int_t
*extents
)
638 cairo_image_surface_t
*image
= NULL
;
640 assert (extents
!= NULL
);
642 /* TODO: require map_to_image != NULL */
643 if (surface
->backend
->map_to_image
)
644 image
= surface
->backend
->map_to_image (surface
, extents
);
647 image
= _cairo_image_surface_clone_subimage (surface
, extents
);
653 * _cairo_surface_unmap_image:
654 * @surface: the surface passed to _cairo_surface_map_to_image().
655 * @image: the currently mapped image
657 * Unmaps the image surface as returned from
658 * _cairo_surface_map_to_image().
660 * The content of the image will be uploaded to the target surface.
661 * Afterwards, the image is destroyed.
663 * Using an image surface which wasn't returned by
664 * _cairo_surface_map_to_image() results in undefined behavior.
666 * An image surface in error status can be passed to
667 * _cairo_surface_unmap_image().
669 * Return value: the unmap status.
671 * Even if the unmap status is not successful, @image is destroyed.
674 _cairo_surface_unmap_image (cairo_surface_t
*surface
,
675 cairo_image_surface_t
*image
)
677 cairo_surface_pattern_t pattern
;
678 cairo_rectangle_int_t extents
;
680 cairo_int_status_t status
;
682 /* map_to_image can return error surfaces */
683 if (unlikely (image
->base
.status
)) {
684 status
= image
->base
.status
;
688 /* If the image is untouched just skip the update */
689 if (image
->base
.serial
== 0) {
690 status
= CAIRO_STATUS_SUCCESS
;
694 /* TODO: require unmap_image != NULL */
695 if (surface
->backend
->unmap_image
&&
696 ! _cairo_image_surface_is_clone (image
))
698 status
= surface
->backend
->unmap_image (surface
, image
);
699 if (status
!= CAIRO_INT_STATUS_UNSUPPORTED
)
703 _cairo_pattern_init_for_surface (&pattern
, &image
->base
);
704 pattern
.base
.filter
= CAIRO_FILTER_NEAREST
;
706 /* We have to apply the translate from map_to_image's extents.x and .y */
707 cairo_matrix_init_translate (&pattern
.base
.matrix
,
708 image
->base
.device_transform
.x0
,
709 image
->base
.device_transform
.y0
);
711 /* And we also have to clip the operation to the image's extents */
712 extents
.x
= image
->base
.device_transform_inverse
.x0
;
713 extents
.y
= image
->base
.device_transform_inverse
.y0
;
714 extents
.width
= image
->width
;
715 extents
.height
= image
->height
;
716 clip
= _cairo_clip_intersect_rectangle (NULL
, &extents
);
718 status
= _cairo_surface_paint (surface
,
719 CAIRO_OPERATOR_SOURCE
,
723 _cairo_pattern_fini (&pattern
.base
);
724 _cairo_clip_destroy (clip
);
727 cairo_surface_finish (&image
->base
);
728 cairo_surface_destroy (&image
->base
);
734 * cairo_surface_map_to_image:
735 * @surface: an existing surface used to extract the image from
736 * @extents: limit the extraction to an rectangular region
738 * Returns an image surface that is the most efficient mechanism for
739 * modifying the backing store of the target surface. The region retrieved
740 * may be limited to the @extents or %NULL for the whole surface
742 * Note, the use of the original surface as a target or source whilst
743 * it is mapped is undefined. The result of mapping the surface
744 * multiple times is undefined. Calling cairo_surface_destroy() or
745 * cairo_surface_finish() on the resulting image surface results in
746 * undefined behavior. Changing the device transform of the image
747 * surface or of @surface before the image surface is unmapped results
748 * in undefined behavior.
750 * Return value: a pointer to the newly allocated image surface. The caller
751 * must use cairo_surface_unmap_image() to destroy this image surface.
753 * This function always returns a valid pointer, but it will return a
754 * pointer to a "nil" surface if @other is already in an error state
755 * or any other error occurs. If the returned pointer does not have an
756 * error status, it is guaranteed to be an image surface whose format
757 * is not %CAIRO_FORMAT_INVALID.
762 cairo_surface_map_to_image (cairo_surface_t
*surface
,
763 const cairo_rectangle_int_t
*extents
)
765 cairo_rectangle_int_t rect
;
766 cairo_image_surface_t
*image
;
767 cairo_status_t status
;
769 if (unlikely (surface
->status
))
770 return _cairo_surface_create_in_error (surface
->status
);
771 if (unlikely (surface
->finished
))
772 return _cairo_surface_create_in_error (CAIRO_STATUS_SURFACE_FINISHED
);
774 if (extents
== NULL
) {
775 if (unlikely (! surface
->backend
->get_extents (surface
, &rect
)))
776 return _cairo_surface_create_in_error (CAIRO_STATUS_INVALID_SIZE
);
780 cairo_rectangle_int_t surface_extents
;
782 /* If this surface is bounded, we can't map parts
783 * that are outside of it. */
784 if (likely (surface
->backend
->get_extents (surface
, &surface_extents
))) {
785 if (unlikely (! _cairo_rectangle_contains_rectangle (&surface_extents
, extents
)))
786 return _cairo_surface_create_in_error (CAIRO_STATUS_INVALID_SIZE
);
790 image
= _cairo_surface_map_to_image (surface
, extents
);
792 status
= image
->base
.status
;
793 if (unlikely (status
)) {
794 cairo_surface_destroy (&image
->base
);
795 return _cairo_surface_create_in_error (status
);
798 if (image
->format
== CAIRO_FORMAT_INVALID
) {
799 cairo_surface_destroy (&image
->base
);
800 image
= _cairo_image_surface_clone_subimage (surface
, extents
);
807 * cairo_surface_unmap_image:
808 * @surface: the surface passed to cairo_surface_map_to_image().
809 * @image: the currently mapped image
811 * Unmaps the image surface as returned from #cairo_surface_map_to_image().
813 * The content of the image will be uploaded to the target surface.
814 * Afterwards, the image is destroyed.
816 * Using an image surface which wasn't returned by cairo_surface_map_to_image()
817 * results in undefined behavior.
822 cairo_surface_unmap_image (cairo_surface_t
*surface
,
823 cairo_surface_t
*image
)
825 cairo_int_status_t status
= CAIRO_STATUS_SUCCESS
;
827 if (unlikely (surface
->status
)) {
828 status
= surface
->status
;
831 if (unlikely (surface
->finished
)) {
832 status
= _cairo_error (CAIRO_STATUS_SURFACE_FINISHED
);
835 if (unlikely (image
->status
)) {
836 status
= image
->status
;
839 if (unlikely (image
->finished
)) {
840 status
= _cairo_error (CAIRO_STATUS_SURFACE_FINISHED
);
843 if (unlikely (! _cairo_surface_is_image (image
))) {
844 status
= _cairo_error (CAIRO_STATUS_SURFACE_TYPE_MISMATCH
);
848 status
= _cairo_surface_unmap_image (surface
,
849 (cairo_image_surface_t
*) image
);
850 if (unlikely (status
))
851 _cairo_surface_set_error (surface
, status
);
856 _cairo_surface_set_error (surface
, status
);
857 cairo_surface_finish (image
);
858 cairo_surface_destroy (image
);
862 _cairo_surface_create_scratch (cairo_surface_t
*other
,
863 cairo_content_t content
,
866 const cairo_color_t
*color
)
868 cairo_surface_t
*surface
;
869 cairo_status_t status
;
870 cairo_solid_pattern_t pattern
;
872 if (unlikely (other
->status
))
873 return _cairo_surface_create_in_error (other
->status
);
876 if (other
->backend
->create_similar
)
877 surface
= other
->backend
->create_similar (other
, content
, width
, height
);
879 surface
= cairo_surface_create_similar_image (other
,
880 _cairo_format_from_content (content
),
883 if (unlikely (surface
->status
))
886 _cairo_surface_copy_similar_properties (surface
, other
);
888 if (unlikely (surface
->status
))
892 _cairo_pattern_init_solid (&pattern
, color
);
893 status
= _cairo_surface_paint (surface
,
894 color
== CAIRO_COLOR_TRANSPARENT
?
895 CAIRO_OPERATOR_CLEAR
: CAIRO_OPERATOR_SOURCE
,
896 &pattern
.base
, NULL
);
897 if (unlikely (status
)) {
898 cairo_surface_destroy (surface
);
899 surface
= _cairo_surface_create_in_error (status
);
907 * cairo_surface_reference:
908 * @surface: a #cairo_surface_t
910 * Increases the reference count on @surface by one. This prevents
911 * @surface from being destroyed until a matching call to
912 * cairo_surface_destroy() is made.
914 * The number of references to a #cairo_surface_t can be get using
915 * cairo_surface_get_reference_count().
917 * Return value: the referenced #cairo_surface_t.
922 cairo_surface_reference (cairo_surface_t
*surface
)
924 if (surface
== NULL
||
925 CAIRO_REFERENCE_COUNT_IS_INVALID (&surface
->ref_count
))
928 assert (CAIRO_REFERENCE_COUNT_HAS_REFERENCE (&surface
->ref_count
));
930 _cairo_reference_count_inc (&surface
->ref_count
);
934 slim_hidden_def (cairo_surface_reference
);
937 * cairo_surface_destroy:
938 * @surface: a #cairo_surface_t
940 * Decreases the reference count on @surface by one. If the result is
941 * zero, then @surface and all associated resources are freed. See
942 * cairo_surface_reference().
947 cairo_surface_destroy (cairo_surface_t
*surface
)
949 if (surface
== NULL
||
950 CAIRO_REFERENCE_COUNT_IS_INVALID (&surface
->ref_count
))
953 assert (CAIRO_REFERENCE_COUNT_HAS_REFERENCE (&surface
->ref_count
));
955 if (! _cairo_reference_count_dec_and_test (&surface
->ref_count
))
958 assert (surface
->snapshot_of
== NULL
);
960 if (! surface
->finished
) {
961 _cairo_surface_finish_snapshots (surface
);
962 /* We may have been referenced by a snapshot prior to have
963 * detaching it with the copy-on-write.
965 if (CAIRO_REFERENCE_COUNT_GET_VALUE (&surface
->ref_count
))
968 _cairo_surface_finish (surface
);
972 _cairo_damage_destroy (surface
->damage
);
974 _cairo_user_data_array_fini (&surface
->user_data
);
975 _cairo_user_data_array_fini (&surface
->mime_data
);
977 if (surface
->owns_device
)
978 cairo_device_destroy (surface
->device
);
980 assert (surface
->snapshot_of
== NULL
);
981 assert (! _cairo_surface_has_snapshots (surface
));
982 /* paranoid check that nobody took a reference whilst finishing */
983 assert (! CAIRO_REFERENCE_COUNT_HAS_REFERENCE (&surface
->ref_count
));
987 slim_hidden_def(cairo_surface_destroy
);
990 * cairo_surface_get_reference_count:
991 * @surface: a #cairo_surface_t
993 * Returns the current reference count of @surface.
995 * Return value: the current reference count of @surface. If the
996 * object is a nil object, 0 will be returned.
1001 cairo_surface_get_reference_count (cairo_surface_t
*surface
)
1003 if (surface
== NULL
||
1004 CAIRO_REFERENCE_COUNT_IS_INVALID (&surface
->ref_count
))
1007 return CAIRO_REFERENCE_COUNT_GET_VALUE (&surface
->ref_count
);
1011 _cairo_surface_finish_snapshots (cairo_surface_t
*surface
)
1013 cairo_status_t status
;
1015 /* update the snapshots *before* we declare the surface as finished */
1016 surface
->_finishing
= TRUE
;
1017 status
= _cairo_surface_flush (surface
, 0);
1022 _cairo_surface_finish (cairo_surface_t
*surface
)
1024 cairo_status_t status
;
1026 surface
->finished
= TRUE
;
1028 /* call finish even if in error mode */
1029 if (surface
->backend
->finish
) {
1030 status
= surface
->backend
->finish (surface
);
1031 if (unlikely (status
))
1032 _cairo_surface_set_error (surface
, status
);
1035 assert (surface
->snapshot_of
== NULL
);
1036 assert (!_cairo_surface_has_snapshots (surface
));
1040 * cairo_surface_finish:
1041 * @surface: the #cairo_surface_t to finish
1043 * This function finishes the surface and drops all references to
1044 * external resources. For example, for the Xlib backend it means
1045 * that cairo will no longer access the drawable, which can be freed.
1046 * After calling cairo_surface_finish() the only valid operations on a
1047 * surface are getting and setting user, referencing and
1048 * destroying, and flushing and finishing it.
1049 * Further drawing to the surface will not affect the
1050 * surface but will instead trigger a %CAIRO_STATUS_SURFACE_FINISHED
1053 * When the last call to cairo_surface_destroy() decreases the
1054 * reference count to zero, cairo will call cairo_surface_finish() if
1055 * it hasn't been called already, before freeing the resources
1056 * associated with the surface.
1061 cairo_surface_finish (cairo_surface_t
*surface
)
1063 if (surface
== NULL
)
1066 if (CAIRO_REFERENCE_COUNT_IS_INVALID (&surface
->ref_count
))
1069 if (surface
->finished
)
1072 /* We have to be careful when decoupling potential reference cycles */
1073 cairo_surface_reference (surface
);
1075 _cairo_surface_finish_snapshots (surface
);
1076 /* XXX need to block and wait for snapshot references */
1077 _cairo_surface_finish (surface
);
1079 cairo_surface_destroy (surface
);
1081 slim_hidden_def (cairo_surface_finish
);
1084 * _cairo_surface_release_device_reference:
1085 * @surface: a #cairo_surface_t
1087 * This function makes @surface release the reference to its device. The
1088 * function is intended to be used for avoiding cycling references for
1089 * surfaces that are owned by their device, for example cache surfaces.
1090 * Note that the @surface will still assume that the device is available.
1091 * So it is the caller's responsibility to ensure the device stays around
1092 * until the @surface is destroyed. Just calling cairo_surface_finish() is
1096 _cairo_surface_release_device_reference (cairo_surface_t
*surface
)
1098 assert (surface
->owns_device
);
1100 cairo_device_destroy (surface
->device
);
1101 surface
->owns_device
= FALSE
;
1105 * cairo_surface_get_user_data:
1106 * @surface: a #cairo_surface_t
1107 * @key: the address of the #cairo_user_data_key_t the user data was
1110 * Return user data previously attached to @surface using the specified
1111 * key. If no user data has been attached with the given key this
1112 * function returns %NULL.
1114 * Return value: the user data previously attached or %NULL.
1119 cairo_surface_get_user_data (cairo_surface_t
*surface
,
1120 const cairo_user_data_key_t
*key
)
1122 /* Prevent reads of the array during teardown */
1123 if (! CAIRO_REFERENCE_COUNT_HAS_REFERENCE (&surface
->ref_count
))
1126 return _cairo_user_data_array_get_data (&surface
->user_data
, key
);
1130 * cairo_surface_set_user_data:
1131 * @surface: a #cairo_surface_t
1132 * @key: the address of a #cairo_user_data_key_t to attach the user data to
1133 * @user_data: the user data to attach to the surface
1134 * @destroy: a #cairo_destroy_func_t which will be called when the
1135 * surface is destroyed or when new user data is attached using the
1138 * Attach user data to @surface. To remove user data from a surface,
1139 * call this function with the key that was used to set it and %NULL
1142 * Return value: %CAIRO_STATUS_SUCCESS or %CAIRO_STATUS_NO_MEMORY if a
1143 * slot could not be allocated for the user data.
1148 cairo_surface_set_user_data (cairo_surface_t
*surface
,
1149 const cairo_user_data_key_t
*key
,
1151 cairo_destroy_func_t destroy
)
1153 if (CAIRO_REFERENCE_COUNT_IS_INVALID (&surface
->ref_count
))
1154 return surface
->status
;
1156 if (! CAIRO_REFERENCE_COUNT_HAS_REFERENCE (&surface
->ref_count
))
1157 return _cairo_error (CAIRO_STATUS_SURFACE_FINISHED
);
1159 return _cairo_user_data_array_set_data (&surface
->user_data
,
1160 key
, user_data
, destroy
);
1164 * cairo_surface_get_mime_data:
1165 * @surface: a #cairo_surface_t
1166 * @mime_type: the mime type of the image data
1167 * @data: the image data to attached to the surface
1168 * @length: the length of the image data
1170 * Return mime data previously attached to @surface using the
1171 * specified mime type. If no data has been attached with the given
1172 * mime type, @data is set %NULL.
1177 cairo_surface_get_mime_data (cairo_surface_t
*surface
,
1178 const char *mime_type
,
1179 const unsigned char **data
,
1180 unsigned long *length
)
1182 cairo_user_data_slot_t
*slots
;
1188 /* Prevent reads of the array during teardown */
1189 if (! CAIRO_REFERENCE_COUNT_HAS_REFERENCE (&surface
->ref_count
))
1192 /* The number of mime-types attached to a surface is usually small,
1193 * typically zero. Therefore it is quicker to do a strcmp() against
1194 * each key than it is to intern the string (i.e. compute a hash,
1195 * search the hash table, and do a final strcmp).
1197 num_slots
= surface
->mime_data
.num_elements
;
1198 slots
= _cairo_array_index (&surface
->mime_data
, 0);
1199 for (i
= 0; i
< num_slots
; i
++) {
1200 if (slots
[i
].key
!= NULL
&& strcmp ((char *) slots
[i
].key
, mime_type
) == 0) {
1201 cairo_mime_data_t
*mime_data
= slots
[i
].user_data
;
1203 *data
= mime_data
->data
;
1204 *length
= mime_data
->length
;
1209 slim_hidden_def (cairo_surface_get_mime_data
);
1212 _cairo_mime_data_destroy (void *ptr
)
1214 cairo_mime_data_t
*mime_data
= ptr
;
1216 if (! _cairo_reference_count_dec_and_test (&mime_data
->ref_count
))
1219 if (mime_data
->destroy
&& mime_data
->closure
)
1220 mime_data
->destroy (mime_data
->closure
);
1226 * CAIRO_MIME_TYPE_JBIG2:
1228 * Joint Bi-level Image Experts Group image coding standard (ISO/IEC 11544).
1234 * CAIRO_MIME_TYPE_JBIG2_GLOBAL:
1236 * Joint Bi-level Image Experts Group image coding standard (ISO/IEC 11544) global segment.
1242 * CAIRO_MIME_TYPE_JBIG2_GLOBAL_ID:
1244 * An unique identifier shared by a JBIG2 global segment and all JBIG2 images
1245 * that depend on the global segment.
1251 * CAIRO_MIME_TYPE_JP2:
1253 * The Joint Photographic Experts Group (JPEG) 2000 image coding standard (ISO/IEC 15444-1).
1259 * CAIRO_MIME_TYPE_JPEG:
1261 * The Joint Photographic Experts Group (JPEG) image coding standard (ISO/IEC 10918-1).
1267 * CAIRO_MIME_TYPE_PNG:
1269 * The Portable Network Graphics image file format (ISO/IEC 15948).
1275 * CAIRO_MIME_TYPE_URI:
1277 * URI for an image file (unofficial MIME type).
1283 * CAIRO_MIME_TYPE_UNIQUE_ID:
1285 * Unique identifier for a surface (cairo specific MIME type). All surfaces with
1286 * the same unique identifier will only be embedded once.
1292 * cairo_surface_set_mime_data:
1293 * @surface: a #cairo_surface_t
1294 * @mime_type: the MIME type of the image data
1295 * @data: the image data to attach to the surface
1296 * @length: the length of the image data
1297 * @destroy: a #cairo_destroy_func_t which will be called when the
1298 * surface is destroyed or when new image data is attached using the
1300 * @closure: the data to be passed to the @destroy notifier
1302 * Attach an image in the format @mime_type to @surface. To remove
1303 * the data from a surface, call this function with same mime type
1304 * and %NULL for @data.
1306 * The attached image (or filename) data can later be used by backends
1307 * which support it (currently: PDF, PS, SVG and Win32 Printing
1308 * surfaces) to emit this data instead of making a snapshot of the
1309 * @surface. This approach tends to be faster and requires less
1310 * memory and disk space.
1312 * The recognized MIME types are the following: %CAIRO_MIME_TYPE_JPEG,
1313 * %CAIRO_MIME_TYPE_PNG, %CAIRO_MIME_TYPE_JP2, %CAIRO_MIME_TYPE_URI,
1314 * %CAIRO_MIME_TYPE_UNIQUE_ID, %CAIRO_MIME_TYPE_JBIG2,
1315 * %CAIRO_MIME_TYPE_JBIG2_GLOBAL, %CAIRO_MIME_TYPE_JBIG2_GLOBAL_ID.
1317 * See corresponding backend surface docs for details about which MIME
1318 * types it can handle. Caution: the associated MIME data will be
1319 * discarded if you draw on the surface afterwards. Use this function
1322 * Even if a backend supports a MIME type, that does not mean cairo
1323 * will always be able to use the attached MIME data. For example, if
1324 * the backend does not natively support the compositing operation used
1325 * to apply the MIME data to the backend. In that case, the MIME data
1326 * will be ignored. Therefore, to apply an image in all cases, it is best
1327 * to create an image surface which contains the decoded image data and
1328 * then attach the MIME data to that. This ensures the image will always
1329 * be used while still allowing the MIME data to be used whenever
1332 * Return value: %CAIRO_STATUS_SUCCESS or %CAIRO_STATUS_NO_MEMORY if a
1333 * slot could not be allocated for the user data.
1338 cairo_surface_set_mime_data (cairo_surface_t
*surface
,
1339 const char *mime_type
,
1340 const unsigned char *data
,
1341 unsigned long length
,
1342 cairo_destroy_func_t destroy
,
1345 cairo_status_t status
;
1346 cairo_mime_data_t
*mime_data
;
1348 if (CAIRO_REFERENCE_COUNT_IS_INVALID (&surface
->ref_count
))
1349 return surface
->status
;
1351 if (! CAIRO_REFERENCE_COUNT_HAS_REFERENCE (&surface
->ref_count
))
1352 return _cairo_error (CAIRO_STATUS_SURFACE_FINISHED
);
1354 if (unlikely (surface
->status
))
1355 return surface
->status
;
1356 if (unlikely (surface
->finished
))
1357 return _cairo_surface_set_error (surface
, _cairo_error (CAIRO_STATUS_SURFACE_FINISHED
));
1359 status
= _cairo_intern_string (&mime_type
, -1);
1360 if (unlikely (status
))
1361 return _cairo_surface_set_error (surface
, status
);
1364 mime_data
= malloc (sizeof (cairo_mime_data_t
));
1365 if (unlikely (mime_data
== NULL
))
1366 return _cairo_surface_set_error (surface
, _cairo_error (CAIRO_STATUS_NO_MEMORY
));
1368 CAIRO_REFERENCE_COUNT_INIT (&mime_data
->ref_count
, 1);
1370 mime_data
->data
= (unsigned char *) data
;
1371 mime_data
->length
= length
;
1372 mime_data
->destroy
= destroy
;
1373 mime_data
->closure
= closure
;
1377 status
= _cairo_user_data_array_set_data (&surface
->mime_data
,
1378 (cairo_user_data_key_t
*) mime_type
,
1380 _cairo_mime_data_destroy
);
1381 if (unlikely (status
)) {
1384 return _cairo_surface_set_error (surface
, status
);
1387 return CAIRO_STATUS_SUCCESS
;
1389 slim_hidden_def (cairo_surface_set_mime_data
);
1392 * cairo_surface_supports_mime_type:
1393 * @surface: a #cairo_surface_t
1394 * @mime_type: the mime type
1396 * Return whether @surface supports @mime_type.
1398 * Return value: %TRUE if @surface supports
1399 * @mime_type, %FALSE otherwise
1404 cairo_surface_supports_mime_type (cairo_surface_t
*surface
,
1405 const char *mime_type
)
1409 if (unlikely (surface
->status
))
1411 if (unlikely (surface
->finished
)) {
1412 _cairo_surface_set_error (surface
, _cairo_error (CAIRO_STATUS_SURFACE_FINISHED
));
1416 if (surface
->backend
->get_supported_mime_types
) {
1417 types
= surface
->backend
->get_supported_mime_types (surface
);
1420 if (strcmp (*types
, mime_type
) == 0)
1429 slim_hidden_def (cairo_surface_supports_mime_type
);
1432 _cairo_mime_data_reference (const void *key
, void *elt
, void *closure
)
1434 cairo_mime_data_t
*mime_data
= elt
;
1436 _cairo_reference_count_inc (&mime_data
->ref_count
);
1440 _cairo_surface_copy_mime_data (cairo_surface_t
*dst
,
1441 cairo_surface_t
*src
)
1443 cairo_status_t status
;
1449 return _cairo_surface_set_error (dst
, src
->status
);
1451 /* first copy the mime-data, discarding any already set on dst */
1452 status
= _cairo_user_data_array_copy (&dst
->mime_data
, &src
->mime_data
);
1453 if (unlikely (status
))
1454 return _cairo_surface_set_error (dst
, status
);
1456 /* now increment the reference counters for the copies */
1457 _cairo_user_data_array_foreach (&dst
->mime_data
,
1458 _cairo_mime_data_reference
,
1461 return CAIRO_STATUS_SUCCESS
;
1465 * _cairo_surface_set_font_options:
1466 * @surface: a #cairo_surface_t
1467 * @options: a #cairo_font_options_t object that contains the
1468 * options to use for this surface instead of backend's default
1471 * Sets the default font rendering options for the surface.
1472 * This is useful to correctly propagate default font options when
1473 * falling back to an image surface in a backend implementation.
1474 * This affects the options returned in cairo_surface_get_font_options().
1476 * If @options is %NULL the surface options are reset to those of
1477 * the backend default.
1480 _cairo_surface_set_font_options (cairo_surface_t
*surface
,
1481 cairo_font_options_t
*options
)
1483 if (surface
->status
)
1486 assert (surface
->snapshot_of
== NULL
);
1488 if (surface
->finished
) {
1489 _cairo_surface_set_error (surface
, _cairo_error (CAIRO_STATUS_SURFACE_FINISHED
));
1494 surface
->has_font_options
= TRUE
;
1495 _cairo_font_options_init_copy (&surface
->font_options
, options
);
1497 surface
->has_font_options
= FALSE
;
1502 * cairo_surface_get_font_options:
1503 * @surface: a #cairo_surface_t
1504 * @options: a #cairo_font_options_t object into which to store
1505 * the retrieved options. All existing values are overwritten
1507 * Retrieves the default font rendering options for the surface.
1508 * This allows display surfaces to report the correct subpixel order
1509 * for rendering on them, print surfaces to disable hinting of
1510 * metrics and so forth. The result can then be used with
1511 * cairo_scaled_font_create().
1516 cairo_surface_get_font_options (cairo_surface_t
*surface
,
1517 cairo_font_options_t
*options
)
1519 if (cairo_font_options_status (options
))
1522 if (surface
->status
) {
1523 _cairo_font_options_init_default (options
);
1527 if (! surface
->has_font_options
) {
1528 surface
->has_font_options
= TRUE
;
1530 _cairo_font_options_init_default (&surface
->font_options
);
1532 if (!surface
->finished
&& surface
->backend
->get_font_options
) {
1533 surface
->backend
->get_font_options (surface
, &surface
->font_options
);
1537 _cairo_font_options_init_copy (options
, &surface
->font_options
);
1539 slim_hidden_def (cairo_surface_get_font_options
);
1542 _cairo_surface_flush (cairo_surface_t
*surface
, unsigned flags
)
1544 /* update the current snapshots *before* the user updates the surface */
1545 _cairo_surface_detach_snapshots (surface
);
1546 if (surface
->snapshot_of
!= NULL
)
1547 _cairo_surface_detach_snapshot (surface
);
1548 _cairo_surface_detach_mime_data (surface
);
1550 return __cairo_surface_flush (surface
, flags
);
1554 * cairo_surface_flush:
1555 * @surface: a #cairo_surface_t
1557 * Do any pending drawing for the surface and also restore any temporary
1558 * modifications cairo has made to the surface's state. This function
1559 * must be called before switching from drawing on the surface with
1560 * cairo to drawing on it directly with native APIs, or accessing its
1561 * memory outside of Cairo. If the surface doesn't support direct
1562 * access, then this function does nothing.
1567 cairo_surface_flush (cairo_surface_t
*surface
)
1569 cairo_status_t status
;
1571 if (surface
->status
)
1574 if (surface
->finished
)
1577 status
= _cairo_surface_flush (surface
, 0);
1578 if (unlikely (status
))
1579 _cairo_surface_set_error (surface
, status
);
1581 slim_hidden_def (cairo_surface_flush
);
1584 * cairo_surface_mark_dirty:
1585 * @surface: a #cairo_surface_t
1587 * Tells cairo that drawing has been done to surface using means other
1588 * than cairo, and that cairo should reread any cached areas. Note
1589 * that you must call cairo_surface_flush() before doing such drawing.
1594 cairo_surface_mark_dirty (cairo_surface_t
*surface
)
1596 cairo_rectangle_int_t extents
;
1598 if (unlikely (surface
->status
))
1600 if (unlikely (surface
->finished
)) {
1601 _cairo_surface_set_error (surface
, _cairo_error (CAIRO_STATUS_SURFACE_FINISHED
));
1605 _cairo_surface_get_extents (surface
, &extents
);
1606 cairo_surface_mark_dirty_rectangle (surface
,
1607 extents
.x
, extents
.y
,
1608 extents
.width
, extents
.height
);
1610 slim_hidden_def (cairo_surface_mark_dirty
);
1613 * cairo_surface_mark_dirty_rectangle:
1614 * @surface: a #cairo_surface_t
1615 * @x: X coordinate of dirty rectangle
1616 * @y: Y coordinate of dirty rectangle
1617 * @width: width of dirty rectangle
1618 * @height: height of dirty rectangle
1620 * Like cairo_surface_mark_dirty(), but drawing has been done only to
1621 * the specified rectangle, so that cairo can retain cached contents
1622 * for other parts of the surface.
1624 * Any cached clip set on the surface will be reset by this function,
1625 * to make sure that future cairo calls have the clip set that they
1631 cairo_surface_mark_dirty_rectangle (cairo_surface_t
*surface
,
1637 cairo_status_t status
;
1639 if (unlikely (surface
->status
))
1642 assert (surface
->snapshot_of
== NULL
);
1644 if (unlikely (surface
->finished
)) {
1645 _cairo_surface_set_error (surface
, _cairo_error (CAIRO_STATUS_SURFACE_FINISHED
));
1649 /* The application *should* have called cairo_surface_flush() before
1650 * modifying the surface independently of cairo (and thus having to
1651 * call mark_dirty()). */
1652 assert (! _cairo_surface_has_snapshots (surface
));
1653 assert (! _cairo_surface_has_mime_data (surface
));
1655 surface
->is_clear
= FALSE
;
1658 if (surface
->damage
) {
1663 box
.p2
.x
= x
+ width
;
1664 box
.p2
.y
= y
+ height
;
1666 surface
->damage
= _cairo_damage_add_box (surface
->damage
, &box
);
1669 if (surface
->backend
->mark_dirty_rectangle
!= NULL
) {
1670 /* XXX: FRAGILE: We're ignoring the scaling component of
1671 * device_transform here. I don't know what the right thing to
1672 * do would actually be if there were some scaling here, but
1673 * we avoid this since device_transfom scaling is not exported
1674 * publicly and mark_dirty is not used internally. */
1675 status
= surface
->backend
->mark_dirty_rectangle (surface
,
1676 x
+ surface
->device_transform
.x0
,
1677 y
+ surface
->device_transform
.y0
,
1680 if (unlikely (status
))
1681 _cairo_surface_set_error (surface
, status
);
1684 slim_hidden_def (cairo_surface_mark_dirty_rectangle
);
1687 * cairo_surface_set_device_scale:
1688 * @surface: a #cairo_surface_t
1689 * @x_scale: a scale factor in the X direction
1690 * @y_scale: a scale factor in the Y direction
1692 * Sets a scale that is multiplied to the device coordinates determined
1693 * by the CTM when drawing to @surface. One common use for this is to
1694 * render to very high resolution display devices at a scale factor, so
1695 * that code that assumes 1 pixel will be a certain size will still work.
1696 * Setting a transformation via cairo_translate() isn't
1697 * sufficient to do this, since functions like
1698 * cairo_device_to_user() will expose the hidden scale.
1700 * Note that the scale affects drawing to the surface as well as
1701 * using the surface in a source pattern.
1706 cairo_surface_set_device_scale (cairo_surface_t
*surface
,
1710 cairo_status_t status
;
1712 if (unlikely (surface
->status
))
1715 assert (surface
->snapshot_of
== NULL
);
1717 if (unlikely (surface
->finished
)) {
1718 _cairo_surface_set_error (surface
, _cairo_error (CAIRO_STATUS_SURFACE_FINISHED
));
1722 status
= _cairo_surface_begin_modification (surface
);
1723 if (unlikely (status
)) {
1724 _cairo_surface_set_error (surface
, status
);
1728 surface
->device_transform
.xx
= x_scale
;
1729 surface
->device_transform
.yy
= y_scale
;
1730 surface
->device_transform
.xy
= 0.0;
1731 surface
->device_transform
.yx
= 0.0;
1733 surface
->device_transform_inverse
= surface
->device_transform
;
1734 status
= cairo_matrix_invert (&surface
->device_transform_inverse
);
1735 /* should always be invertible unless given pathological input */
1736 assert (status
== CAIRO_STATUS_SUCCESS
);
1738 _cairo_observers_notify (&surface
->device_transform_observers
, surface
);
1740 slim_hidden_def (cairo_surface_set_device_scale
);
1743 * cairo_surface_get_device_scale:
1744 * @surface: a #cairo_surface_t
1745 * @x_scale: the scale in the X direction, in device units
1746 * @y_scale: the scale in the Y direction, in device units
1748 * This function returns the previous device offset set by
1749 * cairo_surface_set_device_scale().
1754 cairo_surface_get_device_scale (cairo_surface_t
*surface
,
1759 *x_scale
= surface
->device_transform
.xx
;
1761 *y_scale
= surface
->device_transform
.yy
;
1763 slim_hidden_def (cairo_surface_get_device_scale
);
1766 * cairo_surface_set_device_offset:
1767 * @surface: a #cairo_surface_t
1768 * @x_offset: the offset in the X direction, in device units
1769 * @y_offset: the offset in the Y direction, in device units
1771 * Sets an offset that is added to the device coordinates determined
1772 * by the CTM when drawing to @surface. One use case for this function
1773 * is when we want to create a #cairo_surface_t that redirects drawing
1774 * for a portion of an onscreen surface to an offscreen surface in a
1775 * way that is completely invisible to the user of the cairo
1776 * API. Setting a transformation via cairo_translate() isn't
1777 * sufficient to do this, since functions like
1778 * cairo_device_to_user() will expose the hidden offset.
1780 * Note that the offset affects drawing to the surface as well as
1781 * using the surface in a source pattern.
1786 cairo_surface_set_device_offset (cairo_surface_t
*surface
,
1790 cairo_status_t status
;
1792 if (unlikely (surface
->status
))
1795 assert (surface
->snapshot_of
== NULL
);
1797 if (unlikely (surface
->finished
)) {
1798 _cairo_surface_set_error (surface
, _cairo_error (CAIRO_STATUS_SURFACE_FINISHED
));
1802 status
= _cairo_surface_begin_modification (surface
);
1803 if (unlikely (status
)) {
1804 _cairo_surface_set_error (surface
, status
);
1808 surface
->device_transform
.x0
= x_offset
;
1809 surface
->device_transform
.y0
= y_offset
;
1811 surface
->device_transform_inverse
= surface
->device_transform
;
1812 status
= cairo_matrix_invert (&surface
->device_transform_inverse
);
1813 /* should always be invertible unless given pathological input */
1814 assert (status
== CAIRO_STATUS_SUCCESS
);
1816 _cairo_observers_notify (&surface
->device_transform_observers
, surface
);
1818 slim_hidden_def (cairo_surface_set_device_offset
);
1821 * cairo_surface_get_device_offset:
1822 * @surface: a #cairo_surface_t
1823 * @x_offset: the offset in the X direction, in device units
1824 * @y_offset: the offset in the Y direction, in device units
1826 * This function returns the previous device offset set by
1827 * cairo_surface_set_device_offset().
1832 cairo_surface_get_device_offset (cairo_surface_t
*surface
,
1837 *x_offset
= surface
->device_transform
.x0
;
1839 *y_offset
= surface
->device_transform
.y0
;
1841 slim_hidden_def (cairo_surface_get_device_offset
);
1844 * cairo_surface_set_fallback_resolution:
1845 * @surface: a #cairo_surface_t
1846 * @x_pixels_per_inch: horizontal setting for pixels per inch
1847 * @y_pixels_per_inch: vertical setting for pixels per inch
1849 * Set the horizontal and vertical resolution for image fallbacks.
1851 * When certain operations aren't supported natively by a backend,
1852 * cairo will fallback by rendering operations to an image and then
1853 * overlaying that image onto the output. For backends that are
1854 * natively vector-oriented, this function can be used to set the
1855 * resolution used for these image fallbacks, (larger values will
1856 * result in more detailed images, but also larger file sizes).
1858 * Some examples of natively vector-oriented backends are the ps, pdf,
1861 * For backends that are natively raster-oriented, image fallbacks are
1862 * still possible, but they are always performed at the native
1863 * device resolution. So this function has no effect on those
1866 * Note: The fallback resolution only takes effect at the time of
1867 * completing a page (with cairo_show_page() or cairo_copy_page()) so
1868 * there is currently no way to have more than one fallback resolution
1869 * in effect on a single page.
1871 * The default fallback resoultion is 300 pixels per inch in both
1877 cairo_surface_set_fallback_resolution (cairo_surface_t
*surface
,
1878 double x_pixels_per_inch
,
1879 double y_pixels_per_inch
)
1881 cairo_status_t status
;
1883 if (unlikely (surface
->status
))
1886 assert (surface
->snapshot_of
== NULL
);
1888 if (unlikely (surface
->finished
)) {
1889 _cairo_surface_set_error (surface
, _cairo_error (CAIRO_STATUS_SURFACE_FINISHED
));
1893 if (x_pixels_per_inch
<= 0 || y_pixels_per_inch
<= 0) {
1894 /* XXX Could delay raising the error until we fallback, but throwing
1895 * the error here means that we can catch the real culprit.
1897 _cairo_surface_set_error (surface
, CAIRO_STATUS_INVALID_MATRIX
);
1901 status
= _cairo_surface_begin_modification (surface
);
1902 if (unlikely (status
)) {
1903 _cairo_surface_set_error (surface
, status
);
1907 surface
->x_fallback_resolution
= x_pixels_per_inch
;
1908 surface
->y_fallback_resolution
= y_pixels_per_inch
;
1910 slim_hidden_def (cairo_surface_set_fallback_resolution
);
1913 * cairo_surface_get_fallback_resolution:
1914 * @surface: a #cairo_surface_t
1915 * @x_pixels_per_inch: horizontal pixels per inch
1916 * @y_pixels_per_inch: vertical pixels per inch
1918 * This function returns the previous fallback resolution set by
1919 * cairo_surface_set_fallback_resolution(), or default fallback
1920 * resolution if never set.
1925 cairo_surface_get_fallback_resolution (cairo_surface_t
*surface
,
1926 double *x_pixels_per_inch
,
1927 double *y_pixels_per_inch
)
1929 if (x_pixels_per_inch
)
1930 *x_pixels_per_inch
= surface
->x_fallback_resolution
;
1931 if (y_pixels_per_inch
)
1932 *y_pixels_per_inch
= surface
->y_fallback_resolution
;
1936 _cairo_surface_has_device_transform (cairo_surface_t
*surface
)
1938 return ! _cairo_matrix_is_identity (&surface
->device_transform
);
1942 * _cairo_surface_acquire_source_image:
1943 * @surface: a #cairo_surface_t
1944 * @image_out: location to store a pointer to an image surface that
1945 * has identical contents to @surface. This surface could be @surface
1946 * itself, a surface held internal to @surface, or it could be a new
1947 * surface with a copy of the relevant portion of @surface.
1948 * @image_extra: location to store image specific backend data
1950 * Gets an image surface to use when drawing as a fallback when drawing with
1951 * @surface as a source. _cairo_surface_release_source_image() must be called
1954 * Return value: %CAIRO_STATUS_SUCCESS if an image was stored in @image_out.
1955 * %CAIRO_INT_STATUS_UNSUPPORTED if an image cannot be retrieved for the specified
1956 * surface. Or %CAIRO_STATUS_NO_MEMORY.
1959 _cairo_surface_acquire_source_image (cairo_surface_t
*surface
,
1960 cairo_image_surface_t
**image_out
,
1963 cairo_status_t status
;
1965 if (unlikely (surface
->status
))
1966 return surface
->status
;
1968 assert (!surface
->finished
);
1970 if (surface
->backend
->acquire_source_image
== NULL
)
1971 return CAIRO_INT_STATUS_UNSUPPORTED
;
1973 status
= surface
->backend
->acquire_source_image (surface
,
1974 image_out
, image_extra
);
1975 if (unlikely (status
))
1976 return _cairo_surface_set_error (surface
, status
);
1978 _cairo_debug_check_image_surface_is_defined (&(*image_out
)->base
);
1980 return CAIRO_STATUS_SUCCESS
;
1984 _cairo_surface_default_acquire_source_image (void *_surface
,
1985 cairo_image_surface_t
**image_out
,
1988 cairo_surface_t
*surface
= _surface
;
1989 cairo_rectangle_int_t extents
;
1991 if (unlikely (! surface
->backend
->get_extents (surface
, &extents
)))
1992 return _cairo_error (CAIRO_STATUS_INVALID_SIZE
);
1994 *image_out
= _cairo_surface_map_to_image (surface
, &extents
);
1995 *image_extra
= NULL
;
1996 return (*image_out
)->base
.status
;
2000 * _cairo_surface_release_source_image:
2001 * @surface: a #cairo_surface_t
2002 * @image_extra: same as return from the matching _cairo_surface_acquire_source_image()
2004 * Releases any resources obtained with _cairo_surface_acquire_source_image()
2007 _cairo_surface_release_source_image (cairo_surface_t
*surface
,
2008 cairo_image_surface_t
*image
,
2011 assert (!surface
->finished
);
2013 if (surface
->backend
->release_source_image
)
2014 surface
->backend
->release_source_image (surface
, image
, image_extra
);
2018 _cairo_surface_default_release_source_image (void *surface
,
2019 cairo_image_surface_t
*image
,
2022 cairo_status_t ignored
;
2024 ignored
= _cairo_surface_unmap_image (surface
, image
);
2030 _cairo_surface_get_source (cairo_surface_t
*surface
,
2031 cairo_rectangle_int_t
*extents
)
2033 assert (surface
->backend
->source
);
2034 return surface
->backend
->source (surface
, extents
);
2038 _cairo_surface_default_source (void *surface
,
2039 cairo_rectangle_int_t
*extents
)
2042 _cairo_surface_get_extents(surface
, extents
);
2046 static cairo_status_t
2047 _pattern_has_error (const cairo_pattern_t
*pattern
)
2049 const cairo_surface_pattern_t
*spattern
;
2051 if (unlikely (pattern
->status
))
2052 return pattern
->status
;
2054 if (pattern
->type
!= CAIRO_PATTERN_TYPE_SURFACE
)
2055 return CAIRO_STATUS_SUCCESS
;
2057 spattern
= (const cairo_surface_pattern_t
*) pattern
;
2058 if (unlikely (spattern
->surface
->status
))
2059 return spattern
->surface
->status
;
2061 if (unlikely (spattern
->surface
->finished
))
2062 return _cairo_error (CAIRO_STATUS_SURFACE_FINISHED
);
2064 return CAIRO_STATUS_SUCCESS
;
2068 nothing_to_do (cairo_surface_t
*surface
,
2069 cairo_operator_t op
,
2070 const cairo_pattern_t
*source
)
2072 if (_cairo_pattern_is_clear (source
)) {
2073 if (op
== CAIRO_OPERATOR_OVER
|| op
== CAIRO_OPERATOR_ADD
)
2076 if (op
== CAIRO_OPERATOR_SOURCE
)
2077 op
= CAIRO_OPERATOR_CLEAR
;
2080 if (op
== CAIRO_OPERATOR_CLEAR
&& surface
->is_clear
)
2083 if (op
== CAIRO_OPERATOR_ATOP
&& (surface
->content
& CAIRO_CONTENT_COLOR
) ==0)
2090 _cairo_surface_paint (cairo_surface_t
*surface
,
2091 cairo_operator_t op
,
2092 const cairo_pattern_t
*source
,
2093 const cairo_clip_t
*clip
)
2095 cairo_int_status_t status
;
2097 TRACE ((stderr
, "%s\n", __FUNCTION__
));
2098 if (unlikely (surface
->status
))
2099 return surface
->status
;
2100 if (unlikely (surface
->finished
))
2101 return _cairo_surface_set_error (surface
, _cairo_error (CAIRO_STATUS_SURFACE_FINISHED
));
2103 if (_cairo_clip_is_all_clipped (clip
))
2104 return CAIRO_STATUS_SUCCESS
;
2106 status
= _pattern_has_error (source
);
2107 if (unlikely (status
))
2110 if (nothing_to_do (surface
, op
, source
))
2111 return CAIRO_STATUS_SUCCESS
;
2113 status
= _cairo_surface_begin_modification (surface
);
2114 if (unlikely (status
))
2117 status
= surface
->backend
->paint (surface
, op
, source
, clip
);
2118 if (status
!= CAIRO_INT_STATUS_NOTHING_TO_DO
) {
2119 surface
->is_clear
= op
== CAIRO_OPERATOR_CLEAR
&& clip
== NULL
;
2123 return _cairo_surface_set_error (surface
, status
);
2127 _cairo_surface_mask (cairo_surface_t
*surface
,
2128 cairo_operator_t op
,
2129 const cairo_pattern_t
*source
,
2130 const cairo_pattern_t
*mask
,
2131 const cairo_clip_t
*clip
)
2133 cairo_int_status_t status
;
2135 TRACE ((stderr
, "%s\n", __FUNCTION__
));
2136 if (unlikely (surface
->status
))
2137 return surface
->status
;
2138 if (unlikely (surface
->finished
))
2139 return _cairo_surface_set_error (surface
, _cairo_error (CAIRO_STATUS_SURFACE_FINISHED
));
2141 if (_cairo_clip_is_all_clipped (clip
))
2142 return CAIRO_STATUS_SUCCESS
;
2144 /* If the mask is blank, this is just an expensive no-op */
2145 if (_cairo_pattern_is_clear (mask
) &&
2146 _cairo_operator_bounded_by_mask (op
))
2148 return CAIRO_STATUS_SUCCESS
;
2151 status
= _pattern_has_error (source
);
2152 if (unlikely (status
))
2155 status
= _pattern_has_error (mask
);
2156 if (unlikely (status
))
2159 if (nothing_to_do (surface
, op
, source
))
2160 return CAIRO_STATUS_SUCCESS
;
2162 status
= _cairo_surface_begin_modification (surface
);
2163 if (unlikely (status
))
2166 status
= surface
->backend
->mask (surface
, op
, source
, mask
, clip
);
2167 if (status
!= CAIRO_INT_STATUS_NOTHING_TO_DO
) {
2168 surface
->is_clear
= FALSE
;
2172 return _cairo_surface_set_error (surface
, status
);
2176 _cairo_surface_fill_stroke (cairo_surface_t
*surface
,
2177 cairo_operator_t fill_op
,
2178 const cairo_pattern_t
*fill_source
,
2179 cairo_fill_rule_t fill_rule
,
2180 double fill_tolerance
,
2181 cairo_antialias_t fill_antialias
,
2182 cairo_path_fixed_t
*path
,
2183 cairo_operator_t stroke_op
,
2184 const cairo_pattern_t
*stroke_source
,
2185 const cairo_stroke_style_t
*stroke_style
,
2186 const cairo_matrix_t
*stroke_ctm
,
2187 const cairo_matrix_t
*stroke_ctm_inverse
,
2188 double stroke_tolerance
,
2189 cairo_antialias_t stroke_antialias
,
2190 const cairo_clip_t
*clip
)
2192 cairo_int_status_t status
;
2194 TRACE ((stderr
, "%s\n", __FUNCTION__
));
2195 if (unlikely (surface
->status
))
2196 return surface
->status
;
2197 if (unlikely (surface
->finished
))
2198 return _cairo_surface_set_error (surface
, _cairo_error (CAIRO_STATUS_SURFACE_FINISHED
));
2200 if (_cairo_clip_is_all_clipped (clip
))
2201 return CAIRO_STATUS_SUCCESS
;
2203 if (surface
->is_clear
&&
2204 fill_op
== CAIRO_OPERATOR_CLEAR
&&
2205 stroke_op
== CAIRO_OPERATOR_CLEAR
)
2207 return CAIRO_STATUS_SUCCESS
;
2210 status
= _pattern_has_error (fill_source
);
2211 if (unlikely (status
))
2214 status
= _pattern_has_error (stroke_source
);
2215 if (unlikely (status
))
2218 status
= _cairo_surface_begin_modification (surface
);
2219 if (unlikely (status
))
2222 if (surface
->backend
->fill_stroke
) {
2223 cairo_matrix_t dev_ctm
= *stroke_ctm
;
2224 cairo_matrix_t dev_ctm_inverse
= *stroke_ctm_inverse
;
2226 status
= surface
->backend
->fill_stroke (surface
,
2227 fill_op
, fill_source
, fill_rule
,
2228 fill_tolerance
, fill_antialias
,
2230 stroke_op
, stroke_source
,
2232 &dev_ctm
, &dev_ctm_inverse
,
2233 stroke_tolerance
, stroke_antialias
,
2236 if (status
!= CAIRO_INT_STATUS_UNSUPPORTED
)
2240 status
= _cairo_surface_fill (surface
, fill_op
, fill_source
, path
,
2241 fill_rule
, fill_tolerance
, fill_antialias
,
2243 if (unlikely (status
))
2246 status
= _cairo_surface_stroke (surface
, stroke_op
, stroke_source
, path
,
2247 stroke_style
, stroke_ctm
, stroke_ctm_inverse
,
2248 stroke_tolerance
, stroke_antialias
,
2250 if (unlikely (status
))
2254 if (status
!= CAIRO_INT_STATUS_NOTHING_TO_DO
) {
2255 surface
->is_clear
= FALSE
;
2259 return _cairo_surface_set_error (surface
, status
);
2263 _cairo_surface_stroke (cairo_surface_t
*surface
,
2264 cairo_operator_t op
,
2265 const cairo_pattern_t
*source
,
2266 const cairo_path_fixed_t
*path
,
2267 const cairo_stroke_style_t
*stroke_style
,
2268 const cairo_matrix_t
*ctm
,
2269 const cairo_matrix_t
*ctm_inverse
,
2271 cairo_antialias_t antialias
,
2272 const cairo_clip_t
*clip
)
2274 cairo_int_status_t status
;
2276 TRACE ((stderr
, "%s\n", __FUNCTION__
));
2277 if (unlikely (surface
->status
))
2278 return surface
->status
;
2279 if (unlikely (surface
->finished
))
2280 return _cairo_surface_set_error (surface
, _cairo_error (CAIRO_STATUS_SURFACE_FINISHED
));
2282 if (_cairo_clip_is_all_clipped (clip
))
2283 return CAIRO_STATUS_SUCCESS
;
2285 status
= _pattern_has_error (source
);
2286 if (unlikely (status
))
2289 if (nothing_to_do (surface
, op
, source
))
2290 return CAIRO_STATUS_SUCCESS
;
2292 status
= _cairo_surface_begin_modification (surface
);
2293 if (unlikely (status
))
2296 status
= surface
->backend
->stroke (surface
, op
, source
,
2299 tolerance
, antialias
,
2301 if (status
!= CAIRO_INT_STATUS_NOTHING_TO_DO
) {
2302 surface
->is_clear
= FALSE
;
2306 return _cairo_surface_set_error (surface
, status
);
2310 _cairo_surface_fill (cairo_surface_t
*surface
,
2311 cairo_operator_t op
,
2312 const cairo_pattern_t
*source
,
2313 const cairo_path_fixed_t
*path
,
2314 cairo_fill_rule_t fill_rule
,
2316 cairo_antialias_t antialias
,
2317 const cairo_clip_t
*clip
)
2319 cairo_int_status_t status
;
2321 TRACE ((stderr
, "%s\n", __FUNCTION__
));
2322 if (unlikely (surface
->status
))
2323 return surface
->status
;
2324 if (unlikely (surface
->finished
))
2325 return _cairo_surface_set_error (surface
, _cairo_error (CAIRO_STATUS_SURFACE_FINISHED
));
2327 if (_cairo_clip_is_all_clipped (clip
))
2328 return CAIRO_STATUS_SUCCESS
;
2330 status
= _pattern_has_error (source
);
2331 if (unlikely (status
))
2334 if (nothing_to_do (surface
, op
, source
))
2335 return CAIRO_STATUS_SUCCESS
;
2337 status
= _cairo_surface_begin_modification (surface
);
2338 if (unlikely (status
))
2341 status
= surface
->backend
->fill (surface
, op
, source
,
2343 tolerance
, antialias
,
2345 if (status
!= CAIRO_INT_STATUS_NOTHING_TO_DO
) {
2346 surface
->is_clear
= FALSE
;
2350 return _cairo_surface_set_error (surface
, status
);
2354 * cairo_surface_copy_page:
2355 * @surface: a #cairo_surface_t
2357 * Emits the current page for backends that support multiple pages,
2358 * but doesn't clear it, so that the contents of the current page will
2359 * be retained for the next page. Use cairo_surface_show_page() if you
2360 * want to get an empty page after the emission.
2362 * There is a convenience function for this that takes a #cairo_t,
2363 * namely cairo_copy_page().
2368 cairo_surface_copy_page (cairo_surface_t
*surface
)
2370 if (unlikely (surface
->status
))
2373 assert (surface
->snapshot_of
== NULL
);
2375 if (unlikely (surface
->finished
)) {
2376 _cairo_surface_set_error (surface
, CAIRO_STATUS_SURFACE_FINISHED
);
2380 /* It's fine if some backends don't implement copy_page */
2381 if (surface
->backend
->copy_page
== NULL
)
2384 _cairo_surface_set_error (surface
, surface
->backend
->copy_page (surface
));
2386 slim_hidden_def (cairo_surface_copy_page
);
2389 * cairo_surface_show_page:
2390 * @surface: a #cairo_Surface_t
2392 * Emits and clears the current page for backends that support multiple
2393 * pages. Use cairo_surface_copy_page() if you don't want to clear the page.
2395 * There is a convenience function for this that takes a #cairo_t,
2396 * namely cairo_show_page().
2401 cairo_surface_show_page (cairo_surface_t
*surface
)
2403 cairo_status_t status
;
2405 if (unlikely (surface
->status
))
2408 if (unlikely (surface
->finished
)) {
2409 _cairo_surface_set_error (surface
, CAIRO_STATUS_SURFACE_FINISHED
);
2413 status
= _cairo_surface_begin_modification (surface
);
2414 if (unlikely (status
)) {
2415 _cairo_surface_set_error (surface
, status
);
2419 /* It's fine if some backends don't implement show_page */
2420 if (surface
->backend
->show_page
== NULL
)
2423 _cairo_surface_set_error (surface
, surface
->backend
->show_page (surface
));
2425 slim_hidden_def (cairo_surface_show_page
);
2428 * _cairo_surface_get_extents:
2429 * @surface: the #cairo_surface_t to fetch extents for
2431 * This function returns a bounding box for the surface. The surface
2432 * bounds are defined as a region beyond which no rendering will
2433 * possibly be recorded, in other words, it is the maximum extent of
2434 * potentially usable coordinates.
2436 * For vector surfaces, (PDF, PS, SVG and recording-surfaces), the surface
2437 * might be conceived as unbounded, but we force the user to provide a
2438 * maximum size at the time of surface_create. So get_extents uses
2441 * Note: The coordinates returned are in "backend" space rather than
2442 * "surface" space. That is, they are relative to the true (0,0)
2443 * origin rather than the device_transform origin. This might seem a
2444 * bit inconsistent with other #cairo_surface_t interfaces, but all
2445 * current callers are within the surface layer where backend space is
2448 * This behavior would have to be changed is we ever exported a public
2449 * variant of this function.
2452 _cairo_surface_get_extents (cairo_surface_t
*surface
,
2453 cairo_rectangle_int_t
*extents
)
2455 cairo_bool_t bounded
;
2457 if (unlikely (surface
->status
))
2459 if (unlikely (surface
->finished
)) {
2460 _cairo_surface_set_error(surface
, CAIRO_STATUS_SURFACE_FINISHED
);
2465 if (surface
->backend
->get_extents
!= NULL
)
2466 bounded
= surface
->backend
->get_extents (surface
, extents
);
2469 _cairo_unbounded_rectangle_init (extents
);
2474 extents
->x
= extents
->y
= 0;
2475 extents
->width
= extents
->height
= 0;
2480 * cairo_surface_has_show_text_glyphs:
2481 * @surface: a #cairo_surface_t
2483 * Returns whether the surface supports
2484 * sophisticated cairo_show_text_glyphs() operations. That is,
2485 * whether it actually uses the provided text and cluster data
2486 * to a cairo_show_text_glyphs() call.
2488 * Note: Even if this function returns %FALSE, a
2489 * cairo_show_text_glyphs() operation targeted at @surface will
2490 * still succeed. It just will
2491 * act like a cairo_show_glyphs() operation. Users can use this
2492 * function to avoid computing UTF-8 text and cluster mapping if the
2493 * target surface does not use it.
2495 * Return value: %TRUE if @surface supports
2496 * cairo_show_text_glyphs(), %FALSE otherwise
2501 cairo_surface_has_show_text_glyphs (cairo_surface_t
*surface
)
2503 if (unlikely (surface
->status
))
2506 if (unlikely (surface
->finished
)) {
2507 _cairo_surface_set_error (surface
, CAIRO_STATUS_SURFACE_FINISHED
);
2511 if (surface
->backend
->has_show_text_glyphs
)
2512 return surface
->backend
->has_show_text_glyphs (surface
);
2514 return surface
->backend
->show_text_glyphs
!= NULL
;
2516 slim_hidden_def (cairo_surface_has_show_text_glyphs
);
2518 /* Note: the backends may modify the contents of the glyph array as long as
2519 * they do not return %CAIRO_INT_STATUS_UNSUPPORTED. This makes it possible to
2520 * avoid copying the array again and again, and edit it in-place.
2521 * Backends are in fact free to use the array as a generic buffer as they
2524 * For show_glyphs backend method, and NOT for show_text_glyphs method,
2525 * when they do return UNSUPPORTED, they may adjust remaining_glyphs to notify
2526 * that they have successfully rendered some of the glyphs (from the beginning
2527 * of the array), but not all. If they don't touch remaining_glyphs, it
2528 * defaults to all glyphs.
2530 * See commits 5a9642c5746fd677aed35ce620ce90b1029b1a0c and
2531 * 1781e6018c17909311295a9cc74b70500c6b4d0a for the rationale.
2534 _cairo_surface_show_text_glyphs (cairo_surface_t
*surface
,
2535 cairo_operator_t op
,
2536 const cairo_pattern_t
*source
,
2539 cairo_glyph_t
*glyphs
,
2541 const cairo_text_cluster_t
*clusters
,
2543 cairo_text_cluster_flags_t cluster_flags
,
2544 cairo_scaled_font_t
*scaled_font
,
2545 const cairo_clip_t
*clip
)
2547 cairo_int_status_t status
;
2549 TRACE ((stderr
, "%s\n", __FUNCTION__
));
2550 if (unlikely (surface
->status
))
2551 return surface
->status
;
2552 if (unlikely (surface
->finished
))
2553 return _cairo_surface_set_error (surface
, _cairo_error (CAIRO_STATUS_SURFACE_FINISHED
));
2555 if (num_glyphs
== 0 && utf8_len
== 0)
2556 return CAIRO_STATUS_SUCCESS
;
2558 if (_cairo_clip_is_all_clipped (clip
))
2559 return CAIRO_STATUS_SUCCESS
;
2561 status
= _pattern_has_error (source
);
2562 if (unlikely (status
))
2565 if (nothing_to_do (surface
, op
, source
))
2566 return CAIRO_STATUS_SUCCESS
;
2568 status
= _cairo_surface_begin_modification (surface
);
2569 if (unlikely (status
))
2572 status
= CAIRO_INT_STATUS_UNSUPPORTED
;
2574 /* The logic here is duplicated in _cairo_analysis_surface show_glyphs and
2575 * show_text_glyphs. Keep in synch. */
2577 /* A real show_text_glyphs call. Try show_text_glyphs backend
2579 if (surface
->backend
->show_text_glyphs
!= NULL
) {
2580 status
= surface
->backend
->show_text_glyphs (surface
, op
,
2584 clusters
, num_clusters
, cluster_flags
,
2588 if (status
== CAIRO_INT_STATUS_UNSUPPORTED
&&
2589 surface
->backend
->show_glyphs
)
2591 status
= surface
->backend
->show_glyphs (surface
, op
,
2598 /* A mere show_glyphs call. Try show_glyphs backend method first */
2599 if (surface
->backend
->show_glyphs
!= NULL
) {
2600 status
= surface
->backend
->show_glyphs (surface
, op
,
2605 } else if (surface
->backend
->show_text_glyphs
!= NULL
) {
2606 /* Intentionally only try show_text_glyphs method for show_glyphs
2607 * calls if backend does not have show_glyphs. If backend has
2608 * both methods implemented, we don't fallback from show_glyphs to
2609 * show_text_glyphs, and hence the backend can assume in its
2610 * show_text_glyphs call that clusters is not NULL (which also
2611 * implies that UTF-8 is not NULL, unless the text is
2614 status
= surface
->backend
->show_text_glyphs (surface
, op
,
2618 clusters
, num_clusters
, cluster_flags
,
2624 if (status
!= CAIRO_INT_STATUS_NOTHING_TO_DO
) {
2625 surface
->is_clear
= FALSE
;
2629 return _cairo_surface_set_error (surface
, status
);
2633 * _cairo_surface_set_resolution:
2634 * @surface: the surface
2635 * @x_res: x resolution, in dpi
2636 * @y_res: y resolution, in dpi
2638 * Set the actual surface resolution of @surface to the given x and y DPI.
2639 * Mainly used for correctly computing the scale factor when fallback
2640 * rendering needs to take place in the paginated surface.
2643 _cairo_surface_set_resolution (cairo_surface_t
*surface
,
2647 if (surface
->status
)
2650 surface
->x_resolution
= x_res
;
2651 surface
->y_resolution
= y_res
;
2655 * _cairo_surface_create_in_error:
2656 * @status: the error status
2658 * Return an appropriate static error surface for the error status.
2659 * On error, surface creation functions should always return a surface
2660 * created with _cairo_surface_create_in_error() instead of a new surface
2661 * in an error state. This simplifies internal code as no refcounting has
2665 _cairo_surface_create_in_error (cairo_status_t status
)
2667 assert (status
< CAIRO_STATUS_LAST_STATUS
);
2669 case CAIRO_STATUS_NO_MEMORY
:
2670 return (cairo_surface_t
*) &_cairo_surface_nil
;
2671 case CAIRO_STATUS_SURFACE_TYPE_MISMATCH
:
2672 return (cairo_surface_t
*) &_cairo_surface_nil_surface_type_mismatch
;
2673 case CAIRO_STATUS_INVALID_STATUS
:
2674 return (cairo_surface_t
*) &_cairo_surface_nil_invalid_status
;
2675 case CAIRO_STATUS_INVALID_CONTENT
:
2676 return (cairo_surface_t
*) &_cairo_surface_nil_invalid_content
;
2677 case CAIRO_STATUS_INVALID_FORMAT
:
2678 return (cairo_surface_t
*) &_cairo_surface_nil_invalid_format
;
2679 case CAIRO_STATUS_INVALID_VISUAL
:
2680 return (cairo_surface_t
*) &_cairo_surface_nil_invalid_visual
;
2681 case CAIRO_STATUS_READ_ERROR
:
2682 return (cairo_surface_t
*) &_cairo_surface_nil_read_error
;
2683 case CAIRO_STATUS_WRITE_ERROR
:
2684 return (cairo_surface_t
*) &_cairo_surface_nil_write_error
;
2685 case CAIRO_STATUS_FILE_NOT_FOUND
:
2686 return (cairo_surface_t
*) &_cairo_surface_nil_file_not_found
;
2687 case CAIRO_STATUS_TEMP_FILE_ERROR
:
2688 return (cairo_surface_t
*) &_cairo_surface_nil_temp_file_error
;
2689 case CAIRO_STATUS_INVALID_STRIDE
:
2690 return (cairo_surface_t
*) &_cairo_surface_nil_invalid_stride
;
2691 case CAIRO_STATUS_INVALID_SIZE
:
2692 return (cairo_surface_t
*) &_cairo_surface_nil_invalid_size
;
2693 case CAIRO_STATUS_DEVICE_TYPE_MISMATCH
:
2694 return (cairo_surface_t
*) &_cairo_surface_nil_device_type_mismatch
;
2695 case CAIRO_STATUS_DEVICE_ERROR
:
2696 return (cairo_surface_t
*) &_cairo_surface_nil_device_error
;
2697 case CAIRO_STATUS_SUCCESS
:
2698 case CAIRO_STATUS_LAST_STATUS
:
2701 case CAIRO_STATUS_INVALID_RESTORE
:
2702 case CAIRO_STATUS_INVALID_POP_GROUP
:
2703 case CAIRO_STATUS_NO_CURRENT_POINT
:
2704 case CAIRO_STATUS_INVALID_MATRIX
:
2705 case CAIRO_STATUS_NULL_POINTER
:
2706 case CAIRO_STATUS_INVALID_STRING
:
2707 case CAIRO_STATUS_INVALID_PATH_DATA
:
2708 case CAIRO_STATUS_SURFACE_FINISHED
:
2709 case CAIRO_STATUS_PATTERN_TYPE_MISMATCH
:
2710 case CAIRO_STATUS_INVALID_DASH
:
2711 case CAIRO_STATUS_INVALID_DSC_COMMENT
:
2712 case CAIRO_STATUS_INVALID_INDEX
:
2713 case CAIRO_STATUS_CLIP_NOT_REPRESENTABLE
:
2714 case CAIRO_STATUS_FONT_TYPE_MISMATCH
:
2715 case CAIRO_STATUS_USER_FONT_IMMUTABLE
:
2716 case CAIRO_STATUS_USER_FONT_ERROR
:
2717 case CAIRO_STATUS_NEGATIVE_COUNT
:
2718 case CAIRO_STATUS_INVALID_CLUSTERS
:
2719 case CAIRO_STATUS_INVALID_SLANT
:
2720 case CAIRO_STATUS_INVALID_WEIGHT
:
2721 case CAIRO_STATUS_USER_FONT_NOT_IMPLEMENTED
:
2722 case CAIRO_STATUS_INVALID_MESH_CONSTRUCTION
:
2723 case CAIRO_STATUS_DEVICE_FINISHED
:
2724 case CAIRO_STATUS_JBIG2_GLOBAL_MISSING
:
2726 _cairo_error_throw (CAIRO_STATUS_NO_MEMORY
);
2727 return (cairo_surface_t
*) &_cairo_surface_nil
;
2732 _cairo_int_surface_create_in_error (cairo_int_status_t status
)
2734 if (status
< CAIRO_INT_STATUS_LAST_STATUS
)
2735 return _cairo_surface_create_in_error (status
);
2737 switch ((int)status
) {
2738 case CAIRO_INT_STATUS_UNSUPPORTED
:
2739 return (cairo_surface_t
*) &_cairo_surface_nil_unsupported
;
2740 case CAIRO_INT_STATUS_NOTHING_TO_DO
:
2741 return (cairo_surface_t
*) &_cairo_surface_nil_nothing_to_do
;
2743 _cairo_error_throw (CAIRO_STATUS_NO_MEMORY
);
2744 return (cairo_surface_t
*) &_cairo_surface_nil
;
2748 /* LocalWords: rasterized