src/cairo-surface.c

   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
   3  *
   4  * Copyright © 2002 University of Southern California
   5  * Copyright © 2005 Red Hat, Inc.
   6  *
   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.
  14  *
  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
  20  *
  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/
  25  *
  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.
  29  *
  30  * The Original Code is the cairo graphics library.
  31  *
  32  * The Initial Developer of the Original Code is University of Southern
  33  * California.
  34  *
  35  * Contributor(s):
  36  *      Carl D. Worth <cworth@cworth.org>
  37  */
  38
  39 #include "cairoint.h"
  40
  41 #include "cairo-array-private.h"
  42 #include "cairo-clip-inline.h"
  43 #include "cairo-clip-private.h"
  44 #include "cairo-damage-private.h"
  45 #include "cairo-device-private.h"
  46 #include "cairo-error-private.h"
  47 #include "cairo-list-inline.h"
  48 #include "cairo-image-surface-inline.h"
  49 #include "cairo-recording-surface-private.h"
  50 #include "cairo-region-private.h"
  51 #include "cairo-surface-inline.h"
  52 #include "cairo-tee-surface-private.h"
  53 #include "cairo-surface-subsurface-private.h"
  54
  55 /**
  56  * SECTION:cairo-surface
  57  * @Title: cairo_surface_t
  58  * @Short_Description: Base class for surfaces
  59  * @See_Also: #cairo_t, #cairo_pattern_t
  60  *
  61  * #cairo_surface_t is the abstract type representing all different drawing
  62  * targets that cairo can render to.  The actual drawings are
  63  * performed using a cairo <firstterm>context</firstterm>.
  64  *
  65  * A cairo surface is created by using <firstterm>backend</firstterm>-specific
  66  * constructors, typically of the form
  67  * <function>cairo_<emphasis>backend</emphasis>_surface_create(<!-- -->)</function>.
  68  *
  69  * Most surface types allow accessing the surface without using Cairo
  70  * functions. If you do this, keep in mind that it is mandatory that you call
  71  * cairo_surface_flush() before reading from or writing to the surface and that
  72  * you must use cairo_surface_mark_dirty() after modifying it.
  73  * <example>
  74  * <title>Directly modifying an image surface</title>
  75  * <programlisting>
  76  * void
  77  * modify_image_surface (cairo_surface_t *surface)
  78  * {
  79  *   unsigned char *data;
  80  *   int width, height, stride;
  81  *
  82  *   // flush to ensure all writing to the image was done
  83  *   cairo_surface_flush (surface);
  84  *
  85  *   // modify the image
  86  *   data = cairo_image_surface_get_data (surface);
  87  *   width = cairo_image_surface_get_width (surface);
  88  *   height = cairo_image_surface_get_height (surface);
  89  *   stride = cairo_image_surface_get_stride (surface);
  90  *   modify_image_data (data, width, height, stride);
  91  *
  92  *   // mark the image dirty so Cairo clears its caches.
  93  *   cairo_surface_mark_dirty (surface);
  94  * }
  95  * </programlisting>
  96  * </example>
  97  * Note that for other surface types it might be necessary to acquire the
  98  * surface's device first. See cairo_device_acquire() for a discussion of
  99  * devices.
 100  **/
 101
 102 #define DEFINE_NIL_SURFACE(status, name)                        \
 103 const cairo_surface_t name = {                                  \
 104     NULL,                               /* backend */           \
 105     NULL,                               /* device */            \
 106     CAIRO_SURFACE_TYPE_IMAGE,           /* type */              \
 107     CAIRO_CONTENT_COLOR,                /* content */           \
 108     CAIRO_REFERENCE_COUNT_INVALID,      /* ref_count */         \
 109     status,                             /* status */            \
 110     0,                                  /* unique id */         \
 111     0,                                  /* serial */            \
 112     NULL,                               /* damage */            \
 113     FALSE,                              /* _finishing */        \
 114     FALSE,                              /* finished */          \
 115     TRUE,                               /* is_clear */          \
 116     FALSE,                              /* has_font_options */  \
 117     FALSE,                              /* owns_device */       \
 118     { 0, 0, 0, NULL, },                 /* user_data */         \
 119     { 0, 0, 0, NULL, },                 /* mime_data */         \
 120     { 1.0, 0.0, 0.0, 1.0, 0.0, 0.0 },   /* device_transform */  \
 121     { 1.0, 0.0, 0.0, 1.0, 0.0, 0.0 },   /* device_transform_inverse */  \
 122     { NULL, NULL },                     /* device_transform_observers */ \
 123     0.0,                                /* x_resolution */      \
 124     0.0,                                /* y_resolution */      \
 125     0.0,                                /* x_fallback_resolution */     \
 126     0.0,                                /* y_fallback_resolution */     \
 127     NULL,                               /* snapshot_of */       \
 128     NULL,                               /* snapshot_detach */   \
 129     NULL,                               /* snapshot_subsurface */       \
 130     { NULL, NULL },                     /* snapshots */         \
 131     { NULL, NULL },                     /* snapshot */          \
 132     { CAIRO_ANTIALIAS_DEFAULT,          /* antialias */         \
 133       CAIRO_SUBPIXEL_ORDER_DEFAULT,     /* subpixel_order */    \
 134       CAIRO_LCD_FILTER_DEFAULT,         /* lcd_filter */        \
 135       CAIRO_HINT_STYLE_DEFAULT,         /* hint_style */        \
 136       CAIRO_HINT_METRICS_DEFAULT,       /* hint_metrics */      \
 137       CAIRO_ROUND_GLYPH_POS_DEFAULT     /* round_glyph_positions */     \
 138     }                                   /* font_options */      \
 139 }
 140
 141 /* XXX error object! */
 142
 143 static DEFINE_NIL_SURFACE(CAIRO_STATUS_NO_MEMORY, _cairo_surface_nil);
 144 static DEFINE_NIL_SURFACE(CAIRO_STATUS_SURFACE_TYPE_MISMATCH, _cairo_surface_nil_surface_type_mismatch);
 145 static DEFINE_NIL_SURFACE(CAIRO_STATUS_INVALID_STATUS, _cairo_surface_nil_invalid_status);
 146 static DEFINE_NIL_SURFACE(CAIRO_STATUS_INVALID_CONTENT, _cairo_surface_nil_invalid_content);
 147 static DEFINE_NIL_SURFACE(CAIRO_STATUS_INVALID_FORMAT, _cairo_surface_nil_invalid_format);
 148 static DEFINE_NIL_SURFACE(CAIRO_STATUS_INVALID_VISUAL, _cairo_surface_nil_invalid_visual);
 149 static DEFINE_NIL_SURFACE(CAIRO_STATUS_FILE_NOT_FOUND, _cairo_surface_nil_file_not_found);
 150 static DEFINE_NIL_SURFACE(CAIRO_STATUS_TEMP_FILE_ERROR, _cairo_surface_nil_temp_file_error);
 151 static DEFINE_NIL_SURFACE(CAIRO_STATUS_READ_ERROR, _cairo_surface_nil_read_error);
 152 static DEFINE_NIL_SURFACE(CAIRO_STATUS_WRITE_ERROR, _cairo_surface_nil_write_error);
 153 static DEFINE_NIL_SURFACE(CAIRO_STATUS_INVALID_STRIDE, _cairo_surface_nil_invalid_stride);
 154 static DEFINE_NIL_SURFACE(CAIRO_STATUS_INVALID_SIZE, _cairo_surface_nil_invalid_size);
 155 static DEFINE_NIL_SURFACE(CAIRO_STATUS_DEVICE_TYPE_MISMATCH, _cairo_surface_nil_device_type_mismatch);
 156 static DEFINE_NIL_SURFACE(CAIRO_STATUS_DEVICE_ERROR, _cairo_surface_nil_device_error);
 157
 158 static DEFINE_NIL_SURFACE(CAIRO_INT_STATUS_UNSUPPORTED, _cairo_surface_nil_unsupported);
 159 static DEFINE_NIL_SURFACE(CAIRO_INT_STATUS_NOTHING_TO_DO, _cairo_surface_nil_nothing_to_do);
 160
 161 static void _cairo_surface_finish_snapshots (cairo_surface_t *surface);
 162 static void _cairo_surface_finish (cairo_surface_t *surface);
 163
 164 /**
 165  * _cairo_surface_set_error:
 166  * @surface: a surface
 167  * @status: a status value indicating an error
 168  *
 169  * Atomically sets surface->status to @status and calls _cairo_error;
 170  * Does nothing if status is %CAIRO_STATUS_SUCCESS or any of the internal
 171  * status values.
 172  *
 173  * All assignments of an error status to surface->status should happen
 174  * through _cairo_surface_set_error(). Note that due to the nature of
 175  * the atomic operation, it is not safe to call this function on the
 176  * nil objects.
 177  *
 178  * The purpose of this function is to allow the user to set a
 179  * breakpoint in _cairo_error() to generate a stack trace for when the
 180  * user causes cairo to detect an error.
 181  *
 182  * Return value: the error status.
 183  **/
 184 cairo_int_status_t
 185 _cairo_surface_set_error (cairo_surface_t *surface,
 186                           cairo_int_status_t status)
 187 {
 188     /* NOTHING_TO_DO is magic. We use it to break out of the inner-most
 189      * surface function, but anything higher just sees "success".
 190      */
 191     if (status == CAIRO_INT_STATUS_NOTHING_TO_DO)
 192         status = CAIRO_INT_STATUS_SUCCESS;
 193
 194     if (status == CAIRO_INT_STATUS_SUCCESS ||
 195         status >= (int)CAIRO_INT_STATUS_LAST_STATUS)
 196         return status;
 197
 198     /* Don't overwrite an existing error. This preserves the first
 199      * error, which is the most significant. */
 200     _cairo_status_set_error (&surface->status, (cairo_status_t)status);
 201
 202     return _cairo_error (status);
 203 }
 204
 205 /**
 206  * cairo_surface_get_type:
 207  * @surface: a #cairo_surface_t
 208  *
 209  * This function returns the type of the backend used to create
 210  * a surface. See #cairo_surface_type_t for available types.
 211  *
 212  * Return value: The type of @surface.
 213  *
 214  * Since: 1.2
 215  **/
 216 cairo_surface_type_t
 217 cairo_surface_get_type (cairo_surface_t *surface)
 218 {
 219     /* We don't use surface->backend->type here so that some of the
 220      * special "wrapper" surfaces such as cairo_paginated_surface_t
 221      * can override surface->type with the type of the "child"
 222      * surface. */
 223     return surface->type;
 224 }
 225
 226 /**
 227  * cairo_surface_get_content:
 228  * @surface: a #cairo_surface_t
 229  *
 230  * This function returns the content type of @surface which indicates
 231  * whether the surface contains color and/or alpha information. See
 232  * #cairo_content_t.
 233  *
 234  * Return value: The content type of @surface.
 235  *
 236  * Since: 1.2
 237  **/
 238 cairo_content_t
 239 cairo_surface_get_content (cairo_surface_t *surface)
 240 {
 241     return surface->content;
 242 }
 243
 244 /**
 245  * cairo_surface_status:
 246  * @surface: a #cairo_surface_t
 247  *
 248  * Checks whether an error has previously occurred for this
 249  * surface.
 250  *
 251  * Return value: %CAIRO_STATUS_SUCCESS, %CAIRO_STATUS_NULL_POINTER,
 252  * %CAIRO_STATUS_NO_MEMORY, %CAIRO_STATUS_READ_ERROR,
 253  * %CAIRO_STATUS_INVALID_CONTENT, %CAIRO_STATUS_INVALID_FORMAT, or
 254  * %CAIRO_STATUS_INVALID_VISUAL.
 255  *
 256  * Since: 1.0
 257  **/
 258 cairo_status_t
 259 cairo_surface_status (cairo_surface_t *surface)
 260 {
 261     return surface->status;
 262 }
 263 slim_hidden_def (cairo_surface_status);
 264
 265 static unsigned int
 266 _cairo_surface_allocate_unique_id (void)
 267 {
 268     static cairo_atomic_int_t unique_id;
 269
 270 #if CAIRO_NO_MUTEX
 271     if (++unique_id == 0)
 272         unique_id = 1;
 273     return unique_id;
 274 #else
 275     cairo_atomic_int_t old, id;
 276
 277     do {
 278         old = _cairo_atomic_uint_get (&unique_id);
 279         id = old + 1;
 280         if (id == 0)
 281             id = 1;
 282     } while (! _cairo_atomic_uint_cmpxchg (&unique_id, old, id));
 283
 284     return id;
 285 #endif
 286 }
 287
 288 /**
 289  * cairo_surface_get_device:
 290  * @surface: a #cairo_surface_t
 291  *
 292  * This function returns the device for a @surface.
 293  * See #cairo_device_t.
 294  *
 295  * Return value: The device for @surface or %NULL if the surface does
 296  *               not have an associated device.
 297  *
 298  * Since: 1.10
 299  **/
 300 cairo_device_t *
 301 cairo_surface_get_device (cairo_surface_t *surface)
 302 {
 303     if (unlikely (surface->status))
 304         return _cairo_device_create_in_error (surface->status);
 305
 306     return surface->device;
 307 }
 308
 309 static cairo_bool_t
 310 _cairo_surface_has_snapshots (cairo_surface_t *surface)
 311 {
 312     return ! cairo_list_is_empty (&surface->snapshots);
 313 }
 314
 315 static cairo_bool_t
 316 _cairo_surface_has_mime_data (cairo_surface_t *surface)
 317 {
 318     return surface->mime_data.num_elements != 0;
 319 }
 320
 321 static void
 322 _cairo_surface_detach_mime_data (cairo_surface_t *surface)
 323 {
 324     if (! _cairo_surface_has_mime_data (surface))
 325         return;
 326
 327     _cairo_user_data_array_fini (&surface->mime_data);
 328     _cairo_user_data_array_init (&surface->mime_data);
 329 }
 330
 331 static void
 332 _cairo_surface_detach_snapshots (cairo_surface_t *surface)
 333 {
 334     while (_cairo_surface_has_snapshots (surface)) {
 335         _cairo_surface_detach_snapshot (cairo_list_first_entry (&surface->snapshots,
 336                                                                 cairo_surface_t,
 337                                                                 snapshot));
 338     }
 339 }
 340
 341 void
 342 _cairo_surface_detach_snapshot (cairo_surface_t *snapshot)
 343 {
 344     assert (snapshot->snapshot_of != NULL);
 345
 346     snapshot->snapshot_of = NULL;
 347     cairo_list_del (&snapshot->snapshot);
 348
 349     if (snapshot->snapshot_detach != NULL) {
 350         /* If this is a snapshot of a subsurface, call snapshot_detach with the
 351          * parent subsurface, so that it can clear its snapshot. */
 352         if (snapshot->snapshot_subsurface)
 353             snapshot->snapshot_detach (snapshot->snapshot_subsurface);
 354         else
 355             snapshot->snapshot_detach (snapshot);
 356     }
 357
 358     cairo_surface_destroy (snapshot);
 359 }
 360
 361 static void
 362 _cairo_surface_attach_snapshot_internal (cairo_surface_t *surface,
 363                                          cairo_surface_t *snapshot,
 364                                          cairo_surface_func_t detach_func)
 365 {
 366     assert (surface != snapshot);
 367     assert (snapshot->snapshot_of != surface);
 368
 369     cairo_surface_reference (snapshot);
 370
 371     if (snapshot->snapshot_of != NULL)
 372         _cairo_surface_detach_snapshot (snapshot);
 373
 374     snapshot->snapshot_of = surface;
 375     snapshot->snapshot_detach = detach_func;
 376
 377     cairo_list_add (&snapshot->snapshot, &surface->snapshots);
 378 }
 379
 380 void
 381 _cairo_surface_attach_snapshot (cairo_surface_t *surface,
 382                                  cairo_surface_t *snapshot,
 383                                  cairo_surface_func_t detach_func)
 384 {
 385     _cairo_surface_attach_snapshot_internal (surface, snapshot, detach_func);
 386     assert (_cairo_surface_has_snapshot (surface, snapshot->backend) == snapshot);
 387 }
 388
 389 void
 390 _cairo_surface_attach_subsurface_snapshot (cairo_surface_t *surface,
 391                                            cairo_surface_subsurface_t *subsurface,
 392                                            cairo_surface_t *snapshot,
 393                                            cairo_surface_func_t detach_func)
 394 {
 395     _cairo_surface_attach_snapshot_internal (surface, snapshot, detach_func);
 396     snapshot->snapshot_subsurface = &subsurface->base;
 397 }
 398
 399 cairo_surface_t *
 400 _cairo_surface_has_snapshot (cairo_surface_t *surface,
 401                              const cairo_surface_backend_t *backend)
 402 {
 403     cairo_surface_t *snapshot;
 404
 405     cairo_list_foreach_entry (snapshot, cairo_surface_t,
 406                               &surface->snapshots, snapshot)
 407     {
 408         if (snapshot->backend == backend &&
 409             snapshot->snapshot_subsurface == NULL)
 410             return snapshot;
 411     }
 412
 413     return NULL;
 414 }
 415
 416 cairo_status_t
 417 _cairo_surface_begin_modification (cairo_surface_t *surface)
 418 {
 419     assert (surface->status == CAIRO_STATUS_SUCCESS);
 420     assert (! surface->finished);
 421
 422     return _cairo_surface_flush (surface, 1);
 423 }
 424
 425 void
 426 _cairo_surface_init (cairo_surface_t                    *surface,
 427                      const cairo_surface_backend_t      *backend,
 428                      cairo_device_t                     *device,
 429                      cairo_content_t                     content)
 430 {
 431     CAIRO_MUTEX_INITIALIZE ();
 432
 433     surface->backend = backend;
 434     surface->device = cairo_device_reference (device);
 435     surface->content = content;
 436     surface->type = backend->type;
 437
 438     CAIRO_REFERENCE_COUNT_INIT (&surface->ref_count, 1);
 439     surface->status = CAIRO_STATUS_SUCCESS;
 440     surface->unique_id = _cairo_surface_allocate_unique_id ();
 441     surface->finished = FALSE;
 442     surface->_finishing = FALSE;
 443     surface->is_clear = FALSE;
 444     surface->serial = 0;
 445     surface->damage = NULL;
 446     surface->owns_device = (device != NULL);
 447
 448     _cairo_user_data_array_init (&surface->user_data);
 449     _cairo_user_data_array_init (&surface->mime_data);
 450
 451     cairo_matrix_init_identity (&surface->device_transform);
 452     cairo_matrix_init_identity (&surface->device_transform_inverse);
 453     cairo_list_init (&surface->device_transform_observers);
 454
 455     surface->x_resolution = CAIRO_SURFACE_RESOLUTION_DEFAULT;
 456     surface->y_resolution = CAIRO_SURFACE_RESOLUTION_DEFAULT;
 457
 458     surface->x_fallback_resolution = CAIRO_SURFACE_FALLBACK_RESOLUTION_DEFAULT;
 459     surface->y_fallback_resolution = CAIRO_SURFACE_FALLBACK_RESOLUTION_DEFAULT;
 460
 461     cairo_list_init (&surface->snapshots);
 462     surface->snapshot_of = NULL;
 463     surface->snapshot_subsurface = NULL;
 464
 465     surface->has_font_options = FALSE;
 466 }
 467
 468 static void
 469 _cairo_surface_copy_similar_properties (cairo_surface_t *surface,
 470                                         cairo_surface_t *other)
 471 {
 472     if (other->has_font_options || other->backend != surface->backend) {
 473         cairo_font_options_t options;
 474
 475         cairo_surface_get_font_options (other, &options);
 476         _cairo_surface_set_font_options (surface, &options);
 477     }
 478
 479     cairo_surface_set_fallback_resolution (surface,
 480                                            other->x_fallback_resolution,
 481                                            other->y_fallback_resolution);
 482 }
 483
 484 cairo_surface_t *
 485 _cairo_surface_create_similar_scratch (cairo_surface_t *other,
 486                                        cairo_content_t  content,
 487                                        int              width,
 488                                        int              height)
 489 {
 490     cairo_surface_t *surface;
 491
 492     if (unlikely (other->status))
 493         return _cairo_surface_create_in_error (other->status);
 494
 495     surface = NULL;
 496     if (other->backend->create_similar)
 497         surface = other->backend->create_similar (other, content, width, height);
 498     if (surface == NULL)
 499         surface = cairo_surface_create_similar_image (other,
 500                                                       _cairo_format_from_content (content),
 501                                                       width, height);
 502
 503     if (unlikely (surface->status))
 504         return surface;
 505
 506     _cairo_surface_copy_similar_properties (surface, other);
 507
 508     return surface;
 509 }
 510
 511 /**
 512  * cairo_surface_create_similar:
 513  * @other: an existing surface used to select the backend of the new surface
 514  * @content: the content for the new surface
 515  * @width: width of the new surface, (in device-space units)
 516  * @height: height of the new surface (in device-space units)
 517  *
 518  * Create a new surface that is as compatible as possible with an
 519  * existing surface. For example the new surface will have the same
 520  * fallback resolution and font options as @other. Generally, the new
 521  * surface will also use the same backend as @other, unless that is
 522  * not possible for some reason. The type of the returned surface may
 523  * be examined with cairo_surface_get_type().
 524  *
 525  * Initially the surface contents are all 0 (transparent if contents
 526  * have transparency, black otherwise.)
 527  *
 528  * Use cairo_surface_create_similar_image() if you need an image surface
 529  * which can be painted quickly to the target surface.
 530  *
 531  * Return value: a pointer to the newly allocated surface. The caller
 532  * owns the surface and should call cairo_surface_destroy() when done
 533  * with it.
 534  *
 535  * This function always returns a valid pointer, but it will return a
 536  * pointer to a "nil" surface if @other is already in an error state
 537  * or any other error occurs.
 538  *
 539  * Since: 1.0
 540  **/
 541 cairo_surface_t *
 542 cairo_surface_create_similar (cairo_surface_t  *other,
 543                               cairo_content_t   content,
 544                               int               width,
 545                               int               height)
 546 {
 547     cairo_surface_t *surface;
 548
 549     if (unlikely (other->status))
 550         return _cairo_surface_create_in_error (other->status);
 551     if (unlikely (other->finished))
 552         return _cairo_surface_create_in_error (CAIRO_STATUS_SURFACE_FINISHED);
 553     if (unlikely (width < 0 || height < 0))
 554         return _cairo_surface_create_in_error (CAIRO_STATUS_INVALID_SIZE);
 555
 556     if (unlikely (! CAIRO_CONTENT_VALID (content)))
 557         return _cairo_surface_create_in_error (CAIRO_STATUS_INVALID_CONTENT);
 558
 559     surface = _cairo_surface_create_similar_solid (other,
 560                                                    content, width, height,
 561                                                    CAIRO_COLOR_TRANSPARENT);
 562     assert (surface->is_clear);
 563
 564     return surface;
 565 }
 566
 567 /**
 568  * cairo_surface_create_similar_image:
 569  * @other: an existing surface used to select the preference of the new surface
 570  * @format: the format for the new surface
 571  * @width: width of the new surface, (in device-space units)
 572  * @height: height of the new surface (in device-space units)
 573  *
 574  * Create a new image surface that is as compatible as possible for uploading
 575  * to and the use in conjunction with an existing surface. However, this surface
 576  * can still be used like any normal image surface.
 577  *
 578  * Initially the surface contents are all 0 (transparent if contents
 579  * have transparency, black otherwise.)
 580  *
 581  * Use cairo_surface_create_similar() if you don't need an image surface.
 582  *
 583  * Return value: a pointer to the newly allocated image surface. The caller
 584  * owns the surface and should call cairo_surface_destroy() when done
 585  * with it.
 586  *
 587  * This function always returns a valid pointer, but it will return a
 588  * pointer to a "nil" surface if @other is already in an error state
 589  * or any other error occurs.
 590  *
 591  * Since: 1.12
 592  **/
 593 cairo_surface_t *
 594 cairo_surface_create_similar_image (cairo_surface_t  *other,
 595                                     cairo_format_t    format,
 596                                     int         width,
 597                                     int         height)
 598 {
 599     cairo_surface_t *image;
 600
 601     if (unlikely (other->status))
 602         return _cairo_surface_create_in_error (other->status);
 603     if (unlikely (other->finished))
 604         return _cairo_surface_create_in_error (CAIRO_STATUS_SURFACE_FINISHED);
 605
 606     if (unlikely (width < 0 || height < 0))
 607         return _cairo_surface_create_in_error (CAIRO_STATUS_INVALID_SIZE);
 608     if (unlikely (! CAIRO_FORMAT_VALID (format)))
 609         return _cairo_surface_create_in_error (CAIRO_STATUS_INVALID_FORMAT);
 610
 611     image = NULL;
 612     if (other->backend->create_similar_image)
 613         image = other->backend->create_similar_image (other,
 614                                                       format, width, height);
 615     if (image == NULL)
 616         image = cairo_image_surface_create (format, width, height);
 617
 618     assert (image->is_clear);
 619
 620     return image;
 621 }
 622 slim_hidden_def (cairo_surface_create_similar_image);
 623
 624 /**
 625  * _cairo_surface_map_to_image:
 626  * @surface: an existing surface used to extract the image from
 627  * @extents: limit the extraction to an rectangular region
 628  *
 629  * Returns an image surface that is the most efficient mechanism for
 630  * modifying the backing store of the target surface. The region
 631  * retrieved is limited to @extents.
 632  *
 633  * Note, the use of the original surface as a target or source whilst
 634  * it is mapped is undefined. The result of mapping the surface
 635  * multiple times is undefined. Calling cairo_surface_destroy() or
 636  * cairo_surface_finish() on the resulting image surface results in
 637  * undefined behavior. Changing the device transform of the image
 638  * surface or of @surface before the image surface is unmapped results
 639  * in undefined behavior.
 640  *
 641  * Assumes that @surface is valid (CAIRO_STATUS_SUCCESS,
 642  * non-finished).
 643  *
 644  * Return value: a pointer to the newly allocated image surface. The
 645  * caller must use _cairo_surface_unmap_image() to destroy this image
 646  * surface.
 647  *
 648  * This function always returns a valid pointer, but it will return a
 649  * pointer to a "nil" surface if @other is already in an error state
 650  * or any other error occurs.
 651  *
 652  * The returned image might have a %CAIRO_FORMAT_INVALID format.
 653  **/
 654 cairo_image_surface_t *
 655 _cairo_surface_map_to_image (cairo_surface_t  *surface,
 656                              const cairo_rectangle_int_t *extents)
 657 {
 658     cairo_image_surface_t *image = NULL;
 659
 660     assert (extents != NULL);
 661
 662     /* TODO: require map_to_image != NULL */
 663     if (surface->backend->map_to_image)
 664         image = surface->backend->map_to_image (surface, extents);
 665
 666     if (image == NULL)
 667         image = _cairo_image_surface_clone_subimage (surface, extents);
 668
 669     return image;
 670 }
 671
 672 /**
 673  * _cairo_surface_unmap_image:
 674  * @surface: the surface passed to _cairo_surface_map_to_image().
 675  * @image: the currently mapped image
 676  *
 677  * Unmaps the image surface as returned from
 678  * _cairo_surface_map_to_image().
 679  *
 680  * The content of the image will be uploaded to the target surface.
 681  * Afterwards, the image is destroyed.
 682  *
 683  * Using an image surface which wasn't returned by
 684  * _cairo_surface_map_to_image() results in undefined behavior.
 685  *
 686  * An image surface in error status can be passed to
 687  * _cairo_surface_unmap_image().
 688  *
 689  * Return value: the unmap status.
 690  *
 691  * Even if the unmap status is not successful, @image is destroyed.
 692  **/
 693 cairo_int_status_t
 694 _cairo_surface_unmap_image (cairo_surface_t       *surface,
 695                             cairo_image_surface_t *image)
 696 {
 697     cairo_surface_pattern_t pattern;
 698     cairo_rectangle_int_t extents;
 699     cairo_clip_t *clip;
 700     cairo_int_status_t status;
 701
 702     /* map_to_image can return error surfaces */
 703     if (unlikely (image->base.status)) {
 704         status = image->base.status;
 705         goto destroy;
 706     }
 707
 708     /* If the image is untouched just skip the update */
 709     if (image->base.serial == 0) {
 710         status = CAIRO_STATUS_SUCCESS;
 711         goto destroy;
 712     }
 713
 714     /* TODO: require unmap_image != NULL */
 715     if (surface->backend->unmap_image &&
 716         ! _cairo_image_surface_is_clone (image))
 717     {
 718         status = surface->backend->unmap_image (surface, image);
 719         if (status != CAIRO_INT_STATUS_UNSUPPORTED)
 720             return status;
 721     }
 722
 723     _cairo_pattern_init_for_surface (&pattern, &image->base);
 724     pattern.base.filter = CAIRO_FILTER_NEAREST;
 725
 726     /* We have to apply the translate from map_to_image's extents.x and .y */
 727     cairo_matrix_init_translate (&pattern.base.matrix,
 728                                  image->base.device_transform.x0,
 729                                  image->base.device_transform.y0);
 730
 731     /* And we also have to clip the operation to the image's extents */
 732     extents.x = image->base.device_transform_inverse.x0;
 733     extents.y = image->base.device_transform_inverse.y0;
 734     extents.width  = image->width;
 735     extents.height = image->height;
 736     clip = _cairo_clip_intersect_rectangle (NULL, &extents);
 737
 738     status = _cairo_surface_paint (surface,
 739                                    CAIRO_OPERATOR_SOURCE,
 740                                    &pattern.base,
 741                                    clip);
 742
 743     _cairo_pattern_fini (&pattern.base);
 744     _cairo_clip_destroy (clip);
 745
 746 destroy:
 747     cairo_surface_finish (&image->base);
 748     cairo_surface_destroy (&image->base);
 749
 750     return status;
 751 }
 752
 753 /**
 754  * cairo_surface_map_to_image:
 755  * @surface: an existing surface used to extract the image from
 756  * @extents: limit the extraction to an rectangular region
 757  *
 758  * Returns an image surface that is the most efficient mechanism for
 759  * modifying the backing store of the target surface. The region retrieved
 760  * may be limited to the @extents or %NULL for the whole surface
 761  *
 762  * Note, the use of the original surface as a target or source whilst
 763  * it is mapped is undefined. The result of mapping the surface
 764  * multiple times is undefined. Calling cairo_surface_destroy() or
 765  * cairo_surface_finish() on the resulting image surface results in
 766  * undefined behavior. Changing the device transform of the image
 767  * surface or of @surface before the image surface is unmapped results
 768  * in undefined behavior.
 769  *
 770  * Return value: a pointer to the newly allocated image surface. The caller
 771  * must use cairo_surface_unmap_image() to destroy this image surface.
 772  *
 773  * This function always returns a valid pointer, but it will return a
 774  * pointer to a "nil" surface if @other is already in an error state
 775  * or any other error occurs. If the returned pointer does not have an
 776  * error status, it is guaranteed to be an image surface whose format
 777  * is not %CAIRO_FORMAT_INVALID.
 778  *
 779  * Since: 1.12
 780  **/
 781 cairo_surface_t *
 782 cairo_surface_map_to_image (cairo_surface_t  *surface,
 783                             const cairo_rectangle_int_t *extents)
 784 {
 785     cairo_rectangle_int_t rect;
 786     cairo_image_surface_t *image;
 787     cairo_status_t status;
 788
 789     if (unlikely (surface->status))
 790         return _cairo_surface_create_in_error (surface->status);
 791     if (unlikely (surface->finished))
 792         return _cairo_surface_create_in_error (CAIRO_STATUS_SURFACE_FINISHED);
 793
 794     if (extents == NULL) {
 795         if (unlikely (! surface->backend->get_extents (surface, &rect)))
 796             return _cairo_surface_create_in_error (CAIRO_STATUS_INVALID_SIZE);
 797
 798         extents = &rect;
 799     } else {
 800         cairo_rectangle_int_t surface_extents;
 801
 802         /* If this surface is bounded, we can't map parts
 803          * that are outside of it. */
 804         if (likely (surface->backend->get_extents (surface, &surface_extents))) {
 805             if (unlikely (! _cairo_rectangle_contains_rectangle (&surface_extents, extents)))
 806                 return _cairo_surface_create_in_error (CAIRO_STATUS_INVALID_SIZE);
 807         }
 808     }
 809
 810     image = _cairo_surface_map_to_image (surface, extents);
 811
 812     status = image->base.status;
 813     if (unlikely (status)) {
 814         cairo_surface_destroy (&image->base);
 815         return _cairo_surface_create_in_error (status);
 816     }
 817
 818     if (image->format == CAIRO_FORMAT_INVALID) {
 819         cairo_surface_destroy (&image->base);
 820         image = _cairo_image_surface_clone_subimage (surface, extents);
 821     }
 822
 823     return &image->base;
 824 }
 825
 826 /**
 827  * cairo_surface_unmap_image:
 828  * @surface: the surface passed to cairo_surface_map_to_image().
 829  * @image: the currently mapped image
 830  *
 831  * Unmaps the image surface as returned from #cairo_surface_map_to_image().
 832  *
 833  * The content of the image will be uploaded to the target surface.
 834  * Afterwards, the image is destroyed.
 835  *
 836  * Using an image surface which wasn't returned by cairo_surface_map_to_image()
 837  * results in undefined behavior.
 838  *
 839  * Since: 1.12
 840  **/
 841 void
 842 cairo_surface_unmap_image (cairo_surface_t *surface,
 843                            cairo_surface_t *image)
 844 {
 845     cairo_int_status_t status = CAIRO_STATUS_SUCCESS;
 846
 847     if (unlikely (surface->status)) {
 848         status = surface->status;
 849         goto error;
 850     }
 851     if (unlikely (surface->finished)) {
 852         status = _cairo_error (CAIRO_STATUS_SURFACE_FINISHED);
 853         goto error;
 854     }
 855     if (unlikely (image->status)) {
 856         status = image->status;
 857         goto error;
 858     }
 859     if (unlikely (image->finished)) {
 860         status = _cairo_error (CAIRO_STATUS_SURFACE_FINISHED);
 861         goto error;
 862     }
 863     if (unlikely (! _cairo_surface_is_image (image))) {
 864         status = _cairo_error (CAIRO_STATUS_SURFACE_TYPE_MISMATCH);
 865         goto error;
 866     }
 867
 868     status = _cairo_surface_unmap_image (surface,
 869                                          (cairo_image_surface_t *) image);
 870     if (unlikely (status))
 871         _cairo_surface_set_error (surface, status);
 872
 873     return;
 874
 875 error:
 876     _cairo_surface_set_error (surface, status);
 877     cairo_surface_finish (image);
 878     cairo_surface_destroy (image);
 879 }
 880
 881 cairo_surface_t *
 882 _cairo_surface_create_similar_solid (cairo_surface_t     *other,
 883                                      cairo_content_t      content,
 884                                      int                  width,
 885                                      int                  height,
 886                                      const cairo_color_t *color)
 887 {
 888     cairo_status_t status;
 889     cairo_surface_t *surface;
 890     cairo_solid_pattern_t pattern;
 891
 892     surface = _cairo_surface_create_similar_scratch (other, content,
 893                                                      width, height);
 894     if (unlikely (surface->status))
 895         return surface;
 896
 897     _cairo_pattern_init_solid (&pattern, color);
 898     status = _cairo_surface_paint (surface,
 899                                    color == CAIRO_COLOR_TRANSPARENT ?
 900                                    CAIRO_OPERATOR_CLEAR : CAIRO_OPERATOR_SOURCE,
 901                                    &pattern.base, NULL);
 902     if (unlikely (status)) {
 903         cairo_surface_destroy (surface);
 904         surface = _cairo_surface_create_in_error (status);
 905     }
 906
 907     return surface;
 908 }
 909
 910 /**
 911  * cairo_surface_reference:
 912  * @surface: a #cairo_surface_t
 913  *
 914  * Increases the reference count on @surface by one. This prevents
 915  * @surface from being destroyed until a matching call to
 916  * cairo_surface_destroy() is made.
 917  *
 918  * The number of references to a #cairo_surface_t can be get using
 919  * cairo_surface_get_reference_count().
 920  *
 921  * Return value: the referenced #cairo_surface_t.
 922  *
 923  * Since: 1.0
 924  **/
 925 cairo_surface_t *
 926 cairo_surface_reference (cairo_surface_t *surface)
 927 {
 928     if (surface == NULL ||
 929             CAIRO_REFERENCE_COUNT_IS_INVALID (&surface->ref_count))
 930         return surface;
 931
 932     assert (CAIRO_REFERENCE_COUNT_HAS_REFERENCE (&surface->ref_count));
 933
 934     _cairo_reference_count_inc (&surface->ref_count);
 935
 936     return surface;
 937 }
 938 slim_hidden_def (cairo_surface_reference);
 939
 940 /**
 941  * cairo_surface_destroy:
 942  * @surface: a #cairo_surface_t
 943  *
 944  * Decreases the reference count on @surface by one. If the result is
 945  * zero, then @surface and all associated resources are freed.  See
 946  * cairo_surface_reference().
 947  *
 948  * Since: 1.0
 949  **/
 950 void
 951 cairo_surface_destroy (cairo_surface_t *surface)
 952 {
 953     if (surface == NULL ||
 954             CAIRO_REFERENCE_COUNT_IS_INVALID (&surface->ref_count))
 955         return;
 956
 957     assert (CAIRO_REFERENCE_COUNT_HAS_REFERENCE (&surface->ref_count));
 958
 959     if (! _cairo_reference_count_dec_and_test (&surface->ref_count))
 960         return;
 961
 962     assert (surface->snapshot_of == NULL);
 963
 964     if (! surface->finished) {
 965         _cairo_surface_finish_snapshots (surface);
 966         /* We may have been referenced by a snapshot prior to have
 967          * detaching it with the copy-on-write.
 968          */
 969         if (CAIRO_REFERENCE_COUNT_GET_VALUE (&surface->ref_count))
 970             return;
 971
 972         _cairo_surface_finish (surface);
 973     }
 974
 975     if (surface->damage)
 976         _cairo_damage_destroy (surface->damage);
 977
 978     _cairo_user_data_array_fini (&surface->user_data);
 979     _cairo_user_data_array_fini (&surface->mime_data);
 980
 981     if (surface->owns_device)
 982         cairo_device_destroy (surface->device);
 983
 984     assert (surface->snapshot_of == NULL);
 985     assert (! _cairo_surface_has_snapshots (surface));
 986     /* paranoid check that nobody took a reference whilst finishing */
 987     assert (! CAIRO_REFERENCE_COUNT_HAS_REFERENCE (&surface->ref_count));
 988
 989     free (surface);
 990 }
 991 slim_hidden_def(cairo_surface_destroy);
 992
 993 /**
 994  * cairo_surface_get_reference_count:
 995  * @surface: a #cairo_surface_t
 996  *
 997  * Returns the current reference count of @surface.
 998  *
 999  * Return value: the current reference count of @surface.  If the
1000  * object is a nil object, 0 will be returned.
1001  *
1002  * Since: 1.4
1003  **/
1004 unsigned int
1005 cairo_surface_get_reference_count (cairo_surface_t *surface)
1006 {
1007     if (surface == NULL ||
1008             CAIRO_REFERENCE_COUNT_IS_INVALID (&surface->ref_count))
1009         return 0;
1010
1011     return CAIRO_REFERENCE_COUNT_GET_VALUE (&surface->ref_count);
1012 }
1013
1014 static void
1015 _cairo_surface_finish_snapshots (cairo_surface_t *surface)
1016 {
1017     cairo_status_t status;
1018
1019     /* update the snapshots *before* we declare the surface as finished */
1020     surface->_finishing = TRUE;
1021     status = _cairo_surface_flush (surface, 0);
1022     (void) status;
1023 }
1024
1025 static void
1026 _cairo_surface_finish (cairo_surface_t *surface)
1027 {
1028     cairo_status_t status;
1029
1030     surface->finished = TRUE;
1031
1032     /* call finish even if in error mode */
1033     if (surface->backend->finish) {
1034         status = surface->backend->finish (surface);
1035         if (unlikely (status))
1036             _cairo_surface_set_error (surface, status);
1037     }
1038
1039     assert (surface->snapshot_of == NULL);
1040     assert (!_cairo_surface_has_snapshots (surface));
1041 }
1042
1043 /**
1044  * cairo_surface_finish:
1045  * @surface: the #cairo_surface_t to finish
1046  *
1047  * This function finishes the surface and drops all references to
1048  * external resources.  For example, for the Xlib backend it means
1049  * that cairo will no longer access the drawable, which can be freed.
1050  * After calling cairo_surface_finish() the only valid operations on a
1051  * surface are getting and setting user, referencing and
1052  * destroying, and flushing and finishing it.
1053  * Further drawing to the surface will not affect the
1054  * surface but will instead trigger a %CAIRO_STATUS_SURFACE_FINISHED
1055  * error.
1056  *
1057  * When the last call to cairo_surface_destroy() decreases the
1058  * reference count to zero, cairo will call cairo_surface_finish() if
1059  * it hasn't been called already, before freeing the resources
1060  * associated with the surface.
1061  *
1062  * Since: 1.0
1063  **/
1064 void
1065 cairo_surface_finish (cairo_surface_t *surface)
1066 {
1067     if (surface == NULL)
1068         return;
1069
1070     if (CAIRO_REFERENCE_COUNT_IS_INVALID (&surface->ref_count))
1071         return;
1072
1073     if (surface->finished)
1074         return;
1075
1076     /* We have to be careful when decoupling potential reference cycles */
1077     cairo_surface_reference (surface);
1078
1079     _cairo_surface_finish_snapshots (surface);
1080     /* XXX need to block and wait for snapshot references */
1081     _cairo_surface_finish (surface);
1082
1083     cairo_surface_destroy (surface);
1084 }
1085 slim_hidden_def (cairo_surface_finish);
1086
1087 /**
1088  * _cairo_surface_release_device_reference:
1089  * @surface: a #cairo_surface_t
1090  *
1091  * This function makes @surface release the reference to its device. The
1092  * function is intended to be used for avoiding cycling references for
1093  * surfaces that are owned by their device, for example cache surfaces.
1094  * Note that the @surface will still assume that the device is available.
1095  * So it is the caller's responsibility to ensure the device stays around
1096  * until the @surface is destroyed. Just calling cairo_surface_finish() is
1097  * not enough.
1098  **/
1099 void
1100 _cairo_surface_release_device_reference (cairo_surface_t *surface)
1101 {
1102     assert (surface->owns_device);
1103
1104     cairo_device_destroy (surface->device);
1105     surface->owns_device = FALSE;
1106 }
1107
1108 /**
1109  * cairo_surface_get_user_data:
1110  * @surface: a #cairo_surface_t
1111  * @key: the address of the #cairo_user_data_key_t the user data was
1112  * attached to
1113  *
1114  * Return user data previously attached to @surface using the specified
1115  * key.  If no user data has been attached with the given key this
1116  * function returns %NULL.
1117  *
1118  * Return value: the user data previously attached or %NULL.
1119  *
1120  * Since: 1.0
1121  **/
1122 void *
1123 cairo_surface_get_user_data (cairo_surface_t             *surface,
1124                              const cairo_user_data_key_t *key)
1125 {
1126     return _cairo_user_data_array_get_data (&surface->user_data, key);
1127 }
1128
1129 /**
1130  * cairo_surface_set_user_data:
1131  * @surface: a #cairo_surface_t
1132  * @key: the address of a #cairo_user_data_key_t to attach the user data to
1133  * @user_data: the user data to attach to the surface
1134  * @destroy: a #cairo_destroy_func_t which will be called when the
1135  * surface is destroyed or when new user data is attached using the
1136  * same key.
1137  *
1138  * Attach user data to @surface.  To remove user data from a surface,
1139  * call this function with the key that was used to set it and %NULL
1140  * for @data.
1141  *
1142  * Return value: %CAIRO_STATUS_SUCCESS or %CAIRO_STATUS_NO_MEMORY if a
1143  * slot could not be allocated for the user data.
1144  *
1145  * Since: 1.0
1146  **/
1147 cairo_status_t
1148 cairo_surface_set_user_data (cairo_surface_t             *surface,
1149                              const cairo_user_data_key_t *key,
1150                              void                        *user_data,
1151                              cairo_destroy_func_t        destroy)
1152 {
1153     if (CAIRO_REFERENCE_COUNT_IS_INVALID (&surface->ref_count))
1154         return surface->status;
1155
1156     return _cairo_user_data_array_set_data (&surface->user_data,
1157                                             key, user_data, destroy);
1158 }
1159
1160 /**
1161  * cairo_surface_get_mime_data:
1162  * @surface: a #cairo_surface_t
1163  * @mime_type: the mime type of the image data
1164  * @data: the image data to attached to the surface
1165  * @length: the length of the image data
1166  *
1167  * Return mime data previously attached to @surface using the
1168  * specified mime type.  If no data has been attached with the given
1169  * mime type, @data is set %NULL.
1170  *
1171  * Since: 1.10
1172  **/
1173 void
1174 cairo_surface_get_mime_data (cairo_surface_t            *surface,
1175                              const char                 *mime_type,
1176                              const unsigned char       **data,
1177                              unsigned long              *length)
1178 {
1179     cairo_user_data_slot_t *slots;
1180     int i, num_slots;
1181
1182     *data = NULL;
1183     *length = 0;
1184     if (unlikely (surface->status))
1185         return;
1186
1187     /* The number of mime-types attached to a surface is usually small,
1188      * typically zero. Therefore it is quicker to do a strcmp() against
1189      * each key than it is to intern the string (i.e. compute a hash,
1190      * search the hash table, and do a final strcmp).
1191      */
1192     num_slots = surface->mime_data.num_elements;
1193     slots = _cairo_array_index (&surface->mime_data, 0);
1194     for (i = 0; i < num_slots; i++) {
1195         if (slots[i].key != NULL && strcmp ((char *) slots[i].key, mime_type) == 0) {
1196             cairo_mime_data_t *mime_data = slots[i].user_data;
1197
1198             *data = mime_data->data;
1199             *length = mime_data->length;
1200             return;
1201         }
1202     }
1203 }
1204 slim_hidden_def (cairo_surface_get_mime_data);
1205
1206 static void
1207 _cairo_mime_data_destroy (void *ptr)
1208 {
1209     cairo_mime_data_t *mime_data = ptr;
1210
1211     if (! _cairo_reference_count_dec_and_test (&mime_data->ref_count))
1212         return;
1213
1214     if (mime_data->destroy && mime_data->closure)
1215         mime_data->destroy (mime_data->closure);
1216
1217     free (mime_data);
1218 }
1219
1220 /**
1221  * CAIRO_MIME_TYPE_JP2:
1222  *
1223  * The Joint Photographic Experts Group (JPEG) 2000 image coding standard (ISO/IEC 15444-1).
1224  *
1225  * Since: 1.10
1226  **/
1227
1228 /**
1229  * CAIRO_MIME_TYPE_JPEG:
1230  *
1231  * The Joint Photographic Experts Group (JPEG) image coding standard (ISO/IEC 10918-1).
1232  *
1233  * Since: 1.10
1234  **/
1235
1236 /**
1237  * CAIRO_MIME_TYPE_PNG:
1238  *
1239  * The Portable Network Graphics image file format (ISO/IEC 15948).
1240  *
1241  * Since: 1.10
1242  **/
1243
1244 /**
1245  * CAIRO_MIME_TYPE_URI:
1246  *
1247  * URI for an image file (unofficial MIME type).
1248  *
1249  * Since: 1.10
1250  **/
1251
1252 /**
1253  * CAIRO_MIME_TYPE_UNIQUE_ID:
1254  *
1255  * Unique identifier for a surface (cairo specific MIME type).
1256  *
1257  * Since: 1.12
1258  **/
1259
1260 /**
1261  * cairo_surface_set_mime_data:
1262  * @surface: a #cairo_surface_t
1263  * @mime_type: the MIME type of the image data
1264  * @data: the image data to attach to the surface
1265  * @length: the length of the image data
1266  * @destroy: a #cairo_destroy_func_t which will be called when the
1267  * surface is destroyed or when new image data is attached using the
1268  * same mime type.
1269  * @closure: the data to be passed to the @destroy notifier
1270  *
1271  * Attach an image in the format @mime_type to @surface. To remove
1272  * the data from a surface, call this function with same mime type
1273  * and %NULL for @data.
1274  *
1275  * The attached image (or filename) data can later be used by backends
1276  * which support it (currently: PDF, PS, SVG and Win32 Printing
1277  * surfaces) to emit this data instead of making a snapshot of the
1278  * @surface.  This approach tends to be faster and requires less
1279  * memory and disk space.
1280  *
1281  * The recognized MIME types are the following: %CAIRO_MIME_TYPE_JPEG,
1282  * %CAIRO_MIME_TYPE_PNG, %CAIRO_MIME_TYPE_JP2, %CAIRO_MIME_TYPE_URI.
1283  *
1284  * See corresponding backend surface docs for details about which MIME
1285  * types it can handle. Caution: the associated MIME data will be
1286  * discarded if you draw on the surface afterwards. Use this function
1287  * with care.
1288  *
1289  * Return value: %CAIRO_STATUS_SUCCESS or %CAIRO_STATUS_NO_MEMORY if a
1290  * slot could not be allocated for the user data.
1291  *
1292  * Since: 1.10
1293  **/
1294 cairo_status_t
1295 cairo_surface_set_mime_data (cairo_surface_t            *surface,
1296                              const char                 *mime_type,
1297                              const unsigned char        *data,
1298                              unsigned long               length,
1299                              cairo_destroy_func_t        destroy,
1300                              void                       *closure)
1301 {
1302     cairo_status_t status;
1303     cairo_mime_data_t *mime_data;
1304
1305     if (unlikely (surface->status))
1306         return surface->status;
1307     if (unlikely (surface->finished))
1308         return _cairo_surface_set_error (surface, _cairo_error (CAIRO_STATUS_SURFACE_FINISHED));
1309
1310     status = _cairo_intern_string (&mime_type, -1);
1311     if (unlikely (status))
1312         return _cairo_surface_set_error (surface, status);
1313
1314     if (data != NULL) {
1315         mime_data = malloc (sizeof (cairo_mime_data_t));
1316         if (unlikely (mime_data == NULL))
1317             return _cairo_surface_set_error (surface, _cairo_error (CAIRO_STATUS_NO_MEMORY));
1318
1319         CAIRO_REFERENCE_COUNT_INIT (&mime_data->ref_count, 1);
1320
1321         mime_data->data = (unsigned char *) data;
1322         mime_data->length = length;
1323         mime_data->destroy = destroy;
1324         mime_data->closure = closure;
1325     } else
1326         mime_data = NULL;
1327
1328     status = _cairo_user_data_array_set_data (&surface->mime_data,
1329                                               (cairo_user_data_key_t *) mime_type,
1330                                               mime_data,
1331                                               _cairo_mime_data_destroy);
1332     if (unlikely (status)) {
1333         free (mime_data);
1334
1335         return _cairo_surface_set_error (surface, status);
1336     }
1337
1338     return CAIRO_STATUS_SUCCESS;
1339 }
1340 slim_hidden_def (cairo_surface_set_mime_data);
1341
1342 /**
1343  * cairo_surface_supports_mime_type:
1344  * @surface: a #cairo_surface_t
1345  * @mime_type: the mime type
1346  *
1347  * Return whether @surface supports @mime_type.
1348  *
1349  * Return value: %TRUE if @surface supports
1350  *               @mime_type, %FALSE otherwise
1351  *
1352  * Since: 1.12
1353  **/
1354 cairo_bool_t
1355 cairo_surface_supports_mime_type (cairo_surface_t               *surface,
1356                                   const char                    *mime_type)
1357 {
1358     const char **types;
1359
1360     if (surface->backend->get_supported_mime_types) {
1361         types = surface->backend->get_supported_mime_types (surface);
1362         if (types) {
1363             while (*types) {
1364                 if (strcmp (*types, mime_type) == 0)
1365                     return TRUE;
1366                 types++;
1367             }
1368         }
1369     }
1370
1371     return FALSE;
1372 }
1373 slim_hidden_def (cairo_surface_supports_mime_type);
1374
1375 static void
1376 _cairo_mime_data_reference (const void *key, void *elt, void *closure)
1377 {
1378     cairo_mime_data_t *mime_data = elt;
1379
1380     _cairo_reference_count_inc (&mime_data->ref_count);
1381 }
1382
1383 cairo_status_t
1384 _cairo_surface_copy_mime_data (cairo_surface_t *dst,
1385                                cairo_surface_t *src)
1386 {
1387     cairo_status_t status;
1388
1389     if (dst->status)
1390         return dst->status;
1391
1392     if (src->status)
1393         return _cairo_surface_set_error (dst, src->status);
1394
1395     /* first copy the mime-data, discarding any already set on dst */
1396     status = _cairo_user_data_array_copy (&dst->mime_data, &src->mime_data);
1397     if (unlikely (status))
1398         return _cairo_surface_set_error (dst, status);
1399
1400     /* now increment the reference counters for the copies */
1401     _cairo_user_data_array_foreach (&dst->mime_data,
1402                                     _cairo_mime_data_reference,
1403                                     NULL);
1404
1405     return CAIRO_STATUS_SUCCESS;
1406 }
1407
1408 /**
1409  * _cairo_surface_set_font_options:
1410  * @surface: a #cairo_surface_t
1411  * @options: a #cairo_font_options_t object that contains the
1412  *   options to use for this surface instead of backend's default
1413  *   font options.
1414  *
1415  * Sets the default font rendering options for the surface.
1416  * This is useful to correctly propagate default font options when
1417  * falling back to an image surface in a backend implementation.
1418  * This affects the options returned in cairo_surface_get_font_options().
1419  *
1420  * If @options is %NULL the surface options are reset to those of
1421  * the backend default.
1422  **/
1423 void
1424 _cairo_surface_set_font_options (cairo_surface_t       *surface,
1425                                  cairo_font_options_t  *options)
1426 {
1427     if (surface->status)
1428         return;
1429
1430     assert (surface->snapshot_of == NULL);
1431
1432     if (surface->finished) {
1433         _cairo_surface_set_error (surface, _cairo_error (CAIRO_STATUS_SURFACE_FINISHED));
1434         return;
1435     }
1436
1437     if (options) {
1438         surface->has_font_options = TRUE;
1439         _cairo_font_options_init_copy (&surface->font_options, options);
1440     } else {
1441         surface->has_font_options = FALSE;
1442     }
1443 }
1444
1445 /**
1446  * cairo_surface_get_font_options:
1447  * @surface: a #cairo_surface_t
1448  * @options: a #cairo_font_options_t object into which to store
1449  *   the retrieved options. All existing values are overwritten
1450  *
1451  * Retrieves the default font rendering options for the surface.
1452  * This allows display surfaces to report the correct subpixel order
1453  * for rendering on them, print surfaces to disable hinting of
1454  * metrics and so forth. The result can then be used with
1455  * cairo_scaled_font_create().
1456  *
1457  * Since: 1.0
1458  **/
1459 void
1460 cairo_surface_get_font_options (cairo_surface_t       *surface,
1461                                 cairo_font_options_t  *options)
1462 {
1463     if (cairo_font_options_status (options))
1464         return;
1465
1466     if (surface->status) {
1467         _cairo_font_options_init_default (options);
1468         return;
1469     }
1470
1471     if (! surface->has_font_options) {
1472         surface->has_font_options = TRUE;
1473
1474         _cairo_font_options_init_default (&surface->font_options);
1475
1476         if (!surface->finished && surface->backend->get_font_options) {
1477             surface->backend->get_font_options (surface, &surface->font_options);
1478         }
1479     }
1480
1481     _cairo_font_options_init_copy (options, &surface->font_options);
1482 }
1483 slim_hidden_def (cairo_surface_get_font_options);
1484
1485 cairo_status_t
1486 _cairo_surface_flush (cairo_surface_t *surface, unsigned flags)
1487 {
1488     /* update the current snapshots *before* the user updates the surface */
1489     _cairo_surface_detach_snapshots (surface);
1490     if (surface->snapshot_of != NULL)
1491         _cairo_surface_detach_snapshot (surface);
1492     _cairo_surface_detach_mime_data (surface);
1493
1494     return __cairo_surface_flush (surface, flags);
1495 }
1496
1497 /**
1498  * cairo_surface_flush:
1499  * @surface: a #cairo_surface_t
1500  *
1501  * Do any pending drawing for the surface and also restore any
1502  * temporary modifications cairo has made to the surface's
1503  * state. This function must be called before switching from
1504  * drawing on the surface with cairo to drawing on it directly
1505  * with native APIs. If the surface doesn't support direct access,
1506  * then this function does nothing.
1507  *
1508  * Since: 1.0
1509  **/
1510 void
1511 cairo_surface_flush (cairo_surface_t *surface)
1512 {
1513     cairo_status_t status;
1514
1515     if (surface->status)
1516         return;
1517
1518     if (surface->finished)
1519         return;
1520
1521     status = _cairo_surface_flush (surface, 0);
1522     if (unlikely (status))
1523         _cairo_surface_set_error (surface, status);
1524 }
1525 slim_hidden_def (cairo_surface_flush);
1526
1527 /**
1528  * cairo_surface_mark_dirty:
1529  * @surface: a #cairo_surface_t
1530  *
1531  * Tells cairo that drawing has been done to surface using means other
1532  * than cairo, and that cairo should reread any cached areas. Note
1533  * that you must call cairo_surface_flush() before doing such drawing.
1534  *
1535  * Since: 1.0
1536  **/
1537 void
1538 cairo_surface_mark_dirty (cairo_surface_t *surface)
1539 {
1540     cairo_rectangle_int_t extents;
1541
1542     if (unlikely (surface->status))
1543         return;
1544     if (unlikely (surface->finished)) {
1545         _cairo_surface_set_error (surface, _cairo_error (CAIRO_STATUS_SURFACE_FINISHED));
1546         return;
1547     }
1548
1549     _cairo_surface_get_extents (surface, &extents);
1550     cairo_surface_mark_dirty_rectangle (surface,
1551                                         extents.x, extents.y,
1552                                         extents.width, extents.height);
1553 }
1554 slim_hidden_def (cairo_surface_mark_dirty);
1555
1556 /**
1557  * cairo_surface_mark_dirty_rectangle:
1558  * @surface: a #cairo_surface_t
1559  * @x: X coordinate of dirty rectangle
1560  * @y: Y coordinate of dirty rectangle
1561  * @width: width of dirty rectangle
1562  * @height: height of dirty rectangle
1563  *
1564  * Like cairo_surface_mark_dirty(), but drawing has been done only to
1565  * the specified rectangle, so that cairo can retain cached contents
1566  * for other parts of the surface.
1567  *
1568  * Any cached clip set on the surface will be reset by this function,
1569  * to make sure that future cairo calls have the clip set that they
1570  * expect.
1571  *
1572  * Since: 1.0
1573  **/
1574 void
1575 cairo_surface_mark_dirty_rectangle (cairo_surface_t *surface,
1576                                     int              x,
1577                                     int              y,
1578                                     int              width,
1579                                     int              height)
1580 {
1581     cairo_status_t status;
1582
1583     if (unlikely (surface->status))
1584         return;
1585
1586     assert (surface->snapshot_of == NULL);
1587
1588     if (unlikely (surface->finished)) {
1589         _cairo_surface_set_error (surface, _cairo_error (CAIRO_STATUS_SURFACE_FINISHED));
1590         return;
1591     }
1592
1593     /* The application *should* have called cairo_surface_flush() before
1594      * modifying the surface independently of cairo (and thus having to
1595      * call mark_dirty()). */
1596     assert (! _cairo_surface_has_snapshots (surface));
1597     assert (! _cairo_surface_has_mime_data (surface));
1598
1599     surface->is_clear = FALSE;
1600     surface->serial++;
1601
1602     if (surface->damage) {
1603         cairo_box_t box;
1604
1605         box.p1.x = x;
1606         box.p1.y = y;
1607         box.p2.x = x + width;
1608         box.p2.y = y + height;
1609
1610         surface->damage = _cairo_damage_add_box (surface->damage, &box);
1611     }
1612
1613     if (surface->backend->mark_dirty_rectangle != NULL) {
1614         /* XXX: FRAGILE: We're ignoring the scaling component of
1615          * device_transform here. I don't know what the right thing to
1616          * do would actually be if there were some scaling here, but
1617          * we avoid this since device_transfom scaling is not exported
1618          * publicly and mark_dirty is not used internally. */
1619         status = surface->backend->mark_dirty_rectangle (surface,
1620                                                          x + surface->device_transform.x0,
1621                                                          y + surface->device_transform.y0,
1622                                                          width, height);
1623
1624         if (unlikely (status))
1625             _cairo_surface_set_error (surface, status);
1626     }
1627 }
1628 slim_hidden_def (cairo_surface_mark_dirty_rectangle);
1629
1630 /**
1631  * _cairo_surface_set_device_scale:
1632  * @surface: a #cairo_surface_t
1633  * @sx: a scale factor in the X direction
1634  * @sy: a scale factor in the Y direction
1635  *
1636  * Private function for setting an extra scale factor to affect all
1637  * drawing to a surface. This is used, for example, when replaying a
1638  * recording surface to an image fallback intended for an eventual
1639  * vector-oriented backend. Since the recording surface will record
1640  * coordinates in one backend space, but the image fallback uses a
1641  * different backend space, (differing by the fallback resolution
1642  * scale factors), we need a scale factor correction.
1643  *
1644  * Caution: Not all places we use device transform correctly handle
1645  * both a translate and a scale.  An audit would be nice.
1646  **/
1647 void
1648 _cairo_surface_set_device_scale (cairo_surface_t *surface,
1649                                  double           sx,
1650                                  double           sy)
1651 {
1652     cairo_status_t status;
1653
1654     if (unlikely (surface->status))
1655         return;
1656
1657     assert (surface->snapshot_of == NULL);
1658
1659     if (unlikely (surface->finished)) {
1660         _cairo_surface_set_error (surface, _cairo_error (CAIRO_STATUS_SURFACE_FINISHED));
1661         return;
1662     }
1663
1664     status = _cairo_surface_begin_modification (surface);
1665     if (unlikely (status)) {
1666         _cairo_surface_set_error (surface, status);
1667         return;
1668     }
1669
1670     surface->device_transform.xx = sx;
1671     surface->device_transform.yy = sy;
1672     surface->device_transform.xy = 0.0;
1673     surface->device_transform.yx = 0.0;
1674
1675     surface->device_transform_inverse = surface->device_transform;
1676     status = cairo_matrix_invert (&surface->device_transform_inverse);
1677     /* should always be invertible unless given pathological input */
1678     assert (status == CAIRO_STATUS_SUCCESS);
1679
1680     _cairo_observers_notify (&surface->device_transform_observers, surface);
1681 }
1682
1683 /**
1684  * cairo_surface_set_device_offset:
1685  * @surface: a #cairo_surface_t
1686  * @x_offset: the offset in the X direction, in device units
1687  * @y_offset: the offset in the Y direction, in device units
1688  *
1689  * Sets an offset that is added to the device coordinates determined
1690  * by the CTM when drawing to @surface. One use case for this function
1691  * is when we want to create a #cairo_surface_t that redirects drawing
1692  * for a portion of an onscreen surface to an offscreen surface in a
1693  * way that is completely invisible to the user of the cairo
1694  * API. Setting a transformation via cairo_translate() isn't
1695  * sufficient to do this, since functions like
1696  * cairo_device_to_user() will expose the hidden offset.
1697  *
1698  * Note that the offset affects drawing to the surface as well as
1699  * using the surface in a source pattern.
1700  *
1701  * Since: 1.0
1702  **/
1703 void
1704 cairo_surface_set_device_offset (cairo_surface_t *surface,
1705                                  double           x_offset,
1706                                  double           y_offset)
1707 {
1708     cairo_status_t status;
1709
1710     if (unlikely (surface->status))
1711         return;
1712
1713     assert (surface->snapshot_of == NULL);
1714
1715     if (unlikely (surface->finished)) {
1716         _cairo_surface_set_error (surface, _cairo_error (CAIRO_STATUS_SURFACE_FINISHED));
1717         return;
1718     }
1719
1720     status = _cairo_surface_begin_modification (surface);
1721     if (unlikely (status)) {
1722         _cairo_surface_set_error (surface, status);
1723         return;
1724     }
1725
1726     surface->device_transform.x0 = x_offset;
1727     surface->device_transform.y0 = y_offset;
1728
1729     surface->device_transform_inverse = surface->device_transform;
1730     status = cairo_matrix_invert (&surface->device_transform_inverse);
1731     /* should always be invertible unless given pathological input */
1732     assert (status == CAIRO_STATUS_SUCCESS);
1733
1734     _cairo_observers_notify (&surface->device_transform_observers, surface);
1735 }
1736 slim_hidden_def (cairo_surface_set_device_offset);
1737
1738 /**
1739  * cairo_surface_get_device_offset:
1740  * @surface: a #cairo_surface_t
1741  * @x_offset: the offset in the X direction, in device units
1742  * @y_offset: the offset in the Y direction, in device units
1743  *
1744  * This function returns the previous device offset set by
1745  * cairo_surface_set_device_offset().
1746  *
1747  * Since: 1.2
1748  **/
1749 void
1750 cairo_surface_get_device_offset (cairo_surface_t *surface,
1751                                  double          *x_offset,
1752                                  double          *y_offset)
1753 {
1754     if (x_offset)
1755         *x_offset = surface->device_transform.x0;
1756     if (y_offset)
1757         *y_offset = surface->device_transform.y0;
1758 }
1759 slim_hidden_def (cairo_surface_get_device_offset);
1760
1761 /**
1762  * cairo_surface_set_fallback_resolution:
1763  * @surface: a #cairo_surface_t
1764  * @x_pixels_per_inch: horizontal setting for pixels per inch
1765  * @y_pixels_per_inch: vertical setting for pixels per inch
1766  *
1767  * Set the horizontal and vertical resolution for image fallbacks.
1768  *
1769  * When certain operations aren't supported natively by a backend,
1770  * cairo will fallback by rendering operations to an image and then
1771  * overlaying that image onto the output. For backends that are
1772  * natively vector-oriented, this function can be used to set the
1773  * resolution used for these image fallbacks, (larger values will
1774  * result in more detailed images, but also larger file sizes).
1775  *
1776  * Some examples of natively vector-oriented backends are the ps, pdf,
1777  * and svg backends.
1778  *
1779  * For backends that are natively raster-oriented, image fallbacks are
1780  * still possible, but they are always performed at the native
1781  * device resolution. So this function has no effect on those
1782  * backends.
1783  *
1784  * Note: The fallback resolution only takes effect at the time of
1785  * completing a page (with cairo_show_page() or cairo_copy_page()) so
1786  * there is currently no way to have more than one fallback resolution
1787  * in effect on a single page.
1788  *
1789  * The default fallback resoultion is 300 pixels per inch in both
1790  * dimensions.
1791  *
1792  * Since: 1.2
1793  **/
1794 void
1795 cairo_surface_set_fallback_resolution (cairo_surface_t  *surface,
1796                                        double            x_pixels_per_inch,
1797                                        double            y_pixels_per_inch)
1798 {
1799     cairo_status_t status;
1800
1801     if (unlikely (surface->status))
1802         return;
1803
1804     assert (surface->snapshot_of == NULL);
1805
1806     if (unlikely (surface->finished)) {
1807         _cairo_surface_set_error (surface, _cairo_error (CAIRO_STATUS_SURFACE_FINISHED));
1808         return;
1809     }
1810
1811     if (x_pixels_per_inch <= 0 || y_pixels_per_inch <= 0) {
1812         /* XXX Could delay raising the error until we fallback, but throwing
1813          * the error here means that we can catch the real culprit.
1814          */
1815         _cairo_surface_set_error (surface, CAIRO_STATUS_INVALID_MATRIX);
1816         return;
1817     }
1818
1819     status = _cairo_surface_begin_modification (surface);
1820     if (unlikely (status)) {
1821         _cairo_surface_set_error (surface, status);
1822         return;
1823     }
1824
1825     surface->x_fallback_resolution = x_pixels_per_inch;
1826     surface->y_fallback_resolution = y_pixels_per_inch;
1827 }
1828 slim_hidden_def (cairo_surface_set_fallback_resolution);
1829
1830 /**
1831  * cairo_surface_get_fallback_resolution:
1832  * @surface: a #cairo_surface_t
1833  * @x_pixels_per_inch: horizontal pixels per inch
1834  * @y_pixels_per_inch: vertical pixels per inch
1835  *
1836  * This function returns the previous fallback resolution set by
1837  * cairo_surface_set_fallback_resolution(), or default fallback
1838  * resolution if never set.
1839  *
1840  * Since: 1.8
1841  **/
1842 void
1843 cairo_surface_get_fallback_resolution (cairo_surface_t  *surface,
1844                                        double           *x_pixels_per_inch,
1845                                        double           *y_pixels_per_inch)
1846 {
1847     if (x_pixels_per_inch)
1848         *x_pixels_per_inch = surface->x_fallback_resolution;
1849     if (y_pixels_per_inch)
1850         *y_pixels_per_inch = surface->y_fallback_resolution;
1851 }
1852
1853 cairo_bool_t
1854 _cairo_surface_has_device_transform (cairo_surface_t *surface)
1855 {
1856     return ! _cairo_matrix_is_identity (&surface->device_transform);
1857 }
1858
1859 /**
1860  * _cairo_surface_acquire_source_image:
1861  * @surface: a #cairo_surface_t
1862  * @image_out: location to store a pointer to an image surface that
1863  *    has identical contents to @surface. This surface could be @surface
1864  *    itself, a surface held internal to @surface, or it could be a new
1865  *    surface with a copy of the relevant portion of @surface.
1866  * @image_extra: location to store image specific backend data
1867  *
1868  * Gets an image surface to use when drawing as a fallback when drawing with
1869  * @surface as a source. _cairo_surface_release_source_image() must be called
1870  * when finished.
1871  *
1872  * Return value: %CAIRO_STATUS_SUCCESS if an image was stored in @image_out.
1873  * %CAIRO_INT_STATUS_UNSUPPORTED if an image cannot be retrieved for the specified
1874  * surface. Or %CAIRO_STATUS_NO_MEMORY.
1875  **/
1876 cairo_status_t
1877 _cairo_surface_acquire_source_image (cairo_surface_t         *surface,
1878                                      cairo_image_surface_t  **image_out,
1879                                      void                   **image_extra)
1880 {
1881     cairo_status_t status;
1882
1883     if (unlikely (surface->status))
1884         return surface->status;
1885
1886     assert (!surface->finished);
1887
1888     if (surface->backend->acquire_source_image == NULL)
1889         return CAIRO_INT_STATUS_UNSUPPORTED;
1890
1891     status = surface->backend->acquire_source_image (surface,
1892                                                      image_out, image_extra);
1893     if (unlikely (status))
1894         return _cairo_surface_set_error (surface, status);
1895
1896     _cairo_debug_check_image_surface_is_defined (&(*image_out)->base);
1897
1898     return CAIRO_STATUS_SUCCESS;
1899 }
1900
1901 cairo_status_t
1902 _cairo_surface_default_acquire_source_image (void                    *_surface,
1903                                              cairo_image_surface_t  **image_out,
1904                                              void                   **image_extra)
1905 {
1906     cairo_surface_t *surface = _surface;
1907     cairo_rectangle_int_t extents;
1908
1909     if (unlikely (! surface->backend->get_extents (surface, &extents)))
1910         return _cairo_error (CAIRO_STATUS_INVALID_SIZE);
1911
1912     *image_out = _cairo_surface_map_to_image (surface, &extents);
1913     *image_extra = NULL;
1914     return (*image_out)->base.status;
1915 }
1916
1917 /**
1918  * _cairo_surface_release_source_image:
1919  * @surface: a #cairo_surface_t
1920  * @image_extra: same as return from the matching _cairo_surface_acquire_source_image()
1921  *
1922  * Releases any resources obtained with _cairo_surface_acquire_source_image()
1923  **/
1924 void
1925 _cairo_surface_release_source_image (cairo_surface_t        *surface,
1926                                      cairo_image_surface_t  *image,
1927                                      void                   *image_extra)
1928 {
1929     assert (!surface->finished);
1930
1931     if (surface->backend->release_source_image)
1932         surface->backend->release_source_image (surface, image, image_extra);
1933 }
1934
1935 void
1936 _cairo_surface_default_release_source_image (void                   *surface,
1937                                              cairo_image_surface_t  *image,
1938                                              void                   *image_extra)
1939 {
1940     cairo_status_t ignored;
1941
1942     ignored = _cairo_surface_unmap_image (surface, image);
1943     (void)ignored;
1944 }
1945
1946
1947 cairo_surface_t *
1948 _cairo_surface_get_source (cairo_surface_t *surface,
1949                            cairo_rectangle_int_t *extents)
1950 {
1951     assert (surface->backend->source);
1952     return surface->backend->source (surface, extents);
1953 }
1954
1955 cairo_surface_t *
1956 _cairo_surface_default_source (void *surface,
1957                                cairo_rectangle_int_t *extents)
1958 {
1959     if (extents)
1960         _cairo_surface_get_extents(surface, extents);
1961     return surface;
1962 }
1963
1964 static cairo_status_t
1965 _pattern_has_error (const cairo_pattern_t *pattern)
1966 {
1967     const cairo_surface_pattern_t *spattern;
1968
1969     if (unlikely (pattern->status))
1970         return pattern->status;
1971
1972     if (pattern->type != CAIRO_PATTERN_TYPE_SURFACE)
1973         return CAIRO_STATUS_SUCCESS;
1974
1975     spattern = (const cairo_surface_pattern_t *) pattern;
1976     if (unlikely (spattern->surface->status))
1977         return spattern->surface->status;
1978
1979     if (unlikely (spattern->surface->finished))
1980         return _cairo_error (CAIRO_STATUS_SURFACE_FINISHED);
1981
1982     return CAIRO_STATUS_SUCCESS;
1983 }
1984
1985 static cairo_bool_t
1986 nothing_to_do (cairo_surface_t *surface,
1987                cairo_operator_t op,
1988                const cairo_pattern_t *source)
1989 {
1990     if (_cairo_pattern_is_clear (source)) {
1991         if (op == CAIRO_OPERATOR_OVER || op == CAIRO_OPERATOR_ADD)
1992             return TRUE;
1993
1994         if (op == CAIRO_OPERATOR_SOURCE)
1995             op = CAIRO_OPERATOR_CLEAR;
1996     }
1997
1998     if (op == CAIRO_OPERATOR_CLEAR && surface->is_clear)
1999         return TRUE;
2000
2001     if (op == CAIRO_OPERATOR_ATOP && (surface->content & CAIRO_CONTENT_COLOR) ==0)
2002         return TRUE;
2003
2004     return FALSE;
2005 }
2006
2007 cairo_status_t
2008 _cairo_surface_paint (cairo_surface_t           *surface,
2009                       cairo_operator_t           op,
2010                       const cairo_pattern_t     *source,
2011                       const cairo_clip_t        *clip)
2012 {
2013     cairo_int_status_t status;
2014
2015     TRACE ((stderr, "%s\n", __FUNCTION__));
2016     if (unlikely (surface->status))
2017         return surface->status;
2018
2019     if (_cairo_clip_is_all_clipped (clip))
2020         return CAIRO_STATUS_SUCCESS;
2021
2022     status = _pattern_has_error (source);
2023     if (unlikely (status))
2024         return status;
2025
2026     if (nothing_to_do (surface, op, source))
2027         return CAIRO_STATUS_SUCCESS;
2028
2029     status = _cairo_surface_begin_modification (surface);
2030     if (unlikely (status))
2031         return status;
2032
2033     status = surface->backend->paint (surface, op, source, clip);
2034     if (status != CAIRO_INT_STATUS_NOTHING_TO_DO) {
2035         surface->is_clear = op == CAIRO_OPERATOR_CLEAR && clip == NULL;
2036         surface->serial++;
2037     }
2038
2039     return _cairo_surface_set_error (surface, status);
2040 }
2041
2042 cairo_status_t
2043 _cairo_surface_mask (cairo_surface_t            *surface,
2044                      cairo_operator_t            op,
2045                      const cairo_pattern_t      *source,
2046                      const cairo_pattern_t      *mask,
2047                      const cairo_clip_t         *clip)
2048 {
2049     cairo_int_status_t status;
2050
2051     TRACE ((stderr, "%s\n", __FUNCTION__));
2052     if (unlikely (surface->status))
2053         return surface->status;
2054
2055     if (_cairo_clip_is_all_clipped (clip))
2056         return CAIRO_STATUS_SUCCESS;
2057
2058     /* If the mask is blank, this is just an expensive no-op */
2059     if (_cairo_pattern_is_clear (mask) &&
2060         _cairo_operator_bounded_by_mask (op))
2061     {
2062         return CAIRO_STATUS_SUCCESS;
2063     }
2064
2065     status = _pattern_has_error (source);
2066     if (unlikely (status))
2067         return status;
2068
2069     status = _pattern_has_error (mask);
2070     if (unlikely (status))
2071         return status;
2072
2073     if (nothing_to_do (surface, op, source))
2074         return CAIRO_STATUS_SUCCESS;
2075
2076     status = _cairo_surface_begin_modification (surface);
2077     if (unlikely (status))
2078         return status;
2079
2080     status = surface->backend->mask (surface, op, source, mask, clip);
2081     if (status != CAIRO_INT_STATUS_NOTHING_TO_DO) {
2082         surface->is_clear = FALSE;
2083         surface->serial++;
2084     }
2085
2086     return _cairo_surface_set_error (surface, status);
2087 }
2088
2089 cairo_status_t
2090 _cairo_surface_fill_stroke (cairo_surface_t         *surface,
2091                             cairo_operator_t         fill_op,
2092                             const cairo_pattern_t   *fill_source,
2093                             cairo_fill_rule_t        fill_rule,
2094                             double                   fill_tolerance,
2095                             cairo_antialias_t        fill_antialias,
2096                             cairo_path_fixed_t      *path,
2097                             cairo_operator_t         stroke_op,
2098                             const cairo_pattern_t   *stroke_source,
2099                             const cairo_stroke_style_t    *stroke_style,
2100                             const cairo_matrix_t            *stroke_ctm,
2101                             const cairo_matrix_t            *stroke_ctm_inverse,
2102                             double                   stroke_tolerance,
2103                             cairo_antialias_t        stroke_antialias,
2104                             const cairo_clip_t      *clip)
2105 {
2106     cairo_int_status_t status;
2107
2108     TRACE ((stderr, "%s\n", __FUNCTION__));
2109     if (unlikely (surface->status))
2110         return surface->status;
2111
2112     if (_cairo_clip_is_all_clipped (clip))
2113         return CAIRO_STATUS_SUCCESS;
2114
2115     if (surface->is_clear &&
2116         fill_op == CAIRO_OPERATOR_CLEAR &&
2117         stroke_op == CAIRO_OPERATOR_CLEAR)
2118     {
2119         return CAIRO_STATUS_SUCCESS;
2120     }
2121
2122     status = _pattern_has_error (fill_source);
2123     if (unlikely (status))
2124         return status;
2125
2126     status = _pattern_has_error (stroke_source);
2127     if (unlikely (status))
2128         return status;
2129
2130     status = _cairo_surface_begin_modification (surface);
2131     if (unlikely (status))
2132         return status;
2133
2134     if (surface->backend->fill_stroke) {
2135         cairo_matrix_t dev_ctm = *stroke_ctm;
2136         cairo_matrix_t dev_ctm_inverse = *stroke_ctm_inverse;
2137
2138         status = surface->backend->fill_stroke (surface,
2139                                                 fill_op, fill_source, fill_rule,
2140                                                 fill_tolerance, fill_antialias,
2141                                                 path,
2142                                                 stroke_op, stroke_source,
2143                                                 stroke_style,
2144                                                 &dev_ctm, &dev_ctm_inverse,
2145                                                 stroke_tolerance, stroke_antialias,
2146                                                 clip);
2147
2148         if (status != CAIRO_INT_STATUS_UNSUPPORTED)
2149             goto FINISH;
2150     }
2151
2152     status = _cairo_surface_fill (surface, fill_op, fill_source, path,
2153                                   fill_rule, fill_tolerance, fill_antialias,
2154                                   clip);
2155     if (unlikely (status))
2156         goto FINISH;
2157
2158     status = _cairo_surface_stroke (surface, stroke_op, stroke_source, path,
2159                                     stroke_style, stroke_ctm, stroke_ctm_inverse,
2160                                     stroke_tolerance, stroke_antialias,
2161                                     clip);
2162     if (unlikely (status))
2163         goto FINISH;
2164
2165   FINISH:
2166     if (status != CAIRO_INT_STATUS_NOTHING_TO_DO) {
2167         surface->is_clear = FALSE;
2168         surface->serial++;
2169     }
2170
2171     return _cairo_surface_set_error (surface, status);
2172 }
2173
2174 cairo_status_t
2175 _cairo_surface_stroke (cairo_surface_t                  *surface,
2176                        cairo_operator_t                  op,
2177                        const cairo_pattern_t            *source,
2178                        const cairo_path_fixed_t         *path,
2179                        const cairo_stroke_style_t       *stroke_style,
2180                        const cairo_matrix_t             *ctm,
2181                        const cairo_matrix_t             *ctm_inverse,
2182                        double                            tolerance,
2183                        cairo_antialias_t                 antialias,
2184                        const cairo_clip_t               *clip)
2185 {
2186     cairo_int_status_t status;
2187
2188     TRACE ((stderr, "%s\n", __FUNCTION__));
2189     if (unlikely (surface->status))
2190         return surface->status;
2191
2192     if (_cairo_clip_is_all_clipped (clip))
2193         return CAIRO_STATUS_SUCCESS;
2194
2195     status = _pattern_has_error (source);
2196     if (unlikely (status))
2197         return status;
2198
2199     if (nothing_to_do (surface, op, source))
2200         return CAIRO_STATUS_SUCCESS;
2201
2202     status = _cairo_surface_begin_modification (surface);
2203     if (unlikely (status))
2204         return status;
2205
2206     status = surface->backend->stroke (surface, op, source,
2207                                        path, stroke_style,
2208                                        ctm, ctm_inverse,
2209                                        tolerance, antialias,
2210                                        clip);
2211     if (status != CAIRO_INT_STATUS_NOTHING_TO_DO) {
2212         surface->is_clear = FALSE;
2213         surface->serial++;
2214     }
2215
2216     return _cairo_surface_set_error (surface, status);
2217 }
2218
2219 cairo_status_t
2220 _cairo_surface_fill (cairo_surface_t            *surface,
2221                      cairo_operator_t            op,
2222                      const cairo_pattern_t       *source,
2223                      const cairo_path_fixed_t   *path,
2224                      cairo_fill_rule_t           fill_rule,
2225                      double                      tolerance,
2226                      cairo_antialias_t           antialias,
2227                      const cairo_clip_t         *clip)
2228 {
2229     cairo_int_status_t status;
2230
2231     TRACE ((stderr, "%s\n", __FUNCTION__));
2232     if (unlikely (surface->status))
2233         return surface->status;
2234
2235     if (_cairo_clip_is_all_clipped (clip))
2236         return CAIRO_STATUS_SUCCESS;
2237
2238     status = _pattern_has_error (source);
2239     if (unlikely (status))
2240         return status;
2241
2242     if (nothing_to_do (surface, op, source))
2243         return CAIRO_STATUS_SUCCESS;
2244
2245     status = _cairo_surface_begin_modification (surface);
2246     if (unlikely (status))
2247         return status;
2248
2249     status = surface->backend->fill (surface, op, source,
2250                                      path, fill_rule,
2251                                      tolerance, antialias,
2252                                      clip);
2253     if (status != CAIRO_INT_STATUS_NOTHING_TO_DO) {
2254         surface->is_clear = FALSE;
2255         surface->serial++;
2256     }
2257
2258     return _cairo_surface_set_error (surface, status);
2259 }
2260
2261 /**
2262  * cairo_surface_copy_page:
2263  * @surface: a #cairo_surface_t
2264  *
2265  * Emits the current page for backends that support multiple pages,
2266  * but doesn't clear it, so that the contents of the current page will
2267  * be retained for the next page.  Use cairo_surface_show_page() if you
2268  * want to get an empty page after the emission.
2269  *
2270  * There is a convenience function for this that takes a #cairo_t,
2271  * namely cairo_copy_page().
2272  *
2273  * Since: 1.6
2274  **/
2275 void
2276 cairo_surface_copy_page (cairo_surface_t *surface)
2277 {
2278     if (unlikely (surface->status))
2279         return;
2280
2281     assert (surface->snapshot_of == NULL);
2282
2283     if (unlikely (surface->finished)) {
2284         _cairo_surface_set_error (surface, CAIRO_STATUS_SURFACE_FINISHED);
2285         return;
2286     }
2287
2288     /* It's fine if some backends don't implement copy_page */
2289     if (surface->backend->copy_page == NULL)
2290         return;
2291
2292     _cairo_surface_set_error (surface, surface->backend->copy_page (surface));
2293 }
2294 slim_hidden_def (cairo_surface_copy_page);
2295
2296 /**
2297  * cairo_surface_show_page:
2298  * @surface: a #cairo_Surface_t
2299  *
2300  * Emits and clears the current page for backends that support multiple
2301  * pages.  Use cairo_surface_copy_page() if you don't want to clear the page.
2302  *
2303  * There is a convenience function for this that takes a #cairo_t,
2304  * namely cairo_show_page().
2305  *
2306  * Since: 1.6
2307  **/
2308 void
2309 cairo_surface_show_page (cairo_surface_t *surface)
2310 {
2311     cairo_status_t status;
2312
2313     if (unlikely (surface->status))
2314         return;
2315
2316     if (unlikely (surface->finished)) {
2317         _cairo_surface_set_error (surface, CAIRO_STATUS_SURFACE_FINISHED);
2318         return;
2319     }
2320
2321     status = _cairo_surface_begin_modification (surface);
2322     if (unlikely (status)) {
2323         _cairo_surface_set_error (surface, status);
2324         return;
2325     }
2326
2327     /* It's fine if some backends don't implement show_page */
2328     if (surface->backend->show_page == NULL)
2329         return;
2330
2331     _cairo_surface_set_error (surface, surface->backend->show_page (surface));
2332 }
2333 slim_hidden_def (cairo_surface_show_page);
2334
2335 /**
2336  * _cairo_surface_get_extents:
2337  * @surface: the #cairo_surface_t to fetch extents for
2338  *
2339  * This function returns a bounding box for the surface.  The surface
2340  * bounds are defined as a region beyond which no rendering will
2341  * possibly be recorded, in other words, it is the maximum extent of
2342  * potentially usable coordinates.
2343  *
2344  * For vector surfaces, (PDF, PS, SVG and recording-surfaces), the surface
2345  * might be conceived as unbounded, but we force the user to provide a
2346  * maximum size at the time of surface_create. So get_extents uses
2347  * that size.
2348  *
2349  * Note: The coordinates returned are in "backend" space rather than
2350  * "surface" space. That is, they are relative to the true (0,0)
2351  * origin rather than the device_transform origin. This might seem a
2352  * bit inconsistent with other #cairo_surface_t interfaces, but all
2353  * current callers are within the surface layer where backend space is
2354  * desired.
2355  *
2356  * This behavior would have to be changed is we ever exported a public
2357  * variant of this function.
2358  **/
2359 cairo_bool_t
2360 _cairo_surface_get_extents (cairo_surface_t         *surface,
2361                             cairo_rectangle_int_t   *extents)
2362 {
2363     cairo_bool_t bounded;
2364
2365     bounded = FALSE;
2366     if (surface->backend->get_extents != NULL)
2367         bounded = surface->backend->get_extents (surface, extents);
2368
2369     if (! bounded)
2370         _cairo_unbounded_rectangle_init (extents);
2371
2372     return bounded;
2373 }
2374
2375 /**
2376  * cairo_surface_has_show_text_glyphs:
2377  * @surface: a #cairo_surface_t
2378  *
2379  * Returns whether the surface supports
2380  * sophisticated cairo_show_text_glyphs() operations.  That is,
2381  * whether it actually uses the provided text and cluster data
2382  * to a cairo_show_text_glyphs() call.
2383  *
2384  * Note: Even if this function returns %FALSE, a
2385  * cairo_show_text_glyphs() operation targeted at @surface will
2386  * still succeed.  It just will
2387  * act like a cairo_show_glyphs() operation.  Users can use this
2388  * function to avoid computing UTF-8 text and cluster mapping if the
2389  * target surface does not use it.
2390  *
2391  * Return value: %TRUE if @surface supports
2392  *               cairo_show_text_glyphs(), %FALSE otherwise
2393  *
2394  * Since: 1.8
2395  **/
2396 cairo_bool_t
2397 cairo_surface_has_show_text_glyphs (cairo_surface_t         *surface)
2398 {
2399     if (unlikely (surface->status))
2400         return FALSE;
2401
2402     if (unlikely (surface->finished)) {
2403         _cairo_surface_set_error (surface, CAIRO_STATUS_SURFACE_FINISHED);
2404         return FALSE;
2405     }
2406
2407     if (surface->backend->has_show_text_glyphs)
2408         return surface->backend->has_show_text_glyphs (surface);
2409     else
2410         return surface->backend->show_text_glyphs != NULL;
2411 }
2412 slim_hidden_def (cairo_surface_has_show_text_glyphs);
2413
2414 /* Note: the backends may modify the contents of the glyph array as long as
2415  * they do not return %CAIRO_INT_STATUS_UNSUPPORTED. This makes it possible to
2416  * avoid copying the array again and again, and edit it in-place.
2417  * Backends are in fact free to use the array as a generic buffer as they
2418  * see fit.
2419  *
2420  * For show_glyphs backend method, and NOT for show_text_glyphs method,
2421  * when they do return UNSUPPORTED, they may adjust remaining_glyphs to notify
2422  * that they have successfully rendered some of the glyphs (from the beginning
2423  * of the array), but not all.  If they don't touch remaining_glyphs, it
2424  * defaults to all glyphs.
2425  *
2426  * See commits 5a9642c5746fd677aed35ce620ce90b1029b1a0c and
2427  * 1781e6018c17909311295a9cc74b70500c6b4d0a for the rationale.
2428  */
2429 cairo_status_t
2430 _cairo_surface_show_text_glyphs (cairo_surface_t            *surface,
2431                                  cairo_operator_t            op,
2432                                  const cairo_pattern_t      *source,
2433                                  const char                 *utf8,
2434                                  int                         utf8_len,
2435                                  cairo_glyph_t              *glyphs,
2436                                  int                         num_glyphs,
2437                                  const cairo_text_cluster_t *clusters,
2438                                  int                         num_clusters,
2439                                  cairo_text_cluster_flags_t  cluster_flags,
2440                                  cairo_scaled_font_t        *scaled_font,
2441                                  const cairo_clip_t             *clip)
2442 {
2443     cairo_int_status_t status;
2444     cairo_scaled_font_t *dev_scaled_font = scaled_font;
2445
2446     TRACE ((stderr, "%s\n", __FUNCTION__));
2447     if (unlikely (surface->status))
2448         return surface->status;
2449
2450     if (num_glyphs == 0 && utf8_len == 0)
2451         return CAIRO_STATUS_SUCCESS;
2452
2453     if (_cairo_clip_is_all_clipped (clip))
2454         return CAIRO_STATUS_SUCCESS;
2455
2456     status = _pattern_has_error (source);
2457     if (unlikely (status))
2458         return status;
2459
2460     if (nothing_to_do (surface, op, source))
2461         return CAIRO_STATUS_SUCCESS;
2462
2463     status = _cairo_surface_begin_modification (surface);
2464     if (unlikely (status))
2465         return status;
2466
2467     if (_cairo_surface_has_device_transform (surface) &&
2468         ! _cairo_matrix_is_integer_translation (&surface->device_transform, NULL, NULL))
2469     {
2470         cairo_font_options_t font_options;
2471         cairo_matrix_t dev_ctm, font_matrix;
2472
2473         cairo_scaled_font_get_font_matrix (scaled_font, &font_matrix);
2474         cairo_scaled_font_get_ctm (scaled_font, &dev_ctm);
2475         cairo_matrix_multiply (&dev_ctm, &dev_ctm, &surface->device_transform);
2476         cairo_scaled_font_get_font_options (scaled_font, &font_options);
2477         dev_scaled_font = cairo_scaled_font_create (cairo_scaled_font_get_font_face (scaled_font),
2478                                                     &font_matrix,
2479                                                     &dev_ctm,
2480                                                     &font_options);
2481     }
2482     status = cairo_scaled_font_status (dev_scaled_font);
2483     if (unlikely (status))
2484         return _cairo_surface_set_error (surface, status);
2485
2486     status = CAIRO_INT_STATUS_UNSUPPORTED;
2487
2488     /* The logic here is duplicated in _cairo_analysis_surface show_glyphs and
2489      * show_text_glyphs.  Keep in synch. */
2490     if (clusters) {
2491         /* A real show_text_glyphs call.  Try show_text_glyphs backend
2492          * method first */
2493         if (surface->backend->show_text_glyphs != NULL) {
2494             status = surface->backend->show_text_glyphs (surface, op,
2495                                                          source,
2496                                                          utf8, utf8_len,
2497                                                          glyphs, num_glyphs,
2498                                                          clusters, num_clusters, cluster_flags,
2499                                                          dev_scaled_font,
2500                                                          clip);
2501         }
2502         if (status == CAIRO_INT_STATUS_UNSUPPORTED &&
2503             surface->backend->show_glyphs)
2504         {
2505             status = surface->backend->show_glyphs (surface, op,
2506                                                     source,
2507                                                     glyphs, num_glyphs,
2508                                                     dev_scaled_font,
2509                                                     clip);
2510         }
2511     } else {
2512         /* A mere show_glyphs call.  Try show_glyphs backend method first */
2513         if (surface->backend->show_glyphs != NULL) {
2514             status = surface->backend->show_glyphs (surface, op,
2515                                                     source,
2516                                                     glyphs, num_glyphs,
2517                                                     dev_scaled_font,
2518                                                     clip);
2519         } else if (surface->backend->show_text_glyphs != NULL) {
2520             /* Intentionally only try show_text_glyphs method for show_glyphs
2521              * calls if backend does not have show_glyphs.  If backend has
2522              * both methods implemented, we don't fallback from show_glyphs to
2523              * show_text_glyphs, and hence the backend can assume in its
2524              * show_text_glyphs call that clusters is not NULL (which also
2525              * implies that UTF-8 is not NULL, unless the text is
2526              * zero-length).
2527              */
2528             status = surface->backend->show_text_glyphs (surface, op,
2529                                                          source,
2530                                                          utf8, utf8_len,
2531                                                          glyphs, num_glyphs,
2532                                                          clusters, num_clusters, cluster_flags,
2533                                                          dev_scaled_font,
2534                                                          clip);
2535         }
2536     }
2537
2538     if (dev_scaled_font != scaled_font)
2539         cairo_scaled_font_destroy (dev_scaled_font);
2540
2541     if (status != CAIRO_INT_STATUS_NOTHING_TO_DO) {
2542         surface->is_clear = FALSE;
2543         surface->serial++;
2544     }
2545
2546     return _cairo_surface_set_error (surface, status);
2547 }
2548
2549 /**
2550  * _cairo_surface_set_resolution:
2551  * @surface: the surface
2552  * @x_res: x resolution, in dpi
2553  * @y_res: y resolution, in dpi
2554  *
2555  * Set the actual surface resolution of @surface to the given x and y DPI.
2556  * Mainly used for correctly computing the scale factor when fallback
2557  * rendering needs to take place in the paginated surface.
2558  **/
2559 void
2560 _cairo_surface_set_resolution (cairo_surface_t *surface,
2561                                double x_res,
2562                                double y_res)
2563 {
2564     if (surface->status)
2565         return;
2566
2567     surface->x_resolution = x_res;
2568     surface->y_resolution = y_res;
2569 }
2570
2571 cairo_surface_t *
2572 _cairo_surface_create_in_error (cairo_status_t status)
2573 {
2574     assert (status < CAIRO_STATUS_LAST_STATUS);
2575     switch (status) {
2576     case CAIRO_STATUS_NO_MEMORY:
2577         return (cairo_surface_t *) &_cairo_surface_nil;
2578     case CAIRO_STATUS_SURFACE_TYPE_MISMATCH:
2579         return (cairo_surface_t *) &_cairo_surface_nil_surface_type_mismatch;
2580     case CAIRO_STATUS_INVALID_STATUS:
2581         return (cairo_surface_t *) &_cairo_surface_nil_invalid_status;
2582     case CAIRO_STATUS_INVALID_CONTENT:
2583         return (cairo_surface_t *) &_cairo_surface_nil_invalid_content;
2584     case CAIRO_STATUS_INVALID_FORMAT:
2585         return (cairo_surface_t *) &_cairo_surface_nil_invalid_format;
2586     case CAIRO_STATUS_INVALID_VISUAL:
2587         return (cairo_surface_t *) &_cairo_surface_nil_invalid_visual;
2588     case CAIRO_STATUS_READ_ERROR:
2589         return (cairo_surface_t *) &_cairo_surface_nil_read_error;
2590     case CAIRO_STATUS_WRITE_ERROR:
2591         return (cairo_surface_t *) &_cairo_surface_nil_write_error;
2592     case CAIRO_STATUS_FILE_NOT_FOUND:
2593         return (cairo_surface_t *) &_cairo_surface_nil_file_not_found;
2594     case CAIRO_STATUS_TEMP_FILE_ERROR:
2595         return (cairo_surface_t *) &_cairo_surface_nil_temp_file_error;
2596     case CAIRO_STATUS_INVALID_STRIDE:
2597         return (cairo_surface_t *) &_cairo_surface_nil_invalid_stride;
2598     case CAIRO_STATUS_INVALID_SIZE:
2599         return (cairo_surface_t *) &_cairo_surface_nil_invalid_size;
2600     case CAIRO_STATUS_DEVICE_TYPE_MISMATCH:
2601         return (cairo_surface_t *) &_cairo_surface_nil_device_type_mismatch;
2602     case CAIRO_STATUS_DEVICE_ERROR:
2603         return (cairo_surface_t *) &_cairo_surface_nil_device_error;
2604     case CAIRO_STATUS_SUCCESS:
2605     case CAIRO_STATUS_LAST_STATUS:
2606         ASSERT_NOT_REACHED;
2607         /* fall-through */
2608     case CAIRO_STATUS_INVALID_RESTORE:
2609     case CAIRO_STATUS_INVALID_POP_GROUP:
2610     case CAIRO_STATUS_NO_CURRENT_POINT:
2611     case CAIRO_STATUS_INVALID_MATRIX:
2612     case CAIRO_STATUS_NULL_POINTER:
2613     case CAIRO_STATUS_INVALID_STRING:
2614     case CAIRO_STATUS_INVALID_PATH_DATA:
2615     case CAIRO_STATUS_SURFACE_FINISHED:
2616     case CAIRO_STATUS_PATTERN_TYPE_MISMATCH:
2617     case CAIRO_STATUS_INVALID_DASH:
2618     case CAIRO_STATUS_INVALID_DSC_COMMENT:
2619     case CAIRO_STATUS_INVALID_INDEX:
2620     case CAIRO_STATUS_CLIP_NOT_REPRESENTABLE:
2621     case CAIRO_STATUS_FONT_TYPE_MISMATCH:
2622     case CAIRO_STATUS_USER_FONT_IMMUTABLE:
2623     case CAIRO_STATUS_USER_FONT_ERROR:
2624     case CAIRO_STATUS_NEGATIVE_COUNT:
2625     case CAIRO_STATUS_INVALID_CLUSTERS:
2626     case CAIRO_STATUS_INVALID_SLANT:
2627     case CAIRO_STATUS_INVALID_WEIGHT:
2628     case CAIRO_STATUS_USER_FONT_NOT_IMPLEMENTED:
2629     case CAIRO_STATUS_INVALID_MESH_CONSTRUCTION:
2630     case CAIRO_STATUS_DEVICE_FINISHED:
2631     default:
2632         _cairo_error_throw (CAIRO_STATUS_NO_MEMORY);
2633         return (cairo_surface_t *) &_cairo_surface_nil;
2634     }
2635 }
2636
2637 cairo_surface_t *
2638 _cairo_int_surface_create_in_error (cairo_int_status_t status)
2639 {
2640     if (status < CAIRO_INT_STATUS_LAST_STATUS)
2641         return _cairo_surface_create_in_error (status);
2642
2643     switch ((int)status) {
2644     case CAIRO_INT_STATUS_UNSUPPORTED:
2645         return (cairo_surface_t *) &_cairo_surface_nil_unsupported;
2646     case CAIRO_INT_STATUS_NOTHING_TO_DO:
2647         return (cairo_surface_t *) &_cairo_surface_nil_nothing_to_do;
2648     default:
2649         _cairo_error_throw (CAIRO_STATUS_NO_MEMORY);
2650         return (cairo_surface_t *) &_cairo_surface_nil;
2651     }
2652 }
2653
2654 /*  LocalWords:  rasterized
2655  */