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-tee-surface-private.h"
54 * SECTION:cairo-surface
55 * @Title: cairo_surface_t
56 * @Short_Description: Base class for surfaces
57 * @See_Also: #cairo_t, #cairo_pattern_t
59 * #cairo_surface_t is the abstract type representing all different drawing
60 * targets that cairo can render to. The actual drawings are
61 * performed using a cairo <firstterm>context</firstterm>.
63 * A cairo surface is created by using <firstterm>backend</firstterm>-specific
64 * constructors, typically of the form
65 * <function>cairo_<emphasis>backend</emphasis>_surface_create(<!-- -->)</function>.
67 * Most surface types allow accessing the surface without using Cairo
68 * functions. If you do this, keep in mind that it is mandatory that you call
69 * cairo_surface_flush() before reading from or writing to the surface and that
70 * you must use cairo_surface_mark_dirty() after modifying it.
72 * <title>Directly modifying an image surface</title>
75 * modify_image_surface (cairo_surface_t *surface)
77 * unsigned char *data;
78 * int width, height, stride;
80 * // flush to ensure all writing to the image was done
81 * cairo_surface_flush (surface);
84 * data = cairo_image_surface_get_data (surface);
85 * width = cairo_image_surface_get_width (surface);
86 * height = cairo_image_surface_get_height (surface);
87 * stride = cairo_image_surface_get_stride (surface);
88 * modify_image_data (data, width, height, stride);
90 * // mark the image dirty so Cairo clears its caches.
91 * cairo_surface_mark_dirty (surface);
95 * Note that for other surface types it might be necessary to acquire the
96 * surface's device first. See cairo_device_acquire() for a discussion of
100 #define DEFINE_NIL_SURFACE(status, name) \
101 const cairo_surface_t name = { \
102 NULL, /* backend */ \
104 CAIRO_SURFACE_TYPE_IMAGE, /* type */ \
105 CAIRO_CONTENT_COLOR, /* content */ \
106 CAIRO_REFERENCE_COUNT_INVALID, /* ref_count */ \
107 status, /* status */ \
111 FALSE, /* _finishing */ \
112 FALSE, /* finished */ \
113 TRUE, /* is_clear */ \
114 FALSE, /* has_font_options */ \
115 FALSE, /* owns_device */ \
116 { 0, 0, 0, NULL, }, /* user_data */ \
117 { 0, 0, 0, NULL, }, /* mime_data */ \
118 { 1.0, 0.0, 0.0, 1.0, 0.0, 0.0 }, /* device_transform */ \
119 { 1.0, 0.0, 0.0, 1.0, 0.0, 0.0 }, /* device_transform_inverse */ \
120 { NULL, NULL }, /* device_transform_observers */ \
121 0.0, /* x_resolution */ \
122 0.0, /* y_resolution */ \
123 0.0, /* x_fallback_resolution */ \
124 0.0, /* y_fallback_resolution */ \
125 NULL, /* snapshot_of */ \
126 NULL, /* snapshot_detach */ \
127 { NULL, NULL }, /* snapshots */ \
128 { NULL, NULL }, /* snapshot */ \
129 { CAIRO_ANTIALIAS_DEFAULT, /* antialias */ \
130 CAIRO_SUBPIXEL_ORDER_DEFAULT, /* subpixel_order */ \
131 CAIRO_LCD_FILTER_DEFAULT, /* lcd_filter */ \
132 CAIRO_HINT_STYLE_DEFAULT, /* hint_style */ \
133 CAIRO_HINT_METRICS_DEFAULT, /* hint_metrics */ \
134 CAIRO_ROUND_GLYPH_POS_DEFAULT /* round_glyph_positions */ \
135 } /* font_options */ \
138 /* XXX error object! */
140 static DEFINE_NIL_SURFACE(CAIRO_STATUS_NO_MEMORY, _cairo_surface_nil);
141 static DEFINE_NIL_SURFACE(CAIRO_STATUS_SURFACE_TYPE_MISMATCH, _cairo_surface_nil_surface_type_mismatch);
142 static DEFINE_NIL_SURFACE(CAIRO_STATUS_INVALID_STATUS, _cairo_surface_nil_invalid_status);
143 static DEFINE_NIL_SURFACE(CAIRO_STATUS_INVALID_CONTENT, _cairo_surface_nil_invalid_content);
144 static DEFINE_NIL_SURFACE(CAIRO_STATUS_INVALID_FORMAT, _cairo_surface_nil_invalid_format);
145 static DEFINE_NIL_SURFACE(CAIRO_STATUS_INVALID_VISUAL, _cairo_surface_nil_invalid_visual);
146 static DEFINE_NIL_SURFACE(CAIRO_STATUS_FILE_NOT_FOUND, _cairo_surface_nil_file_not_found);
147 static DEFINE_NIL_SURFACE(CAIRO_STATUS_TEMP_FILE_ERROR, _cairo_surface_nil_temp_file_error);
148 static DEFINE_NIL_SURFACE(CAIRO_STATUS_READ_ERROR, _cairo_surface_nil_read_error);
149 static DEFINE_NIL_SURFACE(CAIRO_STATUS_WRITE_ERROR, _cairo_surface_nil_write_error);
150 static DEFINE_NIL_SURFACE(CAIRO_STATUS_INVALID_STRIDE, _cairo_surface_nil_invalid_stride);
151 static DEFINE_NIL_SURFACE(CAIRO_STATUS_INVALID_SIZE, _cairo_surface_nil_invalid_size);
152 static DEFINE_NIL_SURFACE(CAIRO_STATUS_DEVICE_TYPE_MISMATCH, _cairo_surface_nil_device_type_mismatch);
153 static DEFINE_NIL_SURFACE(CAIRO_STATUS_DEVICE_ERROR, _cairo_surface_nil_device_error);
155 static DEFINE_NIL_SURFACE(CAIRO_INT_STATUS_UNSUPPORTED, _cairo_surface_nil_unsupported);
156 static DEFINE_NIL_SURFACE(CAIRO_INT_STATUS_NOTHING_TO_DO, _cairo_surface_nil_nothing_to_do);
158 static void _cairo_surface_finish_snapshots (cairo_surface_t *surface);
159 static void _cairo_surface_finish (cairo_surface_t *surface);
162 * _cairo_surface_set_error:
163 * @surface: a surface
164 * @status: a status value indicating an error
166 * Atomically sets surface->status to @status and calls _cairo_error;
167 * Does nothing if status is %CAIRO_STATUS_SUCCESS or any of the internal
170 * All assignments of an error status to surface->status should happen
171 * through _cairo_surface_set_error(). Note that due to the nature of
172 * the atomic operation, it is not safe to call this function on the
175 * The purpose of this function is to allow the user to set a
176 * breakpoint in _cairo_error() to generate a stack trace for when the
177 * user causes cairo to detect an error.
179 * Return value: the error status.
182 _cairo_surface_set_error (cairo_surface_t *surface,
183 cairo_int_status_t status)
185 /* NOTHING_TO_DO is magic. We use it to break out of the inner-most
186 * surface function, but anything higher just sees "success".
188 if (status == CAIRO_INT_STATUS_NOTHING_TO_DO)
189 status = CAIRO_INT_STATUS_SUCCESS;
191 if (status == CAIRO_INT_STATUS_SUCCESS ||
192 status >= (int)CAIRO_INT_STATUS_LAST_STATUS)
195 /* Don't overwrite an existing error. This preserves the first
196 * error, which is the most significant. */
197 _cairo_status_set_error (&surface->status, (cairo_status_t)status);
199 return _cairo_error (status);
203 * cairo_surface_get_type:
204 * @surface: a #cairo_surface_t
206 * This function returns the type of the backend used to create
207 * a surface. See #cairo_surface_type_t for available types.
209 * Return value: The type of @surface.
214 cairo_surface_get_type (cairo_surface_t *surface)
216 /* We don't use surface->backend->type here so that some of the
217 * special "wrapper" surfaces such as cairo_paginated_surface_t
218 * can override surface->type with the type of the "child"
220 return surface->type;
222 slim_hidden_def (cairo_surface_get_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;
241 slim_hidden_def(cairo_surface_get_content);
244 * cairo_surface_status:
245 * @surface: a #cairo_surface_t
247 * Checks whether an error has previously occurred for this
250 * Return value: %CAIRO_STATUS_SUCCESS, %CAIRO_STATUS_NULL_POINTER,
251 * %CAIRO_STATUS_NO_MEMORY, %CAIRO_STATUS_READ_ERROR,
252 * %CAIRO_STATUS_INVALID_CONTENT, %CAIRO_STATUS_INVALID_FORMAT, or
253 * %CAIRO_STATUS_INVALID_VISUAL.
258 cairo_surface_status (cairo_surface_t *surface)
260 return surface->status;
262 slim_hidden_def (cairo_surface_status);
265 _cairo_surface_allocate_unique_id (void)
267 static cairo_atomic_int_t unique_id;
270 if (++unique_id == 0)
274 cairo_atomic_int_t old, id;
277 old = _cairo_atomic_uint_get (&unique_id);
281 } while (! _cairo_atomic_uint_cmpxchg (&unique_id, old, id));
288 * cairo_surface_get_device:
289 * @surface: a #cairo_surface_t
291 * This function returns the device for a @surface.
292 * See #cairo_device_t.
294 * Return value: The device for @surface or %NULL if the surface does
295 * not have an associated device.
300 cairo_surface_get_device (cairo_surface_t *surface)
302 if (unlikely (surface->status))
303 return _cairo_device_create_in_error (surface->status);
305 return surface->device;
309 _cairo_surface_has_snapshots (cairo_surface_t *surface)
311 return ! cairo_list_is_empty (&surface->snapshots);
315 _cairo_surface_has_mime_data (cairo_surface_t *surface)
317 return surface->mime_data.num_elements != 0;
321 _cairo_surface_detach_mime_data (cairo_surface_t *surface)
323 if (! _cairo_surface_has_mime_data (surface))
326 _cairo_user_data_array_fini (&surface->mime_data);
327 _cairo_user_data_array_init (&surface->mime_data);
331 _cairo_surface_detach_snapshots (cairo_surface_t *surface)
333 while (_cairo_surface_has_snapshots (surface)) {
334 _cairo_surface_detach_snapshot (cairo_list_first_entry (&surface->snapshots,
341 _cairo_surface_detach_snapshot (cairo_surface_t *snapshot)
343 assert (snapshot->snapshot_of != NULL);
345 snapshot->snapshot_of = NULL;
346 cairo_list_del (&snapshot->snapshot);
348 if (snapshot->snapshot_detach != NULL)
349 snapshot->snapshot_detach (snapshot);
351 cairo_surface_destroy (snapshot);
355 _cairo_surface_attach_snapshot (cairo_surface_t *surface,
356 cairo_surface_t *snapshot,
357 cairo_surface_func_t detach_func)
359 assert (surface != snapshot);
360 assert (snapshot->snapshot_of != surface);
362 cairo_surface_reference (snapshot);
364 if (snapshot->snapshot_of != NULL)
365 _cairo_surface_detach_snapshot (snapshot);
367 snapshot->snapshot_of = surface;
368 snapshot->snapshot_detach = detach_func;
370 cairo_list_add (&snapshot->snapshot, &surface->snapshots);
372 assert (_cairo_surface_has_snapshot (surface, snapshot->backend) == snapshot);
376 _cairo_surface_has_snapshot (cairo_surface_t *surface,
377 const cairo_surface_backend_t *backend)
379 cairo_surface_t *snapshot;
381 cairo_list_foreach_entry (snapshot, cairo_surface_t,
382 &surface->snapshots, snapshot)
384 if (snapshot->backend == backend)
392 _cairo_surface_begin_modification (cairo_surface_t *surface)
394 assert (surface->status == CAIRO_STATUS_SUCCESS);
395 assert (! surface->finished);
397 _cairo_surface_detach_snapshots (surface);
398 if (surface->snapshot_of != NULL)
399 _cairo_surface_detach_snapshot (surface);
401 _cairo_surface_detach_mime_data (surface);
405 _cairo_surface_init (cairo_surface_t *surface,
406 const cairo_surface_backend_t *backend,
407 cairo_device_t *device,
408 cairo_content_t content)
410 CAIRO_MUTEX_INITIALIZE ();
412 surface->backend = backend;
413 surface->device = cairo_device_reference (device);
414 surface->content = content;
415 surface->type = backend->type;
417 CAIRO_REFERENCE_COUNT_INIT (&surface->ref_count, 1);
418 surface->status = CAIRO_STATUS_SUCCESS;
419 surface->unique_id = _cairo_surface_allocate_unique_id ();
420 surface->finished = FALSE;
421 surface->is_clear = FALSE;
423 surface->damage = NULL;
424 surface->owns_device = (device != NULL);
426 _cairo_user_data_array_init (&surface->user_data);
427 _cairo_user_data_array_init (&surface->mime_data);
429 cairo_matrix_init_identity (&surface->device_transform);
430 cairo_matrix_init_identity (&surface->device_transform_inverse);
431 cairo_list_init (&surface->device_transform_observers);
433 surface->x_resolution = CAIRO_SURFACE_RESOLUTION_DEFAULT;
434 surface->y_resolution = CAIRO_SURFACE_RESOLUTION_DEFAULT;
436 surface->x_fallback_resolution = CAIRO_SURFACE_FALLBACK_RESOLUTION_DEFAULT;
437 surface->y_fallback_resolution = CAIRO_SURFACE_FALLBACK_RESOLUTION_DEFAULT;
439 cairo_list_init (&surface->snapshots);
440 surface->snapshot_of = NULL;
442 surface->has_font_options = FALSE;
446 _cairo_surface_copy_similar_properties (cairo_surface_t *surface,
447 cairo_surface_t *other)
449 if (other->has_font_options || other->backend != surface->backend) {
450 cairo_font_options_t options;
452 cairo_surface_get_font_options (other, &options);
453 _cairo_surface_set_font_options (surface, &options);
456 cairo_surface_set_fallback_resolution (surface,
457 other->x_fallback_resolution,
458 other->y_fallback_resolution);
462 _cairo_surface_create_similar_scratch (cairo_surface_t *other,
463 cairo_content_t content,
467 cairo_surface_t *surface;
469 if (unlikely (other->status))
470 return _cairo_surface_create_in_error (other->status);
473 if (other->backend->create_similar)
474 surface = other->backend->create_similar (other, content, width, height);
476 surface = cairo_surface_create_similar_image (other,
477 _cairo_format_from_content (content),
480 if (unlikely (surface->status))
483 _cairo_surface_copy_similar_properties (surface, other);
489 * cairo_surface_create_similar:
490 * @other: an existing surface used to select the backend of the new surface
491 * @content: the content for the new surface
492 * @width: width of the new surface, (in device-space units)
493 * @height: height of the new surface (in device-space units)
495 * Create a new surface that is as compatible as possible with an
496 * existing surface. For example the new surface will have the same
497 * fallback resolution and font options as @other. Generally, the new
498 * surface will also use the same backend as @other, unless that is
499 * not possible for some reason. The type of the returned surface may
500 * be examined with cairo_surface_get_type().
502 * Initially the surface contents are all 0 (transparent if contents
503 * have transparency, black otherwise.)
505 * Use cairo_surface_create_similar_image() if you need an image surface
506 * which can be painted quickly to the target surface.
508 * Return value: a pointer to the newly allocated surface. The caller
509 * owns the surface and should call cairo_surface_destroy() when done
512 * This function always returns a valid pointer, but it will return a
513 * pointer to a "nil" surface if @other is already in an error state
514 * or any other error occurs.
519 cairo_surface_create_similar (cairo_surface_t *other,
520 cairo_content_t content,
524 cairo_surface_t *surface;
526 if (unlikely (other->status))
527 return _cairo_surface_create_in_error (other->status);
528 if (unlikely (other->finished))
529 return _cairo_surface_create_in_error (CAIRO_STATUS_SURFACE_FINISHED);
530 if (unlikely (width < 0 || height < 0))
531 return _cairo_surface_create_in_error (CAIRO_STATUS_INVALID_SIZE);
533 if (unlikely (! CAIRO_CONTENT_VALID (content)))
534 return _cairo_surface_create_in_error (CAIRO_STATUS_INVALID_CONTENT);
536 surface = _cairo_surface_create_similar_solid (other,
537 content, width, height,
538 CAIRO_COLOR_TRANSPARENT);
539 assert (surface->is_clear);
545 * cairo_surface_create_similar_image:
546 * @other: an existing surface used to select the preference of the new surface
547 * @format: the format for the new surface
548 * @width: width of the new surface, (in device-space units)
549 * @height: height of the new surface (in device-space units)
551 * Create a new image surface that is as compatible as possible for uploading
552 * to and the use in conjunction with an existing surface. However, this surface
553 * can still be used like any normal image surface.
555 * Initially the surface contents are all 0 (transparent if contents
556 * have transparency, black otherwise.)
558 * Use cairo_surface_create_similar() if you don't need an image surface.
560 * Return value: a pointer to the newly allocated image surface. The caller
561 * owns the surface and should call cairo_surface_destroy() when done
564 * This function always returns a valid pointer, but it will return a
565 * pointer to a "nil" surface if @other is already in an error state
566 * or any other error occurs.
571 cairo_surface_create_similar_image (cairo_surface_t *other,
572 cairo_format_t format,
576 cairo_surface_t *image;
578 if (unlikely (other->status))
579 return _cairo_surface_create_in_error (other->status);
580 if (unlikely (other->finished))
581 return _cairo_surface_create_in_error (CAIRO_STATUS_SURFACE_FINISHED);
583 if (unlikely (width < 0 || height < 0))
584 return _cairo_surface_create_in_error (CAIRO_STATUS_INVALID_SIZE);
585 if (unlikely (! CAIRO_FORMAT_VALID (format)))
586 return _cairo_surface_create_in_error (CAIRO_STATUS_INVALID_FORMAT);
589 if (other->backend->create_similar_image)
590 image = other->backend->create_similar_image (other,
591 format, width, height);
593 image = cairo_image_surface_create (format, width, height);
595 assert (image->is_clear);
599 slim_hidden_def (cairo_surface_create_similar_image);
602 * cairo_surface_map_to_image:
603 * @surface: an existing surface used to extract the image from
604 * @extents: limit the extraction to an rectangular region
606 * Returns an image surface that is the most efficient mechanism for
607 * modifying the backing store of the target surface. The region retrieved
608 * may be limited to the @extents or %NULL for the whole surface
610 * Note, the use of the original surface as a target or source whilst it is
611 * mapped is undefined. The result of mapping the surface multiple times is
612 * undefined. Calling cairo_surface_destroy() or cairo_surface_finish() on the
613 * resulting image surface results in undefined behavior.
615 * Return value: a pointer to the newly allocated image surface. The caller
616 * must use cairo_surface_unmap_image() to destroy this image surface.
618 * This function always returns a valid pointer, but it will return a
619 * pointer to a "nil" surface if @other is already in an error state
620 * or any other error occurs.
625 cairo_surface_map_to_image (cairo_surface_t *surface,
626 const cairo_rectangle_int_t *extents)
628 cairo_rectangle_int_t rect;
629 cairo_surface_t *image;
631 if (unlikely (surface->status))
632 return _cairo_surface_create_in_error (surface->status);
633 if (unlikely (surface->finished))
634 return _cairo_surface_create_in_error (CAIRO_STATUS_SURFACE_FINISHED);
636 if (extents == NULL) {
637 if (unlikely (! surface->backend->get_extents (surface, &rect)))
638 return _cairo_surface_create_in_error (CAIRO_STATUS_INVALID_SIZE);
642 cairo_rectangle_int_t surface_extents;
644 /* If this surface is bounded, we can't map parts
645 * that are outside of it. */
646 if (likely (surface->backend->get_extents (surface, &surface_extents))) {
647 if (unlikely (! _cairo_rectangle_contains_rectangle (&surface_extents, extents)))
648 return _cairo_surface_create_in_error (CAIRO_STATUS_INVALID_SIZE);
653 if (surface->backend->map_to_image)
654 image = surface->backend->map_to_image (surface, extents);
657 cairo_surface_pattern_t pattern;
658 cairo_status_t status;
660 image = cairo_surface_create_similar_image (surface,
661 _cairo_format_from_content (surface->content),
664 cairo_surface_set_device_offset (image, -extents->x, -extents->y);
666 _cairo_pattern_init_for_surface (&pattern, surface);
667 pattern.base.filter = CAIRO_FILTER_NEAREST;
669 status = _cairo_surface_paint (image,
670 CAIRO_OPERATOR_SOURCE,
674 _cairo_pattern_fini (&pattern.base);
676 if (unlikely (status)) {
677 cairo_surface_destroy (image);
678 image = _cairo_surface_create_in_error (status);
684 slim_hidden_def (cairo_surface_map_to_image);
687 * cairo_surface_unmap_image:
688 * @surface: the surface passed to cairo_surface_map_to_image().
689 * @image: the currently mapped image
691 * Unmaps the image surface as returned from #cairo_surface_map_to_image().
693 * The content of the image will be uploaded to the target surface.
694 * Afterwards, the image is destroyed.
696 * Using an image surface which wasn't returned by cairo_surface_map_to_image()
697 * results in undefined behavior.
702 cairo_surface_unmap_image (cairo_surface_t *surface,
703 cairo_surface_t *image)
705 cairo_int_status_t status;
707 if (unlikely (surface->status)) {
708 status = surface->status;
711 if (unlikely (surface->finished)) {
712 status = _cairo_error (CAIRO_STATUS_SURFACE_FINISHED);
716 if (unlikely (image->status)) {
717 status = image->status;
720 if (unlikely (image->finished)) {
721 status = _cairo_error (CAIRO_STATUS_SURFACE_FINISHED);
724 if (unlikely (! _cairo_surface_is_image (image))) {
725 status = _cairo_error (CAIRO_STATUS_SURFACE_TYPE_MISMATCH);
729 /* If the image is untouched just skip the update */
730 if (image->serial == 0) {
731 status = CAIRO_STATUS_SUCCESS;
735 status = CAIRO_INT_STATUS_UNSUPPORTED;
736 if (surface->backend->unmap_image)
737 status = surface->backend->unmap_image (surface, (cairo_image_surface_t *) image);
738 if (status == CAIRO_INT_STATUS_UNSUPPORTED) {
739 cairo_image_surface_t *img = (cairo_image_surface_t *) image;
740 cairo_surface_pattern_t pattern;
742 cairo_rectangle_int_t extents;
744 _cairo_pattern_init_for_surface (&pattern, image);
745 pattern.base.filter = CAIRO_FILTER_NEAREST;
747 /* We have to apply the translate from map_to_image's extents.x and .y */
748 cairo_matrix_init_translate (&pattern.base.matrix,
749 image->device_transform.x0,
750 image->device_transform.y0);
752 /* And we also have to clip the operation to the image's extents */
753 extents.x = image->device_transform_inverse.x0;
754 extents.y = image->device_transform_inverse.y0;
755 extents.width = img->width;
756 extents.height = img->height;
757 clip = _cairo_clip_intersect_rectangle (NULL, &extents);
759 status = _cairo_surface_paint (surface,
760 CAIRO_OPERATOR_SOURCE,
764 _cairo_pattern_fini (&pattern.base);
765 _cairo_clip_destroy (clip);
769 cairo_surface_finish (image);
770 cairo_surface_destroy (image);
772 _cairo_surface_set_error (surface, status);
774 slim_hidden_def (cairo_surface_unmap_image);
777 _cairo_surface_create_similar_solid (cairo_surface_t *other,
778 cairo_content_t content,
781 const cairo_color_t *color)
783 cairo_status_t status;
784 cairo_surface_t *surface;
785 cairo_solid_pattern_t pattern;
787 surface = _cairo_surface_create_similar_scratch (other, content,
789 if (unlikely (surface->status))
792 _cairo_pattern_init_solid (&pattern, color);
793 status = _cairo_surface_paint (surface,
794 color == CAIRO_COLOR_TRANSPARENT ?
795 CAIRO_OPERATOR_CLEAR : CAIRO_OPERATOR_SOURCE,
796 &pattern.base, NULL);
797 if (unlikely (status)) {
798 cairo_surface_destroy (surface);
799 surface = _cairo_surface_create_in_error (status);
806 * cairo_surface_reference:
807 * @surface: a #cairo_surface_t
809 * Increases the reference count on @surface by one. This prevents
810 * @surface from being destroyed until a matching call to
811 * cairo_surface_destroy() is made.
813 * The number of references to a #cairo_surface_t can be get using
814 * cairo_surface_get_reference_count().
816 * Return value: the referenced #cairo_surface_t.
821 cairo_surface_reference (cairo_surface_t *surface)
823 if (surface == NULL ||
824 CAIRO_REFERENCE_COUNT_IS_INVALID (&surface->ref_count))
827 assert (CAIRO_REFERENCE_COUNT_HAS_REFERENCE (&surface->ref_count));
829 _cairo_reference_count_inc (&surface->ref_count);
833 slim_hidden_def (cairo_surface_reference);
836 * cairo_surface_destroy:
837 * @surface: a #cairo_surface_t
839 * Decreases the reference count on @surface by one. If the result is
840 * zero, then @surface and all associated resources are freed. See
841 * cairo_surface_reference().
846 cairo_surface_destroy (cairo_surface_t *surface)
848 if (surface == NULL ||
849 CAIRO_REFERENCE_COUNT_IS_INVALID (&surface->ref_count))
852 assert (CAIRO_REFERENCE_COUNT_HAS_REFERENCE (&surface->ref_count));
854 if (! _cairo_reference_count_dec_and_test (&surface->ref_count))
857 assert (surface->snapshot_of == NULL);
859 if (! surface->finished) {
860 _cairo_surface_finish_snapshots (surface);
861 /* We may have been referenced by a snapshot prior to have
862 * detaching it with the copy-on-write.
864 if (CAIRO_REFERENCE_COUNT_GET_VALUE (&surface->ref_count))
867 _cairo_surface_finish (surface);
868 /* paranoid check that nobody took a reference whilst finishing */
869 assert (! CAIRO_REFERENCE_COUNT_HAS_REFERENCE (&surface->ref_count));
873 _cairo_damage_destroy (surface->damage);
875 _cairo_user_data_array_fini (&surface->user_data);
876 _cairo_user_data_array_fini (&surface->mime_data);
878 if (surface->owns_device)
879 cairo_device_destroy (surface->device);
881 assert (surface->snapshot_of == NULL);
882 assert (!_cairo_surface_has_snapshots (surface));
886 slim_hidden_def(cairo_surface_destroy);
889 * cairo_surface_get_reference_count:
890 * @surface: a #cairo_surface_t
892 * Returns the current reference count of @surface.
894 * Return value: the current reference count of @surface. If the
895 * object is a nil object, 0 will be returned.
900 cairo_surface_get_reference_count (cairo_surface_t *surface)
902 if (surface == NULL ||
903 CAIRO_REFERENCE_COUNT_IS_INVALID (&surface->ref_count))
906 return CAIRO_REFERENCE_COUNT_GET_VALUE (&surface->ref_count);
910 _cairo_surface_finish_snapshots (cairo_surface_t *surface)
912 cairo_surface_flush (surface);
914 /* update the snapshots *before* we declare the surface as finished */
915 surface->_finishing = TRUE;
917 _cairo_surface_detach_snapshots (surface);
918 if (surface->snapshot_of != NULL)
919 _cairo_surface_detach_snapshot (surface);
923 _cairo_surface_finish (cairo_surface_t *surface)
925 cairo_status_t status;
927 surface->finished = TRUE;
929 /* call finish even if in error mode */
930 if (surface->backend->finish) {
931 status = surface->backend->finish (surface);
932 if (unlikely (status))
933 _cairo_surface_set_error (surface, status);
936 assert (surface->snapshot_of == NULL);
937 assert (!_cairo_surface_has_snapshots (surface));
941 * cairo_surface_finish:
942 * @surface: the #cairo_surface_t to finish
944 * This function finishes the surface and drops all references to
945 * external resources. For example, for the Xlib backend it means
946 * that cairo will no longer access the drawable, which can be freed.
947 * After calling cairo_surface_finish() the only valid operations on a
948 * surface are getting and setting user, referencing and
949 * destroying, and flushing and finishing it.
950 * Further drawing to the surface will not affect the
951 * surface but will instead trigger a %CAIRO_STATUS_SURFACE_FINISHED
954 * When the last call to cairo_surface_destroy() decreases the
955 * reference count to zero, cairo will call cairo_surface_finish() if
956 * it hasn't been called already, before freeing the resources
957 * associated with the surface.
962 cairo_surface_finish (cairo_surface_t *surface)
967 if (CAIRO_REFERENCE_COUNT_IS_INVALID (&surface->ref_count))
970 if (surface->finished)
973 /* We have to be careful when decoupling potential reference cycles */
974 cairo_surface_reference (surface);
976 _cairo_surface_finish_snapshots (surface);
977 /* XXX need to block and wait for snapshot references */
978 _cairo_surface_finish (surface);
980 cairo_surface_destroy (surface);
982 slim_hidden_def (cairo_surface_finish);
985 * _cairo_surface_release_device_reference:
986 * @surface: a #cairo_surface_t
988 * This function makes @surface release the reference to its device. The
989 * function is intended to be used for avoiding cycling references for
990 * surfaces that are owned by their device, for example cache surfaces.
991 * Note that the @surface will still assume that the device is available.
992 * So it is the caller's responsibility to ensure the device stays around
993 * until the @surface is destroyed. Just calling cairo_surface_finish() is
997 _cairo_surface_release_device_reference (cairo_surface_t *surface)
999 assert (surface->owns_device);
1001 cairo_device_destroy (surface->device);
1002 surface->owns_device = FALSE;
1006 * cairo_surface_get_user_data:
1007 * @surface: a #cairo_surface_t
1008 * @key: the address of the #cairo_user_data_key_t the user data was
1011 * Return user data previously attached to @surface using the specified
1012 * key. If no user data has been attached with the given key this
1013 * function returns %NULL.
1015 * Return value: the user data previously attached or %NULL.
1020 cairo_surface_get_user_data (cairo_surface_t *surface,
1021 const cairo_user_data_key_t *key)
1023 return _cairo_user_data_array_get_data (&surface->user_data, key);
1027 * cairo_surface_set_user_data:
1028 * @surface: a #cairo_surface_t
1029 * @key: the address of a #cairo_user_data_key_t to attach the user data to
1030 * @user_data: the user data to attach to the surface
1031 * @destroy: a #cairo_destroy_func_t which will be called when the
1032 * surface is destroyed or when new user data is attached using the
1035 * Attach user data to @surface. To remove user data from a surface,
1036 * call this function with the key that was used to set it and %NULL
1039 * Return value: %CAIRO_STATUS_SUCCESS or %CAIRO_STATUS_NO_MEMORY if a
1040 * slot could not be allocated for the user data.
1045 cairo_surface_set_user_data (cairo_surface_t *surface,
1046 const cairo_user_data_key_t *key,
1048 cairo_destroy_func_t destroy)
1050 if (CAIRO_REFERENCE_COUNT_IS_INVALID (&surface->ref_count))
1051 return surface->status;
1053 return _cairo_user_data_array_set_data (&surface->user_data,
1054 key, user_data, destroy);
1058 * cairo_surface_get_mime_data:
1059 * @surface: a #cairo_surface_t
1060 * @mime_type: the mime type of the image data
1061 * @data: the image data to attached to the surface
1062 * @length: the length of the image data
1064 * Return mime data previously attached to @surface using the
1065 * specified mime type. If no data has been attached with the given
1066 * mime type, @data is set %NULL.
1071 cairo_surface_get_mime_data (cairo_surface_t *surface,
1072 const char *mime_type,
1073 const unsigned char **data,
1074 unsigned long *length)
1076 cairo_user_data_slot_t *slots;
1081 if (unlikely (surface->status))
1084 /* The number of mime-types attached to a surface is usually small,
1085 * typically zero. Therefore it is quicker to do a strcmp() against
1086 * each key than it is to intern the string (i.e. compute a hash,
1087 * search the hash table, and do a final strcmp).
1089 num_slots = surface->mime_data.num_elements;
1090 slots = _cairo_array_index (&surface->mime_data, 0);
1091 for (i = 0; i < num_slots; i++) {
1092 if (slots[i].key != NULL && strcmp ((char *) slots[i].key, mime_type) == 0) {
1093 cairo_mime_data_t *mime_data = slots[i].user_data;
1095 *data = mime_data->data;
1096 *length = mime_data->length;
1101 slim_hidden_def (cairo_surface_get_mime_data);
1104 _cairo_mime_data_destroy (void *ptr)
1106 cairo_mime_data_t *mime_data = ptr;
1108 if (! _cairo_reference_count_dec_and_test (&mime_data->ref_count))
1111 if (mime_data->destroy && mime_data->closure)
1112 mime_data->destroy (mime_data->closure);
1118 * CAIRO_MIME_TYPE_JP2:
1120 * The Joint Photographic Experts Group (JPEG) 2000 image coding standard (ISO/IEC 15444-1).
1126 * CAIRO_MIME_TYPE_JPEG:
1128 * The Joint Photographic Experts Group (JPEG) image coding standard (ISO/IEC 10918-1).
1134 * CAIRO_MIME_TYPE_PNG:
1136 * The Portable Network Graphics image file format (ISO/IEC 15948).
1142 * CAIRO_MIME_TYPE_URI:
1144 * URI for an image file (unofficial MIME type).
1150 * CAIRO_MIME_TYPE_UNIQUE_ID:
1152 * Unique identifier for a surface (cairo specific MIME type).
1158 * cairo_surface_set_mime_data:
1159 * @surface: a #cairo_surface_t
1160 * @mime_type: the MIME type of the image data
1161 * @data: the image data to attach to the surface
1162 * @length: the length of the image data
1163 * @destroy: a #cairo_destroy_func_t which will be called when the
1164 * surface is destroyed or when new image data is attached using the
1166 * @closure: the data to be passed to the @destroy notifier
1168 * Attach an image in the format @mime_type to @surface. To remove
1169 * the data from a surface, call this function with same mime type
1170 * and %NULL for @data.
1172 * The attached image (or filename) data can later be used by backends
1173 * which support it (currently: PDF, PS, SVG and Win32 Printing
1174 * surfaces) to emit this data instead of making a snapshot of the
1175 * @surface. This approach tends to be faster and requires less
1176 * memory and disk space.
1178 * The recognized MIME types are the following: %CAIRO_MIME_TYPE_JPEG,
1179 * %CAIRO_MIME_TYPE_PNG, %CAIRO_MIME_TYPE_JP2, %CAIRO_MIME_TYPE_URI.
1181 * See corresponding backend surface docs for details about which MIME
1182 * types it can handle. Caution: the associated MIME data will be
1183 * discarded if you draw on the surface afterwards. Use this function
1186 * Return value: %CAIRO_STATUS_SUCCESS or %CAIRO_STATUS_NO_MEMORY if a
1187 * slot could not be allocated for the user data.
1192 cairo_surface_set_mime_data (cairo_surface_t *surface,
1193 const char *mime_type,
1194 const unsigned char *data,
1195 unsigned long length,
1196 cairo_destroy_func_t destroy,
1199 cairo_status_t status;
1200 cairo_mime_data_t *mime_data;
1202 if (unlikely (surface->status))
1203 return surface->status;
1204 if (unlikely (surface->finished))
1205 return _cairo_surface_set_error (surface, _cairo_error (CAIRO_STATUS_SURFACE_FINISHED));
1207 status = _cairo_intern_string (&mime_type, -1);
1208 if (unlikely (status))
1209 return _cairo_surface_set_error (surface, status);
1212 mime_data = malloc (sizeof (cairo_mime_data_t));
1213 if (unlikely (mime_data == NULL))
1214 return _cairo_surface_set_error (surface, _cairo_error (CAIRO_STATUS_NO_MEMORY));
1216 CAIRO_REFERENCE_COUNT_INIT (&mime_data->ref_count, 1);
1218 mime_data->data = (unsigned char *) data;
1219 mime_data->length = length;
1220 mime_data->destroy = destroy;
1221 mime_data->closure = closure;
1225 status = _cairo_user_data_array_set_data (&surface->mime_data,
1226 (cairo_user_data_key_t *) mime_type,
1228 _cairo_mime_data_destroy);
1229 if (unlikely (status)) {
1232 return _cairo_surface_set_error (surface, status);
1235 return CAIRO_STATUS_SUCCESS;
1237 slim_hidden_def (cairo_surface_set_mime_data);
1240 * cairo_surface_supports_mime_type:
1241 * @surface: a #cairo_surface_t
1242 * @mime_type: the mime type
1244 * Return whether @surface supports @mime_type.
1246 * Return value: %TRUE if @surface supports
1247 * @mime_type, %FALSE otherwise
1252 cairo_surface_supports_mime_type (cairo_surface_t *surface,
1253 const char *mime_type)
1257 if (surface->backend->get_supported_mime_types) {
1258 types = surface->backend->get_supported_mime_types (surface);
1261 if (strcmp (*types, mime_type) == 0)
1270 slim_hidden_def (cairo_surface_supports_mime_type);
1273 _cairo_mime_data_reference (const void *key, void *elt, void *closure)
1275 cairo_mime_data_t *mime_data = elt;
1277 _cairo_reference_count_inc (&mime_data->ref_count);
1281 _cairo_surface_copy_mime_data (cairo_surface_t *dst,
1282 cairo_surface_t *src)
1284 cairo_status_t status;
1290 return _cairo_surface_set_error (dst, src->status);
1292 /* first copy the mime-data, discarding any already set on dst */
1293 status = _cairo_user_data_array_copy (&dst->mime_data, &src->mime_data);
1294 if (unlikely (status))
1295 return _cairo_surface_set_error (dst, status);
1297 /* now increment the reference counters for the copies */
1298 _cairo_user_data_array_foreach (&dst->mime_data,
1299 _cairo_mime_data_reference,
1302 return CAIRO_STATUS_SUCCESS;
1306 * _cairo_surface_set_font_options:
1307 * @surface: a #cairo_surface_t
1308 * @options: a #cairo_font_options_t object that contains the
1309 * options to use for this surface instead of backend's default
1312 * Sets the default font rendering options for the surface.
1313 * This is useful to correctly propagate default font options when
1314 * falling back to an image surface in a backend implementation.
1315 * This affects the options returned in cairo_surface_get_font_options().
1317 * If @options is %NULL the surface options are reset to those of
1318 * the backend default.
1321 _cairo_surface_set_font_options (cairo_surface_t *surface,
1322 cairo_font_options_t *options)
1324 if (surface->status)
1327 assert (surface->snapshot_of == NULL);
1329 if (surface->finished) {
1330 _cairo_surface_set_error (surface, _cairo_error (CAIRO_STATUS_SURFACE_FINISHED));
1335 surface->has_font_options = TRUE;
1336 _cairo_font_options_init_copy (&surface->font_options, options);
1338 surface->has_font_options = FALSE;
1343 * cairo_surface_get_font_options:
1344 * @surface: a #cairo_surface_t
1345 * @options: a #cairo_font_options_t object into which to store
1346 * the retrieved options. All existing values are overwritten
1348 * Retrieves the default font rendering options for the surface.
1349 * This allows display surfaces to report the correct subpixel order
1350 * for rendering on them, print surfaces to disable hinting of
1351 * metrics and so forth. The result can then be used with
1352 * cairo_scaled_font_create().
1357 cairo_surface_get_font_options (cairo_surface_t *surface,
1358 cairo_font_options_t *options)
1360 if (cairo_font_options_status (options))
1363 if (surface->status) {
1364 _cairo_font_options_init_default (options);
1368 if (! surface->has_font_options) {
1369 surface->has_font_options = TRUE;
1371 _cairo_font_options_init_default (&surface->font_options);
1373 if (!surface->finished && surface->backend->get_font_options) {
1374 surface->backend->get_font_options (surface, &surface->font_options);
1378 _cairo_font_options_init_copy (options, &surface->font_options);
1380 slim_hidden_def (cairo_surface_get_font_options);
1383 * cairo_surface_flush:
1384 * @surface: a #cairo_surface_t
1386 * Do any pending drawing for the surface and also restore any
1387 * temporary modifications cairo has made to the surface's
1388 * state. This function must be called before switching from
1389 * drawing on the surface with cairo to drawing on it directly
1390 * with native APIs. If the surface doesn't support direct access,
1391 * then this function does nothing.
1396 cairo_surface_flush (cairo_surface_t *surface)
1398 cairo_status_t status;
1400 if (surface->status)
1403 if (surface->finished)
1406 /* update the current snapshots *before* the user updates the surface */
1407 _cairo_surface_detach_snapshots (surface);
1408 _cairo_surface_detach_mime_data (surface);
1410 if (surface->backend->flush) {
1411 status = surface->backend->flush (surface);
1412 if (unlikely (status))
1413 _cairo_surface_set_error (surface, status);
1416 slim_hidden_def (cairo_surface_flush);
1419 * cairo_surface_mark_dirty:
1420 * @surface: a #cairo_surface_t
1422 * Tells cairo that drawing has been done to surface using means other
1423 * than cairo, and that cairo should reread any cached areas. Note
1424 * that you must call cairo_surface_flush() before doing such drawing.
1429 cairo_surface_mark_dirty (cairo_surface_t *surface)
1431 cairo_surface_mark_dirty_rectangle (surface, 0, 0, -1, -1);
1433 slim_hidden_def (cairo_surface_mark_dirty);
1436 * cairo_surface_mark_dirty_rectangle:
1437 * @surface: a #cairo_surface_t
1438 * @x: X coordinate of dirty rectangle
1439 * @y: Y coordinate of dirty rectangle
1440 * @width: width of dirty rectangle
1441 * @height: height of dirty rectangle
1443 * Like cairo_surface_mark_dirty(), but drawing has been done only to
1444 * the specified rectangle, so that cairo can retain cached contents
1445 * for other parts of the surface.
1447 * Any cached clip set on the surface will be reset by this function,
1448 * to make sure that future cairo calls have the clip set that they
1454 cairo_surface_mark_dirty_rectangle (cairo_surface_t *surface,
1460 cairo_status_t status;
1462 if (unlikely (surface->status))
1465 assert (surface->snapshot_of == NULL);
1467 if (unlikely (surface->finished)) {
1468 _cairo_surface_set_error (surface, _cairo_error (CAIRO_STATUS_SURFACE_FINISHED));
1472 /* The application *should* have called cairo_surface_flush() before
1473 * modifying the surface independently of cairo (and thus having to
1474 * call mark_dirty()). */
1475 assert (! _cairo_surface_has_snapshots (surface));
1476 assert (! _cairo_surface_has_mime_data (surface));
1478 surface->is_clear = FALSE;
1481 if (surface->damage) {
1486 box.p2.x = x + width;
1487 box.p2.y = y + height;
1489 surface->damage = _cairo_damage_add_box (surface->damage, &box);
1492 if (surface->backend->mark_dirty_rectangle != NULL) {
1493 /* XXX: FRAGILE: We're ignoring the scaling component of
1494 * device_transform here. I don't know what the right thing to
1495 * do would actually be if there were some scaling here, but
1496 * we avoid this since device_transfom scaling is not exported
1497 * publicly and mark_dirty is not used internally. */
1498 status = surface->backend->mark_dirty_rectangle (surface,
1499 x + surface->device_transform.x0,
1500 y + surface->device_transform.y0,
1503 if (unlikely (status))
1504 _cairo_surface_set_error (surface, status);
1507 slim_hidden_def (cairo_surface_mark_dirty_rectangle);
1510 * _cairo_surface_set_device_scale:
1511 * @surface: a #cairo_surface_t
1512 * @sx: a scale factor in the X direction
1513 * @sy: a scale factor in the Y direction
1515 * Private function for setting an extra scale factor to affect all
1516 * drawing to a surface. This is used, for example, when replaying a
1517 * recording surface to an image fallback intended for an eventual
1518 * vector-oriented backend. Since the recording surface will record
1519 * coordinates in one backend space, but the image fallback uses a
1520 * different backend space, (differing by the fallback resolution
1521 * scale factors), we need a scale factor correction.
1523 * Caution: Not all places we use device transform correctly handle
1524 * both a translate and a scale. An audit would be nice.
1527 _cairo_surface_set_device_scale (cairo_surface_t *surface,
1531 cairo_status_t status;
1533 if (unlikely (surface->status))
1536 assert (surface->snapshot_of == NULL);
1538 if (unlikely (surface->finished)) {
1539 _cairo_surface_set_error (surface, _cairo_error (CAIRO_STATUS_SURFACE_FINISHED));
1543 _cairo_surface_begin_modification (surface);
1545 surface->device_transform.xx = sx;
1546 surface->device_transform.yy = sy;
1547 surface->device_transform.xy = 0.0;
1548 surface->device_transform.yx = 0.0;
1550 surface->device_transform_inverse = surface->device_transform;
1551 status = cairo_matrix_invert (&surface->device_transform_inverse);
1552 /* should always be invertible unless given pathological input */
1553 assert (status == CAIRO_STATUS_SUCCESS);
1555 _cairo_observers_notify (&surface->device_transform_observers, surface);
1559 * cairo_surface_set_device_offset:
1560 * @surface: a #cairo_surface_t
1561 * @x_offset: the offset in the X direction, in device units
1562 * @y_offset: the offset in the Y direction, in device units
1564 * Sets an offset that is added to the device coordinates determined
1565 * by the CTM when drawing to @surface. One use case for this function
1566 * is when we want to create a #cairo_surface_t that redirects drawing
1567 * for a portion of an onscreen surface to an offscreen surface in a
1568 * way that is completely invisible to the user of the cairo
1569 * API. Setting a transformation via cairo_translate() isn't
1570 * sufficient to do this, since functions like
1571 * cairo_device_to_user() will expose the hidden offset.
1573 * Note that the offset affects drawing to the surface as well as
1574 * using the surface in a source pattern.
1579 cairo_surface_set_device_offset (cairo_surface_t *surface,
1583 cairo_status_t status;
1585 if (unlikely (surface->status))
1588 assert (surface->snapshot_of == NULL);
1590 if (unlikely (surface->finished)) {
1591 _cairo_surface_set_error (surface, _cairo_error (CAIRO_STATUS_SURFACE_FINISHED));
1595 _cairo_surface_begin_modification (surface);
1597 surface->device_transform.x0 = x_offset;
1598 surface->device_transform.y0 = y_offset;
1600 surface->device_transform_inverse = surface->device_transform;
1601 status = cairo_matrix_invert (&surface->device_transform_inverse);
1602 /* should always be invertible unless given pathological input */
1603 assert (status == CAIRO_STATUS_SUCCESS);
1605 _cairo_observers_notify (&surface->device_transform_observers, surface);
1607 slim_hidden_def (cairo_surface_set_device_offset);
1610 * cairo_surface_get_device_offset:
1611 * @surface: a #cairo_surface_t
1612 * @x_offset: the offset in the X direction, in device units
1613 * @y_offset: the offset in the Y direction, in device units
1615 * This function returns the previous device offset set by
1616 * cairo_surface_set_device_offset().
1621 cairo_surface_get_device_offset (cairo_surface_t *surface,
1626 *x_offset = surface->device_transform.x0;
1628 *y_offset = surface->device_transform.y0;
1630 slim_hidden_def (cairo_surface_get_device_offset);
1633 * cairo_surface_set_fallback_resolution:
1634 * @surface: a #cairo_surface_t
1635 * @x_pixels_per_inch: horizontal setting for pixels per inch
1636 * @y_pixels_per_inch: vertical setting for pixels per inch
1638 * Set the horizontal and vertical resolution for image fallbacks.
1640 * When certain operations aren't supported natively by a backend,
1641 * cairo will fallback by rendering operations to an image and then
1642 * overlaying that image onto the output. For backends that are
1643 * natively vector-oriented, this function can be used to set the
1644 * resolution used for these image fallbacks, (larger values will
1645 * result in more detailed images, but also larger file sizes).
1647 * Some examples of natively vector-oriented backends are the ps, pdf,
1650 * For backends that are natively raster-oriented, image fallbacks are
1651 * still possible, but they are always performed at the native
1652 * device resolution. So this function has no effect on those
1655 * Note: The fallback resolution only takes effect at the time of
1656 * completing a page (with cairo_show_page() or cairo_copy_page()) so
1657 * there is currently no way to have more than one fallback resolution
1658 * in effect on a single page.
1660 * The default fallback resoultion is 300 pixels per inch in both
1666 cairo_surface_set_fallback_resolution (cairo_surface_t *surface,
1667 double x_pixels_per_inch,
1668 double y_pixels_per_inch)
1670 if (unlikely (surface->status))
1673 assert (surface->snapshot_of == NULL);
1675 if (unlikely (surface->finished)) {
1676 _cairo_surface_set_error (surface, _cairo_error (CAIRO_STATUS_SURFACE_FINISHED));
1680 if (x_pixels_per_inch <= 0 || y_pixels_per_inch <= 0) {
1681 /* XXX Could delay raising the error until we fallback, but throwing
1682 * the error here means that we can catch the real culprit.
1684 _cairo_surface_set_error (surface, CAIRO_STATUS_INVALID_MATRIX);
1688 _cairo_surface_begin_modification (surface);
1690 surface->x_fallback_resolution = x_pixels_per_inch;
1691 surface->y_fallback_resolution = y_pixels_per_inch;
1693 slim_hidden_def (cairo_surface_set_fallback_resolution);
1696 * cairo_surface_get_fallback_resolution:
1697 * @surface: a #cairo_surface_t
1698 * @x_pixels_per_inch: horizontal pixels per inch
1699 * @y_pixels_per_inch: vertical pixels per inch
1701 * This function returns the previous fallback resolution set by
1702 * cairo_surface_set_fallback_resolution(), or default fallback
1703 * resolution if never set.
1708 cairo_surface_get_fallback_resolution (cairo_surface_t *surface,
1709 double *x_pixels_per_inch,
1710 double *y_pixels_per_inch)
1712 if (x_pixels_per_inch)
1713 *x_pixels_per_inch = surface->x_fallback_resolution;
1714 if (y_pixels_per_inch)
1715 *y_pixels_per_inch = surface->y_fallback_resolution;
1719 _cairo_surface_has_device_transform (cairo_surface_t *surface)
1721 return ! _cairo_matrix_is_identity (&surface->device_transform);
1725 * _cairo_surface_acquire_source_image:
1726 * @surface: a #cairo_surface_t
1727 * @image_out: location to store a pointer to an image surface that
1728 * has identical contents to @surface. This surface could be @surface
1729 * itself, a surface held internal to @surface, or it could be a new
1730 * surface with a copy of the relevant portion of @surface.
1731 * @image_extra: location to store image specific backend data
1733 * Gets an image surface to use when drawing as a fallback when drawing with
1734 * @surface as a source. _cairo_surface_release_source_image() must be called
1737 * Return value: %CAIRO_STATUS_SUCCESS if an image was stored in @image_out.
1738 * %CAIRO_INT_STATUS_UNSUPPORTED if an image cannot be retrieved for the specified
1739 * surface. Or %CAIRO_STATUS_NO_MEMORY.
1742 _cairo_surface_acquire_source_image (cairo_surface_t *surface,
1743 cairo_image_surface_t **image_out,
1746 cairo_status_t status;
1748 if (unlikely (surface->status))
1749 return surface->status;
1751 assert (!surface->finished);
1753 if (surface->backend->acquire_source_image == NULL)
1754 return CAIRO_INT_STATUS_UNSUPPORTED;
1756 status = surface->backend->acquire_source_image (surface,
1757 image_out, image_extra);
1758 if (unlikely (status))
1759 return _cairo_surface_set_error (surface, status);
1761 _cairo_debug_check_image_surface_is_defined (&(*image_out)->base);
1763 return CAIRO_STATUS_SUCCESS;
1767 _cairo_surface_default_acquire_source_image (void *surface,
1768 cairo_image_surface_t **image_out,
1771 *image_out = (cairo_image_surface_t *)
1772 cairo_surface_map_to_image (surface, NULL);
1773 *image_extra = NULL;
1774 return (*image_out)->base.status;
1778 * _cairo_surface_release_source_image:
1779 * @surface: a #cairo_surface_t
1780 * @image_extra: same as return from the matching _cairo_surface_acquire_source_image()
1782 * Releases any resources obtained with _cairo_surface_acquire_source_image()
1785 _cairo_surface_release_source_image (cairo_surface_t *surface,
1786 cairo_image_surface_t *image,
1789 assert (!surface->finished);
1791 if (surface->backend->release_source_image)
1792 surface->backend->release_source_image (surface, image, image_extra);
1796 _cairo_surface_default_release_source_image (void *surface,
1797 cairo_image_surface_t *image,
1800 cairo_surface_unmap_image (surface, &image->base);
1805 _cairo_surface_get_source (cairo_surface_t *surface,
1806 cairo_rectangle_int_t *extents)
1808 assert (surface->backend->source);
1809 return surface->backend->source (surface, extents);
1813 _cairo_surface_default_source (void *surface,
1814 cairo_rectangle_int_t *extents)
1817 _cairo_surface_get_extents(surface, extents);
1821 static cairo_status_t
1822 _pattern_has_error (const cairo_pattern_t *pattern)
1824 const cairo_surface_pattern_t *spattern;
1826 if (unlikely (pattern->status))
1827 return pattern->status;
1829 if (pattern->type != CAIRO_PATTERN_TYPE_SURFACE)
1830 return CAIRO_STATUS_SUCCESS;
1832 spattern = (const cairo_surface_pattern_t *) pattern;
1833 if (unlikely (spattern->surface->status))
1834 return spattern->surface->status;
1836 if (unlikely (spattern->surface->finished))
1837 return _cairo_error (CAIRO_STATUS_SURFACE_FINISHED);
1839 return CAIRO_STATUS_SUCCESS;
1843 nothing_to_do (cairo_surface_t *surface,
1844 cairo_operator_t op,
1845 const cairo_pattern_t *source)
1847 if (_cairo_pattern_is_clear (source)) {
1848 if (op == CAIRO_OPERATOR_OVER || op == CAIRO_OPERATOR_ADD)
1851 if (op == CAIRO_OPERATOR_SOURCE)
1852 op = CAIRO_OPERATOR_CLEAR;
1855 if (op == CAIRO_OPERATOR_CLEAR && surface->is_clear)
1858 if (op == CAIRO_OPERATOR_ATOP && (surface->content & CAIRO_CONTENT_COLOR) ==0)
1865 _cairo_surface_paint (cairo_surface_t *surface,
1866 cairo_operator_t op,
1867 const cairo_pattern_t *source,
1868 const cairo_clip_t *clip)
1870 cairo_int_status_t status;
1872 TRACE ((stderr, "%s\n", __FUNCTION__));
1873 if (unlikely (surface->status))
1874 return surface->status;
1876 if (_cairo_clip_is_all_clipped (clip))
1877 return CAIRO_STATUS_SUCCESS;
1879 status = _pattern_has_error (source);
1880 if (unlikely (status))
1883 if (nothing_to_do (surface, op, source))
1884 return CAIRO_STATUS_SUCCESS;
1886 _cairo_surface_begin_modification (surface);
1888 status = surface->backend->paint (surface, op, source, clip);
1889 if (status != CAIRO_INT_STATUS_NOTHING_TO_DO) {
1890 surface->is_clear = op == CAIRO_OPERATOR_CLEAR && clip == NULL;
1894 return _cairo_surface_set_error (surface, status);
1898 _cairo_surface_mask (cairo_surface_t *surface,
1899 cairo_operator_t op,
1900 const cairo_pattern_t *source,
1901 const cairo_pattern_t *mask,
1902 const cairo_clip_t *clip)
1904 cairo_int_status_t status;
1906 TRACE ((stderr, "%s\n", __FUNCTION__));
1907 if (unlikely (surface->status))
1908 return surface->status;
1910 if (_cairo_clip_is_all_clipped (clip))
1911 return CAIRO_STATUS_SUCCESS;
1913 /* If the mask is blank, this is just an expensive no-op */
1914 if (_cairo_pattern_is_clear (mask) &&
1915 _cairo_operator_bounded_by_mask (op))
1917 return CAIRO_STATUS_SUCCESS;
1920 status = _pattern_has_error (source);
1921 if (unlikely (status))
1924 status = _pattern_has_error (mask);
1925 if (unlikely (status))
1928 if (nothing_to_do (surface, op, source))
1929 return CAIRO_STATUS_SUCCESS;
1931 _cairo_surface_begin_modification (surface);
1933 status = surface->backend->mask (surface, op, source, mask, clip);
1934 if (status != CAIRO_INT_STATUS_NOTHING_TO_DO) {
1935 surface->is_clear = FALSE;
1939 return _cairo_surface_set_error (surface, status);
1943 _cairo_surface_fill_stroke (cairo_surface_t *surface,
1944 cairo_operator_t fill_op,
1945 const cairo_pattern_t *fill_source,
1946 cairo_fill_rule_t fill_rule,
1947 double fill_tolerance,
1948 cairo_antialias_t fill_antialias,
1949 cairo_path_fixed_t *path,
1950 cairo_operator_t stroke_op,
1951 const cairo_pattern_t *stroke_source,
1952 const cairo_stroke_style_t *stroke_style,
1953 const cairo_matrix_t *stroke_ctm,
1954 const cairo_matrix_t *stroke_ctm_inverse,
1955 double stroke_tolerance,
1956 cairo_antialias_t stroke_antialias,
1957 const cairo_clip_t *clip)
1959 cairo_int_status_t status;
1961 TRACE ((stderr, "%s\n", __FUNCTION__));
1962 if (unlikely (surface->status))
1963 return surface->status;
1965 if (_cairo_clip_is_all_clipped (clip))
1966 return CAIRO_STATUS_SUCCESS;
1968 if (surface->is_clear &&
1969 fill_op == CAIRO_OPERATOR_CLEAR &&
1970 stroke_op == CAIRO_OPERATOR_CLEAR)
1972 return CAIRO_STATUS_SUCCESS;
1975 status = _pattern_has_error (fill_source);
1976 if (unlikely (status))
1979 status = _pattern_has_error (stroke_source);
1980 if (unlikely (status))
1983 _cairo_surface_begin_modification (surface);
1985 if (surface->backend->fill_stroke) {
1986 cairo_matrix_t dev_ctm = *stroke_ctm;
1987 cairo_matrix_t dev_ctm_inverse = *stroke_ctm_inverse;
1989 status = surface->backend->fill_stroke (surface,
1990 fill_op, fill_source, fill_rule,
1991 fill_tolerance, fill_antialias,
1993 stroke_op, stroke_source,
1995 &dev_ctm, &dev_ctm_inverse,
1996 stroke_tolerance, stroke_antialias,
1999 if (status != CAIRO_INT_STATUS_UNSUPPORTED)
2003 status = _cairo_surface_fill (surface, fill_op, fill_source, path,
2004 fill_rule, fill_tolerance, fill_antialias,
2006 if (unlikely (status))
2009 status = _cairo_surface_stroke (surface, stroke_op, stroke_source, path,
2010 stroke_style, stroke_ctm, stroke_ctm_inverse,
2011 stroke_tolerance, stroke_antialias,
2013 if (unlikely (status))
2017 if (status != CAIRO_INT_STATUS_NOTHING_TO_DO) {
2018 surface->is_clear = FALSE;
2022 return _cairo_surface_set_error (surface, status);
2026 _cairo_surface_stroke (cairo_surface_t *surface,
2027 cairo_operator_t op,
2028 const cairo_pattern_t *source,
2029 const cairo_path_fixed_t *path,
2030 const cairo_stroke_style_t *stroke_style,
2031 const cairo_matrix_t *ctm,
2032 const cairo_matrix_t *ctm_inverse,
2034 cairo_antialias_t antialias,
2035 const cairo_clip_t *clip)
2037 cairo_int_status_t status;
2039 TRACE ((stderr, "%s\n", __FUNCTION__));
2040 if (unlikely (surface->status))
2041 return surface->status;
2043 if (_cairo_clip_is_all_clipped (clip))
2044 return CAIRO_STATUS_SUCCESS;
2046 status = _pattern_has_error (source);
2047 if (unlikely (status))
2050 if (nothing_to_do (surface, op, source))
2051 return CAIRO_STATUS_SUCCESS;
2053 _cairo_surface_begin_modification (surface);
2055 status = surface->backend->stroke (surface, op, source,
2058 tolerance, antialias,
2060 if (status != CAIRO_INT_STATUS_NOTHING_TO_DO) {
2061 surface->is_clear = FALSE;
2065 return _cairo_surface_set_error (surface, status);
2069 _cairo_surface_fill (cairo_surface_t *surface,
2070 cairo_operator_t op,
2071 const cairo_pattern_t *source,
2072 const cairo_path_fixed_t *path,
2073 cairo_fill_rule_t fill_rule,
2075 cairo_antialias_t antialias,
2076 const cairo_clip_t *clip)
2078 cairo_int_status_t status;
2080 TRACE ((stderr, "%s\n", __FUNCTION__));
2081 if (unlikely (surface->status))
2082 return surface->status;
2084 if (_cairo_clip_is_all_clipped (clip))
2085 return CAIRO_STATUS_SUCCESS;
2087 status = _pattern_has_error (source);
2088 if (unlikely (status))
2091 if (nothing_to_do (surface, op, source))
2092 return CAIRO_STATUS_SUCCESS;
2094 _cairo_surface_begin_modification (surface);
2096 status = surface->backend->fill (surface, op, source,
2098 tolerance, antialias,
2100 if (status != CAIRO_INT_STATUS_NOTHING_TO_DO) {
2101 surface->is_clear = FALSE;
2105 return _cairo_surface_set_error (surface, status);
2109 * cairo_surface_copy_page:
2110 * @surface: a #cairo_surface_t
2112 * Emits the current page for backends that support multiple pages,
2113 * but doesn't clear it, so that the contents of the current page will
2114 * be retained for the next page. Use cairo_surface_show_page() if you
2115 * want to get an empty page after the emission.
2117 * There is a convenience function for this that takes a #cairo_t,
2118 * namely cairo_copy_page().
2123 cairo_surface_copy_page (cairo_surface_t *surface)
2125 if (unlikely (surface->status))
2128 assert (surface->snapshot_of == NULL);
2130 if (unlikely (surface->finished)) {
2131 _cairo_surface_set_error (surface, CAIRO_STATUS_SURFACE_FINISHED);
2135 /* It's fine if some backends don't implement copy_page */
2136 if (surface->backend->copy_page == NULL)
2139 _cairo_surface_set_error (surface, surface->backend->copy_page (surface));
2141 slim_hidden_def (cairo_surface_copy_page);
2144 * cairo_surface_show_page:
2145 * @surface: a #cairo_Surface_t
2147 * Emits and clears the current page for backends that support multiple
2148 * pages. Use cairo_surface_copy_page() if you don't want to clear the page.
2150 * There is a convenience function for this that takes a #cairo_t,
2151 * namely cairo_show_page().
2156 cairo_surface_show_page (cairo_surface_t *surface)
2158 if (unlikely (surface->status))
2161 if (unlikely (surface->finished)) {
2162 _cairo_surface_set_error (surface, CAIRO_STATUS_SURFACE_FINISHED);
2166 _cairo_surface_begin_modification (surface);
2168 /* It's fine if some backends don't implement show_page */
2169 if (surface->backend->show_page == NULL)
2172 _cairo_surface_set_error (surface, surface->backend->show_page (surface));
2174 slim_hidden_def (cairo_surface_show_page);
2177 * _cairo_surface_get_extents:
2178 * @surface: the #cairo_surface_t to fetch extents for
2180 * This function returns a bounding box for the surface. The surface
2181 * bounds are defined as a region beyond which no rendering will
2182 * possibly be recorded, in other words, it is the maximum extent of
2183 * potentially usable coordinates.
2185 * For vector surfaces, (PDF, PS, SVG and recording-surfaces), the surface
2186 * might be conceived as unbounded, but we force the user to provide a
2187 * maximum size at the time of surface_create. So get_extents uses
2190 * Note: The coordinates returned are in "backend" space rather than
2191 * "surface" space. That is, they are relative to the true (0,0)
2192 * origin rather than the device_transform origin. This might seem a
2193 * bit inconsistent with other #cairo_surface_t interfaces, but all
2194 * current callers are within the surface layer where backend space is
2197 * This behavior would have to be changed is we ever exported a public
2198 * variant of this function.
2201 _cairo_surface_get_extents (cairo_surface_t *surface,
2202 cairo_rectangle_int_t *extents)
2204 cairo_bool_t bounded;
2207 if (surface->backend->get_extents != NULL)
2208 bounded = surface->backend->get_extents (surface, extents);
2211 _cairo_unbounded_rectangle_init (extents);
2217 * cairo_surface_has_show_text_glyphs:
2218 * @surface: a #cairo_surface_t
2220 * Returns whether the surface supports
2221 * sophisticated cairo_show_text_glyphs() operations. That is,
2222 * whether it actually uses the provided text and cluster data
2223 * to a cairo_show_text_glyphs() call.
2225 * Note: Even if this function returns %FALSE, a
2226 * cairo_show_text_glyphs() operation targeted at @surface will
2227 * still succeed. It just will
2228 * act like a cairo_show_glyphs() operation. Users can use this
2229 * function to avoid computing UTF-8 text and cluster mapping if the
2230 * target surface does not use it.
2232 * Return value: %TRUE if @surface supports
2233 * cairo_show_text_glyphs(), %FALSE otherwise
2238 cairo_surface_has_show_text_glyphs (cairo_surface_t *surface)
2240 if (unlikely (surface->status))
2243 if (unlikely (surface->finished)) {
2244 _cairo_surface_set_error (surface, CAIRO_STATUS_SURFACE_FINISHED);
2248 if (surface->backend->has_show_text_glyphs)
2249 return surface->backend->has_show_text_glyphs (surface);
2251 return surface->backend->show_text_glyphs != NULL;
2253 slim_hidden_def (cairo_surface_has_show_text_glyphs);
2255 /* Note: the backends may modify the contents of the glyph array as long as
2256 * they do not return %CAIRO_INT_STATUS_UNSUPPORTED. This makes it possible to
2257 * avoid copying the array again and again, and edit it in-place.
2258 * Backends are in fact free to use the array as a generic buffer as they
2261 * For show_glyphs backend method, and NOT for show_text_glyphs method,
2262 * when they do return UNSUPPORTED, they may adjust remaining_glyphs to notify
2263 * that they have successfully rendered some of the glyphs (from the beginning
2264 * of the array), but not all. If they don't touch remaining_glyphs, it
2265 * defaults to all glyphs.
2267 * See commits 5a9642c5746fd677aed35ce620ce90b1029b1a0c and
2268 * 1781e6018c17909311295a9cc74b70500c6b4d0a for the rationale.
2271 _cairo_surface_show_text_glyphs (cairo_surface_t *surface,
2272 cairo_operator_t op,
2273 const cairo_pattern_t *source,
2276 cairo_glyph_t *glyphs,
2278 const cairo_text_cluster_t *clusters,
2280 cairo_text_cluster_flags_t cluster_flags,
2281 cairo_scaled_font_t *scaled_font,
2282 const cairo_clip_t *clip)
2284 cairo_int_status_t status;
2285 cairo_scaled_font_t *dev_scaled_font = scaled_font;
2287 TRACE ((stderr, "%s\n", __FUNCTION__));
2288 if (unlikely (surface->status))
2289 return surface->status;
2291 if (num_glyphs == 0 && utf8_len == 0)
2292 return CAIRO_STATUS_SUCCESS;
2294 if (_cairo_clip_is_all_clipped (clip))
2295 return CAIRO_STATUS_SUCCESS;
2297 status = _pattern_has_error (source);
2298 if (unlikely (status))
2301 if (nothing_to_do (surface, op, source))
2302 return CAIRO_STATUS_SUCCESS;
2304 _cairo_surface_begin_modification (surface);
2306 if (_cairo_surface_has_device_transform (surface) &&
2307 ! _cairo_matrix_is_integer_translation (&surface->device_transform, NULL, NULL))
2309 cairo_font_options_t font_options;
2310 cairo_matrix_t dev_ctm, font_matrix;
2312 cairo_scaled_font_get_font_matrix (scaled_font, &font_matrix);
2313 cairo_scaled_font_get_ctm (scaled_font, &dev_ctm);
2314 cairo_matrix_multiply (&dev_ctm, &dev_ctm, &surface->device_transform);
2315 cairo_scaled_font_get_font_options (scaled_font, &font_options);
2316 dev_scaled_font = cairo_scaled_font_create (cairo_scaled_font_get_font_face (scaled_font),
2321 status = cairo_scaled_font_status (dev_scaled_font);
2322 if (unlikely (status))
2323 return _cairo_surface_set_error (surface, status);
2325 status = CAIRO_INT_STATUS_UNSUPPORTED;
2327 /* The logic here is duplicated in _cairo_analysis_surface show_glyphs and
2328 * show_text_glyphs. Keep in synch. */
2330 /* A real show_text_glyphs call. Try show_text_glyphs backend
2332 if (surface->backend->show_text_glyphs != NULL) {
2333 status = surface->backend->show_text_glyphs (surface, op,
2337 clusters, num_clusters, cluster_flags,
2341 if (status == CAIRO_INT_STATUS_UNSUPPORTED &&
2342 surface->backend->show_glyphs)
2344 status = surface->backend->show_glyphs (surface, op,
2351 /* A mere show_glyphs call. Try show_glyphs backend method first */
2352 if (surface->backend->show_glyphs != NULL) {
2353 status = surface->backend->show_glyphs (surface, op,
2358 } else if (surface->backend->show_text_glyphs != NULL) {
2359 /* Intentionally only try show_text_glyphs method for show_glyphs
2360 * calls if backend does not have show_glyphs. If backend has
2361 * both methods implemented, we don't fallback from show_glyphs to
2362 * show_text_glyphs, and hence the backend can assume in its
2363 * show_text_glyphs call that clusters is not NULL (which also
2364 * implies that UTF-8 is not NULL, unless the text is
2367 status = surface->backend->show_text_glyphs (surface, op,
2371 clusters, num_clusters, cluster_flags,
2377 if (dev_scaled_font != scaled_font)
2378 cairo_scaled_font_destroy (dev_scaled_font);
2380 if (status != CAIRO_INT_STATUS_NOTHING_TO_DO) {
2381 surface->is_clear = FALSE;
2385 return _cairo_surface_set_error (surface, status);
2389 * _cairo_surface_set_resolution:
2390 * @surface: the surface
2391 * @x_res: x resolution, in dpi
2392 * @y_res: y resolution, in dpi
2394 * Set the actual surface resolution of @surface to the given x and y DPI.
2395 * Mainly used for correctly computing the scale factor when fallback
2396 * rendering needs to take place in the paginated surface.
2399 _cairo_surface_set_resolution (cairo_surface_t *surface,
2403 if (surface->status)
2406 surface->x_resolution = x_res;
2407 surface->y_resolution = y_res;
2411 _cairo_surface_create_in_error (cairo_status_t status)
2413 assert (status < CAIRO_STATUS_LAST_STATUS);
2415 case CAIRO_STATUS_NO_MEMORY:
2416 return (cairo_surface_t *) &_cairo_surface_nil;
2417 case CAIRO_STATUS_SURFACE_TYPE_MISMATCH:
2418 return (cairo_surface_t *) &_cairo_surface_nil_surface_type_mismatch;
2419 case CAIRO_STATUS_INVALID_STATUS:
2420 return (cairo_surface_t *) &_cairo_surface_nil_invalid_status;
2421 case CAIRO_STATUS_INVALID_CONTENT:
2422 return (cairo_surface_t *) &_cairo_surface_nil_invalid_content;
2423 case CAIRO_STATUS_INVALID_FORMAT:
2424 return (cairo_surface_t *) &_cairo_surface_nil_invalid_format;
2425 case CAIRO_STATUS_INVALID_VISUAL:
2426 return (cairo_surface_t *) &_cairo_surface_nil_invalid_visual;
2427 case CAIRO_STATUS_READ_ERROR:
2428 return (cairo_surface_t *) &_cairo_surface_nil_read_error;
2429 case CAIRO_STATUS_WRITE_ERROR:
2430 return (cairo_surface_t *) &_cairo_surface_nil_write_error;
2431 case CAIRO_STATUS_FILE_NOT_FOUND:
2432 return (cairo_surface_t *) &_cairo_surface_nil_file_not_found;
2433 case CAIRO_STATUS_TEMP_FILE_ERROR:
2434 return (cairo_surface_t *) &_cairo_surface_nil_temp_file_error;
2435 case CAIRO_STATUS_INVALID_STRIDE:
2436 return (cairo_surface_t *) &_cairo_surface_nil_invalid_stride;
2437 case CAIRO_STATUS_INVALID_SIZE:
2438 return (cairo_surface_t *) &_cairo_surface_nil_invalid_size;
2439 case CAIRO_STATUS_DEVICE_TYPE_MISMATCH:
2440 return (cairo_surface_t *) &_cairo_surface_nil_device_type_mismatch;
2441 case CAIRO_STATUS_DEVICE_ERROR:
2442 return (cairo_surface_t *) &_cairo_surface_nil_device_error;
2443 case CAIRO_STATUS_SUCCESS:
2444 case CAIRO_STATUS_LAST_STATUS:
2447 case CAIRO_STATUS_INVALID_RESTORE:
2448 case CAIRO_STATUS_INVALID_POP_GROUP:
2449 case CAIRO_STATUS_NO_CURRENT_POINT:
2450 case CAIRO_STATUS_INVALID_MATRIX:
2451 case CAIRO_STATUS_NULL_POINTER:
2452 case CAIRO_STATUS_INVALID_STRING:
2453 case CAIRO_STATUS_INVALID_PATH_DATA:
2454 case CAIRO_STATUS_SURFACE_FINISHED:
2455 case CAIRO_STATUS_PATTERN_TYPE_MISMATCH:
2456 case CAIRO_STATUS_INVALID_DASH:
2457 case CAIRO_STATUS_INVALID_DSC_COMMENT:
2458 case CAIRO_STATUS_INVALID_INDEX:
2459 case CAIRO_STATUS_CLIP_NOT_REPRESENTABLE:
2460 case CAIRO_STATUS_FONT_TYPE_MISMATCH:
2461 case CAIRO_STATUS_USER_FONT_IMMUTABLE:
2462 case CAIRO_STATUS_USER_FONT_ERROR:
2463 case CAIRO_STATUS_NEGATIVE_COUNT:
2464 case CAIRO_STATUS_INVALID_CLUSTERS:
2465 case CAIRO_STATUS_INVALID_SLANT:
2466 case CAIRO_STATUS_INVALID_WEIGHT:
2467 case CAIRO_STATUS_USER_FONT_NOT_IMPLEMENTED:
2468 case CAIRO_STATUS_INVALID_MESH_CONSTRUCTION:
2469 case CAIRO_STATUS_DEVICE_FINISHED:
2471 _cairo_error_throw (CAIRO_STATUS_NO_MEMORY);
2472 return (cairo_surface_t *) &_cairo_surface_nil;
2477 _cairo_int_surface_create_in_error (cairo_int_status_t status)
2479 if (status < CAIRO_INT_STATUS_LAST_STATUS)
2480 return _cairo_surface_create_in_error (status);
2482 switch ((int)status) {
2483 case CAIRO_INT_STATUS_UNSUPPORTED:
2484 return (cairo_surface_t *) &_cairo_surface_nil_unsupported;
2485 case CAIRO_INT_STATUS_NOTHING_TO_DO:
2486 return (cairo_surface_t *) &_cairo_surface_nil_nothing_to_do;
2488 _cairo_error_throw (CAIRO_STATUS_NO_MEMORY);
2489 return (cairo_surface_t *) &_cairo_surface_nil;
2493 /* LocalWords: rasterized