Subversion Repositories Kolibri OS

/* -*- Mode: c; tab-width: 8; c-basic-offset: 4; indent-tabs-mode: t; -*- */

/* cairo - a vector graphics library with display and print output

 *

 * Copyright © 2002 University of Southern California

 * Copyright © 2005 Red Hat, Inc.

 *

 * This library is free software; you can redistribute it and/or

 * modify it either under the terms of the GNU Lesser General Public

 * License version 2.1 as published by the Free Software Foundation

 * (the "LGPL") or, at your option, under the terms of the Mozilla

 * Public License Version 1.1 (the "MPL"). If you do not alter this

 * notice, a recipient may use your version of this file under either

 * the MPL or the LGPL.

 *

 * You should have received a copy of the LGPL along with this library

 * in the file COPYING-LGPL-2.1; if not, write to the Free Software

 * Foundation, Inc., 51 Franklin Street, Suite 500, Boston, MA 02110-1335, USA

 * You should have received a copy of the MPL along with this library

 * in the file COPYING-MPL-1.1

 *

 * The contents of this file are subject to the Mozilla Public License

 * Version 1.1 (the "License"); you may not use this file except in

 * compliance with the License. You may obtain a copy of the License at

 * http://www.mozilla.org/MPL/

 *

 * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY

 * OF ANY KIND, either express or implied. See the LGPL or the MPL for

 * the specific language governing rights and limitations.

 *

 * The Original Code is the cairo graphics library.

 *

 * The Initial Developer of the Original Code is University of Southern

 * California.

 *

 * Contributor(s):

 *	Carl D. Worth 

 */

#include "cairoint.h"

#include "cairo-array-private.h"

#include "cairo-clip-inline.h"

#include "cairo-clip-private.h"

#include "cairo-damage-private.h"

#include "cairo-device-private.h"

#include "cairo-error-private.h"

#include "cairo-list-inline.h"

#include "cairo-image-surface-inline.h"

#include "cairo-recording-surface-private.h"

#include "cairo-region-private.h"

#include "cairo-surface-inline.h"

#include "cairo-tee-surface-private.h"

/**

 * SECTION:cairo-surface

 * @Title: cairo_surface_t

 * @Short_Description: Base class for surfaces

 * @See_Also: #cairo_t, #cairo_pattern_t

 *

 * #cairo_surface_t is the abstract type representing all different drawing

 * targets that cairo can render to.  The actual drawings are

 * performed using a cairo context.

 *

 * A cairo surface is created by using backend-specific

 * constructors, typically of the form

 * cairo_backend_surface_create().

 *

 * Most surface types allow accessing the surface without using Cairo

 * functions. If you do this, keep in mind that it is mandatory that you call

 * cairo_surface_flush() before reading from or writing to the surface and that

 * you must use cairo_surface_mark_dirty() after modifying it.

 * 

 * 

 * 

 * void

 * modify_image_surface (cairo_surface_t *surface)

 * {

 *   unsigned char *data;

 *   int width, height, stride;

 *

 *   // flush to ensure all writing to the image was done

 *   cairo_surface_flush (surface);

 *

 *   // modify the image

 *   data = cairo_image_surface_get_data (surface);

 *   width = cairo_image_surface_get_width (surface);

 *   height = cairo_image_surface_get_height (surface);

 *   stride = cairo_image_surface_get_stride (surface);

 *   modify_image_data (data, width, height, stride);

 *

 *   // mark the image dirty so Cairo clears its caches.

 *   cairo_surface_mark_dirty (surface);

 * }

 * 

 * 

 * Note that for other surface types it might be necessary to acquire the

 * surface's device first. See cairo_device_acquire() for a discussion of

 * devices.

 **/

#define DEFINE_NIL_SURFACE(status, name)			\

const cairo_surface_t name = {					\

    NULL,				/* backend */		\

    NULL,				/* device */		\

    CAIRO_SURFACE_TYPE_IMAGE,		/* type */		\

    CAIRO_CONTENT_COLOR,		/* content */		\

    CAIRO_REFERENCE_COUNT_INVALID,	/* ref_count */		\

    status,				/* status */		\

    0,					/* unique id */		\

    0,					/* serial */		\

    NULL,				/* damage */		\

    FALSE,				/* _finishing */	\

    FALSE,				/* finished */		\

    TRUE,				/* is_clear */		\

    FALSE,				/* has_font_options */	\

    FALSE,				/* owns_device */	\

    { 0, 0, 0, NULL, },			/* user_data */		\

    { 0, 0, 0, NULL, },			/* mime_data */         \

    { 1.0, 0.0, 0.0, 1.0, 0.0, 0.0 },   /* device_transform */	\

    { 1.0, 0.0,	0.0, 1.0, 0.0, 0.0 },	/* device_transform_inverse */	\

    { NULL, NULL },			/* device_transform_observers */ \

    0.0,				/* x_resolution */	\

    0.0,				/* y_resolution */	\

    0.0,				/* x_fallback_resolution */	\

    0.0,				/* y_fallback_resolution */	\

    NULL,				/* snapshot_of */	\

    NULL,				/* snapshot_detach */	\

    { NULL, NULL },			/* snapshots */		\

    { NULL, NULL },			/* snapshot */		\

    { CAIRO_ANTIALIAS_DEFAULT,		/* antialias */		\

      CAIRO_SUBPIXEL_ORDER_DEFAULT,	/* subpixel_order */	\

      CAIRO_LCD_FILTER_DEFAULT,		/* lcd_filter */	\

      CAIRO_HINT_STYLE_DEFAULT,		/* hint_style */	\

      CAIRO_HINT_METRICS_DEFAULT,	/* hint_metrics */	\

      CAIRO_ROUND_GLYPH_POS_DEFAULT	/* round_glyph_positions */	\

    }					/* font_options */	\

}

