diff options
| author | sanine <sanine.not@pm.me> | 2023-02-12 23:53:22 -0600 |
|---|---|---|
| committer | sanine <sanine.not@pm.me> | 2023-02-12 23:53:22 -0600 |
| commit | f1fe73d1909a2448a004a88362a1a532d0d4f7c3 (patch) | |
| tree | ab37ae3837e2f858de2932bcee9f26e69fab3db1 /libs/cairo-1.16.0/doc/public/xml/cairo-surface.xml | |
| parent | f567ea1e2798fd3156a416e61f083ea3e6b95719 (diff) | |
switch to tinyobj and nanovg from assimp and cairo
Diffstat (limited to 'libs/cairo-1.16.0/doc/public/xml/cairo-surface.xml')
| -rw-r--r-- | libs/cairo-1.16.0/doc/public/xml/cairo-surface.xml | 1525 |
1 files changed, 0 insertions, 1525 deletions
diff --git a/libs/cairo-1.16.0/doc/public/xml/cairo-surface.xml b/libs/cairo-1.16.0/doc/public/xml/cairo-surface.xml deleted file mode 100644 index 2b8e112..0000000 --- a/libs/cairo-1.16.0/doc/public/xml/cairo-surface.xml +++ /dev/null @@ -1,1525 +0,0 @@ -<?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-cairo-surface-t"> -<refmeta> -<refentrytitle role="top_of_page" id="cairo-cairo-surface-t.top_of_page">cairo_surface_t</refentrytitle> -<manvolnum>3</manvolnum> -<refmiscinfo>CAIRO Library</refmiscinfo> -</refmeta> -<refnamediv> -<refname>cairo_surface_t</refname> -<refpurpose>Base class for surfaces</refpurpose> -</refnamediv> - -<refsect1 id="cairo-cairo-surface-t.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-surface-t"><returnvalue>cairo_surface_t</returnvalue></link> * -</entry><entry role="function_name"><link linkend="cairo-surface-create-similar">cairo_surface_create_similar</link> <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"><link linkend="cairo-surface-create-similar-image">cairo_surface_create_similar_image</link> <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"><link linkend="cairo-surface-create-for-rectangle">cairo_surface_create_for_rectangle</link> <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"><link linkend="cairo-surface-reference">cairo_surface_reference</link> <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-surface-destroy">cairo_surface_destroy</link> <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"><link linkend="cairo-surface-status">cairo_surface_status</link> <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-surface-finish">cairo_surface_finish</link> <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-surface-flush">cairo_surface_flush</link> <phrase role="c_punctuation">()</phrase></entry></row> -<row><entry role="function_type"><link linkend="cairo-device-t"><returnvalue>cairo_device_t</returnvalue></link> * -</entry><entry role="function_name"><link linkend="cairo-surface-get-device">cairo_surface_get_device</link> <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-surface-get-font-options">cairo_surface_get_font_options</link> <phrase role="c_punctuation">()</phrase></entry></row> -<row><entry role="function_type"><link linkend="cairo-content-t"><returnvalue>cairo_content_t</returnvalue></link> -</entry><entry role="function_name"><link linkend="cairo-surface-get-content">cairo_surface_get_content</link> <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-surface-mark-dirty">cairo_surface_mark_dirty</link> <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-surface-mark-dirty-rectangle">cairo_surface_mark_dirty_rectangle</link> <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-surface-set-device-offset">cairo_surface_set_device_offset</link> <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-surface-get-device-offset">cairo_surface_get_device_offset</link> <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-surface-get-device-scale">cairo_surface_get_device_scale</link> <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-surface-set-device-scale">cairo_surface_set_device_scale</link> <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-surface-set-fallback-resolution">cairo_surface_set_fallback_resolution</link> <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-surface-get-fallback-resolution">cairo_surface_get_fallback_resolution</link> <phrase role="c_punctuation">()</phrase></entry></row> -<row><entry role="function_type"><link linkend="cairo-surface-type-t"><returnvalue>cairo_surface_type_t</returnvalue></link> -</entry><entry role="function_name"><link linkend="cairo-surface-get-type">cairo_surface_get_type</link> <phrase role="c_punctuation">()</phrase></entry></row> -<row><entry role="function_type">unsigned <link linkend="int"><returnvalue>int</returnvalue></link> -</entry><entry role="function_name"><link linkend="cairo-surface-get-reference-count">cairo_surface_get_reference_count</link> <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"><link linkend="cairo-surface-set-user-data">cairo_surface_set_user_data</link> <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-surface-get-user-data">cairo_surface_get_user_data</link> <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-surface-copy-page">cairo_surface_copy_page</link> <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-surface-show-page">cairo_surface_show_page</link> <phrase role="c_punctuation">()</phrase></entry></row> -<row><entry role="function_type"><link linkend="cairo-bool-t"><returnvalue>cairo_bool_t</returnvalue></link> -</entry><entry role="function_name"><link linkend="cairo-surface-has-show-text-glyphs">cairo_surface_has_show_text_glyphs</link> <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"><link linkend="cairo-surface-set-mime-data">cairo_surface_set_mime_data</link> <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-surface-get-mime-data">cairo_surface_get_mime_data</link> <phrase role="c_punctuation">()</phrase></entry></row> -<row><entry role="function_type"><link linkend="cairo-bool-t"><returnvalue>cairo_bool_t</returnvalue></link> -</entry><entry role="function_name"><link linkend="cairo-surface-supports-mime-type">cairo_surface_supports_mime_type</link> <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"><link linkend="cairo-surface-map-to-image">cairo_surface_map_to_image</link> <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-surface-unmap-image">cairo_surface_unmap_image</link> <phrase role="c_punctuation">()</phrase></entry></row> - -</tbody> -</tgroup> -</informaltable> -</refsect1> -<refsect1 id="cairo-cairo-surface-t.other" role="other_proto"> -<title role="other_proto.title">Types and Values</title> -<informaltable role="enum_members_table" pgwide="1" frame="none"> -<tgroup cols="2"> -<colspec colname="name" colwidth="150px"/> -<colspec colname="description"/> -<tbody> -<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="CAIRO-HAS-MIME-SURFACE:CAPS">CAIRO_HAS_MIME_SURFACE</link></entry></row> -<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="CAIRO-MIME-TYPE-CCITT-FAX:CAPS">CAIRO_MIME_TYPE_CCITT_FAX</link></entry></row> -<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="CAIRO-MIME-TYPE-CCITT-FAX-PARAMS:CAPS">CAIRO_MIME_TYPE_CCITT_FAX_PARAMS</link></entry></row> -<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="CAIRO-MIME-TYPE-EPS:CAPS">CAIRO_MIME_TYPE_EPS</link></entry></row> -<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="CAIRO-MIME-TYPE-EPS-PARAMS:CAPS">CAIRO_MIME_TYPE_EPS_PARAMS</link></entry></row> -<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="CAIRO-MIME-TYPE-JBIG2:CAPS">CAIRO_MIME_TYPE_JBIG2</link></entry></row> -<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="CAIRO-MIME-TYPE-JBIG2-GLOBAL:CAPS">CAIRO_MIME_TYPE_JBIG2_GLOBAL</link></entry></row> -<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="CAIRO-MIME-TYPE-JBIG2-GLOBAL-ID:CAPS">CAIRO_MIME_TYPE_JBIG2_GLOBAL_ID</link></entry></row> -<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="CAIRO-MIME-TYPE-JP2:CAPS">CAIRO_MIME_TYPE_JP2</link></entry></row> -<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="CAIRO-MIME-TYPE-JPEG:CAPS">CAIRO_MIME_TYPE_JPEG</link></entry></row> -<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="CAIRO-MIME-TYPE-PNG:CAPS">CAIRO_MIME_TYPE_PNG</link></entry></row> -<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="CAIRO-MIME-TYPE-URI:CAPS">CAIRO_MIME_TYPE_URI</link></entry></row> -<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="CAIRO-MIME-TYPE-UNIQUE-ID:CAPS">CAIRO_MIME_TYPE_UNIQUE_ID</link></entry></row> -<row><entry role="typedef_keyword">typedef</entry><entry role="function_name"><link linkend="cairo-surface-t">cairo_surface_t</link></entry></row> -<row><entry role="datatype_keyword">enum</entry><entry role="function_name"><link linkend="cairo-content-t">cairo_content_t</link></entry></row> -<row><entry role="datatype_keyword">enum</entry><entry role="function_name"><link linkend="cairo-surface-type-t">cairo_surface_type_t</link></entry></row> - -</tbody> -</tgroup> -</informaltable> -</refsect1> - - -<refsect1 id="cairo-cairo-surface-t.description" role="desc"> -<title role="desc.title">Description</title> -<para><link linkend="cairo-surface-t"><type>cairo_surface_t</type></link> is the abstract type representing all different drawing -targets that cairo can render to. The actual drawings are -performed using a cairo <firstterm>context</firstterm>.</para> -<para>A cairo surface is created by using <firstterm>backend</firstterm>-specific -constructors, typically of the form -<function>cairo_<emphasis>backend</emphasis>_surface_create(<!-- -->)</function>.</para> -<para>Most surface types allow accessing the surface without using Cairo -functions. If you do this, keep in mind that it is mandatory that you call -<link linkend="cairo-surface-flush"><function>cairo_surface_flush()</function></link> before reading from or writing to the surface and that -you must use <link linkend="cairo-surface-mark-dirty"><function>cairo_surface_mark_dirty()</function></link> after modifying it.</para> -<example> -<title>Directly modifying an image surface</title> -<programlisting> -void -modify_image_surface (cairo_surface_t *surface) -{ - unsigned char *data; - int width, height, stride; - - // flush to ensure all writing to the image was done - cairo_surface_flush (surface); - - // modify the image - data = cairo_image_surface_get_data (surface); - width = cairo_image_surface_get_width (surface); - height = cairo_image_surface_get_height (surface); - stride = cairo_image_surface_get_stride (surface); - modify_image_data (data, width, height, stride); - - // mark the image dirty so Cairo clears its caches. - cairo_surface_mark_dirty (surface); -} -</programlisting> -</example> -<para>Note that for other surface types it might be necessary to acquire the -surface's device first. See <link linkend="cairo-device-acquire"><function>cairo_device_acquire()</function></link> for a discussion of -devices.</para> - -</refsect1> -<refsect1 id="cairo-cairo-surface-t.functions_details" role="details"> -<title role="details.title">Functions</title> -<refsect2 id="cairo-surface-create-similar" role="function" condition="since:1.0"> -<title>cairo_surface_create_similar ()</title> -<indexterm zone="cairo-surface-create-similar" role="1.0"><primary sortas="surface_create_similar">cairo_surface_create_similar</primary></indexterm> -<programlisting language="C"><link linkend="cairo-surface-t"><returnvalue>cairo_surface_t</returnvalue></link> * -cairo_surface_create_similar (<parameter><link linkend="cairo-surface-t"><type>cairo_surface_t</type></link> *other</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>Create a new surface that is as compatible as possible with an -existing surface. For example the new surface will have the same -device scale, fallback resolution and font options as -<parameter>other</parameter> -. Generally, the new surface will also use the same backend -as <parameter>other</parameter> -, unless that is not possible for some reason. The type of -the returned surface may be examined with -<link linkend="cairo-surface-get-type"><function>cairo_surface_get_type()</function></link>.</para> -<para>Initially the surface contents are all 0 (transparent if contents -have transparency, black otherwise.)</para> -<para>Use <link linkend="cairo-surface-create-similar-image"><function>cairo_surface_create_similar_image()</function></link> if you need an image surface -which can be painted quickly to the target surface.</para> -<refsect3 id="cairo-surface-create-similar.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>other</para></entry> -<entry role="parameter_description"><para>an existing surface used to select the backend of the new surface</para></entry> -<entry role="parameter_annotations"></entry></row> -<row><entry role="parameter_name"><para>content</para></entry> -<entry role="parameter_description"><para>the content for the new surface</para></entry> -<entry role="parameter_annotations"></entry></row> -<row><entry role="parameter_name"><para>width</para></entry> -<entry role="parameter_description"><para>width of the new surface, (in device-space units)</para></entry> -<entry role="parameter_annotations"></entry></row> -<row><entry role="parameter_name"><para>height</para></entry> -<entry role="parameter_description"><para>height of the new surface (in device-space units)</para></entry> -<entry role="parameter_annotations"></entry></row> -</tbody></tgroup></informaltable> -</refsect3><refsect3 id="cairo-surface-create-similar.returns" role="returns"> -<title>Returns</title> -<para> a pointer to the newly allocated surface. The caller -owns the surface and should call <link linkend="cairo-surface-destroy"><function>cairo_surface_destroy()</function></link> when done -with it.</para> -<para>This function always returns a valid pointer, but it will return a -pointer to a "nil" surface if <parameter>other</parameter> -is already in an error state -or any other error occurs.</para> -</refsect3><para role="since">Since: <link linkend="api-index-1.0">1.0</link></para></refsect2> -<refsect2 id="cairo-surface-create-similar-image" role="function" condition="since:1.12"> -<title>cairo_surface_create_similar_image ()</title> -<indexterm zone="cairo-surface-create-similar-image" role="1.12"><primary sortas="surface_create_similar_image">cairo_surface_create_similar_image</primary></indexterm> -<programlisting language="C"><link linkend="cairo-surface-t"><returnvalue>cairo_surface_t</returnvalue></link> * -cairo_surface_create_similar_image (<parameter><link linkend="cairo-surface-t"><type>cairo_surface_t</type></link> *other</parameter>, - <parameter><link linkend="cairo-format-t"><type>cairo_format_t</type></link> format</parameter>, - <parameter><link linkend="int"><type>int</type></link> width</parameter>, - <parameter><link linkend="int"><type>int</type></link> height</parameter>);</programlisting> -<para>Create a new image surface that is as compatible as possible for uploading -to and the use in conjunction with an existing surface. However, this surface -can still be used like any normal image surface. Unlike -<link linkend="cairo-surface-create-similar"><function>cairo_surface_create_similar()</function></link> the new image surface won't inherit -the device scale from <parameter>other</parameter> -.</para> -<para>Initially the surface contents are all 0 (transparent if contents -have transparency, black otherwise.)</para> -<para>Use <link linkend="cairo-surface-create-similar"><function>cairo_surface_create_similar()</function></link> if you don't need an image surface.</para> -<refsect3 id="cairo-surface-create-similar-image.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>other</para></entry> -<entry role="parameter_description"><para>an existing surface used to select the preference of the new surface</para></entry> -<entry role="parameter_annotations"></entry></row> -<row><entry role="parameter_name"><para>format</para></entry> -<entry role="parameter_description"><para>the format for the new surface</para></entry> -<entry role="parameter_annotations"></entry></row> -<row><entry role="parameter_name"><para>width</para></entry> -<entry role="parameter_description"><para>width of the new surface, (in pixels)</para></entry> -<entry role="parameter_annotations"></entry></row> -<row><entry role="parameter_name"><para>height</para></entry> -<entry role="parameter_description"><para>height of the new surface (in pixels)</para></entry> -<entry role="parameter_annotations"></entry></row> -</tbody></tgroup></informaltable> -</refsect3><refsect3 id="cairo-surface-create-similar-image.returns" role="returns"> -<title>Returns</title> -<para> a pointer to the newly allocated image surface. The caller -owns the surface and should call <link linkend="cairo-surface-destroy"><function>cairo_surface_destroy()</function></link> when done -with it.</para> -<para>This function always returns a valid pointer, but it will return a -pointer to a "nil" surface if <parameter>other</parameter> -is already in an error state -or any other error occurs.</para> -</refsect3><para role="since">Since: <link linkend="api-index-1.12">1.12</link></para></refsect2> -<refsect2 id="cairo-surface-create-for-rectangle" role="function" condition="since:1.10"> -<title>cairo_surface_create_for_rectangle ()</title> -<indexterm zone="cairo-surface-create-for-rectangle" role="1.10"><primary sortas="surface_create_for_rectangle">cairo_surface_create_for_rectangle</primary></indexterm> -<programlisting language="C"><link linkend="cairo-surface-t"><returnvalue>cairo_surface_t</returnvalue></link> * -cairo_surface_create_for_rectangle (<parameter><link linkend="cairo-surface-t"><type>cairo_surface_t</type></link> *target</parameter>, - <parameter><link linkend="double"><type>double</type></link> x</parameter>, - <parameter><link linkend="double"><type>double</type></link> y</parameter>, - <parameter><link linkend="double"><type>double</type></link> width</parameter>, - <parameter><link linkend="double"><type>double</type></link> height</parameter>);</programlisting> -<para>Create a new surface that is a rectangle within the target surface. -All operations drawn to this surface are then clipped and translated -onto the target surface. Nothing drawn via this sub-surface outside of -its bounds is drawn onto the target surface, making this a useful method -for passing constrained child surfaces to library routines that draw -directly onto the parent surface, i.e. with no further backend allocations, -double buffering or copies.</para> -<note><para>The semantics of subsurfaces have not been finalized yet -unless the rectangle is in full device units, is contained within -the extents of the target surface, and the target or subsurface's -device transforms are not changed.</para></note> -<refsect3 id="cairo-surface-create-for-rectangle.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>target</para></entry> -<entry role="parameter_description"><para>an existing surface for which the sub-surface will point to</para></entry> -<entry role="parameter_annotations"></entry></row> -<row><entry role="parameter_name"><para>x</para></entry> -<entry role="parameter_description"><para>the x-origin of the sub-surface from the top-left of the target surface (in device-space units)</para></entry> -<entry role="parameter_annotations"></entry></row> -<row><entry role="parameter_name"><para>y</para></entry> -<entry role="parameter_description"><para>the y-origin of the sub-surface from the top-left of the target surface (in device-space units)</para></entry> -<entry role="parameter_annotations"></entry></row> -<row><entry role="parameter_name"><para>width</para></entry> -<entry role="parameter_description"><para>width of the sub-surface (in device-space units)</para></entry> -<entry role="parameter_annotations"></entry></row> -<row><entry role="parameter_name"><para>height</para></entry> -<entry role="parameter_description"><para>height of the sub-surface (in device-space units)</para></entry> -<entry role="parameter_annotations"></entry></row> -</tbody></tgroup></informaltable> -</refsect3><refsect3 id="cairo-surface-create-for-rectangle.returns" role="returns"> -<title>Returns</title> -<para> a pointer to the newly allocated surface. The caller -owns the surface and should call <link linkend="cairo-surface-destroy"><function>cairo_surface_destroy()</function></link> when done -with it.</para> -<para>This function always returns a valid pointer, but it will return a -pointer to a "nil" surface if <parameter>other</parameter> -is already in an error state -or any other error occurs.</para> -</refsect3><para role="since">Since: <link linkend="api-index-1.10">1.10</link></para></refsect2> -<refsect2 id="cairo-surface-reference" role="function" condition="since:1.0"> -<title>cairo_surface_reference ()</title> -<indexterm zone="cairo-surface-reference" role="1.0"><primary sortas="surface_reference">cairo_surface_reference</primary></indexterm> -<programlisting language="C"><link linkend="cairo-surface-t"><returnvalue>cairo_surface_t</returnvalue></link> * -cairo_surface_reference (<parameter><link linkend="cairo-surface-t"><type>cairo_surface_t</type></link> *surface</parameter>);</programlisting> -<para>Increases the reference count on <parameter>surface</parameter> - by one. This prevents -<parameter>surface</parameter> - from being destroyed until a matching call to -<link linkend="cairo-surface-destroy"><function>cairo_surface_destroy()</function></link> is made.</para> -<para>Use <link linkend="cairo-surface-get-reference-count"><function>cairo_surface_get_reference_count()</function></link> to get the number of -references to a <link linkend="cairo-surface-t"><type>cairo_surface_t</type></link>.</para> -<refsect3 id="cairo-surface-reference.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>surface</para></entry> -<entry role="parameter_description"><para>a <link linkend="cairo-surface-t"><type>cairo_surface_t</type></link></para></entry> -<entry role="parameter_annotations"></entry></row> -</tbody></tgroup></informaltable> -</refsect3><refsect3 id="cairo-surface-reference.returns" role="returns"> -<title>Returns</title> -<para> the referenced <link linkend="cairo-surface-t"><type>cairo_surface_t</type></link>.</para> -</refsect3><para role="since">Since: <link linkend="api-index-1.0">1.0</link></para></refsect2> -<refsect2 id="cairo-surface-destroy" role="function" condition="since:1.0"> -<title>cairo_surface_destroy ()</title> -<indexterm zone="cairo-surface-destroy" role="1.0"><primary sortas="surface_destroy">cairo_surface_destroy</primary></indexterm> -<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link> -cairo_surface_destroy (<parameter><link linkend="cairo-surface-t"><type>cairo_surface_t</type></link> *surface</parameter>);</programlisting> -<para>Decreases the reference count on <parameter>surface</parameter> - by one. If the result is -zero, then <parameter>surface</parameter> - and all associated resources are freed. See -<link linkend="cairo-surface-reference"><function>cairo_surface_reference()</function></link>.</para> -<refsect3 id="cairo-surface-destroy.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>surface</para></entry> -<entry role="parameter_description"><para>a <link linkend="cairo-surface-t"><type>cairo_surface_t</type></link></para></entry> -<entry role="parameter_annotations"></entry></row> -</tbody></tgroup></informaltable> -</refsect3><para role="since">Since: <link linkend="api-index-1.0">1.0</link></para></refsect2> -<refsect2 id="cairo-surface-status" role="function" condition="since:1.0"> -<title>cairo_surface_status ()</title> -<indexterm zone="cairo-surface-status" role="1.0"><primary sortas="surface_status">cairo_surface_status</primary></indexterm> -<programlisting language="C"><link linkend="cairo-status-t"><returnvalue>cairo_status_t</returnvalue></link> -cairo_surface_status (<parameter><link linkend="cairo-surface-t"><type>cairo_surface_t</type></link> *surface</parameter>);</programlisting> -<para>Checks whether an error has previously occurred for this -surface.</para> -<refsect3 id="cairo-surface-status.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>surface</para></entry> -<entry role="parameter_description"><para>a <link linkend="cairo-surface-t"><type>cairo_surface_t</type></link></para></entry> -<entry role="parameter_annotations"></entry></row> -</tbody></tgroup></informaltable> -</refsect3><refsect3 id="cairo-surface-status.returns" role="returns"> -<title>Returns</title> -<para> <link linkend="CAIRO-STATUS-SUCCESS:CAPS"><literal>CAIRO_STATUS_SUCCESS</literal></link>, <link linkend="CAIRO-STATUS-NULL-POINTER:CAPS"><literal>CAIRO_STATUS_NULL_POINTER</literal></link>, -<link linkend="CAIRO-STATUS-NO-MEMORY:CAPS"><literal>CAIRO_STATUS_NO_MEMORY</literal></link>, <link linkend="CAIRO-STATUS-READ-ERROR:CAPS"><literal>CAIRO_STATUS_READ_ERROR</literal></link>, -<link linkend="CAIRO-STATUS-INVALID-CONTENT:CAPS"><literal>CAIRO_STATUS_INVALID_CONTENT</literal></link>, <link linkend="CAIRO-STATUS-INVALID-FORMAT:CAPS"><literal>CAIRO_STATUS_INVALID_FORMAT</literal></link>, or -<link linkend="CAIRO-STATUS-INVALID-VISUAL:CAPS"><literal>CAIRO_STATUS_INVALID_VISUAL</literal></link>.</para> -</refsect3><para role="since">Since: <link linkend="api-index-1.0">1.0</link></para></refsect2> -<refsect2 id="cairo-surface-finish" role="function" condition="since:1.0"> -<title>cairo_surface_finish ()</title> -<indexterm zone="cairo-surface-finish" role="1.0"><primary sortas="surface_finish">cairo_surface_finish</primary></indexterm> -<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link> -cairo_surface_finish (<parameter><link linkend="cairo-surface-t"><type>cairo_surface_t</type></link> *surface</parameter>);</programlisting> -<para>This function finishes the surface and drops all references to -external resources. For example, for the Xlib backend it means -that cairo will no longer access the drawable, which can be freed. -After calling <link linkend="cairo-surface-finish"><function>cairo_surface_finish()</function></link> the only valid operations on a -surface are getting and setting user, referencing and -destroying, and flushing and finishing it. -Further drawing to the surface will not affect the -surface but will instead trigger a <link linkend="CAIRO-STATUS-SURFACE-FINISHED:CAPS"><literal>CAIRO_STATUS_SURFACE_FINISHED</literal></link> -error.</para> -<para>When the last call to <link linkend="cairo-surface-destroy"><function>cairo_surface_destroy()</function></link> decreases the -reference count to zero, cairo will call <link linkend="cairo-surface-finish"><function>cairo_surface_finish()</function></link> if -it hasn't been called already, before freeing the resources -associated with the surface.</para> -<refsect3 id="cairo-surface-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>surface</para></entry> -<entry role="parameter_description"><para>the <link linkend="cairo-surface-t"><type>cairo_surface_t</type></link> to finish</para></entry> -<entry role="parameter_annotations"></entry></row> -</tbody></tgroup></informaltable> -</refsect3><para role="since">Since: <link linkend="api-index-1.0">1.0</link></para></refsect2> -<refsect2 id="cairo-surface-flush" role="function" condition="since:1.0"> -<title>cairo_surface_flush ()</title> -<indexterm zone="cairo-surface-flush" role="1.0"><primary sortas="surface_flush">cairo_surface_flush</primary></indexterm> -<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link> -cairo_surface_flush (<parameter><link linkend="cairo-surface-t"><type>cairo_surface_t</type></link> *surface</parameter>);</programlisting> -<para>Do any pending drawing for the surface and also restore any temporary -modifications cairo has made to the surface's state. This function -must be called before switching from drawing on the surface with -cairo to drawing on it directly with native APIs, or accessing its -memory outside of Cairo. If the surface doesn't support direct -access, then this function does nothing.</para> -<refsect3 id="cairo-surface-flush.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>surface</para></entry> -<entry role="parameter_description"><para>a <link linkend="cairo-surface-t"><type>cairo_surface_t</type></link></para></entry> -<entry role="parameter_annotations"></entry></row> -</tbody></tgroup></informaltable> -</refsect3><para role="since">Since: <link linkend="api-index-1.0">1.0</link></para></refsect2> -<refsect2 id="cairo-surface-get-device" role="function" condition="since:1.10"> -<title>cairo_surface_get_device ()</title> -<indexterm zone="cairo-surface-get-device" role="1.10"><primary sortas="surface_get_device">cairo_surface_get_device</primary></indexterm> -<programlisting language="C"><link linkend="cairo-device-t"><returnvalue>cairo_device_t</returnvalue></link> * -cairo_surface_get_device (<parameter><link linkend="cairo-surface-t"><type>cairo_surface_t</type></link> *surface</parameter>);</programlisting> -<para>This function returns the device for a <parameter>surface</parameter> -. -See <link linkend="cairo-device-t"><type>cairo_device_t</type></link>.</para> -<refsect3 id="cairo-surface-get-device.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>surface</para></entry> -<entry role="parameter_description"><para>a <link linkend="cairo-surface-t"><type>cairo_surface_t</type></link></para></entry> -<entry role="parameter_annotations"></entry></row> -</tbody></tgroup></informaltable> -</refsect3><refsect3 id="cairo-surface-get-device.returns" role="returns"> -<title>Returns</title> -<para> The device for <parameter>surface</parameter> -or <link linkend="NULL:CAPS"><literal>NULL</literal></link> if the surface does -not have an associated device.</para> -</refsect3><para role="since">Since: <link linkend="api-index-1.10">1.10</link></para></refsect2> -<refsect2 id="cairo-surface-get-font-options" role="function" condition="since:1.0"> -<title>cairo_surface_get_font_options ()</title> -<indexterm zone="cairo-surface-get-font-options" role="1.0"><primary sortas="surface_get_font_options">cairo_surface_get_font_options</primary></indexterm> -<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link> -cairo_surface_get_font_options (<parameter><link linkend="cairo-surface-t"><type>cairo_surface_t</type></link> *surface</parameter>, - <parameter><link linkend="cairo-font-options-t"><type>cairo_font_options_t</type></link> *options</parameter>);</programlisting> -<para>Retrieves the default font rendering options for the surface. -This allows display surfaces to report the correct subpixel order -for rendering on them, print surfaces to disable hinting of -metrics and so forth. The result can then be used with -<link linkend="cairo-scaled-font-create"><function>cairo_scaled_font_create()</function></link>.</para> -<refsect3 id="cairo-surface-get-font-options.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>surface</para></entry> -<entry role="parameter_description"><para>a <link linkend="cairo-surface-t"><type>cairo_surface_t</type></link></para></entry> -<entry role="parameter_annotations"></entry></row> -<row><entry role="parameter_name"><para>options</para></entry> -<entry role="parameter_description"><para>a <link linkend="cairo-font-options-t"><type>cairo_font_options_t</type></link> object into which to store -the retrieved options. All existing values are overwritten</para></entry> -<entry role="parameter_annotations"></entry></row> -</tbody></tgroup></informaltable> -</refsect3><para role="since">Since: <link linkend="api-index-1.0">1.0</link></para></refsect2> -<refsect2 id="cairo-surface-get-content" role="function" condition="since:1.2"> -<title>cairo_surface_get_content ()</title> -<indexterm zone="cairo-surface-get-content" role="1.2"><primary sortas="surface_get_content">cairo_surface_get_content</primary></indexterm> -<programlisting language="C"><link linkend="cairo-content-t"><returnvalue>cairo_content_t</returnvalue></link> -cairo_surface_get_content (<parameter><link linkend="cairo-surface-t"><type>cairo_surface_t</type></link> *surface</parameter>);</programlisting> -<para>This function returns the content type of <parameter>surface</parameter> - which indicates -whether the surface contains color and/or alpha information. See -<link linkend="cairo-content-t"><type>cairo_content_t</type></link>.</para> -<refsect3 id="cairo-surface-get-content.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>surface</para></entry> -<entry role="parameter_description"><para>a <link linkend="cairo-surface-t"><type>cairo_surface_t</type></link></para></entry> -<entry role="parameter_annotations"></entry></row> -</tbody></tgroup></informaltable> -</refsect3><refsect3 id="cairo-surface-get-content.returns" role="returns"> -<title>Returns</title> -<para> The content type of <parameter>surface</parameter> -.</para> -</refsect3><para role="since">Since: <link linkend="api-index-1.2">1.2</link></para></refsect2> -<refsect2 id="cairo-surface-mark-dirty" role="function" condition="since:1.0"> -<title>cairo_surface_mark_dirty ()</title> -<indexterm zone="cairo-surface-mark-dirty" role="1.0"><primary sortas="surface_mark_dirty">cairo_surface_mark_dirty</primary></indexterm> -<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link> -cairo_surface_mark_dirty (<parameter><link linkend="cairo-surface-t"><type>cairo_surface_t</type></link> *surface</parameter>);</programlisting> -<para>Tells cairo that drawing has been done to surface using means other -than cairo, and that cairo should reread any cached areas. Note -that you must call <link linkend="cairo-surface-flush"><function>cairo_surface_flush()</function></link> before doing such drawing.</para> -<refsect3 id="cairo-surface-mark-dirty.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>surface</para></entry> -<entry role="parameter_description"><para>a <link linkend="cairo-surface-t"><type>cairo_surface_t</type></link></para></entry> -<entry role="parameter_annotations"></entry></row> -</tbody></tgroup></informaltable> -</refsect3><para role="since">Since: <link linkend="api-index-1.0">1.0</link></para></refsect2> -<refsect2 id="cairo-surface-mark-dirty-rectangle" role="function" condition="since:1.0"> -<title>cairo_surface_mark_dirty_rectangle ()</title> -<indexterm zone="cairo-surface-mark-dirty-rectangle" role="1.0"><primary sortas="surface_mark_dirty_rectangle">cairo_surface_mark_dirty_rectangle</primary></indexterm> -<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link> -cairo_surface_mark_dirty_rectangle (<parameter><link linkend="cairo-surface-t"><type>cairo_surface_t</type></link> *surface</parameter>, - <parameter><link linkend="int"><type>int</type></link> x</parameter>, - <parameter><link linkend="int"><type>int</type></link> y</parameter>, - <parameter><link linkend="int"><type>int</type></link> width</parameter>, - <parameter><link linkend="int"><type>int</type></link> height</parameter>);</programlisting> -<para>Like <link linkend="cairo-surface-mark-dirty"><function>cairo_surface_mark_dirty()</function></link>, but drawing has been done only to -the specified rectangle, so that cairo can retain cached contents -for other parts of the surface.</para> -<para>Any cached clip set on the surface will be reset by this function, -to make sure that future cairo calls have the clip set that they -expect.</para> -<refsect3 id="cairo-surface-mark-dirty-rectangle.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>surface</para></entry> -<entry role="parameter_description"><para>a <link linkend="cairo-surface-t"><type>cairo_surface_t</type></link></para></entry> -<entry role="parameter_annotations"></entry></row> -<row><entry role="parameter_name"><para>x</para></entry> -<entry role="parameter_description"><para>X coordinate of dirty rectangle</para></entry> -<entry role="parameter_annotations"></entry></row> -<row><entry role="parameter_name"><para>y</para></entry> -<entry role="parameter_description"><para>Y coordinate of dirty rectangle</para></entry> -<entry role="parameter_annotations"></entry></row> -<row><entry role="parameter_name"><para>width</para></entry> -<entry role="parameter_description"><para>width of dirty rectangle</para></entry> -<entry role="parameter_annotations"></entry></row> -<row><entry role="parameter_name"><para>height</para></entry> -<entry role="parameter_description"><para>height of dirty rectangle</para></entry> -<entry role="parameter_annotations"></entry></row> -</tbody></tgroup></informaltable> -</refsect3><para role="since">Since: <link linkend="api-index-1.0">1.0</link></para></refsect2> -<refsect2 id="cairo-surface-set-device-offset" role="function" condition="since:1.0"> -<title>cairo_surface_set_device_offset ()</title> -<indexterm zone="cairo-surface-set-device-offset" role="1.0"><primary sortas="surface_set_device_offset">cairo_surface_set_device_offset</primary></indexterm> -<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link> -cairo_surface_set_device_offset (<parameter><link linkend="cairo-surface-t"><type>cairo_surface_t</type></link> *surface</parameter>, - <parameter><link linkend="double"><type>double</type></link> x_offset</parameter>, - <parameter><link linkend="double"><type>double</type></link> y_offset</parameter>);</programlisting> -<para>Sets an offset that is added to the device coordinates determined -by the CTM when drawing to <parameter>surface</parameter> -. One use case for this function -is when we want to create a <link linkend="cairo-surface-t"><type>cairo_surface_t</type></link> that redirects drawing -for a portion of an onscreen surface to an offscreen surface in a -way that is completely invisible to the user of the cairo -API. Setting a transformation via <link linkend="cairo-translate"><function>cairo_translate()</function></link> isn't -sufficient to do this, since functions like -<link linkend="cairo-device-to-user"><function>cairo_device_to_user()</function></link> will expose the hidden offset.</para> -<para>Note that the offset affects drawing to the surface as well as -using the surface in a source pattern.</para> -<refsect3 id="cairo-surface-set-device-offset.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>surface</para></entry> -<entry role="parameter_description"><para>a <link linkend="cairo-surface-t"><type>cairo_surface_t</type></link></para></entry> -<entry role="parameter_annotations"></entry></row> -<row><entry role="parameter_name"><para>x_offset</para></entry> -<entry role="parameter_description"><para>the offset in the X direction, in device units</para></entry> -<entry role="parameter_annotations"></entry></row> -<row><entry role="parameter_name"><para>y_offset</para></entry> -<entry role="parameter_description"><para>the offset in the Y direction, in device units</para></entry> -<entry role="parameter_annotations"></entry></row> -</tbody></tgroup></informaltable> -</refsect3><para role="since">Since: <link linkend="api-index-1.0">1.0</link></para></refsect2> -<refsect2 id="cairo-surface-get-device-offset" role="function" condition="since:1.2"> -<title>cairo_surface_get_device_offset ()</title> -<indexterm zone="cairo-surface-get-device-offset" role="1.2"><primary sortas="surface_get_device_offset">cairo_surface_get_device_offset</primary></indexterm> -<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link> -cairo_surface_get_device_offset (<parameter><link linkend="cairo-surface-t"><type>cairo_surface_t</type></link> *surface</parameter>, - <parameter><link linkend="double"><type>double</type></link> *x_offset</parameter>, - <parameter><link linkend="double"><type>double</type></link> *y_offset</parameter>);</programlisting> -<para>This function returns the previous device offset set by -<link linkend="cairo-surface-set-device-offset"><function>cairo_surface_set_device_offset()</function></link>.</para> -<refsect3 id="cairo-surface-get-device-offset.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>surface</para></entry> -<entry role="parameter_description"><para>a <link linkend="cairo-surface-t"><type>cairo_surface_t</type></link></para></entry> -<entry role="parameter_annotations"></entry></row> -<row><entry role="parameter_name"><para>x_offset</para></entry> -<entry role="parameter_description"><para>the offset in the X direction, in device units</para></entry> -<entry role="parameter_annotations"></entry></row> -<row><entry role="parameter_name"><para>y_offset</para></entry> -<entry role="parameter_description"><para>the offset in the Y direction, in device units</para></entry> -<entry role="parameter_annotations"></entry></row> -</tbody></tgroup></informaltable> -</refsect3><para role="since">Since: <link linkend="api-index-1.2">1.2</link></para></refsect2> -<refsect2 id="cairo-surface-get-device-scale" role="function" condition="since:1.14"> -<title>cairo_surface_get_device_scale ()</title> -<indexterm zone="cairo-surface-get-device-scale" role="1.14"><primary sortas="surface_get_device_scale">cairo_surface_get_device_scale</primary></indexterm> -<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link> -cairo_surface_get_device_scale (<parameter><link linkend="cairo-surface-t"><type>cairo_surface_t</type></link> *surface</parameter>, - <parameter><link linkend="double"><type>double</type></link> *x_scale</parameter>, - <parameter><link linkend="double"><type>double</type></link> *y_scale</parameter>);</programlisting> -<para>This function returns the previous device offset set by -<link linkend="cairo-surface-set-device-scale"><function>cairo_surface_set_device_scale()</function></link>.</para> -<refsect3 id="cairo-surface-get-device-scale.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>surface</para></entry> -<entry role="parameter_description"><para>a <link linkend="cairo-surface-t"><type>cairo_surface_t</type></link></para></entry> -<entry role="parameter_annotations"></entry></row> -<row><entry role="parameter_name"><para>x_scale</para></entry> -<entry role="parameter_description"><para>the scale in the X direction, in device units</para></entry> -<entry role="parameter_annotations"></entry></row> -<row><entry role="parameter_name"><para>y_scale</para></entry> -<entry role="parameter_description"><para>the scale in the Y direction, in device units</para></entry> -<entry role="parameter_annotations"></entry></row> -</tbody></tgroup></informaltable> -</refsect3><para role="since">Since: <link linkend="api-index-1.14">1.14</link></para></refsect2> -<refsect2 id="cairo-surface-set-device-scale" role="function" condition="since:1.14"> -<title>cairo_surface_set_device_scale ()</title> -<indexterm zone="cairo-surface-set-device-scale" role="1.14"><primary sortas="surface_set_device_scale">cairo_surface_set_device_scale</primary></indexterm> -<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link> -cairo_surface_set_device_scale (<parameter><link linkend="cairo-surface-t"><type>cairo_surface_t</type></link> *surface</parameter>, - <parameter><link linkend="double"><type>double</type></link> x_scale</parameter>, - <parameter><link linkend="double"><type>double</type></link> y_scale</parameter>);</programlisting> -<para>Sets a scale that is multiplied to the device coordinates determined -by the CTM when drawing to <parameter>surface</parameter> -. One common use for this is to -render to very high resolution display devices at a scale factor, so -that code that assumes 1 pixel will be a certain size will still work. -Setting a transformation via <link linkend="cairo-translate"><function>cairo_translate()</function></link> isn't -sufficient to do this, since functions like -<link linkend="cairo-device-to-user"><function>cairo_device_to_user()</function></link> will expose the hidden scale.</para> -<para>Note that the scale affects drawing to the surface as well as -using the surface in a source pattern.</para> -<refsect3 id="cairo-surface-set-device-scale.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>surface</para></entry> -<entry role="parameter_description"><para>a <link linkend="cairo-surface-t"><type>cairo_surface_t</type></link></para></entry> -<entry role="parameter_annotations"></entry></row> -<row><entry role="parameter_name"><para>x_scale</para></entry> -<entry role="parameter_description"><para>a scale factor in the X direction</para></entry> -<entry role="parameter_annotations"></entry></row> -<row><entry role="parameter_name"><para>y_scale</para></entry> -<entry role="parameter_description"><para>a scale factor in the Y direction</para></entry> -<entry role="parameter_annotations"></entry></row> -</tbody></tgroup></informaltable> -</refsect3><para role="since">Since: <link linkend="api-index-1.14">1.14</link></para></refsect2> -<refsect2 id="cairo-surface-set-fallback-resolution" role="function" condition="since:1.2"> -<title>cairo_surface_set_fallback_resolution ()</title> -<indexterm zone="cairo-surface-set-fallback-resolution" role="1.2"><primary sortas="surface_set_fallback_resolution">cairo_surface_set_fallback_resolution</primary></indexterm> -<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link> -cairo_surface_set_fallback_resolution (<parameter><link linkend="cairo-surface-t"><type>cairo_surface_t</type></link> *surface</parameter>, - <parameter><link linkend="double"><type>double</type></link> x_pixels_per_inch</parameter>, - <parameter><link linkend="double"><type>double</type></link> y_pixels_per_inch</parameter>);</programlisting> -<para>Set the horizontal and vertical resolution for image fallbacks.</para> -<para>When certain operations aren't supported natively by a backend, -cairo will fallback by rendering operations to an image and then -overlaying that image onto the output. For backends that are -natively vector-oriented, this function can be used to set the -resolution used for these image fallbacks, (larger values will -result in more detailed images, but also larger file sizes).</para> -<para>Some examples of natively vector-oriented backends are the ps, pdf, -and svg backends.</para> -<para>For backends that are natively raster-oriented, image fallbacks are -still possible, but they are always performed at the native -device resolution. So this function has no effect on those -backends.</para> -<para>Note: The fallback resolution only takes effect at the time of -completing a page (with <link linkend="cairo-show-page"><function>cairo_show_page()</function></link> or <link linkend="cairo-copy-page"><function>cairo_copy_page()</function></link>) so -there is currently no way to have more than one fallback resolution -in effect on a single page.</para> -<para>The default fallback resoultion is 300 pixels per inch in both -dimensions.</para> -<refsect3 id="cairo-surface-set-fallback-resolution.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>surface</para></entry> -<entry role="parameter_description"><para>a <link linkend="cairo-surface-t"><type>cairo_surface_t</type></link></para></entry> -<entry role="parameter_annotations"></entry></row> -<row><entry role="parameter_name"><para>x_pixels_per_inch</para></entry> -<entry role="parameter_description"><para>horizontal setting for pixels per inch</para></entry> -<entry role="parameter_annotations"></entry></row> -<row><entry role="parameter_name"><para>y_pixels_per_inch</para></entry> -<entry role="parameter_description"><para>vertical setting for pixels per inch</para></entry> -<entry role="parameter_annotations"></entry></row> -</tbody></tgroup></informaltable> -</refsect3><para role="since">Since: <link linkend="api-index-1.2">1.2</link></para></refsect2> -<refsect2 id="cairo-surface-get-fallback-resolution" role="function" condition="since:1.8"> -<title>cairo_surface_get_fallback_resolution ()</title> -<indexterm zone="cairo-surface-get-fallback-resolution" role="1.8"><primary sortas="surface_get_fallback_resolution">cairo_surface_get_fallback_resolution</primary></indexterm> -<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link> -cairo_surface_get_fallback_resolution (<parameter><link linkend="cairo-surface-t"><type>cairo_surface_t</type></link> *surface</parameter>, - <parameter><link linkend="double"><type>double</type></link> *x_pixels_per_inch</parameter>, - <parameter><link linkend="double"><type>double</type></link> *y_pixels_per_inch</parameter>);</programlisting> -<para>This function returns the previous fallback resolution set by -<link linkend="cairo-surface-set-fallback-resolution"><function>cairo_surface_set_fallback_resolution()</function></link>, or default fallback -resolution if never set.</para> -<refsect3 id="cairo-surface-get-fallback-resolution.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>surface</para></entry> -<entry role="parameter_description"><para>a <link linkend="cairo-surface-t"><type>cairo_surface_t</type></link></para></entry> -<entry role="parameter_annotations"></entry></row> -<row><entry role="parameter_name"><para>x_pixels_per_inch</para></entry> -<entry role="parameter_description"><para>horizontal pixels per inch</para></entry> -<entry role="parameter_annotations"></entry></row> -<row><entry role="parameter_name"><para>y_pixels_per_inch</para></entry> -<entry role="parameter_description"><para>vertical pixels per inch</para></entry> -<entry role="parameter_annotations"></entry></row> -</tbody></tgroup></informaltable> -</refsect3><para role="since">Since: <link linkend="api-index-1.8">1.8</link></para></refsect2> -<refsect2 id="cairo-surface-get-type" role="function" condition="since:1.2"> -<title>cairo_surface_get_type ()</title> -<indexterm zone="cairo-surface-get-type" role="1.2"><primary sortas="surface_get_type">cairo_surface_get_type</primary></indexterm> -<programlisting language="C"><link linkend="cairo-surface-type-t"><returnvalue>cairo_surface_type_t</returnvalue></link> -cairo_surface_get_type (<parameter><link linkend="cairo-surface-t"><type>cairo_surface_t</type></link> *surface</parameter>);</programlisting> -<para>This function returns the type of the backend used to create -a surface. See <link linkend="cairo-surface-type-t"><type>cairo_surface_type_t</type></link> for available types.</para> -<refsect3 id="cairo-surface-get-type.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>surface</para></entry> -<entry role="parameter_description"><para>a <link linkend="cairo-surface-t"><type>cairo_surface_t</type></link></para></entry> -<entry role="parameter_annotations"></entry></row> -</tbody></tgroup></informaltable> -</refsect3><refsect3 id="cairo-surface-get-type.returns" role="returns"> -<title>Returns</title> -<para> The type of <parameter>surface</parameter> -.</para> -</refsect3><para role="since">Since: <link linkend="api-index-1.2">1.2</link></para></refsect2> -<refsect2 id="cairo-surface-get-reference-count" role="function" condition="since:1.4"> -<title>cairo_surface_get_reference_count ()</title> -<indexterm zone="cairo-surface-get-reference-count" role="1.4"><primary sortas="surface_get_reference_count">cairo_surface_get_reference_count</primary></indexterm> -<programlisting language="C">unsigned <link linkend="int"><returnvalue>int</returnvalue></link> -cairo_surface_get_reference_count (<parameter><link linkend="cairo-surface-t"><type>cairo_surface_t</type></link> *surface</parameter>);</programlisting> -<para>Returns the current reference count of <parameter>surface</parameter> -.</para> -<refsect3 id="cairo-surface-get-reference-count.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>surface</para></entry> -<entry role="parameter_description"><para>a <link linkend="cairo-surface-t"><type>cairo_surface_t</type></link></para></entry> -<entry role="parameter_annotations"></entry></row> -</tbody></tgroup></informaltable> -</refsect3><refsect3 id="cairo-surface-get-reference-count.returns" role="returns"> -<title>Returns</title> -<para> the current reference count of <parameter>surface</parameter> -. If the -object is a nil object, 0 will be returned.</para> -</refsect3><para role="since">Since: <link linkend="api-index-1.4">1.4</link></para></refsect2> -<refsect2 id="cairo-surface-set-user-data" role="function" condition="since:1.0"> -<title>cairo_surface_set_user_data ()</title> -<indexterm zone="cairo-surface-set-user-data" role="1.0"><primary sortas="surface_set_user_data">cairo_surface_set_user_data</primary></indexterm> -<programlisting language="C"><link linkend="cairo-status-t"><returnvalue>cairo_status_t</returnvalue></link> -cairo_surface_set_user_data (<parameter><link linkend="cairo-surface-t"><type>cairo_surface_t</type></link> *surface</parameter>, - <parameter>const <link linkend="cairo-user-data-key-t"><type>cairo_user_data_key_t</type></link> *key</parameter>, - <parameter><link linkend="void"><type>void</type></link> *user_data</parameter>, - <parameter><link linkend="cairo-destroy-func-t"><type>cairo_destroy_func_t</type></link> destroy</parameter>);</programlisting> -<para>Attach user data to <parameter>surface</parameter> -. To remove user data from a surface, -call this function with the key that was used to set it and <link linkend="NULL:CAPS"><literal>NULL</literal></link> -for <parameter>data</parameter> -.</para> -<refsect3 id="cairo-surface-set-user-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>surface</para></entry> -<entry role="parameter_description"><para>a <link linkend="cairo-surface-t"><type>cairo_surface_t</type></link></para></entry> -<entry role="parameter_annotations"></entry></row> -<row><entry role="parameter_name"><para>key</para></entry> -<entry role="parameter_description"><para>the address of a <link linkend="cairo-user-data-key-t"><type>cairo_user_data_key_t</type></link> to attach the user data to</para></entry> -<entry role="parameter_annotations"></entry></row> -<row><entry role="parameter_name"><para>user_data</para></entry> -<entry role="parameter_description"><para>the user data to attach to the surface</para></entry> -<entry role="parameter_annotations"></entry></row> -<row><entry role="parameter_name"><para>destroy</para></entry> -<entry role="parameter_description"><para>a <link linkend="cairo-destroy-func-t"><type>cairo_destroy_func_t</type></link> which will be called when the -surface is destroyed or when new user data is attached using the -same key.</para></entry> -<entry role="parameter_annotations"></entry></row> -</tbody></tgroup></informaltable> -</refsect3><refsect3 id="cairo-surface-set-user-data.returns" role="returns"> -<title>Returns</title> -<para> <link linkend="CAIRO-STATUS-SUCCESS:CAPS"><literal>CAIRO_STATUS_SUCCESS</literal></link> or <link linkend="CAIRO-STATUS-NO-MEMORY:CAPS"><literal>CAIRO_STATUS_NO_MEMORY</literal></link> if a -slot could not be allocated for the user data.</para> -</refsect3><para role="since">Since: <link linkend="api-index-1.0">1.0</link></para></refsect2> -<refsect2 id="cairo-surface-get-user-data" role="function" condition="since:1.0"> -<title>cairo_surface_get_user_data ()</title> -<indexterm zone="cairo-surface-get-user-data" role="1.0"><primary sortas="surface_get_user_data">cairo_surface_get_user_data</primary></indexterm> -<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link> * -cairo_surface_get_user_data (<parameter><link linkend="cairo-surface-t"><type>cairo_surface_t</type></link> *surface</parameter>, - <parameter>const <link linkend="cairo-user-data-key-t"><type>cairo_user_data_key_t</type></link> *key</parameter>);</programlisting> -<para>Return user data previously attached to <parameter>surface</parameter> - using the specified -key. If no user data has been attached with the given key this -function returns <link linkend="NULL:CAPS"><literal>NULL</literal></link>.</para> -<refsect3 id="cairo-surface-get-user-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>surface</para></entry> -<entry role="parameter_description"><para>a <link linkend="cairo-surface-t"><type>cairo_surface_t</type></link></para></entry> -<entry role="parameter_annotations"></entry></row> -<row><entry role="parameter_name"><para>key</para></entry> -<entry role="parameter_description"><para>the address of the <link linkend="cairo-user-data-key-t"><type>cairo_user_data_key_t</type></link> the user data was -attached to</para></entry> -<entry role="parameter_annotations"></entry></row> -</tbody></tgroup></informaltable> -</refsect3><refsect3 id="cairo-surface-get-user-data.returns" role="returns"> -<title>Returns</title> -<para> the user data previously attached or <link linkend="NULL:CAPS"><literal>NULL</literal></link>.</para> -</refsect3><para role="since">Since: <link linkend="api-index-1.0">1.0</link></para></refsect2> -<refsect2 id="cairo-surface-copy-page" role="function" condition="since:1.6"> -<title>cairo_surface_copy_page ()</title> -<indexterm zone="cairo-surface-copy-page" role="1.6"><primary sortas="surface_copy_page">cairo_surface_copy_page</primary></indexterm> -<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link> -cairo_surface_copy_page (<parameter><link linkend="cairo-surface-t"><type>cairo_surface_t</type></link> *surface</parameter>);</programlisting> -<para>Emits the current page for backends that support multiple pages, -but doesn't clear it, so that the contents of the current page will -be retained for the next page. Use <link linkend="cairo-surface-show-page"><function>cairo_surface_show_page()</function></link> if you -want to get an empty page after the emission.</para> -<para>There is a convenience function for this that takes a <link linkend="cairo-t"><type>cairo_t</type></link>, -namely <link linkend="cairo-copy-page"><function>cairo_copy_page()</function></link>.</para> -<refsect3 id="cairo-surface-copy-page.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>surface</para></entry> -<entry role="parameter_description"><para>a <link linkend="cairo-surface-t"><type>cairo_surface_t</type></link></para></entry> -<entry role="parameter_annotations"></entry></row> -</tbody></tgroup></informaltable> -</refsect3><para role="since">Since: <link linkend="api-index-1.6">1.6</link></para></refsect2> -<refsect2 id="cairo-surface-show-page" role="function" condition="since:1.6"> -<title>cairo_surface_show_page ()</title> -<indexterm zone="cairo-surface-show-page" role="1.6"><primary sortas="surface_show_page">cairo_surface_show_page</primary></indexterm> -<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link> -cairo_surface_show_page (<parameter><link linkend="cairo-surface-t"><type>cairo_surface_t</type></link> *surface</parameter>);</programlisting> -<para>Emits and clears the current page for backends that support multiple -pages. Use <link linkend="cairo-surface-copy-page"><function>cairo_surface_copy_page()</function></link> if you don't want to clear the page.</para> -<para>There is a convenience function for this that takes a <link linkend="cairo-t"><type>cairo_t</type></link>, -namely <link linkend="cairo-show-page"><function>cairo_show_page()</function></link>.</para> -<refsect3 id="cairo-surface-show-page.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>surface</para></entry> -<entry role="parameter_description"><para>a <link linkend="cairo-Surface-t"><type>cairo_Surface_t</type></link></para></entry> -<entry role="parameter_annotations"></entry></row> -</tbody></tgroup></informaltable> -</refsect3><para role="since">Since: <link linkend="api-index-1.6">1.6</link></para></refsect2> -<refsect2 id="cairo-surface-has-show-text-glyphs" role="function" condition="since:1.8"> -<title>cairo_surface_has_show_text_glyphs ()</title> -<indexterm zone="cairo-surface-has-show-text-glyphs" role="1.8"><primary sortas="surface_has_show_text_glyphs">cairo_surface_has_show_text_glyphs</primary></indexterm> -<programlisting language="C"><link linkend="cairo-bool-t"><returnvalue>cairo_bool_t</returnvalue></link> -cairo_surface_has_show_text_glyphs (<parameter><link linkend="cairo-surface-t"><type>cairo_surface_t</type></link> *surface</parameter>);</programlisting> -<para>Returns whether the surface supports -sophisticated <link linkend="cairo-show-text-glyphs"><function>cairo_show_text_glyphs()</function></link> operations. That is, -whether it actually uses the provided text and cluster data -to a <link linkend="cairo-show-text-glyphs"><function>cairo_show_text_glyphs()</function></link> call.</para> -<para>Note: Even if this function returns <link linkend="FALSE:CAPS"><literal>FALSE</literal></link>, a -<link linkend="cairo-show-text-glyphs"><function>cairo_show_text_glyphs()</function></link> operation targeted at <parameter>surface</parameter> - will -still succeed. It just will -act like a <link linkend="cairo-show-glyphs"><function>cairo_show_glyphs()</function></link> operation. Users can use this -function to avoid computing UTF-8 text and cluster mapping if the -target surface does not use it.</para> -<refsect3 id="cairo-surface-has-show-text-glyphs.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>surface</para></entry> -<entry role="parameter_description"><para>a <link linkend="cairo-surface-t"><type>cairo_surface_t</type></link></para></entry> -<entry role="parameter_annotations"></entry></row> -</tbody></tgroup></informaltable> -</refsect3><refsect3 id="cairo-surface-has-show-text-glyphs.returns" role="returns"> -<title>Returns</title> -<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if <parameter>surface</parameter> -supports -<link linkend="cairo-show-text-glyphs"><function>cairo_show_text_glyphs()</function></link>, <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> otherwise</para> -</refsect3><para role="since">Since: <link linkend="api-index-1.8">1.8</link></para></refsect2> -<refsect2 id="cairo-surface-set-mime-data" role="function" condition="since:1.10"> -<title>cairo_surface_set_mime_data ()</title> -<indexterm zone="cairo-surface-set-mime-data" role="1.10"><primary sortas="surface_set_mime_data">cairo_surface_set_mime_data</primary></indexterm> -<programlisting language="C"><link linkend="cairo-status-t"><returnvalue>cairo_status_t</returnvalue></link> -cairo_surface_set_mime_data (<parameter><link linkend="cairo-surface-t"><type>cairo_surface_t</type></link> *surface</parameter>, - <parameter>const <link linkend="char"><type>char</type></link> *mime_type</parameter>, - <parameter>const unsigned <link linkend="char"><type>char</type></link> *data</parameter>, - <parameter><type>unsigned long </type> length</parameter>, - <parameter><link linkend="cairo-destroy-func-t"><type>cairo_destroy_func_t</type></link> destroy</parameter>, - <parameter><link linkend="void"><type>void</type></link> *closure</parameter>);</programlisting> -<para>Attach an image in the format <parameter>mime_type</parameter> - to <parameter>surface</parameter> -. To remove -the data from a surface, call this function with same mime type -and <link linkend="NULL:CAPS"><literal>NULL</literal></link> for <parameter>data</parameter> -.</para> -<para>The attached image (or filename) data can later be used by backends -which support it (currently: PDF, PS, SVG and Win32 Printing -surfaces) to emit this data instead of making a snapshot of the -<parameter>surface</parameter> -. This approach tends to be faster and requires less -memory and disk space.</para> -<para>The recognized MIME types are the following: <link linkend="CAIRO-MIME-TYPE-JPEG:CAPS"><literal>CAIRO_MIME_TYPE_JPEG</literal></link>, -<link linkend="CAIRO-MIME-TYPE-PNG:CAPS"><literal>CAIRO_MIME_TYPE_PNG</literal></link>, <link linkend="CAIRO-MIME-TYPE-JP2:CAPS"><literal>CAIRO_MIME_TYPE_JP2</literal></link>, <link linkend="CAIRO-MIME-TYPE-URI:CAPS"><literal>CAIRO_MIME_TYPE_URI</literal></link>, -<link linkend="CAIRO-MIME-TYPE-UNIQUE-ID:CAPS"><literal>CAIRO_MIME_TYPE_UNIQUE_ID</literal></link>, <link linkend="CAIRO-MIME-TYPE-JBIG2:CAPS"><literal>CAIRO_MIME_TYPE_JBIG2</literal></link>, -<link linkend="CAIRO-MIME-TYPE-JBIG2-GLOBAL:CAPS"><literal>CAIRO_MIME_TYPE_JBIG2_GLOBAL</literal></link>, <link linkend="CAIRO-MIME-TYPE-JBIG2-GLOBAL-ID:CAPS"><literal>CAIRO_MIME_TYPE_JBIG2_GLOBAL_ID</literal></link>, -<link linkend="CAIRO-MIME-TYPE-CCITT-FAX:CAPS"><literal>CAIRO_MIME_TYPE_CCITT_FAX</literal></link>, <link linkend="CAIRO-MIME-TYPE-CCITT-FAX-PARAMS:CAPS"><literal>CAIRO_MIME_TYPE_CCITT_FAX_PARAMS</literal></link>.</para> -<para>See corresponding backend surface docs for details about which MIME -types it can handle. Caution: the associated MIME data will be -discarded if you draw on the surface afterwards. Use this function -with care.</para> -<para>Even if a backend supports a MIME type, that does not mean cairo -will always be able to use the attached MIME data. For example, if -the backend does not natively support the compositing operation used -to apply the MIME data to the backend. In that case, the MIME data -will be ignored. Therefore, to apply an image in all cases, it is best -to create an image surface which contains the decoded image data and -then attach the MIME data to that. This ensures the image will always -be used while still allowing the MIME data to be used whenever -possible.</para> -<refsect3 id="cairo-surface-set-mime-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>surface</para></entry> -<entry role="parameter_description"><para>a <link linkend="cairo-surface-t"><type>cairo_surface_t</type></link></para></entry> -<entry role="parameter_annotations"></entry></row> -<row><entry role="parameter_name"><para>mime_type</para></entry> -<entry role="parameter_description"><para>the MIME type of the image data</para></entry> -<entry role="parameter_annotations"></entry></row> -<row><entry role="parameter_name"><para>data</para></entry> -<entry role="parameter_description"><para>the image data to attach to the surface</para></entry> -<entry role="parameter_annotations"></entry></row> -<row><entry role="parameter_name"><para>length</para></entry> -<entry role="parameter_description"><para>the length of the image data</para></entry> -<entry role="parameter_annotations"></entry></row> -<row><entry role="parameter_name"><para>destroy</para></entry> -<entry role="parameter_description"><para>a <link linkend="cairo-destroy-func-t"><type>cairo_destroy_func_t</type></link> which will be called when the -surface is destroyed or when new image data is attached using the -same mime type.</para></entry> -<entry role="parameter_annotations"></entry></row> -<row><entry role="parameter_name"><para>closure</para></entry> -<entry role="parameter_description"><para>the data to be passed to the <parameter>destroy</parameter> -notifier</para></entry> -<entry role="parameter_annotations"></entry></row> -</tbody></tgroup></informaltable> -</refsect3><refsect3 id="cairo-surface-set-mime-data.returns" role="returns"> -<title>Returns</title> -<para> <link linkend="CAIRO-STATUS-SUCCESS:CAPS"><literal>CAIRO_STATUS_SUCCESS</literal></link> or <link linkend="CAIRO-STATUS-NO-MEMORY:CAPS"><literal>CAIRO_STATUS_NO_MEMORY</literal></link> if a -slot could not be allocated for the user data.</para> -</refsect3><para role="since">Since: <link linkend="api-index-1.10">1.10</link></para></refsect2> -<refsect2 id="cairo-surface-get-mime-data" role="function" condition="since:1.10"> -<title>cairo_surface_get_mime_data ()</title> -<indexterm zone="cairo-surface-get-mime-data" role="1.10"><primary sortas="surface_get_mime_data">cairo_surface_get_mime_data</primary></indexterm> -<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link> -cairo_surface_get_mime_data (<parameter><link linkend="cairo-surface-t"><type>cairo_surface_t</type></link> *surface</parameter>, - <parameter>const <link linkend="char"><type>char</type></link> *mime_type</parameter>, - <parameter>const unsigned <link linkend="char"><type>char</type></link> **data</parameter>, - <parameter>unsigned <link linkend="long"><type>long</type></link> *length</parameter>);</programlisting> -<para>Return mime data previously attached to <parameter>surface</parameter> - using the -specified mime type. If no data has been attached with the given -mime type, <parameter>data</parameter> - is set <link linkend="NULL:CAPS"><literal>NULL</literal></link>.</para> -<refsect3 id="cairo-surface-get-mime-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>surface</para></entry> -<entry role="parameter_description"><para>a <link linkend="cairo-surface-t"><type>cairo_surface_t</type></link></para></entry> -<entry role="parameter_annotations"></entry></row> -<row><entry role="parameter_name"><para>mime_type</para></entry> -<entry role="parameter_description"><para>the mime type of the image data</para></entry> -<entry role="parameter_annotations"></entry></row> -<row><entry role="parameter_name"><para>data</para></entry> -<entry role="parameter_description"><para>the image data to attached to the surface</para></entry> -<entry role="parameter_annotations"></entry></row> -<row><entry role="parameter_name"><para>length</para></entry> -<entry role="parameter_description"><para>the length of the image data</para></entry> -<entry role="parameter_annotations"></entry></row> -</tbody></tgroup></informaltable> -</refsect3><para role="since">Since: <link linkend="api-index-1.10">1.10</link></para></refsect2> -<refsect2 id="cairo-surface-supports-mime-type" role="function" condition="since:1.12"> -<title>cairo_surface_supports_mime_type ()</title> -<indexterm zone="cairo-surface-supports-mime-type" role="1.12"><primary sortas="surface_supports_mime_type">cairo_surface_supports_mime_type</primary></indexterm> -<programlisting language="C"><link linkend="cairo-bool-t"><returnvalue>cairo_bool_t</returnvalue></link> -cairo_surface_supports_mime_type (<parameter><link linkend="cairo-surface-t"><type>cairo_surface_t</type></link> *surface</parameter>, - <parameter>const <link linkend="char"><type>char</type></link> *mime_type</parameter>);</programlisting> -<para>Return whether <parameter>surface</parameter> - supports <parameter>mime_type</parameter> -.</para> -<refsect3 id="cairo-surface-supports-mime-type.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>surface</para></entry> -<entry role="parameter_description"><para>a <link linkend="cairo-surface-t"><type>cairo_surface_t</type></link></para></entry> -<entry role="parameter_annotations"></entry></row> -<row><entry role="parameter_name"><para>mime_type</para></entry> -<entry role="parameter_description"><para>the mime type</para></entry> -<entry role="parameter_annotations"></entry></row> -</tbody></tgroup></informaltable> -</refsect3><refsect3 id="cairo-surface-supports-mime-type.returns" role="returns"> -<title>Returns</title> -<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if <parameter>surface</parameter> -supports -<parameter>mime_type</parameter> -, <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> otherwise</para> -</refsect3><para role="since">Since: <link linkend="api-index-1.12">1.12</link></para></refsect2> -<refsect2 id="cairo-surface-map-to-image" role="function" condition="since:1.12"> -<title>cairo_surface_map_to_image ()</title> -<indexterm zone="cairo-surface-map-to-image" role="1.12"><primary sortas="surface_map_to_image">cairo_surface_map_to_image</primary></indexterm> -<programlisting language="C"><link linkend="cairo-surface-t"><returnvalue>cairo_surface_t</returnvalue></link> * -cairo_surface_map_to_image (<parameter><link linkend="cairo-surface-t"><type>cairo_surface_t</type></link> *surface</parameter>, - <parameter>const <link linkend="cairo-rectangle-int-t"><type>cairo_rectangle_int_t</type></link> *extents</parameter>);</programlisting> -<para>Returns an image surface that is the most efficient mechanism for -modifying the backing store of the target surface. The region retrieved -may be limited to the <parameter>extents</parameter> - or <link linkend="NULL:CAPS"><literal>NULL</literal></link> for the whole surface</para> -<para>Note, the use of the original surface as a target or source whilst -it is mapped is undefined. The result of mapping the surface -multiple times is undefined. Calling <link linkend="cairo-surface-destroy"><function>cairo_surface_destroy()</function></link> or -<link linkend="cairo-surface-finish"><function>cairo_surface_finish()</function></link> on the resulting image surface results in -undefined behavior. Changing the device transform of the image -surface or of <parameter>surface</parameter> - before the image surface is unmapped results -in undefined behavior.</para> -<refsect3 id="cairo-surface-map-to-image.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>surface</para></entry> -<entry role="parameter_description"><para>an existing surface used to extract the image from</para></entry> -<entry role="parameter_annotations"></entry></row> -<row><entry role="parameter_name"><para>extents</para></entry> -<entry role="parameter_description"><para>limit the extraction to an rectangular region</para></entry> -<entry role="parameter_annotations"></entry></row> -</tbody></tgroup></informaltable> -</refsect3><refsect3 id="cairo-surface-map-to-image.returns" role="returns"> -<title>Returns</title> -<para> a pointer to the newly allocated image surface. The caller -must use <link linkend="cairo-surface-unmap-image"><function>cairo_surface_unmap_image()</function></link> to destroy this image surface.</para> -<para>This function always returns a valid pointer, but it will return a -pointer to a "nil" surface if <parameter>other</parameter> -is already in an error state -or any other error occurs. If the returned pointer does not have an -error status, it is guaranteed to be an image surface whose format -is not <link linkend="CAIRO-FORMAT-INVALID:CAPS"><literal>CAIRO_FORMAT_INVALID</literal></link>.</para> -</refsect3><para role="since">Since: <link linkend="api-index-1.12">1.12</link></para></refsect2> -<refsect2 id="cairo-surface-unmap-image" role="function" condition="since:1.12"> -<title>cairo_surface_unmap_image ()</title> -<indexterm zone="cairo-surface-unmap-image" role="1.12"><primary sortas="surface_unmap_image">cairo_surface_unmap_image</primary></indexterm> -<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link> -cairo_surface_unmap_image (<parameter><link linkend="cairo-surface-t"><type>cairo_surface_t</type></link> *surface</parameter>, - <parameter><link linkend="cairo-surface-t"><type>cairo_surface_t</type></link> *image</parameter>);</programlisting> -<para>Unmaps the image surface as returned from <link linkend="cairo-surface-map-to-image"><function><link linkend="cairo-surface-map-to-image"><function>cairo_surface_map_to_image()</function></link></function></link>.</para> -<para>The content of the image will be uploaded to the target surface. -Afterwards, the image is destroyed.</para> -<para>Using an image surface which wasn't returned by <link linkend="cairo-surface-map-to-image"><function>cairo_surface_map_to_image()</function></link> -results in undefined behavior.</para> -<refsect3 id="cairo-surface-unmap-image.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>surface</para></entry> -<entry role="parameter_description"><para>the surface passed to <link linkend="cairo-surface-map-to-image"><function>cairo_surface_map_to_image()</function></link>.</para></entry> -<entry role="parameter_annotations"></entry></row> -<row><entry role="parameter_name"><para>image</para></entry> -<entry role="parameter_description"><para>the currently mapped image</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-cairo-surface-t.other_details" role="details"> -<title role="details.title">Types and Values</title> -<refsect2 id="CAIRO-HAS-MIME-SURFACE:CAPS" role="macro"> -<title>CAIRO_HAS_MIME_SURFACE</title> -<indexterm zone="CAIRO-HAS-MIME-SURFACE:CAPS"><primary sortas="HAS_MIME_SURFACE">CAIRO_HAS_MIME_SURFACE</primary></indexterm> -<programlisting language="C">#define CAIRO_HAS_MIME_SURFACE 1 -</programlisting> -</refsect2> -<refsect2 id="CAIRO-MIME-TYPE-CCITT-FAX:CAPS" role="macro" condition="since:1.16"> -<title>CAIRO_MIME_TYPE_CCITT_FAX</title> -<indexterm zone="CAIRO-MIME-TYPE-CCITT-FAX:CAPS" role="1.16"><primary sortas="MIME_TYPE_CCITT_FAX">CAIRO_MIME_TYPE_CCITT_FAX</primary></indexterm> -<programlisting language="C">#define CAIRO_MIME_TYPE_CCITT_FAX "image/g3fax" -</programlisting> -<para>Group 3 or Group 4 CCITT facsimile encoding (International -Telecommunication Union, Recommendations T.4 and T.6.)</para> -<para role="since">Since: <link linkend="api-index-1.16">1.16</link></para></refsect2> -<refsect2 id="CAIRO-MIME-TYPE-CCITT-FAX-PARAMS:CAPS" role="macro" condition="since:1.16"> -<title>CAIRO_MIME_TYPE_CCITT_FAX_PARAMS</title> -<indexterm zone="CAIRO-MIME-TYPE-CCITT-FAX-PARAMS:CAPS" role="1.16"><primary sortas="MIME_TYPE_CCITT_FAX_PARAMS">CAIRO_MIME_TYPE_CCITT_FAX_PARAMS</primary></indexterm> -<programlisting language="C">#define CAIRO_MIME_TYPE_CCITT_FAX_PARAMS "application/x-cairo.ccitt.params" -</programlisting> -<para>Decode parameters for Group 3 or Group 4 CCITT facsimile encoding. -See <link linkend="ccitt">CCITT Fax Images</link>.</para> -<para role="since">Since: <link linkend="api-index-1.16">1.16</link></para></refsect2> -<refsect2 id="CAIRO-MIME-TYPE-EPS:CAPS" role="macro" condition="since:1.16"> -<title>CAIRO_MIME_TYPE_EPS</title> -<indexterm zone="CAIRO-MIME-TYPE-EPS:CAPS" role="1.16"><primary sortas="MIME_TYPE_EPS">CAIRO_MIME_TYPE_EPS</primary></indexterm> -<programlisting language="C">#define CAIRO_MIME_TYPE_EPS "application/postscript" -</programlisting> -<para>Encapsulated PostScript file. -<ulink url="http://wwwimages.adobe.com/content/dam/Adobe/endevnet/postscript/pdfs/5002.EPSF_Spec.pdf">Encapsulated PostScript File Format Specification</ulink></para> -<para role="since">Since: <link linkend="api-index-1.16">1.16</link></para></refsect2> -<refsect2 id="CAIRO-MIME-TYPE-EPS-PARAMS:CAPS" role="macro" condition="since:1.16"> -<title>CAIRO_MIME_TYPE_EPS_PARAMS</title> -<indexterm zone="CAIRO-MIME-TYPE-EPS-PARAMS:CAPS" role="1.16"><primary sortas="MIME_TYPE_EPS_PARAMS">CAIRO_MIME_TYPE_EPS_PARAMS</primary></indexterm> -<programlisting language="C">#define CAIRO_MIME_TYPE_EPS_PARAMS "application/x-cairo.eps.params" -</programlisting> -<para>Embedding parameters Encapsulated PostScript data. -See <link linkend="eps">Embedding EPS files</link>.</para> -<para role="since">Since: <link linkend="api-index-1.16">1.16</link></para></refsect2> -<refsect2 id="CAIRO-MIME-TYPE-JBIG2:CAPS" role="macro" condition="since:1.14"> -<title>CAIRO_MIME_TYPE_JBIG2</title> -<indexterm zone="CAIRO-MIME-TYPE-JBIG2:CAPS" role="1.14"><primary sortas="MIME_TYPE_JBIG2">CAIRO_MIME_TYPE_JBIG2</primary></indexterm> -<programlisting language="C">#define CAIRO_MIME_TYPE_JBIG2 "application/x-cairo.jbig2" -</programlisting> -<para>Joint Bi-level Image Experts Group image coding standard (ISO/IEC 11544).</para> -<para role="since">Since: <link linkend="api-index-1.14">1.14</link></para></refsect2> -<refsect2 id="CAIRO-MIME-TYPE-JBIG2-GLOBAL:CAPS" role="macro" condition="since:1.14"> -<title>CAIRO_MIME_TYPE_JBIG2_GLOBAL</title> -<indexterm zone="CAIRO-MIME-TYPE-JBIG2-GLOBAL:CAPS" role="1.14"><primary sortas="MIME_TYPE_JBIG2_GLOBAL">CAIRO_MIME_TYPE_JBIG2_GLOBAL</primary></indexterm> -<programlisting language="C">#define CAIRO_MIME_TYPE_JBIG2_GLOBAL "application/x-cairo.jbig2-global" -</programlisting> -<para>Joint Bi-level Image Experts Group image coding standard (ISO/IEC 11544) global segment.</para> -<para role="since">Since: <link linkend="api-index-1.14">1.14</link></para></refsect2> -<refsect2 id="CAIRO-MIME-TYPE-JBIG2-GLOBAL-ID:CAPS" role="macro" condition="since:1.14"> -<title>CAIRO_MIME_TYPE_JBIG2_GLOBAL_ID</title> -<indexterm zone="CAIRO-MIME-TYPE-JBIG2-GLOBAL-ID:CAPS" role="1.14"><primary sortas="MIME_TYPE_JBIG2_GLOBAL_ID">CAIRO_MIME_TYPE_JBIG2_GLOBAL_ID</primary></indexterm> -<programlisting language="C">#define CAIRO_MIME_TYPE_JBIG2_GLOBAL_ID "application/x-cairo.jbig2-global-id" -</programlisting> -<para>An unique identifier shared by a JBIG2 global segment and all JBIG2 images -that depend on the global segment.</para> -<para role="since">Since: <link linkend="api-index-1.14">1.14</link></para></refsect2> -<refsect2 id="CAIRO-MIME-TYPE-JP2:CAPS" role="macro" condition="since:1.10"> -<title>CAIRO_MIME_TYPE_JP2</title> -<indexterm zone="CAIRO-MIME-TYPE-JP2:CAPS" role="1.10"><primary sortas="MIME_TYPE_JP2">CAIRO_MIME_TYPE_JP2</primary></indexterm> -<programlisting language="C">#define CAIRO_MIME_TYPE_JP2 "image/jp2" -</programlisting> -<para>The Joint Photographic Experts Group (JPEG) 2000 image coding standard (ISO/IEC 15444-1).</para> -<para role="since">Since: <link linkend="api-index-1.10">1.10</link></para></refsect2> -<refsect2 id="CAIRO-MIME-TYPE-JPEG:CAPS" role="macro" condition="since:1.10"> -<title>CAIRO_MIME_TYPE_JPEG</title> -<indexterm zone="CAIRO-MIME-TYPE-JPEG:CAPS" role="1.10"><primary sortas="MIME_TYPE_JPEG">CAIRO_MIME_TYPE_JPEG</primary></indexterm> -<programlisting language="C">#define CAIRO_MIME_TYPE_JPEG "image/jpeg" -</programlisting> -<para>The Joint Photographic Experts Group (JPEG) image coding standard (ISO/IEC 10918-1).</para> -<para role="since">Since: <link linkend="api-index-1.10">1.10</link></para></refsect2> -<refsect2 id="CAIRO-MIME-TYPE-PNG:CAPS" role="macro" condition="since:1.10"> -<title>CAIRO_MIME_TYPE_PNG</title> -<indexterm zone="CAIRO-MIME-TYPE-PNG:CAPS" role="1.10"><primary sortas="MIME_TYPE_PNG">CAIRO_MIME_TYPE_PNG</primary></indexterm> -<programlisting language="C">#define CAIRO_MIME_TYPE_PNG "image/png" -</programlisting> -<para>The Portable Network Graphics image file format (ISO/IEC 15948).</para> -<para role="since">Since: <link linkend="api-index-1.10">1.10</link></para></refsect2> -<refsect2 id="CAIRO-MIME-TYPE-URI:CAPS" role="macro" condition="since:1.10"> -<title>CAIRO_MIME_TYPE_URI</title> -<indexterm zone="CAIRO-MIME-TYPE-URI:CAPS" role="1.10"><primary sortas="MIME_TYPE_URI">CAIRO_MIME_TYPE_URI</primary></indexterm> -<programlisting language="C">#define CAIRO_MIME_TYPE_URI "text/x-uri" -</programlisting> -<para>URI for an image file (unofficial MIME type).</para> -<para role="since">Since: <link linkend="api-index-1.10">1.10</link></para></refsect2> -<refsect2 id="CAIRO-MIME-TYPE-UNIQUE-ID:CAPS" role="macro" condition="since:1.12"> -<title>CAIRO_MIME_TYPE_UNIQUE_ID</title> -<indexterm zone="CAIRO-MIME-TYPE-UNIQUE-ID:CAPS" role="1.12"><primary sortas="MIME_TYPE_UNIQUE_ID">CAIRO_MIME_TYPE_UNIQUE_ID</primary></indexterm> -<programlisting language="C">#define CAIRO_MIME_TYPE_UNIQUE_ID "application/x-cairo.uuid" -</programlisting> -<para>Unique identifier for a surface (cairo specific MIME type). All surfaces with -the same unique identifier will only be embedded once.</para> -<para role="since">Since: <link linkend="api-index-1.12">1.12</link></para></refsect2> -<refsect2 id="cairo-surface-t" role="typedef" condition="since:1.0"> -<title>cairo_surface_t</title> -<indexterm zone="cairo-surface-t" role="1.0"><primary sortas="surface_t">cairo_surface_t</primary></indexterm> -<programlisting language="C">typedef struct _cairo_surface cairo_surface_t; -</programlisting> -<para>A <link linkend="cairo-surface-t"><type>cairo_surface_t</type></link> represents an image, either as the destination -of a drawing operation or as source when drawing onto another -surface. To draw to a <link linkend="cairo-surface-t"><type>cairo_surface_t</type></link>, create a cairo context -with the surface as the target, using <link linkend="cairo-create"><function>cairo_create()</function></link>.</para> -<para>There are different subtypes of <link linkend="cairo-surface-t"><type>cairo_surface_t</type></link> for -different drawing backends; for example, <link linkend="cairo-image-surface-create"><function>cairo_image_surface_create()</function></link> -creates a bitmap image in memory. -The type of a surface can be queried with <link linkend="cairo-surface-get-type"><function>cairo_surface_get_type()</function></link>.</para> -<para>The initial contents of a surface after creation depend upon the manner -of its creation. If cairo creates the surface and backing storage for -the user, it will be initially cleared; for example, -<link linkend="cairo-image-surface-create"><function>cairo_image_surface_create()</function></link> and <link linkend="cairo-surface-create-similar"><function>cairo_surface_create_similar()</function></link>. -Alternatively, if the user passes in a reference to some backing storage -and asks cairo to wrap that in a <link linkend="cairo-surface-t"><type>cairo_surface_t</type></link>, then the contents are -not modified; for example, <link linkend="cairo-image-surface-create-for-data"><function>cairo_image_surface_create_for_data()</function></link> and -<link linkend="cairo-xlib-surface-create"><function>cairo_xlib_surface_create()</function></link>.</para> -<para>Memory management of <link linkend="cairo-surface-t"><type>cairo_surface_t</type></link> is done with -<link linkend="cairo-surface-reference"><function>cairo_surface_reference()</function></link> and <link linkend="cairo-surface-destroy"><function>cairo_surface_destroy()</function></link>.</para> -<para role="since">Since: <link linkend="api-index-1.0">1.0</link></para></refsect2> -<refsect2 id="cairo-content-t" role="enum" condition="since:1.0"> -<title>enum cairo_content_t</title> -<indexterm zone="cairo-content-t" role="1.0"><primary sortas="content_t">cairo_content_t</primary></indexterm> -<para><link linkend="cairo-content-t"><type>cairo_content_t</type></link> is used to describe the content that a surface will -contain, whether color information, alpha information (translucence -vs. opacity), or both.</para> -<para>Note: The large values here are designed to keep <link linkend="cairo-content-t"><type>cairo_content_t</type></link> -values distinct from <link linkend="cairo-format-t"><type>cairo_format_t</type></link> values so that the -implementation can detect the error if users confuse the two types.</para> -<refsect3 id="cairo-content-t.members" role="enum_members"> -<title>Members</title> -<informaltable role="enum_members_table" pgwide="1" frame="none"> -<tgroup cols="3"> -<colspec colname="enum_members_name" colwidth="300px"/> -<colspec colname="enum_members_description"/> -<colspec colname="enum_members_annotations" colwidth="200px"/> -<tbody> -<row role="constant"><entry role="enum_member_name"><para id="CAIRO-CONTENT-COLOR:CAPS">CAIRO_CONTENT_COLOR</para></entry> -<entry role="enum_member_description"><para>The surface will hold color content only. (Since 1.0)</para> -</entry> -<entry role="enum_member_annotations"></entry> -</row> -<row role="constant"><entry role="enum_member_name"><para id="CAIRO-CONTENT-ALPHA:CAPS">CAIRO_CONTENT_ALPHA</para></entry> -<entry role="enum_member_description"><para>The surface will hold alpha content only. (Since 1.0)</para> -</entry> -<entry role="enum_member_annotations"></entry> -</row> -<row role="constant"><entry role="enum_member_name"><para id="CAIRO-CONTENT-COLOR-ALPHA:CAPS">CAIRO_CONTENT_COLOR_ALPHA</para></entry> -<entry role="enum_member_description"><para>The surface will hold color and alpha content. (Since 1.0)</para> -</entry> -<entry role="enum_member_annotations"></entry> -</row> -</tbody></tgroup></informaltable> -</refsect3><para role="since">Since: <link linkend="api-index-1.0">1.0</link></para></refsect2> -<refsect2 id="cairo-surface-type-t" role="enum" condition="since:1.2"> -<title>enum cairo_surface_type_t</title> -<indexterm zone="cairo-surface-type-t" role="1.2"><primary sortas="surface_type_t">cairo_surface_type_t</primary></indexterm> -<para><link linkend="cairo-surface-type-t"><type>cairo_surface_type_t</type></link> is used to describe the type of a given -surface. The surface types are also known as "backends" or "surface -backends" within cairo.</para> -<para>The type of a surface is determined by the function used to create -it, which will generally be of the form -<function>cairo_<emphasis>type</emphasis>_surface_create(<!-- -->)</function>, -(though see <link linkend="cairo-surface-create-similar"><function>cairo_surface_create_similar()</function></link> as well).</para> -<para>The surface type can be queried with <link linkend="cairo-surface-get-type"><function>cairo_surface_get_type()</function></link></para> -<para>The various <link linkend="cairo-surface-t"><type>cairo_surface_t</type></link> functions can be used with surfaces of -any type, but some backends also provide type-specific functions -that must only be called with a surface of the appropriate -type. These functions have names that begin with -<literal>cairo_<emphasis>type</emphasis>_surface</literal> such as <link linkend="cairo-image-surface-get-width"><function>cairo_image_surface_get_width()</function></link>.</para> -<para>The behavior of calling a type-specific function with a surface of -the wrong type is undefined.</para> -<para>New entries may be added in future versions.</para> -<refsect3 id="cairo-surface-type-t.members" role="enum_members"> -<title>Members</title> -<informaltable role="enum_members_table" pgwide="1" frame="none"> -<tgroup cols="3"> -<colspec colname="enum_members_name" colwidth="300px"/> -<colspec colname="enum_members_description"/> -<colspec colname="enum_members_annotations" colwidth="200px"/> -<tbody> -<row role="constant"><entry role="enum_member_name"><para id="CAIRO-SURFACE-TYPE-IMAGE:CAPS">CAIRO_SURFACE_TYPE_IMAGE</para></entry> -<entry role="enum_member_description"><para>The surface is of type image, since 1.2</para> -</entry> -<entry role="enum_member_annotations"></entry> -</row> -<row role="constant"><entry role="enum_member_name"><para id="CAIRO-SURFACE-TYPE-PDF:CAPS">CAIRO_SURFACE_TYPE_PDF</para></entry> -<entry role="enum_member_description"><para>The surface is of type pdf, since 1.2</para> -</entry> -<entry role="enum_member_annotations"></entry> -</row> -<row role="constant"><entry role="enum_member_name"><para id="CAIRO-SURFACE-TYPE-PS:CAPS">CAIRO_SURFACE_TYPE_PS</para></entry> -<entry role="enum_member_description"><para>The surface is of type ps, since 1.2</para> -</entry> -<entry role="enum_member_annotations"></entry> -</row> -<row role="constant"><entry role="enum_member_name"><para id="CAIRO-SURFACE-TYPE-XLIB:CAPS">CAIRO_SURFACE_TYPE_XLIB</para></entry> -<entry role="enum_member_description"><para>The surface is of type xlib, since 1.2</para> -</entry> -<entry role="enum_member_annotations"></entry> -</row> -<row role="constant"><entry role="enum_member_name"><para id="CAIRO-SURFACE-TYPE-XCB:CAPS">CAIRO_SURFACE_TYPE_XCB</para></entry> -<entry role="enum_member_description"><para>The surface is of type xcb, since 1.2</para> -</entry> -<entry role="enum_member_annotations"></entry> -</row> -<row role="constant"><entry role="enum_member_name"><para id="CAIRO-SURFACE-TYPE-GLITZ:CAPS">CAIRO_SURFACE_TYPE_GLITZ</para></entry> -<entry role="enum_member_description"><para>The surface is of type glitz, since 1.2</para> -</entry> -<entry role="enum_member_annotations"></entry> -</row> -<row role="constant"><entry role="enum_member_name"><para id="CAIRO-SURFACE-TYPE-QUARTZ:CAPS">CAIRO_SURFACE_TYPE_QUARTZ</para></entry> -<entry role="enum_member_description"><para>The surface is of type quartz, since 1.2</para> -</entry> -<entry role="enum_member_annotations"></entry> -</row> -<row role="constant"><entry role="enum_member_name"><para id="CAIRO-SURFACE-TYPE-WIN32:CAPS">CAIRO_SURFACE_TYPE_WIN32</para></entry> -<entry role="enum_member_description"><para>The surface is of type win32, since 1.2</para> -</entry> -<entry role="enum_member_annotations"></entry> -</row> -<row role="constant"><entry role="enum_member_name"><para id="CAIRO-SURFACE-TYPE-BEOS:CAPS">CAIRO_SURFACE_TYPE_BEOS</para></entry> -<entry role="enum_member_description"><para>The surface is of type beos, since 1.2</para> -</entry> -<entry role="enum_member_annotations"></entry> -</row> -<row role="constant"><entry role="enum_member_name"><para id="CAIRO-SURFACE-TYPE-DIRECTFB:CAPS">CAIRO_SURFACE_TYPE_DIRECTFB</para></entry> -<entry role="enum_member_description"><para>The surface is of type directfb, since 1.2</para> -</entry> -<entry role="enum_member_annotations"></entry> -</row> -<row role="constant"><entry role="enum_member_name"><para id="CAIRO-SURFACE-TYPE-SVG:CAPS">CAIRO_SURFACE_TYPE_SVG</para></entry> -<entry role="enum_member_description"><para>The surface is of type svg, since 1.2</para> -</entry> -<entry role="enum_member_annotations"></entry> -</row> -<row role="constant"><entry role="enum_member_name"><para id="CAIRO-SURFACE-TYPE-OS2:CAPS">CAIRO_SURFACE_TYPE_OS2</para></entry> -<entry role="enum_member_description"><para>The surface is of type os2, since 1.4</para> -</entry> -<entry role="enum_member_annotations"></entry> -</row> -<row role="constant"><entry role="enum_member_name"><para id="CAIRO-SURFACE-TYPE-WIN32-PRINTING:CAPS">CAIRO_SURFACE_TYPE_WIN32_PRINTING</para></entry> -<entry role="enum_member_description"><para>The surface is a win32 printing surface, since 1.6</para> -</entry> -<entry role="enum_member_annotations"></entry> -</row> -<row role="constant"><entry role="enum_member_name"><para id="CAIRO-SURFACE-TYPE-QUARTZ-IMAGE:CAPS">CAIRO_SURFACE_TYPE_QUARTZ_IMAGE</para></entry> -<entry role="enum_member_description"><para>The surface is of type quartz_image, since 1.6</para> -</entry> -<entry role="enum_member_annotations"></entry> -</row> -<row role="constant"><entry role="enum_member_name"><para id="CAIRO-SURFACE-TYPE-SCRIPT:CAPS">CAIRO_SURFACE_TYPE_SCRIPT</para></entry> -<entry role="enum_member_description"><para>The surface is of type script, since 1.10</para> -</entry> -<entry role="enum_member_annotations"></entry> -</row> -<row role="constant"><entry role="enum_member_name"><para id="CAIRO-SURFACE-TYPE-QT:CAPS">CAIRO_SURFACE_TYPE_QT</para></entry> -<entry role="enum_member_description"><para>The surface is of type Qt, since 1.10</para> -</entry> -<entry role="enum_member_annotations"></entry> -</row> -<row role="constant"><entry role="enum_member_name"><para id="CAIRO-SURFACE-TYPE-RECORDING:CAPS">CAIRO_SURFACE_TYPE_RECORDING</para></entry> -<entry role="enum_member_description"><para>The surface is of type recording, since 1.10</para> -</entry> -<entry role="enum_member_annotations"></entry> -</row> -<row role="constant"><entry role="enum_member_name"><para id="CAIRO-SURFACE-TYPE-VG:CAPS">CAIRO_SURFACE_TYPE_VG</para></entry> -<entry role="enum_member_description"><para>The surface is a OpenVG surface, since 1.10</para> -</entry> -<entry role="enum_member_annotations"></entry> -</row> -<row role="constant"><entry role="enum_member_name"><para id="CAIRO-SURFACE-TYPE-GL:CAPS">CAIRO_SURFACE_TYPE_GL</para></entry> -<entry role="enum_member_description"><para>The surface is of type OpenGL, since 1.10</para> -</entry> -<entry role="enum_member_annotations"></entry> -</row> -<row role="constant"><entry role="enum_member_name"><para id="CAIRO-SURFACE-TYPE-DRM:CAPS">CAIRO_SURFACE_TYPE_DRM</para></entry> -<entry role="enum_member_description"><para>The surface is of type Direct Render Manager, since 1.10</para> -</entry> -<entry role="enum_member_annotations"></entry> -</row> -<row role="constant"><entry role="enum_member_name"><para id="CAIRO-SURFACE-TYPE-TEE:CAPS">CAIRO_SURFACE_TYPE_TEE</para></entry> -<entry role="enum_member_description"><para>The surface is of type 'tee' (a multiplexing surface), since 1.10</para> -</entry> -<entry role="enum_member_annotations"></entry> -</row> -<row role="constant"><entry role="enum_member_name"><para id="CAIRO-SURFACE-TYPE-XML:CAPS">CAIRO_SURFACE_TYPE_XML</para></entry> -<entry role="enum_member_description"><para>The surface is of type XML (for debugging), since 1.10</para> -</entry> -<entry role="enum_member_annotations"></entry> -</row> -<row role="constant"><entry role="enum_member_name"><para id="CAIRO-SURFACE-TYPE-SKIA:CAPS">CAIRO_SURFACE_TYPE_SKIA</para></entry> -<entry /><entry /> -</row> -<row role="constant"><entry role="enum_member_name"><para id="CAIRO-SURFACE-TYPE-SUBSURFACE:CAPS">CAIRO_SURFACE_TYPE_SUBSURFACE</para></entry> -<entry role="enum_member_description"><para>The surface is a subsurface created with - <link linkend="cairo-surface-create-for-rectangle"><function>cairo_surface_create_for_rectangle()</function></link>, since 1.10</para> -</entry> -<entry role="enum_member_annotations"></entry> -</row> -<row role="constant"><entry role="enum_member_name"><para id="CAIRO-SURFACE-TYPE-COGL:CAPS">CAIRO_SURFACE_TYPE_COGL</para></entry> -<entry role="enum_member_description"><para>This surface is of type Cogl, since 1.12</para> -</entry> -<entry role="enum_member_annotations"></entry> -</row> -</tbody></tgroup></informaltable> -</refsect3><para role="since">Since: <link linkend="api-index-1.2">1.2</link></para></refsect2> - -</refsect1> -<refsect1 id="cairo-cairo-surface-t.see-also"> -<title>See Also</title> -<para><link linkend="cairo-t"><type>cairo_t</type></link>, <link linkend="cairo-pattern-t"><type>cairo_pattern_t</type></link></para> - -</refsect1> - -</refentry> |