summaryrefslogtreecommitdiff
path: root/doc/public/xml/cairo-raster-source.xml
diff options
context:
space:
mode:
Diffstat (limited to 'doc/public/xml/cairo-raster-source.xml')
-rw-r--r--doc/public/xml/cairo-raster-source.xml565
1 files changed, 565 insertions, 0 deletions
diff --git a/doc/public/xml/cairo-raster-source.xml b/doc/public/xml/cairo-raster-source.xml
new file mode 100644
index 000000000..f0697fb75
--- /dev/null
+++ b/doc/public/xml/cairo-raster-source.xml
@@ -0,0 +1,565 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+<!ENTITY version SYSTEM "version.xml">
+]>
+<refentry id="cairo-Raster-Sources">
+<refmeta>
+<refentrytitle role="top_of_page" id="cairo-Raster-Sources.top_of_page">Raster Sources</refentrytitle>
+<manvolnum>3</manvolnum>
+<refmiscinfo>
+ CAIRO Library
+</refmiscinfo>
+</refmeta>
+<refnamediv>
+<refname>Raster Sources</refname>
+<refpurpose>Supplying arbitrary image data</refpurpose>
+</refnamediv>
+
+<refsect1 id="cairo-Raster-Sources.functions" role="functions_proto">
+<title role="functions_proto.title">Functions</title>
+<informaltable pgwide="1" frame="none">
+<tgroup cols="2">
+<colspec colname="functions_return" colwidth="150px"/>
+<colspec colname="functions_name"/>
+<tbody>
+<row><entry role="function_type"><link linkend="cairo-pattern-t"><returnvalue>cairo_pattern_t</returnvalue></link>&#160;*
+</entry><entry role="function_name"><link linkend="cairo-pattern-create-raster-source">cairo_pattern_create_raster_source</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
+<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
+</entry><entry role="function_name"><link linkend="cairo-raster-source-pattern-set-callback-data">cairo_raster_source_pattern_set_callback_data</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
+<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>&#160;*
+</entry><entry role="function_name"><link linkend="cairo-raster-source-pattern-get-callback-data">cairo_raster_source_pattern_get_callback_data</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
+<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
+</entry><entry role="function_name"><link linkend="cairo-raster-source-pattern-set-acquire">cairo_raster_source_pattern_set_acquire</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
+<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
+</entry><entry role="function_name"><link linkend="cairo-raster-source-pattern-get-acquire">cairo_raster_source_pattern_get_acquire</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
+<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
+</entry><entry role="function_name"><link linkend="cairo-raster-source-pattern-set-snapshot">cairo_raster_source_pattern_set_snapshot</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
+<row><entry role="function_type"><link linkend="cairo-raster-source-snapshot-func-t"><returnvalue>cairo_raster_source_snapshot_func_t</returnvalue></link>
+</entry><entry role="function_name"><link linkend="cairo-raster-source-pattern-get-snapshot">cairo_raster_source_pattern_get_snapshot</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
+<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
+</entry><entry role="function_name"><link linkend="cairo-raster-source-pattern-set-copy">cairo_raster_source_pattern_set_copy</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
+<row><entry role="function_type"><link linkend="cairo-raster-source-copy-func-t"><returnvalue>cairo_raster_source_copy_func_t</returnvalue></link>
+</entry><entry role="function_name"><link linkend="cairo-raster-source-pattern-get-copy">cairo_raster_source_pattern_get_copy</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
+<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
+</entry><entry role="function_name"><link linkend="cairo-raster-source-pattern-set-finish">cairo_raster_source_pattern_set_finish</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
+<row><entry role="function_type"><link linkend="cairo-raster-source-finish-func-t"><returnvalue>cairo_raster_source_finish_func_t</returnvalue></link>
+</entry><entry role="function_name"><link linkend="cairo-raster-source-pattern-get-finish">cairo_raster_source_pattern_get_finish</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
+<row><entry role="function_type"><link linkend="cairo-surface-t"><returnvalue>cairo_surface_t</returnvalue></link>
+</entry><entry role="function_name"><phrase role="c_punctuation">(</phrase><link linkend="cairo-raster-source-acquire-func-t">*cairo_raster_source_acquire_func_t</link><phrase role="c_punctuation">)</phrase>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
+<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
+</entry><entry role="function_name"><phrase role="c_punctuation">(</phrase><link linkend="cairo-raster-source-release-func-t">*cairo_raster_source_release_func_t</link><phrase role="c_punctuation">)</phrase>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
+<row><entry role="function_type"><link linkend="cairo-status-t"><returnvalue>cairo_status_t</returnvalue></link>
+</entry><entry role="function_name"><phrase role="c_punctuation">(</phrase><link linkend="cairo-raster-source-snapshot-func-t">*cairo_raster_source_snapshot_func_t</link><phrase role="c_punctuation">)</phrase>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
+<row><entry role="function_type"><link linkend="cairo-status-t"><returnvalue>cairo_status_t</returnvalue></link>
+</entry><entry role="function_name"><phrase role="c_punctuation">(</phrase><link linkend="cairo-raster-source-copy-func-t">*cairo_raster_source_copy_func_t</link><phrase role="c_punctuation">)</phrase>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
+<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
+</entry><entry role="function_name"><phrase role="c_punctuation">(</phrase><link linkend="cairo-raster-source-finish-func-t">*cairo_raster_source_finish_func_t</link><phrase role="c_punctuation">)</phrase>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
+
+</tbody>
+</tgroup>
+</informaltable>
+</refsect1>
+<refsect1 id="cairo-Raster-Sources.object-hierarchy" role="object_hierarchy">
+<title role="object_hierarchy.title">Object Hierarchy</title>
+<screen>
+</screen>
+</refsect1>
+
+
+<refsect1 id="cairo-Raster-Sources.description" role="desc">
+<title role="desc.title">Description</title>
+<para>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.</para>
+<para>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.</para>
+
+</refsect1>
+<refsect1 id="cairo-Raster-Sources.functions_details" role="details">
+<title role="details.title">Functions</title>
+<refsect2 id="cairo-pattern-create-raster-source" role="function" condition="since:1.12">
+<title>cairo_pattern_create_raster_source&#160;()</title>
+<indexterm zone="cairo-pattern-create-raster-source" role="1.12"><primary sortas="pattern_create_raster_source">cairo_pattern_create_raster_source</primary></indexterm>
+<programlisting language="C"><link linkend="cairo-pattern-t"><returnvalue>cairo_pattern_t</returnvalue></link>&#160;*
+cairo_pattern_create_raster_source (<parameter><link linkend="void"><type>void</type></link> *user_data</parameter>,
+ <parameter><link linkend="cairo-content-t"><type>cairo_content_t</type></link> content</parameter>,
+ <parameter><link linkend="int"><type>int</type></link> width</parameter>,
+ <parameter><link linkend="int"><type>int</type></link> height</parameter>);</programlisting>
+<para>Creates a new user pattern for providing pixel data.</para>
+<para>Use the setter functions to associate callbacks with the returned
+pattern. The only mandatory callback is acquire.</para>
+<refsect3 role="parameters">
+<title>Parameters</title>
+<informaltable role="parameters_table" pgwide="1" frame="none">
+<tgroup cols="3">
+<colspec colname="parameters_name" colwidth="150px"/>
+<colspec colname="parameters_description"/>
+<colspec colname="parameters_annotations" colwidth="200px"/>
+<tbody>
+<row><entry role="parameter_name"><para>user_data</para></entry>
+<entry role="parameter_description"><para>the user data to be passed to all callbacks</para></entry>
+<entry role="parameter_annotations"></entry></row>
+<row><entry role="parameter_name"><para>content</para></entry>
+<entry role="parameter_description"><para>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.</para></entry>
+<entry role="parameter_annotations"></entry></row>
+<row><entry role="parameter_name"><para>width</para></entry>
+<entry role="parameter_description"><para>maximum size of the sample area</para></entry>
+<entry role="parameter_annotations"></entry></row>
+<row><entry role="parameter_name"><para>height</para></entry>
+<entry role="parameter_description"><para>maximum size of the sample area</para></entry>
+<entry role="parameter_annotations"></entry></row>
+</tbody></tgroup></informaltable>
+</refsect3><refsect3 role="returns">
+<title>Returns</title>
+<para> a newly created <link linkend="cairo-pattern-t"><type>cairo_pattern_t</type></link>. Free with
+<link linkend="cairo-pattern-destroy"><function>cairo_pattern_destroy()</function></link> when you are done using it.</para>
+<para></para>
+</refsect3><para role="since">Since 1.12</para></refsect2>
+<refsect2 id="cairo-raster-source-pattern-set-callback-data" role="function" condition="since:1.12">
+<title>cairo_raster_source_pattern_set_callback_data&#160;()</title>
+<indexterm zone="cairo-raster-source-pattern-set-callback-data" role="1.12"><primary sortas="raster_source_pattern_set_callback_data">cairo_raster_source_pattern_set_callback_data</primary></indexterm>
+<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
+cairo_raster_source_pattern_set_callback_data
+ (<parameter><link linkend="cairo-pattern-t"><type>cairo_pattern_t</type></link> *pattern</parameter>,
+ <parameter><link linkend="void"><type>void</type></link> *data</parameter>);</programlisting>
+<para>Updates the user data that is provided to all callbacks.</para>
+<refsect3 role="parameters">
+<title>Parameters</title>
+<informaltable role="parameters_table" pgwide="1" frame="none">
+<tgroup cols="3">
+<colspec colname="parameters_name" colwidth="150px"/>
+<colspec colname="parameters_description"/>
+<colspec colname="parameters_annotations" colwidth="200px"/>
+<tbody>
+<row><entry role="parameter_name"><para>pattern</para></entry>
+<entry role="parameter_description"><para>the pattern to update</para></entry>
+<entry role="parameter_annotations"></entry></row>
+<row><entry role="parameter_name"><para>data</para></entry>
+<entry role="parameter_description"><para>the user data to be passed to all callbacks</para></entry>
+<entry role="parameter_annotations"></entry></row>
+</tbody></tgroup></informaltable>
+</refsect3><para role="since">Since 1.12</para></refsect2>
+<refsect2 id="cairo-raster-source-pattern-get-callback-data" role="function" condition="since:1.12">
+<title>cairo_raster_source_pattern_get_callback_data&#160;()</title>
+<indexterm zone="cairo-raster-source-pattern-get-callback-data" role="1.12"><primary sortas="raster_source_pattern_get_callback_data">cairo_raster_source_pattern_get_callback_data</primary></indexterm>
+<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>&#160;*
+cairo_raster_source_pattern_get_callback_data
+ (<parameter><link linkend="cairo-pattern-t"><type>cairo_pattern_t</type></link> *pattern</parameter>);</programlisting>
+<para>Queries the current user data.</para>
+<refsect3 role="parameters">
+<title>Parameters</title>
+<informaltable role="parameters_table" pgwide="1" frame="none">
+<tgroup cols="3">
+<colspec colname="parameters_name" colwidth="150px"/>
+<colspec colname="parameters_description"/>
+<colspec colname="parameters_annotations" colwidth="200px"/>
+<tbody>
+<row><entry role="parameter_name"><para>pattern</para></entry>
+<entry role="parameter_description"><para>the pattern to update</para></entry>
+<entry role="parameter_annotations"></entry></row>
+</tbody></tgroup></informaltable>
+</refsect3><refsect3 role="returns">
+<title>Returns</title>
+<para> the current user-data passed to each callback</para>
+<para></para>
+</refsect3><para role="since">Since 1.12</para></refsect2>
+<refsect2 id="cairo-raster-source-pattern-set-acquire" role="function" condition="since:1.12">
+<title>cairo_raster_source_pattern_set_acquire&#160;()</title>
+<indexterm zone="cairo-raster-source-pattern-set-acquire" role="1.12"><primary sortas="raster_source_pattern_set_acquire">cairo_raster_source_pattern_set_acquire</primary></indexterm>
+<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
+cairo_raster_source_pattern_set_acquire
+ (<parameter><link linkend="cairo-pattern-t"><type>cairo_pattern_t</type></link> *pattern</parameter>,
+ <parameter><link linkend="cairo-raster-source-acquire-func-t"><type>cairo_raster_source_acquire_func_t</type></link> acquire</parameter>,
+ <parameter><link linkend="cairo-raster-source-release-func-t"><type>cairo_raster_source_release_func_t</type></link> release</parameter>);</programlisting>
+<para>Specifies the callbacks used to generate the image surface for a rendering
+operation (acquire) and the function used to cleanup that surface afterwards.</para>
+<para>The <parameter>acquire</parameter>
+ callback should create a surface (preferably an image
+surface created to match the target using
+<link linkend="cairo-surface-create-similar-image"><function>cairo_surface_create_similar_image()</function></link>) 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 <link linkend="cairo-surface-set-device-offset"><function>cairo_surface_set_device_offset()</function></link>.</para>
+<refsect3 role="parameters">
+<title>Parameters</title>
+<informaltable role="parameters_table" pgwide="1" frame="none">
+<tgroup cols="3">
+<colspec colname="parameters_name" colwidth="150px"/>
+<colspec colname="parameters_description"/>
+<colspec colname="parameters_annotations" colwidth="200px"/>
+<tbody>
+<row><entry role="parameter_name"><para>pattern</para></entry>
+<entry role="parameter_description"><para>the pattern to update</para></entry>
+<entry role="parameter_annotations"></entry></row>
+<row><entry role="parameter_name"><para>acquire</para></entry>
+<entry role="parameter_description"><para>acquire callback</para></entry>
+<entry role="parameter_annotations"></entry></row>
+<row><entry role="parameter_name"><para>release</para></entry>
+<entry role="parameter_description"><para>release callback</para></entry>
+<entry role="parameter_annotations"></entry></row>
+</tbody></tgroup></informaltable>
+</refsect3><para role="since">Since 1.12</para></refsect2>
+<refsect2 id="cairo-raster-source-pattern-get-acquire" role="function" condition="since:1.12">
+<title>cairo_raster_source_pattern_get_acquire&#160;()</title>
+<indexterm zone="cairo-raster-source-pattern-get-acquire" role="1.12"><primary sortas="raster_source_pattern_get_acquire">cairo_raster_source_pattern_get_acquire</primary></indexterm>
+<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
+cairo_raster_source_pattern_get_acquire
+ (<parameter><link linkend="cairo-pattern-t"><type>cairo_pattern_t</type></link> *pattern</parameter>,
+ <parameter><link linkend="cairo-raster-source-acquire-func-t"><type>cairo_raster_source_acquire_func_t</type></link> *acquire</parameter>,
+ <parameter><link linkend="cairo-raster-source-release-func-t"><type>cairo_raster_source_release_func_t</type></link> *release</parameter>);</programlisting>
+<para>Queries the current acquire and release callbacks.</para>
+<refsect3 role="parameters">
+<title>Parameters</title>
+<informaltable role="parameters_table" pgwide="1" frame="none">
+<tgroup cols="3">
+<colspec colname="parameters_name" colwidth="150px"/>
+<colspec colname="parameters_description"/>
+<colspec colname="parameters_annotations" colwidth="200px"/>
+<tbody>
+<row><entry role="parameter_name"><para>pattern</para></entry>
+<entry role="parameter_description"><para>the pattern to query</para></entry>
+<entry role="parameter_annotations"></entry></row>
+<row><entry role="parameter_name"><para>acquire</para></entry>
+<entry role="parameter_description"><para>return value for the current acquire callback</para></entry>
+<entry role="parameter_annotations"></entry></row>
+<row><entry role="parameter_name"><para>release</para></entry>
+<entry role="parameter_description"><para>return value for the current release callback</para></entry>
+<entry role="parameter_annotations"></entry></row>
+</tbody></tgroup></informaltable>
+</refsect3><para role="since">Since 1.12</para></refsect2>
+<refsect2 id="cairo-raster-source-pattern-set-snapshot" role="function" condition="since:1.12">
+<title>cairo_raster_source_pattern_set_snapshot&#160;()</title>
+<indexterm zone="cairo-raster-source-pattern-set-snapshot" role="1.12"><primary sortas="raster_source_pattern_set_snapshot">cairo_raster_source_pattern_set_snapshot</primary></indexterm>
+<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
+cairo_raster_source_pattern_set_snapshot
+ (<parameter><link linkend="cairo-pattern-t"><type>cairo_pattern_t</type></link> *pattern</parameter>,
+ <parameter><link linkend="cairo-raster-source-snapshot-func-t"><type>cairo_raster_source_snapshot_func_t</type></link> snapshot</parameter>);</programlisting>
+<para>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.</para>
+<refsect3 role="parameters">
+<title>Parameters</title>
+<informaltable role="parameters_table" pgwide="1" frame="none">
+<tgroup cols="3">
+<colspec colname="parameters_name" colwidth="150px"/>
+<colspec colname="parameters_description"/>
+<colspec colname="parameters_annotations" colwidth="200px"/>
+<tbody>
+<row><entry role="parameter_name"><para>pattern</para></entry>
+<entry role="parameter_description"><para>the pattern to update</para></entry>
+<entry role="parameter_annotations"></entry></row>
+<row><entry role="parameter_name"><para>snapshot</para></entry>
+<entry role="parameter_description"><para>snapshot callback</para></entry>
+<entry role="parameter_annotations"></entry></row>
+</tbody></tgroup></informaltable>
+</refsect3><para role="since">Since 1.12</para></refsect2>
+<refsect2 id="cairo-raster-source-pattern-get-snapshot" role="function" condition="since:1.12">
+<title>cairo_raster_source_pattern_get_snapshot&#160;()</title>
+<indexterm zone="cairo-raster-source-pattern-get-snapshot" role="1.12"><primary sortas="raster_source_pattern_get_snapshot">cairo_raster_source_pattern_get_snapshot</primary></indexterm>
+<programlisting language="C"><link linkend="cairo-raster-source-snapshot-func-t"><returnvalue>cairo_raster_source_snapshot_func_t</returnvalue></link>
+cairo_raster_source_pattern_get_snapshot
+ (<parameter><link linkend="cairo-pattern-t"><type>cairo_pattern_t</type></link> *pattern</parameter>);</programlisting>
+<para>Queries the current snapshot callback.</para>
+<refsect3 role="parameters">
+<title>Parameters</title>
+<informaltable role="parameters_table" pgwide="1" frame="none">
+<tgroup cols="3">
+<colspec colname="parameters_name" colwidth="150px"/>
+<colspec colname="parameters_description"/>
+<colspec colname="parameters_annotations" colwidth="200px"/>
+<tbody>
+<row><entry role="parameter_name"><para>pattern</para></entry>
+<entry role="parameter_description"><para>the pattern to query</para></entry>
+<entry role="parameter_annotations"></entry></row>
+</tbody></tgroup></informaltable>
+</refsect3><refsect3 role="returns">
+<title>Returns</title>
+<para> the current snapshot callback</para>
+<para></para>
+</refsect3><para role="since">Since 1.12</para></refsect2>
+<refsect2 id="cairo-raster-source-pattern-set-copy" role="function" condition="since:1.12">
+<title>cairo_raster_source_pattern_set_copy&#160;()</title>
+<indexterm zone="cairo-raster-source-pattern-set-copy" role="1.12"><primary sortas="raster_source_pattern_set_copy">cairo_raster_source_pattern_set_copy</primary></indexterm>
+<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
+cairo_raster_source_pattern_set_copy (<parameter><link linkend="cairo-pattern-t"><type>cairo_pattern_t</type></link> *pattern</parameter>,
+ <parameter><link linkend="cairo-raster-source-copy-func-t"><type>cairo_raster_source_copy_func_t</type></link> copy</parameter>);</programlisting>
+<para>Updates the copy callback which is used whenever a temporary copy of the
+pattern is taken.</para>
+<refsect3 role="parameters">
+<title>Parameters</title>
+<informaltable role="parameters_table" pgwide="1" frame="none">
+<tgroup cols="3">
+<colspec colname="parameters_name" colwidth="150px"/>
+<colspec colname="parameters_description"/>
+<colspec colname="parameters_annotations" colwidth="200px"/>
+<tbody>
+<row><entry role="parameter_name"><para>pattern</para></entry>
+<entry role="parameter_description"><para>the pattern to update</para></entry>
+<entry role="parameter_annotations"></entry></row>
+<row><entry role="parameter_name"><para>copy</para></entry>
+<entry role="parameter_description"><para>the copy callback</para></entry>
+<entry role="parameter_annotations"></entry></row>
+</tbody></tgroup></informaltable>
+</refsect3><para role="since">Since 1.12</para></refsect2>
+<refsect2 id="cairo-raster-source-pattern-get-copy" role="function" condition="since:1.12">
+<title>cairo_raster_source_pattern_get_copy&#160;()</title>
+<indexterm zone="cairo-raster-source-pattern-get-copy" role="1.12"><primary sortas="raster_source_pattern_get_copy">cairo_raster_source_pattern_get_copy</primary></indexterm>
+<programlisting language="C"><link linkend="cairo-raster-source-copy-func-t"><returnvalue>cairo_raster_source_copy_func_t</returnvalue></link>
+cairo_raster_source_pattern_get_copy (<parameter><link linkend="cairo-pattern-t"><type>cairo_pattern_t</type></link> *pattern</parameter>);</programlisting>
+<para>Queries the current copy callback.</para>
+<refsect3 role="parameters">
+<title>Parameters</title>
+<informaltable role="parameters_table" pgwide="1" frame="none">
+<tgroup cols="3">
+<colspec colname="parameters_name" colwidth="150px"/>
+<colspec colname="parameters_description"/>
+<colspec colname="parameters_annotations" colwidth="200px"/>
+<tbody>
+<row><entry role="parameter_name"><para>pattern</para></entry>
+<entry role="parameter_description"><para>the pattern to query</para></entry>
+<entry role="parameter_annotations"></entry></row>
+</tbody></tgroup></informaltable>
+</refsect3><refsect3 role="returns">
+<title>Returns</title>
+<para> the current copy callback</para>
+<para></para>
+</refsect3><para role="since">Since 1.12</para></refsect2>
+<refsect2 id="cairo-raster-source-pattern-set-finish" role="function" condition="since:1.12">
+<title>cairo_raster_source_pattern_set_finish&#160;()</title>
+<indexterm zone="cairo-raster-source-pattern-set-finish" role="1.12"><primary sortas="raster_source_pattern_set_finish">cairo_raster_source_pattern_set_finish</primary></indexterm>
+<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
+cairo_raster_source_pattern_set_finish
+ (<parameter><link linkend="cairo-pattern-t"><type>cairo_pattern_t</type></link> *pattern</parameter>,
+ <parameter><link linkend="cairo-raster-source-finish-func-t"><type>cairo_raster_source_finish_func_t</type></link> finish</parameter>);</programlisting>
+<para>Updates the finish callback which is used whenever a pattern (or a copy
+thereof) will no longer be used.</para>
+<refsect3 role="parameters">
+<title>Parameters</title>
+<informaltable role="parameters_table" pgwide="1" frame="none">
+<tgroup cols="3">
+<colspec colname="parameters_name" colwidth="150px"/>
+<colspec colname="parameters_description"/>
+<colspec colname="parameters_annotations" colwidth="200px"/>
+<tbody>
+<row><entry role="parameter_name"><para>pattern</para></entry>
+<entry role="parameter_description"><para>the pattern to update</para></entry>
+<entry role="parameter_annotations"></entry></row>
+<row><entry role="parameter_name"><para>finish</para></entry>
+<entry role="parameter_description"><para>the finish callback</para></entry>
+<entry role="parameter_annotations"></entry></row>
+</tbody></tgroup></informaltable>
+</refsect3><para role="since">Since 1.12</para></refsect2>
+<refsect2 id="cairo-raster-source-pattern-get-finish" role="function" condition="since:1.12">
+<title>cairo_raster_source_pattern_get_finish&#160;()</title>
+<indexterm zone="cairo-raster-source-pattern-get-finish" role="1.12"><primary sortas="raster_source_pattern_get_finish">cairo_raster_source_pattern_get_finish</primary></indexterm>
+<programlisting language="C"><link linkend="cairo-raster-source-finish-func-t"><returnvalue>cairo_raster_source_finish_func_t</returnvalue></link>
+cairo_raster_source_pattern_get_finish
+ (<parameter><link linkend="cairo-pattern-t"><type>cairo_pattern_t</type></link> *pattern</parameter>);</programlisting>
+<para>Queries the current finish callback.</para>
+<refsect3 role="parameters">
+<title>Parameters</title>
+<informaltable role="parameters_table" pgwide="1" frame="none">
+<tgroup cols="3">
+<colspec colname="parameters_name" colwidth="150px"/>
+<colspec colname="parameters_description"/>
+<colspec colname="parameters_annotations" colwidth="200px"/>
+<tbody>
+<row><entry role="parameter_name"><para>pattern</para></entry>
+<entry role="parameter_description"><para>the pattern to query</para></entry>
+<entry role="parameter_annotations"></entry></row>
+</tbody></tgroup></informaltable>
+</refsect3><refsect3 role="returns">
+<title>Returns</title>
+<para> the current finish callback</para>
+<para></para>
+</refsect3><para role="since">Since 1.12</para></refsect2>
+<refsect2 id="cairo-raster-source-acquire-func-t" role="function" condition="since:1.12">
+<title>cairo_raster_source_acquire_func_t&#160;()</title>
+<indexterm zone="cairo-raster-source-acquire-func-t" role="1.12"><primary sortas="raster_source_acquire_func_t">cairo_raster_source_acquire_func_t</primary></indexterm>
+<programlisting language="C"><link linkend="cairo-surface-t"><returnvalue>cairo_surface_t</returnvalue></link>
+<phrase role="c_punctuation">(</phrase>*cairo_raster_source_acquire_func_t<phrase role="c_punctuation">)</phrase> (<parameter><link linkend="cairo-pattern-t"><type>cairo_pattern_t</type></link> *pattern</parameter>,
+ <parameter><link linkend="void"><type>void</type></link> *callback_data</parameter>,
+ <parameter><link linkend="cairo-surface-t"><type>cairo_surface_t</type></link> *target</parameter>,
+ <parameter>const <link linkend="cairo-rectangle-int-t"><type>cairo_rectangle_int_t</type></link> *extents</parameter>);</programlisting>
+<para><link linkend="cairo-raster-source-acquire-func-t"><type>cairo_raster_source_acquire_func_t</type></link> 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 <link linkend="cairo-surface-create-similar-image"><function>cairo_surface_create_similar_image()</function></link> for the target (which
+enables the number of copies to be reduced during transfer to the
+device). Another 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
+<link linkend="cairo-surface-set-device-offset"><function>cairo_surface_set_device_offset()</function></link> to specify the top-left corner of the
+sample data (along with width and height of the surface).</para>
+<refsect3 role="parameters">
+<title>Parameters</title>
+<informaltable role="parameters_table" pgwide="1" frame="none">
+<tgroup cols="3">
+<colspec colname="parameters_name" colwidth="150px"/>
+<colspec colname="parameters_description"/>
+<colspec colname="parameters_annotations" colwidth="200px"/>
+<tbody>
+<row><entry role="parameter_name"><para>pattern</para></entry>
+<entry role="parameter_description"><para>the pattern being rendered from</para></entry>
+<entry role="parameter_annotations"></entry></row>
+<row><entry role="parameter_name"><para>callback_data</para></entry>
+<entry role="parameter_description"><para>the user data supplied during creation</para></entry>
+<entry role="parameter_annotations"></entry></row>
+<row><entry role="parameter_name"><para>target</para></entry>
+<entry role="parameter_description"><para>the rendering target surface</para></entry>
+<entry role="parameter_annotations"></entry></row>
+<row><entry role="parameter_name"><para>extents</para></entry>
+<entry role="parameter_description"><para>rectangular region of interest in pixels in sample space</para></entry>
+<entry role="parameter_annotations"></entry></row>
+</tbody></tgroup></informaltable>
+</refsect3><refsect3 role="returns">
+<title>Returns</title>
+<para> a <link linkend="cairo-surface-t"><type>cairo_surface_t</type></link></para>
+<para></para>
+</refsect3><para role="since">Since 1.12</para></refsect2>
+<refsect2 id="cairo-raster-source-release-func-t" role="function" condition="since:1.12">
+<title>cairo_raster_source_release_func_t&#160;()</title>
+<indexterm zone="cairo-raster-source-release-func-t" role="1.12"><primary sortas="raster_source_release_func_t">cairo_raster_source_release_func_t</primary></indexterm>
+<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
+<phrase role="c_punctuation">(</phrase>*cairo_raster_source_release_func_t<phrase role="c_punctuation">)</phrase> (<parameter><link linkend="cairo-pattern-t"><type>cairo_pattern_t</type></link> *pattern</parameter>,
+ <parameter><link linkend="void"><type>void</type></link> *callback_data</parameter>,
+ <parameter><link linkend="cairo-surface-t"><type>cairo_surface_t</type></link> *surface</parameter>);</programlisting>
+<para><link linkend="cairo-raster-source-release-func-t"><type>cairo_raster_source_release_func_t</type></link> 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.</para>
+<refsect3 role="parameters">
+<title>Parameters</title>
+<informaltable role="parameters_table" pgwide="1" frame="none">
+<tgroup cols="3">
+<colspec colname="parameters_name" colwidth="150px"/>
+<colspec colname="parameters_description"/>
+<colspec colname="parameters_annotations" colwidth="200px"/>
+<tbody>
+<row><entry role="parameter_name"><para>pattern</para></entry>
+<entry role="parameter_description"><para>the pattern being rendered from</para></entry>
+<entry role="parameter_annotations"></entry></row>
+<row><entry role="parameter_name"><para>callback_data</para></entry>
+<entry role="parameter_description"><para>the user data supplied during creation</para></entry>
+<entry role="parameter_annotations"></entry></row>
+<row><entry role="parameter_name"><para>surface</para></entry>
+<entry role="parameter_description"><para>the surface created during acquire</para></entry>
+<entry role="parameter_annotations"></entry></row>
+</tbody></tgroup></informaltable>
+</refsect3><para role="since">Since 1.12</para></refsect2>
+<refsect2 id="cairo-raster-source-snapshot-func-t" role="function" condition="since:1.12">
+<title>cairo_raster_source_snapshot_func_t&#160;()</title>
+<indexterm zone="cairo-raster-source-snapshot-func-t" role="1.12"><primary sortas="raster_source_snapshot_func_t">cairo_raster_source_snapshot_func_t</primary></indexterm>
+<programlisting language="C"><link linkend="cairo-status-t"><returnvalue>cairo_status_t</returnvalue></link>
+<phrase role="c_punctuation">(</phrase>*cairo_raster_source_snapshot_func_t<phrase role="c_punctuation">)</phrase>
+ (<parameter><link linkend="cairo-pattern-t"><type>cairo_pattern_t</type></link> *pattern</parameter>,
+ <parameter><link linkend="void"><type>void</type></link> *callback_data</parameter>);</programlisting>
+<para><link linkend="cairo-raster-source-snapshot-func-t"><type>cairo_raster_source_snapshot_func_t</type></link> 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.</para>
+<refsect3 role="parameters">
+<title>Parameters</title>
+<informaltable role="parameters_table" pgwide="1" frame="none">
+<tgroup cols="3">
+<colspec colname="parameters_name" colwidth="150px"/>
+<colspec colname="parameters_description"/>
+<colspec colname="parameters_annotations" colwidth="200px"/>
+<tbody>
+<row><entry role="parameter_name"><para>pattern</para></entry>
+<entry role="parameter_description"><para>the pattern being rendered from</para></entry>
+<entry role="parameter_annotations"></entry></row>
+<row><entry role="parameter_name"><para>callback_data</para></entry>
+<entry role="parameter_description"><para>the user data supplied during creation</para></entry>
+<entry role="parameter_annotations"></entry></row>
+</tbody></tgroup></informaltable>
+</refsect3><refsect3 role="returns">
+<title>Returns</title>
+<para> CAIRO_STATUS_SUCCESS on success, or one of the
+<link linkend="cairo-status-t"><type>cairo_status_t</type></link> error codes for failure.</para>
+<para></para>
+</refsect3><para role="since">Since 1.12</para></refsect2>
+<refsect2 id="cairo-raster-source-copy-func-t" role="function" condition="since:1.12">
+<title>cairo_raster_source_copy_func_t&#160;()</title>
+<indexterm zone="cairo-raster-source-copy-func-t" role="1.12"><primary sortas="raster_source_copy_func_t">cairo_raster_source_copy_func_t</primary></indexterm>
+<programlisting language="C"><link linkend="cairo-status-t"><returnvalue>cairo_status_t</returnvalue></link>
+<phrase role="c_punctuation">(</phrase>*cairo_raster_source_copy_func_t<phrase role="c_punctuation">)</phrase> (<parameter><link linkend="cairo-pattern-t"><type>cairo_pattern_t</type></link> *pattern</parameter>,
+ <parameter><link linkend="void"><type>void</type></link> *callback_data</parameter>,
+ <parameter>const <link linkend="cairo-pattern-t"><type>cairo_pattern_t</type></link> *other</parameter>);</programlisting>
+<para><link linkend="cairo-raster-source-copy-func-t"><type>cairo_raster_source_copy_func_t</type></link> is the type of function which is
+called when the pattern gets copied as a normal part of rendering.</para>
+<refsect3 role="parameters">
+<title>Parameters</title>
+<informaltable role="parameters_table" pgwide="1" frame="none">
+<tgroup cols="3">
+<colspec colname="parameters_name" colwidth="150px"/>
+<colspec colname="parameters_description"/>
+<colspec colname="parameters_annotations" colwidth="200px"/>
+<tbody>
+<row><entry role="parameter_name"><para>pattern</para></entry>
+<entry role="parameter_description"><para>the <link linkend="cairo-pattern-t"><type>cairo_pattern_t</type></link> that was copied to</para></entry>
+<entry role="parameter_annotations"></entry></row>
+<row><entry role="parameter_name"><para>callback_data</para></entry>
+<entry role="parameter_description"><para>the user data supplied during creation</para></entry>
+<entry role="parameter_annotations"></entry></row>
+<row><entry role="parameter_name"><para>other</para></entry>
+<entry role="parameter_description"><para>the <link linkend="cairo-pattern-t"><type>cairo_pattern_t</type></link> being used as the source for the copy</para></entry>
+<entry role="parameter_annotations"></entry></row>
+</tbody></tgroup></informaltable>
+</refsect3><refsect3 role="returns">
+<title>Returns</title>
+<para> CAIRO_STATUS_SUCCESS on success, or one of the
+<link linkend="cairo-status-t"><type>cairo_status_t</type></link> error codes for failure.</para>
+<para></para>
+</refsect3><para role="since">Since 1.12</para></refsect2>
+<refsect2 id="cairo-raster-source-finish-func-t" role="function" condition="since:1.12">
+<title>cairo_raster_source_finish_func_t&#160;()</title>
+<indexterm zone="cairo-raster-source-finish-func-t" role="1.12"><primary sortas="raster_source_finish_func_t">cairo_raster_source_finish_func_t</primary></indexterm>
+<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
+<phrase role="c_punctuation">(</phrase>*cairo_raster_source_finish_func_t<phrase role="c_punctuation">)</phrase> (<parameter><link linkend="cairo-pattern-t"><type>cairo_pattern_t</type></link> *pattern</parameter>,
+ <parameter><link linkend="void"><type>void</type></link> *callback_data</parameter>);</programlisting>
+<para><link linkend="cairo-raster-source-finish-func-t"><type>cairo_raster_source_finish_func_t</type></link> is the type of function which is
+called when the pattern (or a copy thereof) is no longer required.</para>
+<refsect3 role="parameters">
+<title>Parameters</title>
+<informaltable role="parameters_table" pgwide="1" frame="none">
+<tgroup cols="3">
+<colspec colname="parameters_name" colwidth="150px"/>
+<colspec colname="parameters_description"/>
+<colspec colname="parameters_annotations" colwidth="200px"/>
+<tbody>
+<row><entry role="parameter_name"><para>pattern</para></entry>
+<entry role="parameter_description"><para>the pattern being rendered from</para></entry>
+<entry role="parameter_annotations"></entry></row>
+<row><entry role="parameter_name"><para>callback_data</para></entry>
+<entry role="parameter_description"><para>the user data supplied during creation</para></entry>
+<entry role="parameter_annotations"></entry></row>
+</tbody></tgroup></informaltable>
+</refsect3><para role="since">Since 1.12</para></refsect2>
+
+</refsect1>
+<refsect1 id="cairo-Raster-Sources.other_details" role="details">
+<title role="details.title">Types and Values</title>
+
+</refsect1>
+<refsect1 id="cairo-Raster-Sources.see-also">
+<title>See Also</title>
+<para><link linkend="cairo-pattern-t"><type>cairo_pattern_t</type></link></para>
+
+</refsect1>
+
+</refentry>