/* XXX error object! */

static DEFINE_NIL_SURFACE(CAIRO_STATUS_NO_MEMORY, _cairo_surface_nil);

static DEFINE_NIL_SURFACE(CAIRO_STATUS_SURFACE_TYPE_MISMATCH, _cairo_surface_nil_surface_type_mismatch);

static DEFINE_NIL_SURFACE(CAIRO_STATUS_INVALID_STATUS, _cairo_surface_nil_invalid_status);

static DEFINE_NIL_SURFACE(CAIRO_STATUS_INVALID_CONTENT, _cairo_surface_nil_invalid_content);

static DEFINE_NIL_SURFACE(CAIRO_STATUS_INVALID_FORMAT, _cairo_surface_nil_invalid_format);

static DEFINE_NIL_SURFACE(CAIRO_STATUS_INVALID_VISUAL, _cairo_surface_nil_invalid_visual);

static DEFINE_NIL_SURFACE(CAIRO_STATUS_FILE_NOT_FOUND, _cairo_surface_nil_file_not_found);

static DEFINE_NIL_SURFACE(CAIRO_STATUS_TEMP_FILE_ERROR, _cairo_surface_nil_temp_file_error);

static DEFINE_NIL_SURFACE(CAIRO_STATUS_READ_ERROR, _cairo_surface_nil_read_error);

static DEFINE_NIL_SURFACE(CAIRO_STATUS_WRITE_ERROR, _cairo_surface_nil_write_error);

static DEFINE_NIL_SURFACE(CAIRO_STATUS_INVALID_STRIDE, _cairo_surface_nil_invalid_stride);

static DEFINE_NIL_SURFACE(CAIRO_STATUS_INVALID_SIZE, _cairo_surface_nil_invalid_size);

static DEFINE_NIL_SURFACE(CAIRO_STATUS_DEVICE_TYPE_MISMATCH, _cairo_surface_nil_device_type_mismatch);

static DEFINE_NIL_SURFACE(CAIRO_STATUS_DEVICE_ERROR, _cairo_surface_nil_device_error);

static DEFINE_NIL_SURFACE(CAIRO_INT_STATUS_UNSUPPORTED, _cairo_surface_nil_unsupported);

static DEFINE_NIL_SURFACE(CAIRO_INT_STATUS_NOTHING_TO_DO, _cairo_surface_nil_nothing_to_do);

static void _cairo_surface_finish_snapshots (cairo_surface_t *surface);

static void _cairo_surface_finish (cairo_surface_t *surface);

/**

 * _cairo_surface_set_error:

 * @surface: a surface

 * @status: a status value indicating an error

 *

 * Atomically sets surface->status to @status and calls _cairo_error;

 * Does nothing if status is %CAIRO_STATUS_SUCCESS or any of the internal

 * status values.

 *

 * All assignments of an error status to surface->status should happen

 * through _cairo_surface_set_error(). Note that due to the nature of

 * the atomic operation, it is not safe to call this function on the

 * nil objects.

 *

 * The purpose of this function is to allow the user to set a

 * breakpoint in _cairo_error() to generate a stack trace for when the

 * user causes cairo to detect an error.

 *

 * Return value: the error status.

 **/

cairo_int_status_t

_cairo_surface_set_error (cairo_surface_t *surface,

			  cairo_int_status_t status)

{

    /* NOTHING_TO_DO is magic. We use it to break out of the inner-most

     * surface function, but anything higher just sees "success".

     */

    if (status == CAIRO_INT_STATUS_NOTHING_TO_DO)

	status = CAIRO_INT_STATUS_SUCCESS;

    if (status == CAIRO_INT_STATUS_SUCCESS ||

        status >= (int)CAIRO_INT_STATUS_LAST_STATUS)

        return status;

    /* Don't overwrite an existing error. This preserves the first

     * error, which is the most significant. */

    _cairo_status_set_error (&surface->status, (cairo_status_t)status);

    return _cairo_error (status);

}

