fdo-mirrors/cairo
1
0
Fork 0
mirror of https://gitlab.freedesktop.org/cairo/cairo.git synced 2026-05-04 23:28:07 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

doc: Add documentation for cairo_raster_source_pattern

Browse source 
Signed-off-by: Chris Wilson <chris@chris-wilson.co.uk>
This commit is contained in:
Chris Wilson 2011-12-07 13:14:58 +00:00
parent cff0097954
commit 98335b4390
3 changed files with 241 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

20
doc/public/cairo-sections.txt
View file

@ -322,6 +322,26 @@ cairo_pattern_set_user_data
cairo_pattern_get_user_data
</SECTION>
<SECTION>
<FILE>cairo-raster-source</FILE>
cairo_pattern_create_raster_source
cairo_raster_source_pattern_set_callback_data
cairo_raster_source_pattern_get_callback_data
cairo_raster_source_pattern_set_acquire
cairo_raster_source_pattern_get_acquire
cairo_raster_source_pattern_set_snapshot
cairo_raster_source_pattern_get_snapshot
cairo_raster_source_pattern_set_copy
cairo_raster_source_pattern_get_copy
cairo_raster_source_pattern_set_finish
cairo_raster_source_pattern_get_finish
cairo_raster_source_acquire_func_t
cairo_raster_source_release_func_t
cairo_raster_source_snapshot_func_t
cairo_raster_source_copy_func_t
cairo_raster_source_finish_func_t
</SECTION>
<SECTION>
<FILE>cairo-matrix</FILE>
cairo_matrix_t

151
src/cairo-raster-source-pattern.c
View file

@ -38,6 +38,29 @@
#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.
*
* Since: 1.12
**/
cairo_surface_t *
_cairo_raster_source_pattern_acquire (const cairo_pattern_t *abstract_pattern,
cairo_surface_t *target,
@ -112,6 +135,27 @@ _cairo_raster_source_pattern_finish (cairo_pattern_t *abstract_pattern)
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,
@ -147,6 +191,15 @@ cairo_pattern_create_raster_source (void *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)
@ -160,6 +213,14 @@ cairo_raster_source_pattern_set_callback_data (cairo_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.
*
* Since: 1.12
**/
void *
cairo_raster_source_pattern_get_callback_data (cairo_pattern_t *abstract_pattern)
{
@ -172,6 +233,25 @@ cairo_raster_source_pattern_get_callback_data (cairo_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,
@ -187,6 +267,16 @@ cairo_raster_source_pattern_set_acquire (cairo_pattern_t *abstract_pattern,
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,
@ -204,6 +294,17 @@ cairo_raster_source_pattern_get_acquire (cairo_pattern_t *abstract_pattern,
*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)
@ -217,6 +318,16 @@ cairo_raster_source_pattern_set_snapshot (cairo_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)
{
@ -229,6 +340,16 @@ cairo_raster_source_pattern_get_snapshot (cairo_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)
@ -242,6 +363,16 @@ cairo_raster_source_pattern_set_copy (cairo_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)
{
@ -254,6 +385,16 @@ cairo_raster_source_pattern_get_copy (cairo_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)
@ -267,6 +408,16 @@ cairo_raster_source_pattern_set_finish (cairo_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)
{

70
src/cairo.h
View file

@ -2479,26 +2479,96 @@ cairo_recording_surface_get_extents (cairo_surface_t *surface,
/* raster-source pattern (callback) functions */
/**
* cairo_raster_source_acquire_func_t:
* @pattern: the pattern being rendered from
* @callback_data: the user data supplied during creation
* @target: the rendering target surface
* @extents: rectangular region of interest in pixels in sample space
*
* #cairo_raster_source_acquire_func_t is the type of function which is
* called when a pattern is being rendered from. It should create a surface
* that provides the pixel data for the region of interest as defined by
* extents, though the surface itself does not have to be limited to that
* area. For convenience the surface should probably be of image type,
* created with cairo_surface_create_similar_image() for the target (which
* enables the number of copies to be reduced during transfer to the
* device). Anothjr option, might be to return a similar surface to the
* target for explicit handling by the application of a set of cached sources
* on the device. The region of sample data provided should be defined using
* cairo_surface_set_device_offset() to specify the top-left corner of the
* sample data (along with width and height of the surface).
*
* Returns: a #cairo_surface_t
*
* Since: 1.12
**/
typedef cairo_surface_t *
(*cairo_raster_source_acquire_func_t) (cairo_pattern_t *pattern,
void *callback_data,
cairo_surface_t *target,
const cairo_rectangle_int_t *extents);
/**
* cairo_raster_source_release_func_t:
* @pattern: the pattern being rendered from
* @callback_data: the user data supplied during creation
* @surface: the surface created during acquire
*
* #cairo_raster_source_release_func_t is the type of function which is
* called when the pixel data is no longer being access by the pattern
* for the rendering operation. Typically this function will simply
* destroy the surface created during acquire.
*
* Since: 1.12
**/
typedef void
(*cairo_raster_source_release_func_t) (cairo_pattern_t *pattern,
void *callback_data,
cairo_surface_t *surface);
/**
* cairo_raster_source_snapshot_func_t:
* @pattern: the pattern being rendered from
* @callback_data: the user data supplied during creation
*
* #cairo_raster_source_release_func_t is the type of function which is
* called when the pixel data needs to be preserved for later use
* during printing. This pattern will be accessed again later, and it
* is expected to provide the pixel data that was current at the time
* of snapshotting.
*
* Since: 1.12
**/
typedef cairo_status_t
(*cairo_raster_source_snapshot_func_t) (cairo_pattern_t *pattern,
void *callback_data);
/**
* cairo_raster_source_copy_func_t:
* @pattern: the pattern being rendered from
* @callback_data: the user data supplied during creation
*
* #cairo_raster_source_copy_func_t is the type of function which is
* called when the pattern gets copied as a normal part of rendering.
*
* Since: 1.12
**/
typedef cairo_status_t
(*cairo_raster_source_copy_func_t) (cairo_pattern_t *pattern,
void *callback_data,
const cairo_pattern_t *other);
/**
* cairo_raster_source_finish_func_t:
* @pattern: the pattern being rendered from
* @callback_data: the user data supplied during creation
*
* #cairo_raster_source_copy_func_t is the type of function which is
* called when the pattern (or a copy thereof) is no longer required.
*
* Since: 1.12
**/
typedef void
(*cairo_raster_source_finish_func_t) (cairo_pattern_t *pattern,
void *callback_data);