<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
<!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
<!ENTITY version SYSTEM "version.xml">
]>
<refentry id="gdk4-Cairo-Interaction">
<refmeta>
<refentrytitle role="top_of_page" id="gdk4-Cairo-Interaction.top_of_page">Cairo Interaction</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GDK4 Library</refmiscinfo>
</refmeta>
<refnamediv>
<refname>Cairo Interaction</refname>
<refpurpose>Functions to support using cairo</refpurpose>
</refnamediv>

<refsect1 id="gdk4-Cairo-Interaction.functions" role="functions_proto">
<title role="functions_proto.title">Functions</title>
<informaltable pgwide="1" frame="none">
<tgroup cols="2">
<colspec colname="functions_proto_type" colwidth="150px"/>
<colspec colname="functions_proto_name"/>
<tbody>
<row><entry role="function_type"><link linkend="cairo-surface-t"><returnvalue>cairo_surface_t</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="gdk-surface-create-similar-surface">gdk_surface_create_similar_surface</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="gdk-cairo-set-source-rgba">gdk_cairo_set_source_rgba</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="gdk-cairo-set-source-pixbuf">gdk_cairo_set_source_pixbuf</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="gdk-cairo-rectangle">gdk_cairo_rectangle</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="gdk-cairo-region">gdk_cairo_region</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="cairo-region-t"><returnvalue>cairo_region_t</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="gdk-cairo-region-create-from-surface">gdk_cairo_region_create_from_surface</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="gdk-cairo-draw-from-gl">gdk_cairo_draw_from_gl</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>

</tbody>
</tgroup>
</informaltable>
</refsect1>

<refsect1 id="gdk4-Cairo-Interaction.includes"><title>Includes</title><synopsis>#include &lt;gdk/gdk.h&gt;
</synopsis></refsect1>

<refsect1 id="gdk4-Cairo-Interaction.description" role="desc">
<title role="desc.title">Description</title>
<para><ulink url="http://cairographics.org">Cairo</ulink> is a graphics
library that supports vector graphics and image compositing that
can be used with GDK and GTK.</para>
<para>GDK does not wrap the cairo API, instead it allows to create cairo
contexts which can be used to draw on <link linkend="GdkSurfaces"><type>GdkSurfaces</type></link>. Additional
functions allow use <link linkend="GdkRectangles"><type>GdkRectangles</type></link> with cairo and to use <link linkend="GdkRGBAs"><type>GdkRGBAs</type></link>,
<link linkend="GdkPixbufs"><type>GdkPixbufs</type></link> and <link linkend="GdkSurfaces"><type>GdkSurfaces</type></link> as sources for drawing operations.</para>