/**

 * cairo_surface_get_type:

 * @surface: a #cairo_surface_t

 *

 * This function returns the type of the backend used to create

 * a surface. See #cairo_surface_type_t for available types.

 *

 * Return value: The type of @surface.

 *

 * Since: 1.2

 **/

cairo_surface_type_t

cairo_surface_get_type (cairo_surface_t *surface)

{

    /* We don't use surface->backend->type here so that some of the

     * special "wrapper" surfaces such as cairo_paginated_surface_t

     * can override surface->type with the type of the "child"

     * surface. */

    return surface->type;

}

/**

 * cairo_surface_get_content:

 * @surface: a #cairo_surface_t

 *

 * This function returns the content type of @surface which indicates

 * whether the surface contains color and/or alpha information. See

 * #cairo_content_t.

 *

 * Return value: The content type of @surface.

 *

 * Since: 1.2

 **/

cairo_content_t

cairo_surface_get_content (cairo_surface_t *surface)

{

    return surface->content;

}

/**

 * cairo_surface_status:

 * @surface: a #cairo_surface_t

 *

 * Checks whether an error has previously occurred for this

 * surface.

 *

 * Return value: %CAIRO_STATUS_SUCCESS, %CAIRO_STATUS_NULL_POINTER,

 * %CAIRO_STATUS_NO_MEMORY, %CAIRO_STATUS_READ_ERROR,

 * %CAIRO_STATUS_INVALID_CONTENT, %CAIRO_STATUS_INVALID_FORMAT, or

 * %CAIRO_STATUS_INVALID_VISUAL.

 *

 * Since: 1.0

 **/

cairo_status_t

cairo_surface_status (cairo_surface_t *surface)

{

    return surface->status;

}

slim_hidden_def (cairo_surface_status);

static unsigned int

_cairo_surface_allocate_unique_id (void)

{

    static cairo_atomic_int_t unique_id;

#if CAIRO_NO_MUTEX

    if (++unique_id == 0)

	unique_id = 1;

    return unique_id;

#else

    cairo_atomic_int_t old, id;

    do {

	old = _cairo_atomic_uint_get (&unique_id);

	id = old + 1;

	if (id == 0)

	    id = 1;

    } while (! _cairo_atomic_uint_cmpxchg (&unique_id, old, id));

    return id;

#endif

}

/**

 * cairo_surface_get_device:

 * @surface: a #cairo_surface_t

 *

 * This function returns the device for a @surface.

 * See #cairo_device_t.

 *

 * Return value: The device for @surface or %NULL if the surface does

 *               not have an associated device.

 *

 * Since: 1.10

 **/

cairo_device_t *

cairo_surface_get_device (cairo_surface_t *surface)

{

    if (unlikely (surface->status))

	return _cairo_device_create_in_error (surface->status);

    return surface->device;

}

static cairo_bool_t

_cairo_surface_has_snapshots (cairo_surface_t *surface)

{

    return ! cairo_list_is_empty (&surface->snapshots);

}

static cairo_bool_t

_cairo_surface_has_mime_data (cairo_surface_t *surface)

{

    return surface->mime_data.num_elements != 0;

}

static void

_cairo_surface_detach_mime_data (cairo_surface_t *surface)

{

    if (! _cairo_surface_has_mime_data (surface))

	return;

    _cairo_user_data_array_fini (&surface->mime_data);

    _cairo_user_data_array_init (&surface->mime_data);

}

static void

_cairo_surface_detach_snapshots (cairo_surface_t *surface)

{

    while (_cairo_surface_has_snapshots (surface)) {

	_cairo_surface_detach_snapshot (cairo_list_first_entry (&surface->snapshots,

								cairo_surface_t,

								snapshot));

    }

}

void

_cairo_surface_detach_snapshot (cairo_surface_t *snapshot)

{

    assert (snapshot->snapshot_of != NULL);

    snapshot->snapshot_of = NULL;

    cairo_list_del (&snapshot->snapshot);

    if (snapshot->snapshot_detach != NULL)

	snapshot->snapshot_detach (snapshot);

    cairo_surface_destroy (snapshot);

}

void

_cairo_surface_attach_snapshot (cairo_surface_t *surface,

				 cairo_surface_t *snapshot,

				 cairo_surface_func_t detach_func)

{

    assert (surface != snapshot);

    assert (snapshot->snapshot_of != surface);

    cairo_surface_reference (snapshot);

    if (snapshot->snapshot_of != NULL)

	_cairo_surface_detach_snapshot (snapshot);

    snapshot->snapshot_of = surface;

    snapshot->snapshot_detach = detach_func;

    cairo_list_add (&snapshot->snapshot, &surface->snapshots);

    assert (_cairo_surface_has_snapshot (surface, snapshot->backend) == snapshot);

}

