path: root/libs/cairo-1.16.0/doc/public/xml/cairo-raster-source.xml

<?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.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 id="cairo-pattern-create-raster-source.parameters" 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 id="cairo-pattern-create-raster-source.returns" 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>
</refsect3><para role="since">Since: <link linkend="api-index-1.12">1.12</link></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 id="cairo-raster-source-pattern-set-callback-data.parameters" 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: <link linkend="api-index-1.12">1.12</link></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 id="cairo-raster-source-pattern-get-callback-data.parameters" 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 id="cairo-raster-source-pattern-get-callback-data.returns" role="returns">
<title>Returns</title>
<para> the current user-data passed to each callback</para>
</refsect3><para role="since">Since: <link linkend="api-index-1.12">1.12</link></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 id="cairo-raster-source-pattern-set-acquire.parameters" 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: <link linkend="api-index-1.12">1.12</link></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 id="cairo-raster-source-pattern-get-acquire.parameters" 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: <link linkend="api-index-1.12">1.12</link></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 id="cairo-raster-source-pattern-set-snapshot.parameters" 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: <link linkend="api-index-1.12">1.12</link></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 id="cairo-raster-source-pattern-get-snapshot.parameters" 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 id="cairo-raster-source-pattern-get-snapshot.returns" role="returns">
<title>Returns</title>
<para> the current snapshot callback</para>
</refsect3><para role="since">Since: <link linkend="api-index-1.12">1.12</link></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 id="cairo-raster-source-pattern-set-copy.parameters" 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: <link linkend="api-index-1.12">1.12</link></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 id="cairo-raster-source-pattern-get-copy.parameters" 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 id="cairo-raster-source-pattern-get-copy.returns" role="returns">
<title>Returns</title>
<para> the current copy callback</para>
</refsect3><para role="since">Since: <link linkend="api-index-1.12">1.12</link></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 id="cairo-raster-source-pattern-set-finish.parameters" 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: <link linkend="api-index-1.12">1.12</link></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 id="cairo-raster-source-pattern-get-finish.parameters" 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 id="cairo-raster-source-pattern-get-finish.returns" role="returns">
<title>Returns</title>
<para> the current finish callback</para>
</refsect3><para role="since">Since: <link linkend="api-index-1.12">1.12</link></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 id="cairo-raster-source-acquire-func-t.parameters" 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 id="cairo-raster-source-acquire-func-t.returns" role="returns">
<title>Returns</title>
<para> a <link linkend="cairo-surface-t"><type>cairo_surface_t</type></link></para>
</refsect3><para role="since">Since: <link linkend="api-index-1.12">1.12</link></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 id="cairo-raster-source-release-func-t.parameters" 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: <link linkend="api-index-1.12">1.12</link></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 id="cairo-raster-source-snapshot-func-t.parameters" 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 id="cairo-raster-source-snapshot-func-t.returns" 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>
</refsect3><para role="since">Since: <link linkend="api-index-1.12">1.12</link></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 id="cairo-raster-source-copy-func-t.parameters" 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 id="cairo-raster-source-copy-func-t.returns" 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>
</refsect3><para role="since">Since: <link linkend="api-index-1.12">1.12</link></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 id="cairo-raster-source-finish-func-t.parameters" 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: <link linkend="api-index-1.12">1.12</link></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>