/* -*- Mode: c; tab-width: 8; c-basic-offset: 4; indent-tabs-mode: t; -*- */
/* cairo - a vector graphics library with display and print output
*
* Copyright © 2011 Intel Corporation
*
* 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 Red Hat, Inc.
*
* Contributor(s):
* Chris Wilson <chris@chris-wilson.co.uk>
*/
#include "cairoint.h"
#include "cairo-error-private.h"
#include "cairo-pattern-private.h"
/**
* SECTION:cairo-raster-source
* @Title: Raster Sources
* @Short_Description: Supplying arbitrary image data
* @See_Also: #cairo_pattern_t
*
* The raster source provides the ability to supply arbitrary pixel data
* whilst rendering. The pixels are queried at the time of rasterisation
* by means of user callback functions, allowing for the ultimate
* flexibility. For example, in handling compressed image sources, you
* may keep a MRU cache of decompressed images and decompress sources on the
* fly and discard old ones to conserve memory.
*
* For the raster source to be effective, you must at least specify
* the acquire and release callbacks which are used to retrieve the pixel
* data for the region of interest and demark when it can be freed afterwards.
* Other callbacks are provided for when the pattern is copied temporarily
* during rasterisation, or more permanently as a snapshot in order to keep
* the pixel data available for printing.
**/
cairo_surface_t *
_cairo_raster_source_pattern_acquire (
const cairo_pattern_t *abstract_pattern,
cairo_surface_t *target,
const cairo_rectangle_int_t *extents)
{
cairo_raster_source_pattern_t *pattern =
(cairo_raster_source_pattern_t *) abstract_pattern;
if (pattern->acquire == NULL)
return NULL;
if (extents == NULL)
extents = &pattern->extents;
return pattern->acquire (&pattern->base, pattern->user_data,
target, extents);
}
void
_cairo_raster_source_pattern_release (
const cairo_pattern_t *abstract_pattern,
cairo_surface_t *surface)
{
cairo_raster_source_pattern_t *pattern =
(cairo_raster_source_pattern_t *) abstract_pattern;
if (pattern->release == NULL)
return;
pattern->release (&pattern->base, pattern->user_data, surface);
}
cairo_status_t
_cairo_raster_source_pattern_init_copy (cairo_pattern_t *abstract_pattern,
const cairo_pattern_t *other)
{
cairo_raster_source_pattern_t *pattern =
(cairo_raster_source_pattern_t *) abstract_pattern;
cairo_status_t status;
VG (VALGRIND_MAKE_MEM_UNDEFINED (pattern,
sizeof (cairo_raster_source_pattern_t)));
memcpy(pattern, other,
sizeof (cairo_raster_source_pattern_t));
status = CAIRO_STATUS_SUCCESS;
if (pattern->copy)
status = pattern->copy (&pattern->base, pattern->user_data, other);
return status;
}
cairo_status_t
_cairo_raster_source_pattern_snapshot (cairo_pattern_t *abstract_pattern)
{
cairo_raster_source_pattern_t *pattern =
(cairo_raster_source_pattern_t *) abstract_pattern;
if (pattern->snapshot == NULL)
return CAIRO_STATUS_SUCCESS;
return pattern->snapshot (&pattern->base, pattern->user_data);
}
void
_cairo_raster_source_pattern_finish (cairo_pattern_t *abstract_pattern)
{
cairo_raster_source_pattern_t *pattern =
(cairo_raster_source_pattern_t *) abstract_pattern;
if (pattern->finish == NULL)
return;
pattern->finish (&pattern->base, pattern->user_data);
}
/* Public interface */
/**
* cairo_pattern_create_raster_source:
* @user_data: the user data to be passed to all callbacks
* @content: content type for the pixel data that will be returned. Knowing
* the content type ahead of time is used for analysing the operation and
* picking the appropriate rendering path.
* @width: maximum size of the sample area
* @height: maximum size of the sample area
*
* Creates a new user pattern for providing pixel data.
*
* Use the setter functions to associate callbacks with the returned
* pattern. The only mandatory callback is acquire.
*
* Return value: a newly created #cairo_pattern_t. Free with
* cairo_pattern_destroy() when you are done using it.
*
* Since: 1.12
**/
cairo_pattern_t *
cairo_pattern_create_raster_source (
void *user_data,
cairo_content_t content,
int width,
int height)
{
cairo_raster_source_pattern_t *pattern;
CAIRO_MUTEX_INITIALIZE ();
if (width < 0 || height < 0)
return _cairo_pattern_create_in_error (CAIRO_STATUS_INVALID_SIZE);
if (! CAIRO_CONTENT_VALID (content))
return _cairo_pattern_create_in_error (CAIRO_STATUS_INVALID_CONTENT);
pattern = calloc (1,
sizeof (*pattern));
if (unlikely (pattern == NULL))
return _cairo_pattern_create_in_error (CAIRO_STATUS_NO_MEMORY);
_cairo_pattern_init (&pattern->base,
CAIRO_PATTERN_TYPE_RASTER_SOURCE);
CAIRO_REFERENCE_COUNT_INIT (&pattern->base.ref_count, 1);
pattern->content = content;
pattern->extents.x = 0;
pattern->extents.y = 0;
pattern->extents.width = width;
pattern->extents.height = height;
pattern->user_data = user_data;
return &pattern->base;
}
/**
* cairo_raster_source_pattern_set_callback_data:
* @pattern: the pattern to update
* @data: the user data to be passed to all callbacks
*
* Updates the user data that is provided to all callbacks.
*
* Since: 1.12
**/
void
cairo_raster_source_pattern_set_callback_data (cairo_pattern_t *abstract_pattern,
void *data)
{
cairo_raster_source_pattern_t *pattern;
if (abstract_pattern->type != CAIRO_PATTERN_TYPE_RASTER_SOURCE)
return;
pattern = (cairo_raster_source_pattern_t *) abstract_pattern;
pattern->user_data = data;
}
/**
* cairo_raster_source_pattern_get_callback_data:
* @pattern: the pattern to update
*
* Queries the current user data.
*
* Return value: the current user-data passed to each callback
*
* Since: 1.12
**/
void *
cairo_raster_source_pattern_get_callback_data (cairo_pattern_t *abstract_pattern)
{
cairo_raster_source_pattern_t *pattern;
if (abstract_pattern->type != CAIRO_PATTERN_TYPE_RASTER_SOURCE)
return NULL;
pattern = (cairo_raster_source_pattern_t *) abstract_pattern;
return pattern->user_data;
}
/**
* cairo_raster_source_pattern_set_acquire:
* @pattern: the pattern to update
* @acquire: acquire callback
* @release: release callback
*
* Specifies the callbacks used to generate the image surface for a rendering
* operation (acquire) and the function used to cleanup that surface afterwards.
*
* The @acquire callback should create a surface (preferably an image
* surface created to match the target using
* cairo_surface_create_similar_image()) that defines at least the region
* of interest specified by extents. The surface is allowed to be the entire
* sample area, but if it does contain a subsection of the sample area,
* the surface extents should be provided by setting the device offset (along
* with its width and height) using cairo_surface_set_device_offset().
*
* Since: 1.12
**/
void
cairo_raster_source_pattern_set_acquire (cairo_pattern_t *abstract_pattern,
cairo_raster_source_acquire_func_t acquire,
cairo_raster_source_release_func_t release)
{
cairo_raster_source_pattern_t *pattern;
if (abstract_pattern->type != CAIRO_PATTERN_TYPE_RASTER_SOURCE)
return;
pattern = (cairo_raster_source_pattern_t *) abstract_pattern;
pattern->acquire = acquire;
pattern->release = release;
}
/**
* cairo_raster_source_pattern_get_acquire:
* @pattern: the pattern to query
* @acquire: return value for the current acquire callback
* @release: return value for the current release callback
*
* Queries the current acquire and release callbacks.
*
* Since: 1.12
**/
void
cairo_raster_source_pattern_get_acquire (cairo_pattern_t *abstract_pattern,
cairo_raster_source_acquire_func_t *acquire,
cairo_raster_source_release_func_t *release)
{
cairo_raster_source_pattern_t *pattern;
if (abstract_pattern->type != CAIRO_PATTERN_TYPE_RASTER_SOURCE)
return;
pattern = (cairo_raster_source_pattern_t *) abstract_pattern;
if (acquire)
*acquire = pattern->acquire;
if (release)
*release = pattern->release;
}
/**
* cairo_raster_source_pattern_set_snapshot:
* @pattern: the pattern to update
* @snapshot: snapshot callback
*
* Sets the callback that will be used whenever a snapshot is taken of the
* pattern, that is whenever the current contents of the pattern should be
* preserved for later use. This is typically invoked whilst printing.
*
* Since: 1.12
**/
void
cairo_raster_source_pattern_set_snapshot (cairo_pattern_t *abstract_pattern,
cairo_raster_source_snapshot_func_t snapshot)
{
cairo_raster_source_pattern_t *pattern;
if (abstract_pattern->type != CAIRO_PATTERN_TYPE_RASTER_SOURCE)
return;
pattern = (cairo_raster_source_pattern_t *) abstract_pattern;
pattern->snapshot = snapshot;
}
/**
* cairo_raster_source_pattern_get_snapshot:
* @pattern: the pattern to query
*
* Queries the current snapshot callback.
*
* Return value: the current snapshot callback
*
* Since: 1.12
**/
cairo_raster_source_snapshot_func_t
cairo_raster_source_pattern_get_snapshot (cairo_pattern_t *abstract_pattern)
{
cairo_raster_source_pattern_t *pattern;
if (abstract_pattern->type != CAIRO_PATTERN_TYPE_RASTER_SOURCE)
return NULL;
pattern = (cairo_raster_source_pattern_t *) abstract_pattern;
return pattern->snapshot;
}
/**
* cairo_raster_source_pattern_set_copy:
* @pattern: the pattern to update
* @copy: the copy callback
*
* Updates the copy callback which is used whenever a temporary copy of the
* pattern is taken.
*
* Since: 1.12
**/
void
cairo_raster_source_pattern_set_copy (cairo_pattern_t *abstract_pattern,
cairo_raster_source_copy_func_t copy)
{
cairo_raster_source_pattern_t *pattern;
if (abstract_pattern->type != CAIRO_PATTERN_TYPE_RASTER_SOURCE)
return;
pattern = (cairo_raster_source_pattern_t *) abstract_pattern;
pattern->copy = copy;
}
/**
* cairo_raster_source_pattern_get_copy:
* @pattern: the pattern to query
*
* Queries the current copy callback.
*
* Return value: the current copy callback
*
* Since: 1.12
**/
cairo_raster_source_copy_func_t
cairo_raster_source_pattern_get_copy (cairo_pattern_t *abstract_pattern)
{
cairo_raster_source_pattern_t *pattern;
if (abstract_pattern->type != CAIRO_PATTERN_TYPE_RASTER_SOURCE)
return NULL;
pattern = (cairo_raster_source_pattern_t *) abstract_pattern;
return pattern->copy;
}
/**
* cairo_raster_source_pattern_set_finish:
* @pattern: the pattern to update
* @finish: the finish callback
*
* Updates the finish callback which is used whenever a pattern (or a copy
* thereof) will no longer be used.
*
* Since: 1.12
**/
void
cairo_raster_source_pattern_set_finish (cairo_pattern_t *abstract_pattern,
cairo_raster_source_finish_func_t finish)
{
cairo_raster_source_pattern_t *pattern;
if (abstract_pattern->type != CAIRO_PATTERN_TYPE_RASTER_SOURCE)
return;
pattern = (cairo_raster_source_pattern_t *) abstract_pattern;
pattern->finish = finish;
}
/**
* cairo_raster_source_pattern_get_finish:
* @pattern: the pattern to query
*
* Queries the current finish callback.
*
* Return value: the current finish callback
*
* Since: 1.12
**/
cairo_raster_source_finish_func_t
cairo_raster_source_pattern_get_finish (cairo_pattern_t *abstract_pattern)
{
cairo_raster_source_pattern_t *pattern;
if (abstract_pattern->type != CAIRO_PATTERN_TYPE_RASTER_SOURCE)
return NULL;
pattern = (cairo_raster_source_pattern_t *) abstract_pattern;
return pattern->finish;
}