cairo_surface_t *

_cairo_surface_has_snapshot (cairo_surface_t *surface,

			     const cairo_surface_backend_t *backend)

{

    cairo_surface_t *snapshot;

    cairo_list_foreach_entry (snapshot, cairo_surface_t,

			      &surface->snapshots, snapshot)

    {

	if (snapshot->backend == backend)

	    return snapshot;

    }

    return NULL;

}

cairo_status_t

_cairo_surface_begin_modification (cairo_surface_t *surface)

{

    assert (surface->status == CAIRO_STATUS_SUCCESS);

    assert (! surface->finished);

    return _cairo_surface_flush (surface, 1);

}

void

_cairo_surface_init (cairo_surface_t			*surface,

		     const cairo_surface_backend_t	*backend,

		     cairo_device_t			*device,

		     cairo_content_t			 content)

{

    CAIRO_MUTEX_INITIALIZE ();

    surface->backend = backend;

    surface->device = cairo_device_reference (device);

    surface->content = content;

    surface->type = backend->type;

    CAIRO_REFERENCE_COUNT_INIT (&surface->ref_count, 1);

    surface->status = CAIRO_STATUS_SUCCESS;

    surface->unique_id = _cairo_surface_allocate_unique_id ();

    surface->finished = FALSE;

    surface->_finishing = FALSE;

    surface->is_clear = FALSE;

    surface->serial = 0;

    surface->damage = NULL;

    surface->owns_device = (device != NULL);

    _cairo_user_data_array_init (&surface->user_data);

    _cairo_user_data_array_init (&surface->mime_data);

    cairo_matrix_init_identity (&surface->device_transform);

    cairo_matrix_init_identity (&surface->device_transform_inverse);

    cairo_list_init (&surface->device_transform_observers);

    surface->x_resolution = CAIRO_SURFACE_RESOLUTION_DEFAULT;

    surface->y_resolution = CAIRO_SURFACE_RESOLUTION_DEFAULT;

    surface->x_fallback_resolution = CAIRO_SURFACE_FALLBACK_RESOLUTION_DEFAULT;

    surface->y_fallback_resolution = CAIRO_SURFACE_FALLBACK_RESOLUTION_DEFAULT;

    cairo_list_init (&surface->snapshots);

    surface->snapshot_of = NULL;

    surface->has_font_options = FALSE;

}

static void

_cairo_surface_copy_similar_properties (cairo_surface_t *surface,

					cairo_surface_t *other)

{

    if (other->has_font_options || other->backend != surface->backend) {

	cairo_font_options_t options;

	cairo_surface_get_font_options (other, &options);

	_cairo_surface_set_font_options (surface, &options);

    }

    cairo_surface_set_fallback_resolution (surface,

					   other->x_fallback_resolution,

					   other->y_fallback_resolution);

}

cairo_surface_t *

_cairo_surface_create_similar_scratch (cairo_surface_t *other,

				       cairo_content_t	content,

				       int		width,

				       int		height)

{

    cairo_surface_t *surface;

    if (unlikely (other->status))

	return _cairo_surface_create_in_error (other->status);

    surface = NULL;

    if (other->backend->create_similar)

	surface = other->backend->create_similar (other, content, width, height);

    if (surface == NULL)

	surface = cairo_surface_create_similar_image (other,

						      _cairo_format_from_content (content),

						      width, height);

    if (unlikely (surface->status))

	return surface;

    _cairo_surface_copy_similar_properties (surface, other);

    return surface;

}

/**

 * cairo_surface_create_similar:

 * @other: an existing surface used to select the backend of the new surface

 * @content: the content for the new surface

 * @width: width of the new surface, (in device-space units)

 * @height: height of the new surface (in device-space units)

 *

 * Create a new surface that is as compatible as possible with an

 * existing surface. For example the new surface will have the same

 * fallback resolution and font options as @other. Generally, the new

 * surface will also use the same backend as @other, unless that is

 * not possible for some reason. The type of the returned surface may

 * be examined with cairo_surface_get_type().

 *

 * Initially the surface contents are all 0 (transparent if contents

 * have transparency, black otherwise.)

 *

 * Use cairo_surface_create_similar_image() if you need an image surface

 * which can be painted quickly to the target surface.

 *

 * Return value: a pointer to the newly allocated surface. The caller

 * owns the surface and should call cairo_surface_destroy() when done

 * with it.

 *

 * This function always returns a valid pointer, but it will return a

 * pointer to a "nil" surface if @other is already in an error state

 * or any other error occurs.

 *

 * Since: 1.0

 **/

cairo_surface_t *

cairo_surface_create_similar (cairo_surface_t  *other,

			      cairo_content_t	content,

			      int		width,

			      int		height)

