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-private.h"
43 #include "cairo-device-private.h"
44 #include "cairo-error-private.h"
45 #include "cairo-image-surface-private.h"
46 #include "cairo-recording-surface-private.h"
47 #include "cairo-region-private.h"
48 #include "cairo-tee-surface-private.h"
51 * SECTION:cairo-surface
52 * @Title: cairo_surface_t
53 * @Short_Description: Base class for surfaces
54 * @See_Also: #cairo_t, #cairo_pattern_t
56 * #cairo_surface_t is the abstract type representing all different drawing
57 * targets that cairo can render to. The actual drawings are
58 * performed using a cairo <firstterm>context</firstterm>.
60 * A cairo surface is created by using <firstterm>backend</firstterm>-specific
61 * constructors, typically of the form
62 * <function>cairo_<emphasis>backend</emphasis>_surface_create(<!-- -->)</function>.
64 * Most surface types allow accessing the surface without using Cairo
65 * functions. If you do this, keep in mind that it is mandatory that you call
66 * cairo_surface_flush() before reading from or writing to the surface and that
67 * you must use cairo_surface_mark_dirty() after modifying it.
69 * <title>Directly modifying an image surface</title>
72 * modify_image_surface (cairo_surface_t *surface)
74 * unsigned char *data;
75 * int width, height, stride;
77 * // flush to ensure all writing to the image was done
78 * cairo_surface_flush (surface);
81 * data = cairo_image_surface_get_data (surface);
82 * width = cairo_image_surface_get_width (surface);
83 * height = cairo_image_surface_get_height (surface);
84 * stride = cairo_image_surface_get_stride (surface);
85 * modify_image_data (data, width, height, stride);
87 * // mark the image dirty so Cairo clears its caches.
88 * cairo_surface_mark_dirty (surface);
92 * Note that for other surface types it might be necessary to acquire the
93 * surface's device first. See cairo_device_acquire() for a discussion of
97 #define DEFINE_NIL_SURFACE(status, name) \
98 const cairo_surface_t name = { \
101 CAIRO_SURFACE_TYPE_IMAGE, /* type */ \
102 CAIRO_CONTENT_COLOR, /* content */ \
103 CAIRO_REFERENCE_COUNT_INVALID, /* ref_count */ \
104 status, /* status */ \
107 FALSE, /* finished */ \
108 TRUE, /* is_clear */ \
109 FALSE, /* has_font_options */ \
110 FALSE, /* owns_device */ \
111 { 0, 0, 0, NULL, }, /* user_data */ \
112 { 0, 0, 0, NULL, }, /* mime_data */ \
113 { 1.0, 0.0, 0.0, 1.0, 0.0, 0.0 }, /* device_transform */ \
114 { 1.0, 0.0, 0.0, 1.0, 0.0, 0.0 }, /* device_transform_inverse */ \
115 { NULL, NULL }, /* device_transform_observers */ \
116 0.0, /* x_resolution */ \
117 0.0, /* y_resolution */ \
118 0.0, /* x_fallback_resolution */ \
119 0.0, /* y_fallback_resolution */ \
120 NULL, /* snapshot_of */ \
121 NULL, /* snapshot_detach */ \
122 { NULL, NULL }, /* snapshots */ \
123 { NULL, NULL }, /* snapshot */ \
124 { CAIRO_ANTIALIAS_DEFAULT, /* antialias */ \
125 CAIRO_SUBPIXEL_ORDER_DEFAULT, /* subpixel_order */ \
126 CAIRO_LCD_FILTER_DEFAULT, /* lcd_filter */ \
127 CAIRO_HINT_STYLE_DEFAULT, /* hint_style */ \
128 CAIRO_HINT_METRICS_DEFAULT, /* hint_metrics */ \
129 CAIRO_ROUND_GLYPH_POS_DEFAULT /* round_glyph_positions */ \
130 } /* font_options */ \
133 /* XXX error object! */
135 static DEFINE_NIL_SURFACE(CAIRO_STATUS_NO_MEMORY, _cairo_surface_nil);
136 static DEFINE_NIL_SURFACE(CAIRO_STATUS_SURFACE_TYPE_MISMATCH, _cairo_surface_nil_surface_type_mismatch);
137 static DEFINE_NIL_SURFACE(CAIRO_STATUS_INVALID_STATUS, _cairo_surface_nil_invalid_status);
138 static DEFINE_NIL_SURFACE(CAIRO_STATUS_INVALID_CONTENT, _cairo_surface_nil_invalid_content);
139 static DEFINE_NIL_SURFACE(CAIRO_STATUS_INVALID_FORMAT, _cairo_surface_nil_invalid_format);
140 static DEFINE_NIL_SURFACE(CAIRO_STATUS_INVALID_VISUAL, _cairo_surface_nil_invalid_visual);
141 static DEFINE_NIL_SURFACE(CAIRO_STATUS_FILE_NOT_FOUND, _cairo_surface_nil_file_not_found);
142 static DEFINE_NIL_SURFACE(CAIRO_STATUS_TEMP_FILE_ERROR, _cairo_surface_nil_temp_file_error);
143 static DEFINE_NIL_SURFACE(CAIRO_STATUS_READ_ERROR, _cairo_surface_nil_read_error);
144 static DEFINE_NIL_SURFACE(CAIRO_STATUS_WRITE_ERROR, _cairo_surface_nil_write_error);
145 static DEFINE_NIL_SURFACE(CAIRO_STATUS_INVALID_STRIDE, _cairo_surface_nil_invalid_stride);
146 static DEFINE_NIL_SURFACE(CAIRO_STATUS_INVALID_SIZE, _cairo_surface_nil_invalid_size);
147 static DEFINE_NIL_SURFACE(CAIRO_STATUS_DEVICE_TYPE_MISMATCH, _cairo_surface_nil_device_type_mismatch);
148 static DEFINE_NIL_SURFACE(CAIRO_STATUS_DEVICE_ERROR, _cairo_surface_nil_device_error);
150 static DEFINE_NIL_SURFACE(CAIRO_INT_STATUS_UNSUPPORTED, _cairo_surface_nil_unsupported);
151 static DEFINE_NIL_SURFACE(CAIRO_INT_STATUS_NOTHING_TO_DO, _cairo_surface_nil_nothing_to_do);
154 * _cairo_surface_set_error:
155 * @surface: a surface
156 * @status: a status value indicating an error
158 * Atomically sets surface->status to @status and calls _cairo_error;
159 * Does nothing if status is %CAIRO_STATUS_SUCCESS or any of the internal
162 * All assignments of an error status to surface->status should happen
163 * through _cairo_surface_set_error(). Note that due to the nature of
164 * the atomic operation, it is not safe to call this function on the
167 * The purpose of this function is to allow the user to set a
168 * breakpoint in _cairo_error() to generate a stack trace for when the
169 * user causes cairo to detect an error.
171 * Return value: the error status.
174 _cairo_surface_set_error (cairo_surface_t *surface,
175 cairo_int_status_t status)
177 /* NOTHING_TO_DO is magic. We use it to break out of the inner-most
178 * surface function, but anything higher just sees "success".
180 if (status == CAIRO_INT_STATUS_NOTHING_TO_DO)
181 status = CAIRO_INT_STATUS_SUCCESS;
183 if (status == CAIRO_INT_STATUS_SUCCESS ||
184 status >= (int)CAIRO_INT_STATUS_LAST_STATUS)
187 /* Don't overwrite an existing error. This preserves the first
188 * error, which is the most significant. */
189 _cairo_status_set_error (&surface->status, (cairo_status_t)status);
191 return _cairo_error (status);
195 * cairo_surface_get_type:
196 * @surface: a #cairo_surface_t
198 * This function returns the type of the backend used to create
199 * a surface. See #cairo_surface_type_t for available types.
201 * Return value: The type of @surface.
206 cairo_surface_get_type (cairo_surface_t *surface)
208 /* We don't use surface->backend->type here so that some of the
209 * special "wrapper" surfaces such as cairo_paginated_surface_t
210 * can override surface->type with the type of the "child"
212 return surface->type;
214 slim_hidden_def (cairo_surface_get_type);
217 * cairo_surface_get_content:
218 * @surface: a #cairo_surface_t
220 * This function returns the content type of @surface which indicates
221 * whether the surface contains color and/or alpha information. See
224 * Return value: The content type of @surface.
229 cairo_surface_get_content (cairo_surface_t *surface)
231 return surface->content;
233 slim_hidden_def(cairo_surface_get_content);
236 * cairo_surface_status:
237 * @surface: a #cairo_surface_t
239 * Checks whether an error has previously occurred for this
242 * Return value: %CAIRO_STATUS_SUCCESS, %CAIRO_STATUS_NULL_POINTER,
243 * %CAIRO_STATUS_NO_MEMORY, %CAIRO_STATUS_READ_ERROR,
244 * %CAIRO_STATUS_INVALID_CONTENT, %CAIRO_STATUS_INVALID_FORMAT, or
245 * %CAIRO_STATUS_INVALID_VISUAL.
248 cairo_surface_status (cairo_surface_t *surface)
250 return surface->status;
252 slim_hidden_def (cairo_surface_status);
255 _cairo_surface_allocate_unique_id (void)
257 static cairo_atomic_int_t unique_id;
260 if (++unique_id == 0)
264 cairo_atomic_int_t old, id;
267 old = _cairo_atomic_uint_get (&unique_id);
271 } while (! _cairo_atomic_uint_cmpxchg (&unique_id, old, id));
278 * cairo_surface_get_device:
279 * @surface: a #cairo_surface_t
281 * This function returns the device for a @surface.
282 * See #cairo_device_t.
284 * Return value: The device for @surface or %NULL if the surface does
285 * not have an associated device.
290 cairo_surface_get_device (cairo_surface_t *surface)
292 if (unlikely (surface->status))
293 return _cairo_device_create_in_error (surface->status);
295 return surface->device;
299 _cairo_surface_has_snapshots (cairo_surface_t *surface)
301 return ! cairo_list_is_empty (&surface->snapshots);
305 _cairo_surface_has_mime_data (cairo_surface_t *surface)
307 return surface->mime_data.num_elements != 0;
311 _cairo_surface_detach_mime_data (cairo_surface_t *surface)
313 if (! _cairo_surface_has_mime_data (surface))
316 _cairo_user_data_array_fini (&surface->mime_data);
317 _cairo_user_data_array_init (&surface->mime_data);
321 _cairo_surface_detach_snapshots (cairo_surface_t *surface)
323 while (_cairo_surface_has_snapshots (surface)) {
324 _cairo_surface_detach_snapshot (cairo_list_first_entry (&surface->snapshots,
331 _cairo_surface_detach_snapshot (cairo_surface_t *snapshot)
333 assert (snapshot->snapshot_of != NULL);
335 snapshot->snapshot_of = NULL;
336 cairo_list_del (&snapshot->snapshot);
338 if (snapshot->snapshot_detach != NULL)
339 snapshot->snapshot_detach (snapshot);
341 cairo_surface_destroy (snapshot);
345 _cairo_surface_attach_snapshot (cairo_surface_t *surface,
346 cairo_surface_t *snapshot,
347 cairo_surface_func_t detach_func)
349 assert (surface != snapshot);
350 assert (snapshot->snapshot_of != surface);
352 cairo_surface_reference (snapshot);
354 if (snapshot->snapshot_of != NULL)
355 _cairo_surface_detach_snapshot (snapshot);
357 snapshot->snapshot_of = surface;
358 snapshot->snapshot_detach = detach_func;
360 cairo_list_add (&snapshot->snapshot, &surface->snapshots);
362 assert (_cairo_surface_has_snapshot (surface, snapshot->backend) == snapshot);
366 _cairo_surface_has_snapshot (cairo_surface_t *surface,
367 const cairo_surface_backend_t *backend)
369 cairo_surface_t *snapshot;
371 cairo_list_foreach_entry (snapshot, cairo_surface_t,
372 &surface->snapshots, snapshot)
374 if (snapshot->backend == backend)
382 _cairo_surface_begin_modification (cairo_surface_t *surface)
384 assert (surface->status == CAIRO_STATUS_SUCCESS);
385 assert (! surface->finished);
386 assert (surface->snapshot_of == NULL);
388 _cairo_surface_detach_snapshots (surface);
389 _cairo_surface_detach_mime_data (surface);
393 _cairo_surface_init (cairo_surface_t *surface,
394 const cairo_surface_backend_t *backend,
395 cairo_device_t *device,
396 cairo_content_t content)
398 CAIRO_MUTEX_INITIALIZE ();
400 surface->backend = backend;
401 surface->device = cairo_device_reference (device);
402 surface->content = content;
403 surface->type = backend->type;
405 CAIRO_REFERENCE_COUNT_INIT (&surface->ref_count, 1);
406 surface->status = CAIRO_STATUS_SUCCESS;
407 surface->unique_id = _cairo_surface_allocate_unique_id ();
408 surface->finished = FALSE;
409 surface->is_clear = FALSE;
411 surface->owns_device = (device != NULL);
413 _cairo_user_data_array_init (&surface->user_data);
414 _cairo_user_data_array_init (&surface->mime_data);
416 cairo_matrix_init_identity (&surface->device_transform);
417 cairo_matrix_init_identity (&surface->device_transform_inverse);
418 cairo_list_init (&surface->device_transform_observers);
420 surface->x_resolution = CAIRO_SURFACE_RESOLUTION_DEFAULT;
421 surface->y_resolution = CAIRO_SURFACE_RESOLUTION_DEFAULT;
423 surface->x_fallback_resolution = CAIRO_SURFACE_FALLBACK_RESOLUTION_DEFAULT;
424 surface->y_fallback_resolution = CAIRO_SURFACE_FALLBACK_RESOLUTION_DEFAULT;
426 cairo_list_init (&surface->snapshots);
427 surface->snapshot_of = NULL;
429 surface->has_font_options = FALSE;
433 _cairo_surface_copy_similar_properties (cairo_surface_t *surface,
434 cairo_surface_t *other)
436 if (other->has_font_options || other->backend != surface->backend) {
437 cairo_font_options_t options;
439 cairo_surface_get_font_options (other, &options);
440 _cairo_surface_set_font_options (surface, &options);
443 cairo_surface_set_fallback_resolution (surface,
444 other->x_fallback_resolution,
445 other->y_fallback_resolution);
449 _cairo_surface_create_similar_scratch (cairo_surface_t *other,
450 cairo_content_t content,
454 cairo_surface_t *surface;
456 if (unlikely (other->status))
457 return _cairo_surface_create_in_error (other->status);
460 if (other->backend->create_similar)
461 surface = other->backend->create_similar (other, content, width, height);
463 surface = cairo_surface_create_similar_image (other,
464 _cairo_format_from_content (content),
467 if (unlikely (surface->status))
470 _cairo_surface_copy_similar_properties (surface, other);
476 * cairo_surface_create_similar:
477 * @other: an existing surface used to select the backend of the new surface
478 * @content: the content for the new surface
479 * @width: width of the new surface, (in device-space units)
480 * @height: height of the new surface (in device-space units)
482 * Create a new surface that is as compatible as possible with an
483 * existing surface. For example the new surface will have the same
484 * fallback resolution and font options as @other. Generally, the new
485 * surface will also use the same backend as @other, unless that is
486 * not possible for some reason. The type of the returned surface may
487 * be examined with cairo_surface_get_type().
489 * Initially the surface contents are all 0 (transparent if contents
490 * have transparency, black otherwise.)
492 * Use cairo_surface_create_similar_image() if you need an image surface
493 * which can be painted quickly to the target surface.
495 * Return value: a pointer to the newly allocated surface. The caller
496 * owns the surface and should call cairo_surface_destroy() when done
499 * This function always returns a valid pointer, but it will return a
500 * pointer to a "nil" surface if @other is already in an error state
501 * or any other error occurs.
504 cairo_surface_create_similar (cairo_surface_t *other,
505 cairo_content_t content,
509 cairo_surface_t *surface;
511 if (unlikely (other->status))
512 return _cairo_surface_create_in_error (other->status);
513 if (unlikely (other->finished))
514 return _cairo_surface_create_in_error (CAIRO_STATUS_SURFACE_FINISHED);
515 if (unlikely (width < 0 || height < 0))
516 return _cairo_surface_create_in_error (CAIRO_STATUS_INVALID_SIZE);
518 if (unlikely (! CAIRO_CONTENT_VALID (content)))
519 return _cairo_surface_create_in_error (CAIRO_STATUS_INVALID_CONTENT);
521 surface = _cairo_surface_create_similar_solid (other,
522 content, width, height,
523 CAIRO_COLOR_TRANSPARENT);
524 assert (surface->is_clear);
530 * cairo_surface_create_similar_image:
531 * @other: an existing surface used to select the preference of the new surface
532 * @format: the format for the new surface
533 * @width: width of the new surface, (in device-space units)
534 * @height: height of the new surface (in device-space units)
536 * Create a new image surface that is as compatible as possible for uploading
537 * to and the use in conjunction with an existing surface. However, this surface
538 * can still be used like any normal image surface.
540 * Initially the surface contents are all 0 (transparent if contents
541 * have transparency, black otherwise.)
543 * Use cairo_surface_create_similar() if you don't need an image surface.
545 * Return value: a pointer to the newly allocated image surface. The caller
546 * owns the surface and should call cairo_surface_destroy() when done
549 * This function always returns a valid pointer, but it will return a
550 * pointer to a "nil" surface if @other is already in an error state
551 * or any other error occurs.
556 cairo_surface_create_similar_image (cairo_surface_t *other,
557 cairo_format_t format,
561 cairo_surface_t *image;
563 if (unlikely (other->status))
564 return _cairo_surface_create_in_error (other->status);
565 if (unlikely (other->finished))
566 return _cairo_surface_create_in_error (CAIRO_STATUS_SURFACE_FINISHED);
568 if (unlikely (width < 0 || height < 0))
569 return _cairo_surface_create_in_error (CAIRO_STATUS_INVALID_SIZE);
570 if (unlikely (! CAIRO_FORMAT_VALID (format)))
571 return _cairo_surface_create_in_error (CAIRO_STATUS_INVALID_FORMAT);
574 if (other->backend->create_similar_image)
575 image = other->backend->create_similar_image (other,
576 format, width, height);
578 image = cairo_image_surface_create (format, width, height);
580 assert (image->is_clear);
584 slim_hidden_def (cairo_surface_create_similar_image);
587 * cairo_surface_map_to_image:
588 * @surface: an existing surface used to extract the image from
589 * @extents: limit the extraction to an rectangular region
591 * Returns an image surface that is the most efficient mechanism for
592 * modifying the backing store of the target surface. The region retrieved
593 * may be limited to the @extents or %NULL for the whole surface
595 * Note, the use of the original surface as a target or source whilst it is
596 * mapped is undefined. The result of mapping the surface multiple times is
597 * undefined. Calling cairo_surface_destroy() or cairo_surface_finish() on the
598 * resulting image surface results in undefined behavior.
600 * Return value: a pointer to the newly allocated image surface. The caller
601 * must use cairo_surface_unmap_image() to destroy this image surface.
603 * This function always returns a valid pointer, but it will return a
604 * pointer to a "nil" surface if @other is already in an error state
605 * or any other error occurs.
610 cairo_surface_map_to_image (cairo_surface_t *surface,
611 const cairo_rectangle_int_t *extents)
613 cairo_rectangle_int_t rect;
614 cairo_surface_t *image;
616 if (unlikely (surface->status))
617 return _cairo_surface_create_in_error (surface->status);
618 if (unlikely (surface->finished))
619 return _cairo_surface_create_in_error (CAIRO_STATUS_SURFACE_FINISHED);
621 if (extents == NULL) {
622 if (unlikely (! surface->backend->get_extents (surface, &rect)))
623 return _cairo_surface_create_in_error (CAIRO_STATUS_INVALID_SIZE);
627 cairo_rectangle_int_t surface_extents;
629 /* If this surface is bounded, we can't map parts
630 * that are outside of it. */
631 if (likely (surface->backend->get_extents (surface, &surface_extents))) {
632 if (unlikely (extents->x < surface_extents.x ||
633 extents->y < surface_extents.y ||
634 extents->x + extents->width > surface_extents.x + surface_extents.width ||
635 extents->y + extents->height > surface_extents.y + surface_extents.height))
636 return _cairo_surface_create_in_error (CAIRO_STATUS_INVALID_SIZE);
641 if (surface->backend->map_to_image)
642 image = surface->backend->map_to_image (surface, extents);
645 cairo_surface_pattern_t pattern;
646 cairo_status_t status;
648 image = cairo_surface_create_similar_image (surface,
649 _cairo_format_from_content (surface->content),
652 cairo_surface_set_device_offset (image, -extents->y, -extents->y);
654 _cairo_pattern_init_for_surface (&pattern, surface);
655 pattern.base.filter = CAIRO_FILTER_NEAREST;
657 status = _cairo_surface_paint (image,
658 CAIRO_OPERATOR_SOURCE,
662 _cairo_pattern_fini (&pattern.base);
664 if (unlikely (status)) {
665 cairo_surface_destroy (image);
666 image = _cairo_surface_create_in_error (status);
672 slim_hidden_def (cairo_surface_map_to_image);
675 * cairo_surface_unmap_image:
676 * @surface: the surface passed to cairo_surface_map_to_image().
677 * @image: the currently mapped image
679 * Unmaps the image surface as returned from #cairo_surface_map_to_image().
681 * The content of the image will be uploaded to the target surface.
682 * Afterwards, the image is destroyed.
684 * Using an image surface which wasn't returned by cairo_surface_map_to_image()
685 * results in undefined behavior.
690 cairo_surface_unmap_image (cairo_surface_t *surface,
691 cairo_surface_t *image)
693 cairo_int_status_t status;
695 if (unlikely (surface->status)) {
696 status = surface->status;
699 if (unlikely (surface->finished)) {
700 status = _cairo_error (CAIRO_STATUS_SURFACE_FINISHED);
704 if (unlikely (image->status)) {
705 status = image->status;
708 if (unlikely (image->finished)) {
709 status = _cairo_error (CAIRO_STATUS_SURFACE_FINISHED);
712 if (unlikely (! _cairo_surface_is_image (image))) {
713 status = _cairo_error (CAIRO_STATUS_SURFACE_TYPE_MISMATCH);
717 /* If the image is untouched just skip the update */
718 if (image->serial == 0) {
719 status = CAIRO_STATUS_SUCCESS;
723 status = CAIRO_INT_STATUS_UNSUPPORTED;
724 if (surface->backend->unmap_image)
725 status = surface->backend->unmap_image (surface, (cairo_image_surface_t *) image);
726 if (status == CAIRO_INT_STATUS_UNSUPPORTED) {
727 cairo_image_surface_t *img = (cairo_image_surface_t *) image;
728 cairo_surface_pattern_t pattern;
730 cairo_rectangle_int_t extents;
732 _cairo_pattern_init_for_surface (&pattern, image);
733 pattern.base.filter = CAIRO_FILTER_NEAREST;
735 /* We have to apply the translate from map_to_image's extents.x and .y */
736 cairo_matrix_init_translate (&pattern.base.matrix,
737 image->device_transform.x0,
738 image->device_transform.y0);
740 /* And we also have to clip the operation to the image's extents */
741 extents.x = image->device_transform_inverse.x0;
742 extents.y = image->device_transform_inverse.y0;
743 extents.width = img->width;
744 extents.height = img->height;
745 clip = _cairo_clip_intersect_rectangle (NULL, &extents);
747 status = _cairo_surface_paint (surface,
748 CAIRO_OPERATOR_SOURCE,
752 _cairo_pattern_fini (&pattern.base);
753 _cairo_clip_destroy (clip);
757 cairo_surface_finish (image);
758 cairo_surface_destroy (image);
760 _cairo_surface_set_error (surface, status);
762 slim_hidden_def (cairo_surface_unmap_image);
765 _cairo_surface_create_similar_solid (cairo_surface_t *other,
766 cairo_content_t content,
769 const cairo_color_t *color)
771 cairo_status_t status;
772 cairo_surface_t *surface;
773 cairo_solid_pattern_t pattern;
775 surface = _cairo_surface_create_similar_scratch (other, content,
777 if (unlikely (surface->status))
780 _cairo_pattern_init_solid (&pattern, color);
781 status = _cairo_surface_paint (surface,
782 color == CAIRO_COLOR_TRANSPARENT ?
783 CAIRO_OPERATOR_CLEAR : CAIRO_OPERATOR_SOURCE,
784 &pattern.base, NULL);
785 if (unlikely (status)) {
786 cairo_surface_destroy (surface);
787 surface = _cairo_surface_create_in_error (status);
794 * cairo_surface_reference:
795 * @surface: a #cairo_surface_t
797 * Increases the reference count on @surface by one. This prevents
798 * @surface from being destroyed until a matching call to
799 * cairo_surface_destroy() is made.
801 * The number of references to a #cairo_surface_t can be get using
802 * cairo_surface_get_reference_count().
804 * Return value: the referenced #cairo_surface_t.
807 cairo_surface_reference (cairo_surface_t *surface)
809 if (surface == NULL ||
810 CAIRO_REFERENCE_COUNT_IS_INVALID (&surface->ref_count))
813 assert (CAIRO_REFERENCE_COUNT_HAS_REFERENCE (&surface->ref_count));
815 _cairo_reference_count_inc (&surface->ref_count);
819 slim_hidden_def (cairo_surface_reference);
822 * cairo_surface_destroy:
823 * @surface: a #cairo_surface_t
825 * Decreases the reference count on @surface by one. If the result is
826 * zero, then @surface and all associated resources are freed. See
827 * cairo_surface_reference().
830 cairo_surface_destroy (cairo_surface_t *surface)
832 if (surface == NULL ||
833 CAIRO_REFERENCE_COUNT_IS_INVALID (&surface->ref_count))
836 assert (CAIRO_REFERENCE_COUNT_HAS_REFERENCE (&surface->ref_count));
838 if (! _cairo_reference_count_dec_and_test (&surface->ref_count))
841 assert (surface->snapshot_of == NULL);
843 if (! surface->finished)
844 cairo_surface_finish (surface);
846 /* paranoid check that nobody took a reference whilst finishing */
847 assert (! CAIRO_REFERENCE_COUNT_HAS_REFERENCE (&surface->ref_count));
849 _cairo_user_data_array_fini (&surface->user_data);
850 _cairo_user_data_array_fini (&surface->mime_data);
852 if (surface->owns_device)
853 cairo_device_destroy (surface->device);
855 assert (surface->snapshot_of == NULL);
856 assert (!_cairo_surface_has_snapshots (surface));
860 slim_hidden_def(cairo_surface_destroy);
863 * cairo_surface_get_reference_count:
864 * @surface: a #cairo_surface_t
866 * Returns the current reference count of @surface.
868 * Return value: the current reference count of @surface. If the
869 * object is a nil object, 0 will be returned.
874 cairo_surface_get_reference_count (cairo_surface_t *surface)
876 if (surface == NULL ||
877 CAIRO_REFERENCE_COUNT_IS_INVALID (&surface->ref_count))
880 return CAIRO_REFERENCE_COUNT_GET_VALUE (&surface->ref_count);
884 * cairo_surface_finish:
885 * @surface: the #cairo_surface_t to finish
887 * This function finishes the surface and drops all references to
888 * external resources. For example, for the Xlib backend it means
889 * that cairo will no longer access the drawable, which can be freed.
890 * After calling cairo_surface_finish() the only valid operations on a
891 * surface are getting and setting user, referencing and
892 * destroying, and flushing and finishing it.
893 * Further drawing to the surface will not affect the
894 * surface but will instead trigger a %CAIRO_STATUS_SURFACE_FINISHED
897 * When the last call to cairo_surface_destroy() decreases the
898 * reference count to zero, cairo will call cairo_surface_finish() if
899 * it hasn't been called already, before freeing the resources
900 * associated with the surface.
903 cairo_surface_finish (cairo_surface_t *surface)
905 cairo_status_t status;
910 if (CAIRO_REFERENCE_COUNT_IS_INVALID (&surface->ref_count))
913 if (surface->finished)
916 cairo_surface_flush (surface);
918 /* update the snapshots *before* we declare the surface as finished */
919 _cairo_surface_detach_snapshots (surface);
920 if (surface->snapshot_of != NULL)
921 _cairo_surface_detach_snapshot (surface);
923 surface->finished = TRUE;
925 /* call finish even if in error mode */
926 if (surface->backend->finish) {
927 status = surface->backend->finish (surface);
928 if (unlikely (status))
929 _cairo_surface_set_error (surface, status);
932 assert (surface->snapshot_of == NULL);
933 assert (!_cairo_surface_has_snapshots (surface));
935 slim_hidden_def (cairo_surface_finish);
938 * _cairo_surface_release_device_reference:
939 * @surface: a #cairo_surface_t
941 * This function makes @surface release the reference to its device. The
942 * function is intended to be used for avoiding cycling references for
943 * surfaces that are owned by their device, for example cache surfaces.
944 * Note that the @surface will still assume that the device is available.
945 * So it is the caller's responsibility to ensure the device stays around
946 * until the @surface is destroyed. Just calling cairo_surface_finish() is
950 _cairo_surface_release_device_reference (cairo_surface_t *surface)
952 assert (surface->owns_device);
954 cairo_device_destroy (surface->device);
955 surface->owns_device = FALSE;
959 * cairo_surface_get_user_data:
960 * @surface: a #cairo_surface_t
961 * @key: the address of the #cairo_user_data_key_t the user data was
964 * Return user data previously attached to @surface using the specified
965 * key. If no user data has been attached with the given key this
966 * function returns %NULL.
968 * Return value: the user data previously attached or %NULL.
971 cairo_surface_get_user_data (cairo_surface_t *surface,
972 const cairo_user_data_key_t *key)
974 return _cairo_user_data_array_get_data (&surface->user_data, key);
978 * cairo_surface_set_user_data:
979 * @surface: a #cairo_surface_t
980 * @key: the address of a #cairo_user_data_key_t to attach the user data to
981 * @user_data: the user data to attach to the surface
982 * @destroy: a #cairo_destroy_func_t which will be called when the
983 * surface is destroyed or when new user data is attached using the
986 * Attach user data to @surface. To remove user data from a surface,
987 * call this function with the key that was used to set it and %NULL
990 * Return value: %CAIRO_STATUS_SUCCESS or %CAIRO_STATUS_NO_MEMORY if a
991 * slot could not be allocated for the user data.
994 cairo_surface_set_user_data (cairo_surface_t *surface,
995 const cairo_user_data_key_t *key,
997 cairo_destroy_func_t destroy)
999 if (CAIRO_REFERENCE_COUNT_IS_INVALID (&surface->ref_count))
1000 return surface->status;
1002 return _cairo_user_data_array_set_data (&surface->user_data,
1003 key, user_data, destroy);
1007 * cairo_surface_get_mime_data:
1008 * @surface: a #cairo_surface_t
1009 * @mime_type: the mime type of the image data
1010 * @data: the image data to attached to the surface
1011 * @length: the length of the image data
1013 * Return mime data previously attached to @surface using the
1014 * specified mime type. If no data has been attached with the given
1015 * mime type, @data is set %NULL.
1020 cairo_surface_get_mime_data (cairo_surface_t *surface,
1021 const char *mime_type,
1022 const unsigned char **data,
1023 unsigned long *length)
1025 cairo_user_data_slot_t *slots;
1030 if (unlikely (surface->status))
1033 /* The number of mime-types attached to a surface is usually small,
1034 * typically zero. Therefore it is quicker to do a strcmp() against
1035 * each key than it is to intern the string (i.e. compute a hash,
1036 * search the hash table, and do a final strcmp).
1038 num_slots = surface->mime_data.num_elements;
1039 slots = _cairo_array_index (&surface->mime_data, 0);
1040 for (i = 0; i < num_slots; i++) {
1041 if (slots[i].key != NULL && strcmp ((char *) slots[i].key, mime_type) == 0) {
1042 cairo_mime_data_t *mime_data = slots[i].user_data;
1044 *data = mime_data->data;
1045 *length = mime_data->length;
1050 slim_hidden_def (cairo_surface_get_mime_data);
1053 _cairo_mime_data_destroy (void *ptr)
1055 cairo_mime_data_t *mime_data = ptr;
1057 if (! _cairo_reference_count_dec_and_test (&mime_data->ref_count))
1060 if (mime_data->destroy && mime_data->closure)
1061 mime_data->destroy (mime_data->closure);
1067 * CAIRO_MIME_TYPE_JP2:
1069 * The Joint Photographic Experts Group (JPEG) 2000 image coding standard (ISO/IEC 15444-1).
1075 * CAIRO_MIME_TYPE_JPEG:
1077 * The Joint Photographic Experts Group (JPEG) image coding standard (ISO/IEC 10918-1).
1083 * CAIRO_MIME_TYPE_PNG:
1085 * The Portable Network Graphics image file format (ISO/IEC 15948).
1091 * CAIRO_MIME_TYPE_URI:
1093 * URI for an image file (unofficial MIME type).
1099 * CAIRO_MIME_TYPE_UNIQUE_ID:
1101 * Unique identifier for a surface (cairo specific MIME type).
1107 * cairo_surface_set_mime_data:
1108 * @surface: a #cairo_surface_t
1109 * @mime_type: the MIME type of the image data
1110 * @data: the image data to attach to the surface
1111 * @length: the length of the image data
1112 * @destroy: a #cairo_destroy_func_t which will be called when the
1113 * surface is destroyed or when new image data is attached using the
1115 * @closure: the data to be passed to the @destroy notifier
1117 * Attach an image in the format @mime_type to @surface. To remove
1118 * the data from a surface, call this function with same mime type
1119 * and %NULL for @data.
1121 * The attached image (or filename) data can later be used by backends
1122 * which support it (currently: PDF, PS, SVG and Win32 Printing
1123 * surfaces) to emit this data instead of making a snapshot of the
1124 * @surface. This approach tends to be faster and requires less
1125 * memory and disk space.
1127 * The recognized MIME types are the following: %CAIRO_MIME_TYPE_JPEG,
1128 * %CAIRO_MIME_TYPE_PNG, %CAIRO_MIME_TYPE_JP2, %CAIRO_MIME_TYPE_URI.
1130 * See corresponding backend surface docs for details about which MIME
1131 * types it can handle. Caution: the associated MIME data will be
1132 * discarded if you draw on the surface afterwards. Use this function
1137 * Return value: %CAIRO_STATUS_SUCCESS or %CAIRO_STATUS_NO_MEMORY if a
1138 * slot could not be allocated for the user data.
1141 cairo_surface_set_mime_data (cairo_surface_t *surface,
1142 const char *mime_type,
1143 const unsigned char *data,
1144 unsigned long length,
1145 cairo_destroy_func_t destroy,
1148 cairo_status_t status;
1149 cairo_mime_data_t *mime_data;
1151 if (unlikely (surface->status))
1152 return surface->status;
1153 if (unlikely (surface->finished))
1154 return _cairo_surface_set_error (surface, _cairo_error (CAIRO_STATUS_SURFACE_FINISHED));
1156 status = _cairo_intern_string (&mime_type, -1);
1157 if (unlikely (status))
1158 return _cairo_surface_set_error (surface, status);
1161 mime_data = malloc (sizeof (cairo_mime_data_t));
1162 if (unlikely (mime_data == NULL))
1163 return _cairo_surface_set_error (surface, _cairo_error (CAIRO_STATUS_NO_MEMORY));
1165 CAIRO_REFERENCE_COUNT_INIT (&mime_data->ref_count, 1);
1167 mime_data->data = (unsigned char *) data;
1168 mime_data->length = length;
1169 mime_data->destroy = destroy;
1170 mime_data->closure = closure;
1174 status = _cairo_user_data_array_set_data (&surface->mime_data,
1175 (cairo_user_data_key_t *) mime_type,
1177 _cairo_mime_data_destroy);
1178 if (unlikely (status)) {
1181 return _cairo_surface_set_error (surface, status);
1184 return CAIRO_STATUS_SUCCESS;
1186 slim_hidden_def (cairo_surface_set_mime_data);
1189 _cairo_mime_data_reference (const void *key, void *elt, void *closure)
1191 cairo_mime_data_t *mime_data = elt;
1193 _cairo_reference_count_inc (&mime_data->ref_count);
1197 _cairo_surface_copy_mime_data (cairo_surface_t *dst,
1198 cairo_surface_t *src)
1200 cairo_status_t status;
1206 return _cairo_surface_set_error (dst, src->status);
1208 /* first copy the mime-data, discarding any already set on dst */
1209 status = _cairo_user_data_array_copy (&dst->mime_data, &src->mime_data);
1210 if (unlikely (status))
1211 return _cairo_surface_set_error (dst, status);
1213 /* now increment the reference counters for the copies */
1214 _cairo_user_data_array_foreach (&dst->mime_data,
1215 _cairo_mime_data_reference,
1218 return CAIRO_STATUS_SUCCESS;
1222 * _cairo_surface_set_font_options:
1223 * @surface: a #cairo_surface_t
1224 * @options: a #cairo_font_options_t object that contains the
1225 * options to use for this surface instead of backend's default
1228 * Sets the default font rendering options for the surface.
1229 * This is useful to correctly propagate default font options when
1230 * falling back to an image surface in a backend implementation.
1231 * This affects the options returned in cairo_surface_get_font_options().
1233 * If @options is %NULL the surface options are reset to those of
1234 * the backend default.
1237 _cairo_surface_set_font_options (cairo_surface_t *surface,
1238 cairo_font_options_t *options)
1240 if (surface->status)
1243 assert (surface->snapshot_of == NULL);
1245 if (surface->finished) {
1246 _cairo_surface_set_error (surface, _cairo_error (CAIRO_STATUS_SURFACE_FINISHED));
1251 surface->has_font_options = TRUE;
1252 _cairo_font_options_init_copy (&surface->font_options, options);
1254 surface->has_font_options = FALSE;
1259 * cairo_surface_get_font_options:
1260 * @surface: a #cairo_surface_t
1261 * @options: a #cairo_font_options_t object into which to store
1262 * the retrieved options. All existing values are overwritten
1264 * Retrieves the default font rendering options for the surface.
1265 * This allows display surfaces to report the correct subpixel order
1266 * for rendering on them, print surfaces to disable hinting of
1267 * metrics and so forth. The result can then be used with
1268 * cairo_scaled_font_create().
1271 cairo_surface_get_font_options (cairo_surface_t *surface,
1272 cairo_font_options_t *options)
1274 if (cairo_font_options_status (options))
1277 if (surface->status) {
1278 _cairo_font_options_init_default (options);
1282 if (! surface->has_font_options) {
1283 surface->has_font_options = TRUE;
1285 _cairo_font_options_init_default (&surface->font_options);
1287 if (!surface->finished && surface->backend->get_font_options) {
1288 surface->backend->get_font_options (surface, &surface->font_options);
1292 _cairo_font_options_init_copy (options, &surface->font_options);
1294 slim_hidden_def (cairo_surface_get_font_options);
1297 * cairo_surface_flush:
1298 * @surface: a #cairo_surface_t
1300 * Do any pending drawing for the surface and also restore any
1301 * temporary modifications cairo has made to the surface's
1302 * state. This function must be called before switching from
1303 * drawing on the surface with cairo to drawing on it directly
1304 * with native APIs. If the surface doesn't support direct access,
1305 * then this function does nothing.
1308 cairo_surface_flush (cairo_surface_t *surface)
1310 cairo_status_t status;
1312 if (surface->status)
1315 if (surface->finished)
1318 /* update the current snapshots *before* the user updates the surface */
1319 _cairo_surface_detach_snapshots (surface);
1320 _cairo_surface_detach_mime_data (surface);
1322 if (surface->backend->flush) {
1323 status = surface->backend->flush (surface);
1324 if (unlikely (status))
1325 _cairo_surface_set_error (surface, status);
1328 slim_hidden_def (cairo_surface_flush);
1331 * cairo_surface_mark_dirty:
1332 * @surface: a #cairo_surface_t
1334 * Tells cairo that drawing has been done to surface using means other
1335 * than cairo, and that cairo should reread any cached areas. Note
1336 * that you must call cairo_surface_flush() before doing such drawing.
1339 cairo_surface_mark_dirty (cairo_surface_t *surface)
1341 cairo_surface_mark_dirty_rectangle (surface, 0, 0, -1, -1);
1343 slim_hidden_def (cairo_surface_mark_dirty);
1346 * cairo_surface_mark_dirty_rectangle:
1347 * @surface: a #cairo_surface_t
1348 * @x: X coordinate of dirty rectangle
1349 * @y: Y coordinate of dirty rectangle
1350 * @width: width of dirty rectangle
1351 * @height: height of dirty rectangle
1353 * Like cairo_surface_mark_dirty(), but drawing has been done only to
1354 * the specified rectangle, so that cairo can retain cached contents
1355 * for other parts of the surface.
1357 * Any cached clip set on the surface will be reset by this function,
1358 * to make sure that future cairo calls have the clip set that they
1362 cairo_surface_mark_dirty_rectangle (cairo_surface_t *surface,
1368 cairo_status_t status;
1370 if (unlikely (surface->status))
1373 assert (surface->snapshot_of == NULL);
1375 if (unlikely (surface->finished)) {
1376 _cairo_surface_set_error (surface, _cairo_error (CAIRO_STATUS_SURFACE_FINISHED));
1380 /* The application *should* have called cairo_surface_flush() before
1381 * modifying the surface independently of cairo (and thus having to
1382 * call mark_dirty()). */
1383 assert (! _cairo_surface_has_snapshots (surface));
1384 assert (! _cairo_surface_has_mime_data (surface));
1386 surface->is_clear = FALSE;
1389 if (surface->backend->mark_dirty_rectangle != NULL) {
1390 /* XXX: FRAGILE: We're ignoring the scaling component of
1391 * device_transform here. I don't know what the right thing to
1392 * do would actually be if there were some scaling here, but
1393 * we avoid this since device_transfom scaling is not exported
1394 * publicly and mark_dirty is not used internally. */
1395 status = surface->backend->mark_dirty_rectangle (surface,
1396 x + surface->device_transform.x0,
1397 y + surface->device_transform.y0,
1400 if (unlikely (status))
1401 _cairo_surface_set_error (surface, status);
1404 slim_hidden_def (cairo_surface_mark_dirty_rectangle);
1407 * _cairo_surface_set_device_scale:
1408 * @surface: a #cairo_surface_t
1409 * @sx: a scale factor in the X direction
1410 * @sy: a scale factor in the Y direction
1412 * Private function for setting an extra scale factor to affect all
1413 * drawing to a surface. This is used, for example, when replaying a
1414 * recording surface to an image fallback intended for an eventual
1415 * vector-oriented backend. Since the recording surface will record
1416 * coordinates in one backend space, but the image fallback uses a
1417 * different backend space, (differing by the fallback resolution
1418 * scale factors), we need a scale factor correction.
1420 * Caution: Not all places we use device transform correctly handle
1421 * both a translate and a scale. An audit would be nice.
1424 _cairo_surface_set_device_scale (cairo_surface_t *surface,
1428 cairo_status_t status;
1430 if (unlikely (surface->status))
1433 assert (surface->snapshot_of == NULL);
1435 if (unlikely (surface->finished)) {
1436 _cairo_surface_set_error (surface, _cairo_error (CAIRO_STATUS_SURFACE_FINISHED));
1440 _cairo_surface_begin_modification (surface);
1442 surface->device_transform.xx = sx;
1443 surface->device_transform.yy = sy;
1444 surface->device_transform.xy = 0.0;
1445 surface->device_transform.yx = 0.0;
1447 surface->device_transform_inverse = surface->device_transform;
1448 status = cairo_matrix_invert (&surface->device_transform_inverse);
1449 /* should always be invertible unless given pathological input */
1450 assert (status == CAIRO_STATUS_SUCCESS);
1452 _cairo_observers_notify (&surface->device_transform_observers, surface);
1456 * cairo_surface_set_device_offset:
1457 * @surface: a #cairo_surface_t
1458 * @x_offset: the offset in the X direction, in device units
1459 * @y_offset: the offset in the Y direction, in device units
1461 * Sets an offset that is added to the device coordinates determined
1462 * by the CTM when drawing to @surface. One use case for this function
1463 * is when we want to create a #cairo_surface_t that redirects drawing
1464 * for a portion of an onscreen surface to an offscreen surface in a
1465 * way that is completely invisible to the user of the cairo
1466 * API. Setting a transformation via cairo_translate() isn't
1467 * sufficient to do this, since functions like
1468 * cairo_device_to_user() will expose the hidden offset.
1470 * Note that the offset affects drawing to the surface as well as
1471 * using the surface in a source pattern.
1474 cairo_surface_set_device_offset (cairo_surface_t *surface,
1478 cairo_status_t status;
1480 if (unlikely (surface->status))
1483 assert (surface->snapshot_of == NULL);
1485 if (unlikely (surface->finished)) {
1486 _cairo_surface_set_error (surface, _cairo_error (CAIRO_STATUS_SURFACE_FINISHED));
1490 _cairo_surface_begin_modification (surface);
1492 surface->device_transform.x0 = x_offset;
1493 surface->device_transform.y0 = y_offset;
1495 surface->device_transform_inverse = surface->device_transform;
1496 status = cairo_matrix_invert (&surface->device_transform_inverse);
1497 /* should always be invertible unless given pathological input */
1498 assert (status == CAIRO_STATUS_SUCCESS);
1500 _cairo_observers_notify (&surface->device_transform_observers, surface);
1502 slim_hidden_def (cairo_surface_set_device_offset);
1505 * cairo_surface_get_device_offset:
1506 * @surface: a #cairo_surface_t
1507 * @x_offset: the offset in the X direction, in device units
1508 * @y_offset: the offset in the Y direction, in device units
1510 * This function returns the previous device offset set by
1511 * cairo_surface_set_device_offset().
1516 cairo_surface_get_device_offset (cairo_surface_t *surface,
1521 *x_offset = surface->device_transform.x0;
1523 *y_offset = surface->device_transform.y0;
1525 slim_hidden_def (cairo_surface_get_device_offset);
1528 * cairo_surface_set_fallback_resolution:
1529 * @surface: a #cairo_surface_t
1530 * @x_pixels_per_inch: horizontal setting for pixels per inch
1531 * @y_pixels_per_inch: vertical setting for pixels per inch
1533 * Set the horizontal and vertical resolution for image fallbacks.
1535 * When certain operations aren't supported natively by a backend,
1536 * cairo will fallback by rendering operations to an image and then
1537 * overlaying that image onto the output. For backends that are
1538 * natively vector-oriented, this function can be used to set the
1539 * resolution used for these image fallbacks, (larger values will
1540 * result in more detailed images, but also larger file sizes).
1542 * Some examples of natively vector-oriented backends are the ps, pdf,
1545 * For backends that are natively raster-oriented, image fallbacks are
1546 * still possible, but they are always performed at the native
1547 * device resolution. So this function has no effect on those
1550 * Note: The fallback resolution only takes effect at the time of
1551 * completing a page (with cairo_show_page() or cairo_copy_page()) so
1552 * there is currently no way to have more than one fallback resolution
1553 * in effect on a single page.
1555 * The default fallback resoultion is 300 pixels per inch in both
1561 cairo_surface_set_fallback_resolution (cairo_surface_t *surface,
1562 double x_pixels_per_inch,
1563 double y_pixels_per_inch)
1565 if (unlikely (surface->status))
1568 assert (surface->snapshot_of == NULL);
1570 if (unlikely (surface->finished)) {
1571 _cairo_surface_set_error (surface, _cairo_error (CAIRO_STATUS_SURFACE_FINISHED));
1575 if (x_pixels_per_inch <= 0 || y_pixels_per_inch <= 0) {
1576 /* XXX Could delay raising the error until we fallback, but throwing
1577 * the error here means that we can catch the real culprit.
1579 _cairo_surface_set_error (surface, CAIRO_STATUS_INVALID_MATRIX);
1583 _cairo_surface_begin_modification (surface);
1585 surface->x_fallback_resolution = x_pixels_per_inch;
1586 surface->y_fallback_resolution = y_pixels_per_inch;
1588 slim_hidden_def (cairo_surface_set_fallback_resolution);
1591 * cairo_surface_get_fallback_resolution:
1592 * @surface: a #cairo_surface_t
1593 * @x_pixels_per_inch: horizontal pixels per inch
1594 * @y_pixels_per_inch: vertical pixels per inch
1596 * This function returns the previous fallback resolution set by
1597 * cairo_surface_set_fallback_resolution(), or default fallback
1598 * resolution if never set.
1603 cairo_surface_get_fallback_resolution (cairo_surface_t *surface,
1604 double *x_pixels_per_inch,
1605 double *y_pixels_per_inch)
1607 if (x_pixels_per_inch)
1608 *x_pixels_per_inch = surface->x_fallback_resolution;
1609 if (y_pixels_per_inch)
1610 *y_pixels_per_inch = surface->y_fallback_resolution;
1614 _cairo_surface_has_device_transform (cairo_surface_t *surface)
1616 return ! _cairo_matrix_is_identity (&surface->device_transform);
1620 * _cairo_surface_acquire_source_image:
1621 * @surface: a #cairo_surface_t
1622 * @image_out: location to store a pointer to an image surface that
1623 * has identical contents to @surface. This surface could be @surface
1624 * itself, a surface held internal to @surface, or it could be a new
1625 * surface with a copy of the relevant portion of @surface.
1626 * @image_extra: location to store image specific backend data
1628 * Gets an image surface to use when drawing as a fallback when drawing with
1629 * @surface as a source. _cairo_surface_release_source_image() must be called
1632 * Return value: %CAIRO_STATUS_SUCCESS if an image was stored in @image_out.
1633 * %CAIRO_INT_STATUS_UNSUPPORTED if an image cannot be retrieved for the specified
1634 * surface. Or %CAIRO_STATUS_NO_MEMORY.
1637 _cairo_surface_acquire_source_image (cairo_surface_t *surface,
1638 cairo_image_surface_t **image_out,
1641 cairo_status_t status;
1643 if (unlikely (surface->status))
1644 return surface->status;
1646 assert (!surface->finished);
1648 if (surface->backend->acquire_source_image == NULL)
1649 return CAIRO_INT_STATUS_UNSUPPORTED;
1651 status = surface->backend->acquire_source_image (surface,
1652 image_out, image_extra);
1653 if (unlikely (status))
1654 return _cairo_surface_set_error (surface, status);
1656 _cairo_debug_check_image_surface_is_defined (&(*image_out)->base);
1658 return CAIRO_STATUS_SUCCESS;
1662 * _cairo_surface_release_source_image:
1663 * @surface: a #cairo_surface_t
1664 * @image_extra: same as return from the matching _cairo_surface_acquire_source_image()
1666 * Releases any resources obtained with _cairo_surface_acquire_source_image()
1669 _cairo_surface_release_source_image (cairo_surface_t *surface,
1670 cairo_image_surface_t *image,
1673 assert (!surface->finished);
1675 if (surface->backend->release_source_image)
1676 surface->backend->release_source_image (surface, image, image_extra);
1679 static cairo_status_t
1680 _pattern_has_error (const cairo_pattern_t *pattern)
1682 const cairo_surface_pattern_t *spattern;
1684 if (unlikely (pattern->status))
1685 return pattern->status;
1687 if (pattern->type != CAIRO_PATTERN_TYPE_SURFACE)
1688 return CAIRO_STATUS_SUCCESS;
1690 spattern = (const cairo_surface_pattern_t *) pattern;
1691 if (unlikely (spattern->surface->status))
1692 return spattern->surface->status;
1694 if (unlikely (spattern->surface->finished))
1695 return _cairo_error (CAIRO_STATUS_SURFACE_FINISHED);
1697 return CAIRO_STATUS_SUCCESS;
1701 nothing_to_do (cairo_surface_t *surface,
1702 cairo_operator_t op,
1703 const cairo_pattern_t *source)
1705 if (_cairo_pattern_is_clear (source)) {
1706 if (op == CAIRO_OPERATOR_OVER || op == CAIRO_OPERATOR_ADD)
1709 if (op == CAIRO_OPERATOR_SOURCE)
1710 op = CAIRO_OPERATOR_CLEAR;
1713 if (op == CAIRO_OPERATOR_CLEAR && surface->is_clear)
1716 if (op == CAIRO_OPERATOR_ATOP && (surface->content & CAIRO_CONTENT_COLOR) ==0)
1723 _cairo_surface_paint (cairo_surface_t *surface,
1724 cairo_operator_t op,
1725 const cairo_pattern_t *source,
1726 const cairo_clip_t *clip)
1728 cairo_int_status_t status;
1730 if (unlikely (surface->status))
1731 return surface->status;
1733 if (_cairo_clip_is_all_clipped (clip))
1734 return CAIRO_STATUS_SUCCESS;
1736 status = _pattern_has_error (source);
1737 if (unlikely (status))
1740 if (nothing_to_do (surface, op, source))
1741 return CAIRO_STATUS_SUCCESS;
1743 _cairo_surface_begin_modification (surface);
1745 status = surface->backend->paint (surface, op, source, clip);
1746 if (status != CAIRO_INT_STATUS_NOTHING_TO_DO) {
1747 surface->is_clear = op == CAIRO_OPERATOR_CLEAR && clip == NULL;
1751 return _cairo_surface_set_error (surface, status);
1755 _cairo_surface_mask (cairo_surface_t *surface,
1756 cairo_operator_t op,
1757 const cairo_pattern_t *source,
1758 const cairo_pattern_t *mask,
1759 const cairo_clip_t *clip)
1761 cairo_int_status_t status;
1763 if (unlikely (surface->status))
1764 return surface->status;
1766 if (_cairo_clip_is_all_clipped (clip))
1767 return CAIRO_STATUS_SUCCESS;
1769 /* If the mask is blank, this is just an expensive no-op */
1770 if (_cairo_pattern_is_clear (mask) &&
1771 _cairo_operator_bounded_by_mask (op))
1773 return CAIRO_STATUS_SUCCESS;
1776 status = _pattern_has_error (source);
1777 if (unlikely (status))
1780 status = _pattern_has_error (mask);
1781 if (unlikely (status))
1784 if (nothing_to_do (surface, op, source))
1785 return CAIRO_STATUS_SUCCESS;
1787 _cairo_surface_begin_modification (surface);
1789 status = surface->backend->mask (surface, op, source, mask, clip);
1790 if (status != CAIRO_INT_STATUS_NOTHING_TO_DO) {
1791 surface->is_clear = FALSE;
1795 return _cairo_surface_set_error (surface, status);
1799 _cairo_surface_fill_stroke (cairo_surface_t *surface,
1800 cairo_operator_t fill_op,
1801 const cairo_pattern_t *fill_source,
1802 cairo_fill_rule_t fill_rule,
1803 double fill_tolerance,
1804 cairo_antialias_t fill_antialias,
1805 cairo_path_fixed_t *path,
1806 cairo_operator_t stroke_op,
1807 const cairo_pattern_t *stroke_source,
1808 const cairo_stroke_style_t *stroke_style,
1809 const cairo_matrix_t *stroke_ctm,
1810 const cairo_matrix_t *stroke_ctm_inverse,
1811 double stroke_tolerance,
1812 cairo_antialias_t stroke_antialias,
1813 const cairo_clip_t *clip)
1815 cairo_int_status_t status;
1817 if (unlikely (surface->status))
1818 return surface->status;
1820 if (_cairo_clip_is_all_clipped (clip))
1821 return CAIRO_STATUS_SUCCESS;
1823 if (surface->is_clear &&
1824 fill_op == CAIRO_OPERATOR_CLEAR &&
1825 stroke_op == CAIRO_OPERATOR_CLEAR)
1827 return CAIRO_STATUS_SUCCESS;
1830 status = _pattern_has_error (fill_source);
1831 if (unlikely (status))
1834 status = _pattern_has_error (stroke_source);
1835 if (unlikely (status))
1838 _cairo_surface_begin_modification (surface);
1840 if (surface->backend->fill_stroke) {
1841 cairo_matrix_t dev_ctm = *stroke_ctm;
1842 cairo_matrix_t dev_ctm_inverse = *stroke_ctm_inverse;
1844 status = surface->backend->fill_stroke (surface,
1845 fill_op, fill_source, fill_rule,
1846 fill_tolerance, fill_antialias,
1848 stroke_op, stroke_source,
1850 &dev_ctm, &dev_ctm_inverse,
1851 stroke_tolerance, stroke_antialias,
1854 if (status != CAIRO_INT_STATUS_UNSUPPORTED)
1858 status = _cairo_surface_fill (surface, fill_op, fill_source, path,
1859 fill_rule, fill_tolerance, fill_antialias,
1861 if (unlikely (status))
1864 status = _cairo_surface_stroke (surface, stroke_op, stroke_source, path,
1865 stroke_style, stroke_ctm, stroke_ctm_inverse,
1866 stroke_tolerance, stroke_antialias,
1868 if (unlikely (status))
1872 if (status != CAIRO_INT_STATUS_NOTHING_TO_DO) {
1873 surface->is_clear = FALSE;
1877 return _cairo_surface_set_error (surface, status);
1881 _cairo_surface_stroke (cairo_surface_t *surface,
1882 cairo_operator_t op,
1883 const cairo_pattern_t *source,
1884 const cairo_path_fixed_t *path,
1885 const cairo_stroke_style_t *stroke_style,
1886 const cairo_matrix_t *ctm,
1887 const cairo_matrix_t *ctm_inverse,
1889 cairo_antialias_t antialias,
1890 const cairo_clip_t *clip)
1892 cairo_int_status_t status;
1894 if (unlikely (surface->status))
1895 return surface->status;
1897 if (_cairo_clip_is_all_clipped (clip))
1898 return CAIRO_STATUS_SUCCESS;
1900 status = _pattern_has_error (source);
1901 if (unlikely (status))
1904 if (nothing_to_do (surface, op, source))
1905 return CAIRO_STATUS_SUCCESS;
1907 _cairo_surface_begin_modification (surface);
1909 status = surface->backend->stroke (surface, op, source,
1912 tolerance, antialias,
1914 if (status != CAIRO_INT_STATUS_NOTHING_TO_DO) {
1915 surface->is_clear = FALSE;
1919 return _cairo_surface_set_error (surface, status);
1923 _cairo_surface_fill (cairo_surface_t *surface,
1924 cairo_operator_t op,
1925 const cairo_pattern_t *source,
1926 const cairo_path_fixed_t *path,
1927 cairo_fill_rule_t fill_rule,
1929 cairo_antialias_t antialias,
1930 const cairo_clip_t *clip)
1932 cairo_int_status_t status;
1934 if (unlikely (surface->status))
1935 return surface->status;
1937 if (_cairo_clip_is_all_clipped (clip))
1938 return CAIRO_STATUS_SUCCESS;
1940 status = _pattern_has_error (source);
1941 if (unlikely (status))
1944 if (nothing_to_do (surface, op, source))
1945 return CAIRO_STATUS_SUCCESS;
1947 _cairo_surface_begin_modification (surface);
1949 status = surface->backend->fill (surface, op, source,
1951 tolerance, antialias,
1953 if (status != CAIRO_INT_STATUS_NOTHING_TO_DO) {
1954 surface->is_clear = FALSE;
1958 return _cairo_surface_set_error (surface, status);
1962 * cairo_surface_copy_page:
1963 * @surface: a #cairo_surface_t
1965 * Emits the current page for backends that support multiple pages,
1966 * but doesn't clear it, so that the contents of the current page will
1967 * be retained for the next page. Use cairo_surface_show_page() if you
1968 * want to get an empty page after the emission.
1970 * There is a convenience function for this that takes a #cairo_t,
1971 * namely cairo_copy_page().
1976 cairo_surface_copy_page (cairo_surface_t *surface)
1978 if (unlikely (surface->status))
1981 assert (surface->snapshot_of == NULL);
1983 if (unlikely (surface->finished)) {
1984 _cairo_surface_set_error (surface, CAIRO_STATUS_SURFACE_FINISHED);
1988 /* It's fine if some backends don't implement copy_page */
1989 if (surface->backend->copy_page == NULL)
1992 _cairo_surface_set_error (surface, surface->backend->copy_page (surface));
1994 slim_hidden_def (cairo_surface_copy_page);
1997 * cairo_surface_show_page:
1998 * @surface: a #cairo_Surface_t
2000 * Emits and clears the current page for backends that support multiple
2001 * pages. Use cairo_surface_copy_page() if you don't want to clear the page.
2003 * There is a convenience function for this that takes a #cairo_t,
2004 * namely cairo_show_page().
2009 cairo_surface_show_page (cairo_surface_t *surface)
2011 if (unlikely (surface->status))
2014 if (unlikely (surface->finished)) {
2015 _cairo_surface_set_error (surface, CAIRO_STATUS_SURFACE_FINISHED);
2019 _cairo_surface_begin_modification (surface);
2021 /* It's fine if some backends don't implement show_page */
2022 if (surface->backend->show_page == NULL)
2025 _cairo_surface_set_error (surface, surface->backend->show_page (surface));
2027 slim_hidden_def (cairo_surface_show_page);
2030 * _cairo_surface_get_extents:
2031 * @surface: the #cairo_surface_t to fetch extents for
2033 * This function returns a bounding box for the surface. The surface
2034 * bounds are defined as a region beyond which no rendering will
2035 * possibly be recorded, in other words, it is the maximum extent of
2036 * potentially usable coordinates.
2038 * For vector surfaces, (PDF, PS, SVG and recording-surfaces), the surface
2039 * might be conceived as unbounded, but we force the user to provide a
2040 * maximum size at the time of surface_create. So get_extents uses
2043 * Note: The coordinates returned are in "backend" space rather than
2044 * "surface" space. That is, they are relative to the true (0,0)
2045 * origin rather than the device_transform origin. This might seem a
2046 * bit inconsistent with other #cairo_surface_t interfaces, but all
2047 * current callers are within the surface layer where backend space is
2050 * This behavior would have to be changed is we ever exported a public
2051 * variant of this function.
2054 _cairo_surface_get_extents (cairo_surface_t *surface,
2055 cairo_rectangle_int_t *extents)
2057 cairo_bool_t bounded;
2060 if (surface->backend->get_extents != NULL)
2061 bounded = surface->backend->get_extents (surface, extents);
2064 _cairo_unbounded_rectangle_init (extents);
2070 * cairo_surface_has_show_text_glyphs:
2071 * @surface: a #cairo_surface_t
2073 * Returns whether the surface supports
2074 * sophisticated cairo_show_text_glyphs() operations. That is,
2075 * whether it actually uses the provided text and cluster data
2076 * to a cairo_show_text_glyphs() call.
2078 * Note: Even if this function returns %FALSE, a
2079 * cairo_show_text_glyphs() operation targeted at @surface will
2080 * still succeed. It just will
2081 * act like a cairo_show_glyphs() operation. Users can use this
2082 * function to avoid computing UTF-8 text and cluster mapping if the
2083 * target surface does not use it.
2085 * Return value: %TRUE if @surface supports
2086 * cairo_show_text_glyphs(), %FALSE otherwise
2091 cairo_surface_has_show_text_glyphs (cairo_surface_t *surface)
2093 if (unlikely (surface->status))
2096 if (unlikely (surface->finished)) {
2097 _cairo_surface_set_error (surface, CAIRO_STATUS_SURFACE_FINISHED);
2101 if (surface->backend->has_show_text_glyphs)
2102 return surface->backend->has_show_text_glyphs (surface);
2104 return surface->backend->show_text_glyphs != NULL;
2106 slim_hidden_def (cairo_surface_has_show_text_glyphs);
2108 /* Note: the backends may modify the contents of the glyph array as long as
2109 * they do not return %CAIRO_INT_STATUS_UNSUPPORTED. This makes it possible to
2110 * avoid copying the array again and again, and edit it in-place.
2111 * Backends are in fact free to use the array as a generic buffer as they
2114 * For show_glyphs backend method, and NOT for show_text_glyphs method,
2115 * when they do return UNSUPPORTED, they may adjust remaining_glyphs to notify
2116 * that they have successfully rendered some of the glyphs (from the beginning
2117 * of the array), but not all. If they don't touch remaining_glyphs, it
2118 * defaults to all glyphs.
2120 * See commits 5a9642c5746fd677aed35ce620ce90b1029b1a0c and
2121 * 1781e6018c17909311295a9cc74b70500c6b4d0a for the rationale.
2124 _cairo_surface_show_text_glyphs (cairo_surface_t *surface,
2125 cairo_operator_t op,
2126 const cairo_pattern_t *source,
2129 cairo_glyph_t *glyphs,
2131 const cairo_text_cluster_t *clusters,
2133 cairo_text_cluster_flags_t cluster_flags,
2134 cairo_scaled_font_t *scaled_font,
2135 const cairo_clip_t *clip)
2137 cairo_int_status_t status;
2138 cairo_scaled_font_t *dev_scaled_font = scaled_font;
2140 if (unlikely (surface->status))
2141 return surface->status;
2143 if (num_glyphs == 0 && utf8_len == 0)
2144 return CAIRO_STATUS_SUCCESS;
2146 if (_cairo_clip_is_all_clipped (clip))
2147 return CAIRO_STATUS_SUCCESS;
2149 status = _pattern_has_error (source);
2150 if (unlikely (status))
2153 if (nothing_to_do (surface, op, source))
2154 return CAIRO_STATUS_SUCCESS;
2156 _cairo_surface_begin_modification (surface);
2158 if (_cairo_surface_has_device_transform (surface) &&
2159 ! _cairo_matrix_is_integer_translation (&surface->device_transform, NULL, NULL))
2161 cairo_font_options_t font_options;
2162 cairo_matrix_t dev_ctm, font_matrix;
2164 cairo_scaled_font_get_font_matrix (scaled_font, &font_matrix);
2165 cairo_scaled_font_get_ctm (scaled_font, &dev_ctm);
2166 cairo_matrix_multiply (&dev_ctm, &dev_ctm, &surface->device_transform);
2167 cairo_scaled_font_get_font_options (scaled_font, &font_options);
2168 dev_scaled_font = cairo_scaled_font_create (cairo_scaled_font_get_font_face (scaled_font),
2173 status = cairo_scaled_font_status (dev_scaled_font);
2174 if (unlikely (status))
2175 return _cairo_surface_set_error (surface, status);
2177 status = CAIRO_INT_STATUS_UNSUPPORTED;
2179 /* The logic here is duplicated in _cairo_analysis_surface show_glyphs and
2180 * show_text_glyphs. Keep in synch. */
2182 /* A real show_text_glyphs call. Try show_text_glyphs backend
2184 if (surface->backend->show_text_glyphs != NULL) {
2185 status = surface->backend->show_text_glyphs (surface, op,
2189 clusters, num_clusters, cluster_flags,
2193 if (status == CAIRO_INT_STATUS_UNSUPPORTED &&
2194 surface->backend->show_glyphs)
2196 status = surface->backend->show_glyphs (surface, op,
2203 /* A mere show_glyphs call. Try show_glyphs backend method first */
2204 if (surface->backend->show_glyphs != NULL) {
2205 status = surface->backend->show_glyphs (surface, op,
2210 } else if (surface->backend->show_text_glyphs != NULL) {
2211 /* Intentionally only try show_text_glyphs method for show_glyphs
2212 * calls if backend does not have show_glyphs. If backend has
2213 * both methods implemented, we don't fallback from show_glyphs to
2214 * show_text_glyphs, and hence the backend can assume in its
2215 * show_text_glyphs call that clusters is not NULL (which also
2216 * implies that UTF-8 is not NULL, unless the text is
2219 status = surface->backend->show_text_glyphs (surface, op,
2223 clusters, num_clusters, cluster_flags,
2229 if (dev_scaled_font != scaled_font)
2230 cairo_scaled_font_destroy (dev_scaled_font);
2232 if (status != CAIRO_INT_STATUS_NOTHING_TO_DO) {
2233 surface->is_clear = FALSE;
2237 return _cairo_surface_set_error (surface, status);
2241 * _cairo_surface_set_resolution
2242 * @surface: the surface
2243 * @x_res: x resolution, in dpi
2244 * @y_res: y resolution, in dpi
2246 * Set the actual surface resolution of @surface to the given x and y DPI.
2247 * Mainly used for correctly computing the scale factor when fallback
2248 * rendering needs to take place in the paginated surface.
2251 _cairo_surface_set_resolution (cairo_surface_t *surface,
2255 if (surface->status)
2258 surface->x_resolution = x_res;
2259 surface->y_resolution = y_res;
2263 _cairo_surface_create_in_error (cairo_status_t status)
2265 assert (status < CAIRO_STATUS_LAST_STATUS);
2267 case CAIRO_STATUS_NO_MEMORY:
2268 return (cairo_surface_t *) &_cairo_surface_nil;
2269 case CAIRO_STATUS_SURFACE_TYPE_MISMATCH:
2270 return (cairo_surface_t *) &_cairo_surface_nil_surface_type_mismatch;
2271 case CAIRO_STATUS_INVALID_STATUS:
2272 return (cairo_surface_t *) &_cairo_surface_nil_invalid_status;
2273 case CAIRO_STATUS_INVALID_CONTENT:
2274 return (cairo_surface_t *) &_cairo_surface_nil_invalid_content;
2275 case CAIRO_STATUS_INVALID_FORMAT:
2276 return (cairo_surface_t *) &_cairo_surface_nil_invalid_format;
2277 case CAIRO_STATUS_INVALID_VISUAL:
2278 return (cairo_surface_t *) &_cairo_surface_nil_invalid_visual;
2279 case CAIRO_STATUS_READ_ERROR:
2280 return (cairo_surface_t *) &_cairo_surface_nil_read_error;
2281 case CAIRO_STATUS_WRITE_ERROR:
2282 return (cairo_surface_t *) &_cairo_surface_nil_write_error;
2283 case CAIRO_STATUS_FILE_NOT_FOUND:
2284 return (cairo_surface_t *) &_cairo_surface_nil_file_not_found;
2285 case CAIRO_STATUS_TEMP_FILE_ERROR:
2286 return (cairo_surface_t *) &_cairo_surface_nil_temp_file_error;
2287 case CAIRO_STATUS_INVALID_STRIDE:
2288 return (cairo_surface_t *) &_cairo_surface_nil_invalid_stride;
2289 case CAIRO_STATUS_INVALID_SIZE:
2290 return (cairo_surface_t *) &_cairo_surface_nil_invalid_size;
2291 case CAIRO_STATUS_DEVICE_TYPE_MISMATCH:
2292 return (cairo_surface_t *) &_cairo_surface_nil_device_type_mismatch;
2293 case CAIRO_STATUS_DEVICE_ERROR:
2294 return (cairo_surface_t *) &_cairo_surface_nil_device_error;
2295 case CAIRO_STATUS_SUCCESS:
2296 case CAIRO_STATUS_LAST_STATUS:
2299 case CAIRO_STATUS_INVALID_RESTORE:
2300 case CAIRO_STATUS_INVALID_POP_GROUP:
2301 case CAIRO_STATUS_NO_CURRENT_POINT:
2302 case CAIRO_STATUS_INVALID_MATRIX:
2303 case CAIRO_STATUS_NULL_POINTER:
2304 case CAIRO_STATUS_INVALID_STRING:
2305 case CAIRO_STATUS_INVALID_PATH_DATA:
2306 case CAIRO_STATUS_SURFACE_FINISHED:
2307 case CAIRO_STATUS_PATTERN_TYPE_MISMATCH:
2308 case CAIRO_STATUS_INVALID_DASH:
2309 case CAIRO_STATUS_INVALID_DSC_COMMENT:
2310 case CAIRO_STATUS_INVALID_INDEX:
2311 case CAIRO_STATUS_CLIP_NOT_REPRESENTABLE:
2312 case CAIRO_STATUS_FONT_TYPE_MISMATCH:
2313 case CAIRO_STATUS_USER_FONT_IMMUTABLE:
2314 case CAIRO_STATUS_USER_FONT_ERROR:
2315 case CAIRO_STATUS_NEGATIVE_COUNT:
2316 case CAIRO_STATUS_INVALID_CLUSTERS:
2317 case CAIRO_STATUS_INVALID_SLANT:
2318 case CAIRO_STATUS_INVALID_WEIGHT:
2319 case CAIRO_STATUS_USER_FONT_NOT_IMPLEMENTED:
2320 case CAIRO_STATUS_INVALID_MESH_CONSTRUCTION:
2321 case CAIRO_STATUS_DEVICE_FINISHED:
2323 _cairo_error_throw (CAIRO_STATUS_NO_MEMORY);
2324 return (cairo_surface_t *) &_cairo_surface_nil;
2329 _cairo_int_surface_create_in_error (cairo_int_status_t status)
2331 if (status < CAIRO_INT_STATUS_LAST_STATUS)
2332 return _cairo_surface_create_in_error (status);
2334 switch ((int)status) {
2335 case CAIRO_INT_STATUS_UNSUPPORTED:
2336 return (cairo_surface_t *) &_cairo_surface_nil_unsupported;
2337 case CAIRO_INT_STATUS_NOTHING_TO_DO:
2338 return (cairo_surface_t *) &_cairo_surface_nil_nothing_to_do;
2340 _cairo_error_throw (CAIRO_STATUS_NO_MEMORY);
2341 return (cairo_surface_t *) &_cairo_surface_nil;
2345 /* LocalWords: rasterized