</refsect1>
<refsect1 id="gdk4-Cairo-Interaction.functions_details" role="details">
<title role="details.title">Functions</title>
<refsect2 id="gdk-surface-create-similar-surface" role="function">
<title>gdk_surface_create_similar_surface&#160;()</title>
<indexterm zone="gdk-surface-create-similar-surface"><primary>gdk_surface_create_similar_surface</primary></indexterm>
<programlisting language="C"><link linkend="cairo-surface-t"><returnvalue>cairo_surface_t</returnvalue></link>&#160;*
gdk_surface_create_similar_surface (<parameter><link linkend="GdkSurface"><type>GdkSurface</type></link> *surface</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 the
given <parameter>surface</parameter>
. For example the new surface will have the same
fallback resolution and font options as <parameter>surface</parameter>
. Generally, the new
surface will also use the same backend as <parameter>surface</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>
<refsect3 id="gdk-surface-create-similar-surface.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>surface to make new surface similar to</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</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</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gdk-surface-create-similar-surface.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></refsect2>
<refsect2 id="gdk-cairo-set-source-rgba" role="function">
<title>gdk_cairo_set_source_rgba&#160;()</title>
<indexterm zone="gdk-cairo-set-source-rgba"><primary>gdk_cairo_set_source_rgba</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
gdk_cairo_set_source_rgba (<parameter><link linkend="cairo-t"><type>cairo_t</type></link> *cr</parameter>,
                           <parameter>const <link linkend="GdkRGBA"><type>GdkRGBA</type></link> *rgba</parameter>);</programlisting>
<para>Sets the specified <link linkend="GdkRGBA"><type>GdkRGBA</type></link> as the source color of <parameter>cr</parameter>
.</para>
<refsect3 id="gdk-cairo-set-source-rgba.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>cr</para></entry>
<entry role="parameter_description"><para>a cairo context</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>rgba</para></entry>
<entry role="parameter_description"><para>a <link linkend="GdkRGBA"><type>GdkRGBA</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="gdk-cairo-set-source-pixbuf" role="function">
<title>gdk_cairo_set_source_pixbuf&#160;()</title>
<indexterm zone="gdk-cairo-set-source-pixbuf"><primary>gdk_cairo_set_source_pixbuf</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
gdk_cairo_set_source_pixbuf (<parameter><link linkend="cairo-t"><type>cairo_t</type></link> *cr</parameter>,
                             <parameter>const <link linkend="GdkPixbuf"><type>GdkPixbuf</type></link> *pixbuf</parameter>,
                             <parameter><link linkend="double"><type>double</type></link> pixbuf_x</parameter>,
                             <parameter><link linkend="double"><type>double</type></link> pixbuf_y</parameter>);</programlisting>
<para>Sets the given pixbuf as the source pattern for <parameter>cr</parameter>
.</para>
<para>The pattern has an extend mode of <link linkend="CAIRO-EXTEND-NONE:CAPS"><literal>CAIRO_EXTEND_NONE</literal></link> and is aligned
so that the origin of <parameter>pixbuf</parameter>
 is <parameter>pixbuf_x</parameter>
, <parameter>pixbuf_y</parameter>
.</para>
<refsect3 id="gdk-cairo-set-source-pixbuf.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>cr</para></entry>
<entry role="parameter_description"><para>a cairo context</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>pixbuf</para></entry>
<entry role="parameter_description"><para>a <link linkend="GdkPixbuf"><type>GdkPixbuf</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>pixbuf_x</para></entry>
<entry role="parameter_description"><para>X coordinate of location to place upper left corner of <parameter>pixbuf</parameter>
</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>pixbuf_y</para></entry>
<entry role="parameter_description"><para>Y coordinate of location to place upper left corner of <parameter>pixbuf</parameter>
</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="gdk-cairo-rectangle" role="function">
<title>gdk_cairo_rectangle&#160;()</title>
<indexterm zone="gdk-cairo-rectangle"><primary>gdk_cairo_rectangle</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
gdk_cairo_rectangle (<parameter><link linkend="cairo-t"><type>cairo_t</type></link> *cr</parameter>,
                     <parameter>const <link linkend="GdkRectangle"><type>GdkRectangle</type></link> *rectangle</parameter>);</programlisting>
<para>Adds the given rectangle to the current path of <parameter>cr</parameter>
.</para>
<refsect3 id="gdk-cairo-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>cr</para></entry>
<entry role="parameter_description"><para>a cairo context</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>rectangle</para></entry>
<entry role="parameter_description"><para>a <link linkend="GdkRectangle"><type>GdkRectangle</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="gdk-cairo-region" role="function">
<title>gdk_cairo_region&#160;()</title>
<indexterm zone="gdk-cairo-region"><primary>gdk_cairo_region</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
gdk_cairo_region (<parameter><link linkend="cairo-t"><type>cairo_t</type></link> *cr</parameter>,
                  <parameter>const <link linkend="cairo-region-t"><type>cairo_region_t</type></link> *region</parameter>);</programlisting>
<para>Adds the given region to the current path of <parameter>cr</parameter>
.</para>
<refsect3 id="gdk-cairo-region.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>cr</para></entry>
<entry role="parameter_description"><para>a cairo context</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>region</para></entry>
<entry role="parameter_description"><para>a <link linkend="cairo-region-t"><type>cairo_region_t</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="gdk-cairo-region-create-from-surface" role="function">
<title>gdk_cairo_region_create_from_surface&#160;()</title>
<indexterm zone="gdk-cairo-region-create-from-surface"><primary>gdk_cairo_region_create_from_surface</primary></indexterm>
<programlisting language="C"><link linkend="cairo-region-t"><returnvalue>cairo_region_t</returnvalue></link>&#160;*
gdk_cairo_region_create_from_surface (<parameter><link linkend="cairo-surface-t"><type>cairo_surface_t</type></link> *surface</parameter>);</programlisting>
<para>Creates region that describes covers the area where the given
<parameter>surface</parameter>
 is more than 50% opaque.</para>
<para>This function takes into account device offsets that might be
set with <link linkend="cairo-surface-set-device-offset"><function>cairo_surface_set_device_offset()</function></link>.</para>
<refsect3 id="gdk-cairo-region-create-from-surface.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 cairo surface</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gdk-cairo-region-create-from-surface.returns" role="returns">
<title>Returns</title>
<para> A <link linkend="cairo-region-t"><type>cairo_region_t</type></link>; must be freed with <link linkend="cairo-region-destroy"><function>cairo_region_destroy()</function></link></para>
</refsect3></refsect2>
<refsect2 id="gdk-cairo-draw-from-gl" role="function">
<title>gdk_cairo_draw_from_gl&#160;()</title>
<indexterm zone="gdk-cairo-draw-from-gl"><primary>gdk_cairo_draw_from_gl</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
gdk_cairo_draw_from_gl (<parameter><link linkend="cairo-t"><type>cairo_t</type></link> *cr</parameter>,
                        <parameter><link linkend="GdkSurface"><type>GdkSurface</type></link> *surface</parameter>,
                        <parameter><link linkend="int"><type>int</type></link> source</parameter>,
                        <parameter><link linkend="int"><type>int</type></link> source_type</parameter>,
                        <parameter><link linkend="int"><type>int</type></link> buffer_scale</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>This is the main way to draw GL content in GTK. It takes a render buffer ID 
(<parameter>source_type</parameter>
 == <link linkend="GL-RENDERBUFFER:CAPS"><type>GL_RENDERBUFFER</type></link>) or a texture id (<parameter>source_type</parameter>
 == <link linkend="GL-TEXTURE:CAPS"><type>GL_TEXTURE</type></link>)
and draws it onto <parameter>cr</parameter>
 with an OVER operation, respecting the current clip.
The top left corner of the rectangle specified by <parameter>x</parameter>
, <parameter>y</parameter>
, <parameter>width</parameter>
 and <parameter>height</parameter>

will be drawn at the current (0,0) position of the cairo_t.</para>
<para>This will work for *all* cairo_t, as long as <parameter>surface</parameter>
 is realized, but the
fallback implementation that reads back the pixels from the buffer may be
used in the general case. In the case of direct drawing to a surface with
no special effects applied to <parameter>cr</parameter>
 it will however use a more efficient
approach.</para>
<para>For <link linkend="GL-RENDERBUFFER:CAPS"><type>GL_RENDERBUFFER</type></link> the code will always fall back to software for buffers
with alpha components, so make sure you use <link linkend="GL-TEXTURE:CAPS"><type>GL_TEXTURE</type></link> if using alpha.</para>
<para>Calling this may change the current GL context.</para>
<refsect3 id="gdk-cairo-draw-from-gl.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>cr</para></entry>
<entry role="parameter_description"><para>a cairo context</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>surface</para></entry>
<entry role="parameter_description"><para>The surface we're rendering for (not necessarily into)</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>source</para></entry>
<entry role="parameter_description"><para>The GL ID of the source buffer</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>source_type</para></entry>
<entry role="parameter_description"><para>The type of the <parameter>source</parameter>
</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>buffer_scale</para></entry>
<entry role="parameter_description"><para>The scale-factor that the <parameter>source</parameter>
buffer is allocated for</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>x</para></entry>
<entry role="parameter_description"><para>The source x position in <parameter>source</parameter>
to start copying from in GL coordinates</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>y</para></entry>
<entry role="parameter_description"><para>The source y position in <parameter>source</parameter>
to start copying from in GL coordinates</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>width</para></entry>
<entry role="parameter_description"><para>The width of the region to draw</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>height</para></entry>
<entry role="parameter_description"><para>The height of the region to draw</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>

</refsect1>

</refentry>