{

    cairo_surface_t *surface;

    if (unlikely (other->status))

	return _cairo_surface_create_in_error (other->status);

    if (unlikely (other->finished))

	return _cairo_surface_create_in_error (CAIRO_STATUS_SURFACE_FINISHED);

    if (unlikely (width < 0 || height < 0))

	return _cairo_surface_create_in_error (CAIRO_STATUS_INVALID_SIZE);

    if (unlikely (! CAIRO_CONTENT_VALID (content)))

	return _cairo_surface_create_in_error (CAIRO_STATUS_INVALID_CONTENT);

    surface = _cairo_surface_create_similar_solid (other,

						   content, width, height,

						   CAIRO_COLOR_TRANSPARENT);

    assert (surface->is_clear);

    return surface;

}

/**

 * cairo_surface_create_similar_image:

 * @other: an existing surface used to select the preference of the new surface

 * @format: the format for the new surface

 * @width: width of the new surface, (in device-space units)

 * @height: height of the new surface (in device-space units)

 *

 * Create a new image surface that is as compatible as possible for uploading

 * to and the use in conjunction with an existing surface. However, this surface

 * can still be used like any normal image surface.

 *

 * Initially the surface contents are all 0 (transparent if contents

 * have transparency, black otherwise.)

 *

 * Use cairo_surface_create_similar() if you don't need an image surface.

 *

 * Return value: a pointer to the newly allocated image surface. The caller

 * owns the surface and should call cairo_surface_destroy() when done

 * with it.

 *

 * This function always returns a valid pointer, but it will return a

 * pointer to a "nil" surface if @other is already in an error state

 * or any other error occurs.

 *

 * Since: 1.12

 **/

cairo_surface_t *

cairo_surface_create_similar_image (cairo_surface_t  *other,

				    cairo_format_t    format,

				    int		width,

				    int		height)

{

    cairo_surface_t *image;

    if (unlikely (other->status))

	return _cairo_surface_create_in_error (other->status);

    if (unlikely (other->finished))

	return _cairo_surface_create_in_error (CAIRO_STATUS_SURFACE_FINISHED);

    if (unlikely (width < 0 || height < 0))

	return _cairo_surface_create_in_error (CAIRO_STATUS_INVALID_SIZE);

    if (unlikely (! CAIRO_FORMAT_VALID (format)))

	return _cairo_surface_create_in_error (CAIRO_STATUS_INVALID_FORMAT);

    image = NULL;

    if (other->backend->create_similar_image)

	image = other->backend->create_similar_image (other,

						      format, width, height);

    if (image == NULL)

	image = cairo_image_surface_create (format, width, height);

    assert (image->is_clear);

    return image;

}

slim_hidden_def (cairo_surface_create_similar_image);

/**

 * _cairo_surface_map_to_image:

 * @surface: an existing surface used to extract the image from

 * @extents: limit the extraction to an rectangular region

 *

 * Returns an image surface that is the most efficient mechanism for

 * modifying the backing store of the target surface. The region

 * retrieved is limited to @extents.

 *

 * Note, the use of the original surface as a target or source whilst

 * it is mapped is undefined. The result of mapping the surface

 * multiple times is undefined. Calling cairo_surface_destroy() or

 * cairo_surface_finish() on the resulting image surface results in

 * undefined behavior. Changing the device transform of the image

 * surface or of @surface before the image surface is unmapped results

 * in undefined behavior.

 *

 * Assumes that @surface is valid (CAIRO_STATUS_SUCCESS,

 * non-finished).

 *

 * Return value: a pointer to the newly allocated image surface. The

 * caller must use _cairo_surface_unmap_image() to destroy this image

 * surface.

 *

 * This function always returns a valid pointer, but it will return a

 * pointer to a "nil" surface if @other is already in an error state

 * or any other error occurs.

 *

 * The returned image might have a %CAIRO_FORMAT_INVALID format.

 **/

cairo_image_surface_t *

_cairo_surface_map_to_image (cairo_surface_t  *surface,

			     const cairo_rectangle_int_t *extents)

{

    cairo_image_surface_t *image = NULL;

    assert (extents != NULL);

    /* TODO: require map_to_image != NULL */

    if (surface->backend->map_to_image)

	image = surface->backend->map_to_image (surface, extents);

    if (image == NULL)

	image = _cairo_image_surface_clone_subimage (surface, extents);

    return image;

}

/**

 * _cairo_surface_unmap_image:

 * @surface: the surface passed to _cairo_surface_map_to_image().

 * @image: the currently mapped image

 *

 * Unmaps the image surface as returned from

 * _cairo_surface_map_to_image().

 *

 * The content of the image will be uploaded to the target surface.

 * Afterwards, the image is destroyed.

 *

 * Using an image surface which wasn't returned by

 * _cairo_surface_map_to_image() results in undefined behavior.

 *

 * An image surface in error status can be passed to

 * _cairo_surface_unmap_image().

 *

 * Return value: the unmap status.

 *

 * Even if the unmap status is not successful, @image is destroyed.

 **/

cairo_int_status_t

_cairo_surface_unmap_image (cairo_surface_t       *surface,

			    cairo_image_surface_t *image)

{

    cairo_surface_pattern_t pattern;

    cairo_rectangle_int_t extents;

    cairo_clip_t *clip;

    cairo_int_status_t status;

    /* map_to_image can return error surfaces */

    if (unlikely (image->base.status)) {

	status = image->base.status;

	goto destroy;

    }

    /* If the image is untouched just skip the update */

    if (image->base.serial == 0) {

	status = CAIRO_STATUS_SUCCESS;

	goto destroy;

    }

    /* TODO: require unmap_image != NULL */

    if (surface->backend->unmap_image &&

	! _cairo_image_surface_is_clone (image))

    {

	status = surface->backend->unmap_image (surface, image);

	if (status != CAIRO_INT_STATUS_UNSUPPORTED)

	    return status;

    }

    _cairo_pattern_init_for_surface (&pattern, &image->base);

    pattern.base.filter = CAIRO_FILTER_NEAREST;

    /* We have to apply the translate from map_to_image's extents.x and .y */

    cairo_matrix_init_translate (&pattern.base.matrix,

				 image->base.device_transform.x0,

				 image->base.device_transform.y0);

    /* And we also have to clip the operation to the image's extents */

    extents.x = image->base.device_transform_inverse.x0;

    extents.y = image->base.device_transform_inverse.y0;

    extents.width  = image->width;

    extents.height = image->height;

    clip = _cairo_clip_intersect_rectangle (NULL, &extents);

    status = _cairo_surface_paint (surface,

				   CAIRO_OPERATOR_SOURCE,

				   &pattern.base,

				   clip);

    _cairo_pattern_fini (&pattern.base);

    _cairo_clip_destroy (clip);

destroy:

    cairo_surface_finish (&image->base);

    cairo_surface_destroy (&image->base);

    return status;

}

/**

 * cairo_surface_map_to_image:

 * @surface: an existing surface used to extract the image from

 * @extents: limit the extraction to an rectangular region

 *

 * Returns an image surface that is the most efficient mechanism for

 * modifying the backing store of the target surface. The region retrieved

 * may be limited to the @extents or %NULL for the whole surface

 *

 * Note, the use of the original surface as a target or source whilst

 * it is mapped is undefined. The result of mapping the surface

 * multiple times is undefined. Calling cairo_surface_destroy() or

 * cairo_surface_finish() on the resulting image surface results in

 * undefined behavior. Changing the device transform of the image

 * surface or of @surface before the image surface is unmapped results

 * in undefined behavior.

 *

 * Return value: a pointer to the newly allocated image surface. The caller

 * must use cairo_surface_unmap_image() to destroy this image surface.

 *

 * This function always returns a valid pointer, but it will return a

 * pointer to a "nil" surface if @other is already in an error state

 * or any other error occurs. If the returned pointer does not have an

 * error status, it is guaranteed to be an image surface whose format

 * is not %CAIRO_FORMAT_INVALID.

 *

 * Since: 1.12

 **/

cairo_surface_t *

cairo_surface_map_to_image (cairo_surface_t  *surface,

			    const cairo_rectangle_int_t *extents)

{

    cairo_rectangle_int_t rect;

    cairo_image_surface_t *image;

    cairo_status_t status;

    if (unlikely (surface->status))

	return _cairo_surface_create_in_error (surface->status);

    if (unlikely (surface->finished))

	return _cairo_surface_create_in_error (CAIRO_STATUS_SURFACE_FINISHED);

    if (extents == NULL) {

	if (unlikely (! surface->backend->get_extents (surface, &rect)))

	    return _cairo_surface_create_in_error (CAIRO_STATUS_INVALID_SIZE);

	extents = ▭

    } else {

	cairo_rectangle_int_t surface_extents;

	/* If this surface is bounded, we can't map parts

	 * that are outside of it. */

	if (likely (surface->backend->get_extents (surface, &surface_extents))) {

	    if (unlikely (! _cairo_rectangle_contains_rectangle (&surface_extents, extents)))

		return _cairo_surface_create_in_error (CAIRO_STATUS_INVALID_SIZE);

	}

    }

    image = _cairo_surface_map_to_image (surface, extents);

    status = image->base.status;

    if (unlikely (status)) {

	cairo_surface_destroy (&image->base);

	return _cairo_surface_create_in_error (status);

    }

    if (image->format == CAIRO_FORMAT_INVALID) {

	cairo_surface_destroy (&image->base);

	image = _cairo_image_surface_clone_subimage (surface, extents);

    }

    return &image->base;

}

/**

 * cairo_surface_unmap_image:

 * @surface: the surface passed to cairo_surface_map_to_image().

 * @image: the currently mapped image

 *

 * Unmaps the image surface as returned from #cairo_surface_map_to_image().

 *

 * The content of the image will be uploaded to the target surface.

 * Afterwards, the image is destroyed.

 *

 * Using an image surface which wasn't returned by cairo_surface_map_to_image()

 * results in undefined behavior.

 *

 * Since: 1.12

 **/

void

cairo_surface_unmap_image (cairo_surface_t *surface,

			   cairo_surface_t *image)

{

    cairo_int_status_t status = CAIRO_STATUS_SUCCESS;

    if (unlikely (surface->status)) {

	status = surface->status;

	goto error;

    }

    if (unlikely (surface->finished)) {

	status = _cairo_error (CAIRO_STATUS_SURFACE_FINISHED);

	goto error;

    }

    if (unlikely (image->status)) {

	status = image->status;

	goto error;

    }

    if (unlikely (image->finished)) {

	status = _cairo_error (CAIRO_STATUS_SURFACE_FINISHED);

	goto error;

    }

    if (unlikely (! _cairo_surface_is_image (image))) {

	status = _cairo_error (CAIRO_STATUS_SURFACE_TYPE_MISMATCH);

	goto error;

    }

    status = _cairo_surface_unmap_image (surface,

					 (cairo_image_surface_t *) image);

    if (unlikely (status))

	_cairo_surface_set_error (surface, status);

    return;

error:

    _cairo_surface_set_error (surface, status);

    cairo_surface_finish (image);

    cairo_surface_destroy (image);

}

cairo_surface_t *

_cairo_surface_create_similar_solid (cairo_surface_t	 *other,

				     cairo_content_t	  content,

				     int		  width,

				     int		  height,

				     const cairo_color_t *color)

{

    cairo_status_t status;

    cairo_surface_t *surface;

    cairo_solid_pattern_t pattern;

    surface = _cairo_surface_create_similar_scratch (other, content,

						     width, height);

    if (unlikely (surface->status))

	return surface;

    _cairo_pattern_init_solid (&pattern, color);

    status = _cairo_surface_paint (surface,

				   color == CAIRO_COLOR_TRANSPARENT ?

				   CAIRO_OPERATOR_CLEAR : CAIRO_OPERATOR_SOURCE,

				   &pattern.base, NULL);

    if (unlikely (status)) {

	cairo_surface_destroy (surface);

	surface = _cairo_surface_create_in_error (status);

    }

    return surface;

}

/**

 * cairo_surface_reference:

 * @surface: a #cairo_surface_t

 *

 * Increases the reference count on @surface by one. This prevents

 * @surface from being destroyed until a matching call to

 * cairo_surface_destroy() is made.

 *

 * The number of references to a #cairo_surface_t can be get using

 * cairo_surface_get_reference_count().

 *

 * Return value: the referenced #cairo_surface_t.

 *

 * Since: 1.0

 **/

cairo_surface_t *

cairo_surface_reference (cairo_surface_t *surface)

{

    if (surface == NULL ||

	    CAIRO_REFERENCE_COUNT_IS_INVALID (&surface->ref_count))

	return surface;

    assert (CAIRO_REFERENCE_COUNT_HAS_REFERENCE (&surface->ref_count));

    _cairo_reference_count_inc (&surface->ref_count);

    return surface;

}

slim_hidden_def (cairo_surface_reference);

/**

 * cairo_surface_destroy:

 * @surface: a #cairo_surface_t

 *

 * Decreases the reference count on @surface by one. If the result is

 * zero, then @surface and all associated resources are freed.  See

 * cairo_surface_reference().

 *

 * Since: 1.0

 **/

void

cairo_surface_destroy (cairo_surface_t *surface)

{

    if (surface == NULL ||

	    CAIRO_REFERENCE_COUNT_IS_INVALID (&surface->ref_count))

	return;

    assert (CAIRO_REFERENCE_COUNT_HAS_REFERENCE (&surface->ref_count));

    if (! _cairo_reference_count_dec_and_test (&surface->ref_count))

	return;

    assert (surface->snapshot_of == NULL);

    if (! surface->finished) {

	_cairo_surface_finish_snapshots (surface);

	/* We may have been referenced by a snapshot prior to have

	 * detaching it with the copy-on-write.

	 */

	if (CAIRO_REFERENCE_COUNT_GET_VALUE (&surface->ref_count))

	    return;

	_cairo_surface_finish (surface);

    }

    if (surface->damage)

	_cairo_damage_destroy (surface->damage);

    _cairo_user_data_array_fini (&surface->user_data);

    _cairo_user_data_array_fini (&surface->mime_data);

    if (surface->owns_device)

        cairo_device_destroy (surface->device);

    assert (surface->snapshot_of == NULL);

    assert (! _cairo_surface_has_snapshots (surface));

    /* paranoid check that nobody took a reference whilst finishing */

    assert (! CAIRO_REFERENCE_COUNT_HAS_REFERENCE (&surface->ref_count));

    free (surface);

}

slim_hidden_def(cairo_surface_destroy);

/**

 * cairo_surface_get_reference_count:

 * @surface: a #cairo_surface_t

 *

 * Returns the current reference count of @surface.

 *

 * Return value: the current reference count of @surface.  If the

 * object is a nil object, 0 will be returned.

 *

 * Since: 1.4

 **/

unsigned int

cairo_surface_get_reference_count (cairo_surface_t *surface)

{

    if (surface == NULL ||

	    CAIRO_REFERENCE_COUNT_IS_INVALID (&surface->ref_count))

	return 0;

    return CAIRO_REFERENCE_COUNT_GET_VALUE (&surface->ref_count);

}

static void

_cairo_surface_finish_snapshots (cairo_surface_t *surface)

{

    cairo_status_t status;

    /* update the snapshots *before* we declare the surface as finished */

    surface->_finishing = TRUE;

    status = _cairo_surface_flush (surface, 0);

    (void) status;

}

static void

_cairo_surface_finish (cairo_surface_t *surface)

{

    cairo_status_t status;

    surface->finished = TRUE;

    /* call finish even if in error mode */

    if (surface->backend->finish) {

	status = surface->backend->finish (surface);

	if (unlikely (status))

	    _cairo_surface_set_error (surface, status);

    }

    assert (surface->snapshot_of == NULL);

    assert (!_cairo_surface_has_snapshots (surface));

}

/**

 * cairo_surface_finish:

 * @surface: the #cairo_surface_t to finish

 *

 * This function finishes the surface and drops all references to

 * external resources.  For example, for the Xlib backend it means

 * that cairo will no longer access the drawable, which can be freed.

 * After calling cairo_surface_finish() the only valid operations on a

 * surface are getting and setting user, referencing and

 * destroying, and flushing and finishing it.

 * Further drawing to the surface will not affect the

 * surface but will instead trigger a %CAIRO_STATUS_SURFACE_FINISHED

 * error.

 *

 * When the last call to cairo_surface_destroy() decreases the

 * reference count to zero, cairo will call cairo_surface_finish() if

 * it hasn't been called already, before freeing the resources

 * associated with the surface.

 *

 * Since: 1.0

 **/

void

cairo_surface_finish (cairo_surface_t *surface)

{

    if (surface == NULL)

	return;

    if (CAIRO_REFERENCE_COUNT_IS_INVALID (&surface->ref_count))

	return;

    if (surface->finished)

	return;

    /* We have to be careful when decoupling potential reference cycles */

    cairo_surface_reference (surface);

    _cairo_surface_finish_snapshots (surface);

    /* XXX need to block and wait for snapshot references */

    _cairo_surface_finish (surface);

    cairo_surface_destroy (surface);

}

slim_hidden_def (cairo_surface_finish);

/**

 * _cairo_surface_release_device_reference:

 * @surface: a #cairo_surface_t

 *

 * This function makes @surface release the reference to its device. The

 * function is intended to be used for avoiding cycling references for

 * surfaces that are owned by their device, for example cache surfaces.

 * Note that the @surface will still assume that the device is available.

 * So it is the caller's responsibility to ensure the device stays around

 * until the @surface is destroyed. Just calling cairo_surface_finish() is

 * not enough.

 **/

void

_cairo_surface_release_device_reference (cairo_surface_t *surface)

{

    assert (surface->owns_device);

    cairo_device_destroy (surface->device);

    surface->owns_device = FALSE;

}

/**

 * cairo_surface_get_user_data:

 * @surface: a #cairo_surface_t

 * @key: the address of the #cairo_user_data_key_t the user data was

 * attached to

 *

 * Return user data previously attached to @surface using the specified

 * key.  If no user data has been attached with the given key this

 * function returns %NULL.

 *

 * Return value: the user data previously attached or %NULL.

 *

 * Since: 1.0

 **/

void *

cairo_surface_get_user_data (cairo_surface_t		 *surface,

			     const cairo_user_data_key_t *key)

{

    /* Prevent reads of the array during teardown */

    if (! CAIRO_REFERENCE_COUNT_HAS_REFERENCE (&surface->ref_count))

	return NULL;

    return _cairo_user_data_array_get_data (&surface->user_data, key);

}

/**

 * cairo_surface_set_user_data:

 * @surface: a #cairo_surface_t

 * @key: the address of a #cairo_user_data_key_t to attach the user data to

 * @user_data: the user data to attach to the surface

 * @destroy: a #cairo_destroy_func_t which will be called when the

 * surface is destroyed or when new user data is attached using the

 * same key.

 *

 * Attach user data to @surface.  To remove user data from a surface,