path: root/doc/public/xml/cairo-paths.xml

<?xml version='1.0' encoding='UTF-8'?> 
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
                "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
<!ENTITY version SYSTEM "version.xml">
]>
<refentry id="cairo-Paths">
<refmeta>
<refentrytitle id="top_of_page">Paths</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>CAIRO Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>Paths</refname>
<refpurpose>Creating paths and manipulating path data</refpurpose>
<!--[<xref linkend="desc" endterm="desc.title"/>]-->
</refnamediv>

<refsynopsisdiv id="synopsis">
<title id="synopsis.title">Synopsis</title>

<synopsis>



            <link linkend="cairo-path-t">cairo_path_t</link>;
union       <link linkend="cairo-path-data-t">cairo_path_data_t</link>;
enum        <link linkend="cairo-path-data-type-t">cairo_path_data_type_t</link>;
<link linkend="cairo-path-t">cairo_path_t</link>* <link linkend="cairo-copy-path">cairo_copy_path</link>               (<link linkend="cairo-t">cairo_t</link> *cr);
<link linkend="cairo-path-t">cairo_path_t</link>* <link linkend="cairo-copy-path-flat">cairo_copy_path_flat</link>          (<link linkend="cairo-t">cairo_t</link> *cr);
<link linkend="void">void</link>        <link linkend="cairo-path-destroy">cairo_path_destroy</link>              (<link linkend="cairo-path-t">cairo_path_t</link> *path);
<link linkend="void">void</link>        <link linkend="cairo-append-path">cairo_append_path</link>               (<link linkend="cairo-t">cairo_t</link> *cr,
                                             <link linkend="cairo-path-t">cairo_path_t</link> *path);
<link linkend="void">void</link>        <link linkend="cairo-get-current-point">cairo_get_current_point</link>         (<link linkend="cairo-t">cairo_t</link> *cr,
                                             <link linkend="double">double</link> *x,
                                             <link linkend="double">double</link> *y);
<link linkend="void">void</link>        <link linkend="cairo-new-path">cairo_new_path</link>                  (<link linkend="cairo-t">cairo_t</link> *cr);
<link linkend="void">void</link>        <link linkend="cairo-new-sub-path">cairo_new_sub_path</link>              (<link linkend="cairo-t">cairo_t</link> *cr);
<link linkend="void">void</link>        <link linkend="cairo-close-path">cairo_close_path</link>                (<link linkend="cairo-t">cairo_t</link> *cr);
<link linkend="void">void</link>        <link linkend="cairo-arc">cairo_arc</link>                       (<link linkend="cairo-t">cairo_t</link> *cr,
                                             <link linkend="double">double</link> xc,
                                             <link linkend="double">double</link> yc,
                                             <link linkend="double">double</link> radius,
                                             <link linkend="double">double</link> angle1,
                                             <link linkend="double">double</link> angle2);
<link linkend="void">void</link>        <link linkend="cairo-arc-negative">cairo_arc_negative</link>              (<link linkend="cairo-t">cairo_t</link> *cr,
                                             <link linkend="double">double</link> xc,
                                             <link linkend="double">double</link> yc,
                                             <link linkend="double">double</link> radius,
                                             <link linkend="double">double</link> angle1,
                                             <link linkend="double">double</link> angle2);
<link linkend="void">void</link>        <link linkend="cairo-curve-to">cairo_curve_to</link>                  (<link linkend="cairo-t">cairo_t</link> *cr,
                                             <link linkend="double">double</link> x1,
                                             <link linkend="double">double</link> y1,
                                             <link linkend="double">double</link> x2,
                                             <link linkend="double">double</link> y2,
                                             <link linkend="double">double</link> x3,
                                             <link linkend="double">double</link> y3);
<link linkend="void">void</link>        <link linkend="cairo-line-to">cairo_line_to</link>                   (<link linkend="cairo-t">cairo_t</link> *cr,
                                             <link linkend="double">double</link> x,
                                             <link linkend="double">double</link> y);
<link linkend="void">void</link>        <link linkend="cairo-move-to">cairo_move_to</link>                   (<link linkend="cairo-t">cairo_t</link> *cr,
                                             <link linkend="double">double</link> x,
                                             <link linkend="double">double</link> y);
<link linkend="void">void</link>        <link linkend="cairo-rectangle">cairo_rectangle</link>                 (<link linkend="cairo-t">cairo_t</link> *cr,
                                             <link linkend="double">double</link> x,
                                             <link linkend="double">double</link> y,
                                             <link linkend="double">double</link> width,
                                             <link linkend="double">double</link> height);
<link linkend="void">void</link>        <link linkend="cairo-glyph-path">cairo_glyph_path</link>                (<link linkend="cairo-t">cairo_t</link> *cr,
                                             <link linkend="cairo-glyph-t">cairo_glyph_t</link> *glyphs,
                                             <link linkend="int">int</link> num_glyphs);
<link linkend="void">void</link>        <link linkend="cairo-text-path">cairo_text_path</link>                 (<link linkend="cairo-t">cairo_t</link> *cr,
                                             const <link linkend="char">char</link> *utf8);
<link linkend="void">void</link>        <link linkend="cairo-rel-curve-to">cairo_rel_curve_to</link>              (<link linkend="cairo-t">cairo_t</link> *cr,
                                             <link linkend="double">double</link> dx1,
                                             <link linkend="double">double</link> dy1,
                                             <link linkend="double">double</link> dx2,
                                             <link linkend="double">double</link> dy2,
                                             <link linkend="double">double</link> dx3,
                                             <link linkend="double">double</link> dy3);
<link linkend="void">void</link>        <link linkend="cairo-rel-line-to">cairo_rel_line_to</link>               (<link linkend="cairo-t">cairo_t</link> *cr,
                                             <link linkend="double">double</link> dx,
                                             <link linkend="double">double</link> dy);
<link linkend="void">void</link>        <link linkend="cairo-rel-move-to">cairo_rel_move_to</link>               (<link linkend="cairo-t">cairo_t</link> *cr,
                                             <link linkend="double">double</link> dx,
                                             <link linkend="double">double</link> dy);
</synopsis>
</refsynopsisdiv>









<refsect1 id="desc">
<title id="desc.title">Description</title>
<para>

</para>
</refsect1>

<refsect1 id="details">
<title id="details.title">Details</title>
<refsect2>
<title><anchor id="cairo-path-t" role="struct"/>cairo_path_t</title>
<indexterm><primary>cairo_path_t</primary></indexterm><programlisting>typedef struct {
    cairo_status_t status;
    cairo_path_data_t *data;
    int num_data;
} cairo_path_t;
</programlisting>
<para>
A data structure for holding a path. This data structure serves as
the return value for <link linkend="cairo-copy-path"><function>cairo_copy_path()</function></link> and
<link linkend="cairo-copy-path-flat"><function>cairo_copy_path_flat()</function></link> as well the input value for
<link linkend="cairo-append-path"><function>cairo_append_path()</function></link>.
</para>
<para>
See <link linkend="cairo-path-data-t"><type>cairo_path_data_t</type></link> for hints on how to iterate over the
actual data within the path.
</para>
<para>
The num_data member gives the number of elements in the data
array. This number is larger than the number of independent path
portions (defined in <link linkend="cairo-path-data-type-t"><type>cairo_path_data_type_t</type></link>), since the data
includes both headers and coordinates for each portion.</para>
<para>

</para><variablelist role="struct">
<varlistentry>
<term><link linkend="cairo-status-t">cairo_status_t</link>&nbsp;<structfield>status</structfield>;</term>
<listitem><simpara> the current error status
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><link linkend="cairo-path-data-t">cairo_path_data_t</link>&nbsp;*<structfield>data</structfield>;</term>
<listitem><simpara> the elements in the path
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><link linkend="int">int</link>&nbsp;<structfield>num_data</structfield>;</term>
<listitem><simpara> the number of elements in the data array
</simpara></listitem>
</varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="cairo-path-data-t" role="union"/>union cairo_path_data_t</title>
<indexterm><primary>cairo_path_data_t</primary></indexterm><programlisting>union cairo_path_data_t {
    struct {
	cairo_path_data_type_t type;
	int length;
    } header;
    struct {
	double x, y;
    } point;
};
</programlisting>
<para>
<link linkend="cairo-path-data-t"><type>cairo_path_data_t</type></link> is used to represent the path data inside a
<link linkend="cairo-path-t"><type>cairo_path_t</type></link>.
</para>
<para>
The data structure is designed to try to balance the demands of
efficiency and ease-of-use. A path is represented as an array of
<link linkend="cairo-path-data-t"><type>cairo_path_data_t</type></link>, which is a union of headers and points.
</para>
<para>
Each portion of the path is represented by one or more elements in
the array, (one header followed by 0 or more points). The length
value of the header is the number of array elements for the current
portion including the header, (ie. length == 1 + # of points), and
where the number of points for each element type must be as
follows:
</para>
<para>
<programlisting>
    <link linkend="CAIRO-PATH-MOVE-TO:CAPS"><literal>CAIRO_PATH_MOVE_TO</literal></link>:     1 point
    <link linkend="CAIRO-PATH-LINE-TO:CAPS"><literal>CAIRO_PATH_LINE_TO</literal></link>:     1 point
    <link linkend="CAIRO-PATH-CURVE-TO:CAPS"><literal>CAIRO_PATH_CURVE_TO</literal></link>:    3 points
    <link linkend="CAIRO-PATH-CLOSE-PATH:CAPS"><literal>CAIRO_PATH_CLOSE_PATH</literal></link>:  0 points
</programlisting>
</para>
<para>
The semantics and ordering of the coordinate values are consistent
with <link linkend="cairo-move-to"><function>cairo_move_to()</function></link>, <link linkend="cairo-line-to"><function>cairo_line_to()</function></link>, <link linkend="cairo-curve-to"><function>cairo_curve_to()</function></link>, and
<link linkend="cairo-close-path"><function>cairo_close_path()</function></link>.
</para>
<para>
Here is sample code for iterating through a <link linkend="cairo-path-t--"><type>cairo_path_t:</type></link>
</para>
<para>
<informalexample><programlisting>
     int i;
     cairo_path_t *path;
     cairo_path_data_t *data;
&nbsp;
     path = cairo_copy_path (cr);
&nbsp;
     for (i=0; i &lt; path->num_data; i += path->data[i].header.length) {
         data = &amp;path->data[i];
         switch (data->header.type) {
         case CAIRO_PATH_MOVE_TO:
             do_move_to_things (data[1].point.x, data[1].point.y);
             break;
         case CAIRO_PATH_LINE_TO:
             do_line_to_things (data[1].point.x, data[1].point.y);
             break;
         case CAIRO_PATH_CURVE_TO:
             do_curve_to_things (data[1].point.x, data[1].point.y,
                                 data[2].point.x, data[2].point.y,
                                 data[3].point.x, data[3].point.y);
             break;
         case CAIRO_PATH_CLOSE_PATH:
             <link linkend="do-close-path-things"><function>do_close_path_things()</function></link>;
             break;
         }
     }
     cairo_path_destroy (path);
</programlisting></informalexample></para>
<para>

</para></refsect2>
<refsect2>
<title><anchor id="cairo-path-data-type-t" role="enum"/>enum cairo_path_data_type_t</title>
<indexterm><primary>cairo_path_data_type_t</primary></indexterm><programlisting>typedef enum _cairo_path_data_type {
    CAIRO_PATH_MOVE_TO,
    CAIRO_PATH_LINE_TO,
    CAIRO_PATH_CURVE_TO,
    CAIRO_PATH_CLOSE_PATH
} cairo_path_data_type_t;
</programlisting>
<para>

</para></refsect2>
<refsect2>
<title><anchor id="cairo-copy-path" role="function"/>cairo_copy_path ()</title>
<indexterm><primary>cairo_copy_path</primary></indexterm><programlisting><link linkend="cairo-path-t">cairo_path_t</link>* cairo_copy_path               (<link linkend="cairo-t">cairo_t</link> *cr);</programlisting>
<para>
Creates a copy of the current path and returns it to the user as a
<link linkend="cairo-path-t"><type>cairo_path_t</type></link>. See <link linkend="cairo-path-data-t"><type>cairo_path_data_t</type></link> for hints on how to iterate
over the returned data structure.
</para>
<para>
This function will always return a valid pointer, but the result
will have no data (<literal>data==NULL</literal> and
<literal>num_data==0</literal>), if either of the following
conditions hold:
</para>
<para>
<orderedlist>
<listitem>If there is insufficient memory to copy the path. In this
    case <literal>path->status</literal> will be set to
    <link linkend="CAIRO-STATUS-NO-MEMORY:CAPS"><literal>CAIRO_STATUS_NO_MEMORY</literal></link>.</listitem>
<listitem>If <parameter>cr</parameter> is already in an error state. In this case
   <literal>path->status</literal> will contain the same status that
   would be returned by <link linkend="cairo-status"><function>cairo_status()</function></link>.</listitem>
</orderedlist>
</para>
<para>
In either case, <literal>path->status</literal> will be set to
<link linkend="CAIRO-STATUS-NO-MEMORY:CAPS"><literal>CAIRO_STATUS_NO_MEMORY</literal></link> (regardless of what the error status in
<parameter>cr</parameter> might have been).</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>cr</parameter>&nbsp;:</term>
<listitem><simpara> a cairo context
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> the copy of the current path. The caller owns the
returned object and should call <link linkend="cairo-path-destroy"><function>cairo_path_destroy()</function></link> when finished
with it.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="cairo-copy-path-flat" role="function"/>cairo_copy_path_flat ()</title>
<indexterm><primary>cairo_copy_path_flat</primary></indexterm><programlisting><link linkend="cairo-path-t">cairo_path_t</link>* cairo_copy_path_flat          (<link linkend="cairo-t">cairo_t</link> *cr);</programlisting>
<para>
Gets a flattened copy of the current path and returns it to the
user as a <link linkend="cairo-path-t"><type>cairo_path_t</type></link>. See <link linkend="cairo-path-data-t"><type>cairo_path_data_t</type></link> for hints on
how to iterate over the returned data structure.
</para>
<para>
This function is like <link linkend="cairo-copy-path"><function>cairo_copy_path()</function></link> except that any curves
in the path will be approximated with piecewise-linear
approximations, (accurate to within the current tolerance
value). That is, the result is guaranteed to not have any elements
of type <link linkend="CAIRO-PATH-CURVE-TO:CAPS"><literal>CAIRO_PATH_CURVE_TO</literal></link> which will instead be replaced by a
series of <link linkend="CAIRO-PATH-LINE-TO:CAPS"><literal>CAIRO_PATH_LINE_TO</literal></link> elements.
</para>
<para>
This function will always return a valid pointer, but the result
will have no data (<literal>data==NULL</literal> and
<literal>num_data==0</literal>), if either of the following
conditions hold:
</para>
<para>
<orderedlist>
<listitem>If there is insufficient memory to copy the path. In this
    case <literal>path->status</literal> will be set to
    <link linkend="CAIRO-STATUS-NO-MEMORY:CAPS"><literal>CAIRO_STATUS_NO_MEMORY</literal></link>.</listitem>
<listitem>If <parameter>cr</parameter> is already in an error state. In this case
   <literal>path->status</literal> will contain the same status that
   would be returned by <link linkend="cairo-status"><function>cairo_status()</function></link>.</listitem>
</orderedlist></para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>cr</parameter>&nbsp;:</term>
<listitem><simpara> a cairo context
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> the copy of the current path. The caller owns the
returned object and should call <link linkend="cairo-path-destroy"><function>cairo_path_destroy()</function></link> when finished
with it.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="cairo-path-destroy" role="function"/>cairo_path_destroy ()</title>
<indexterm><primary>cairo_path_destroy</primary></indexterm><programlisting><link linkend="void">void</link>        cairo_path_destroy              (<link linkend="cairo-path-t">cairo_path_t</link> *path);</programlisting>
<para>
Immediately releases all memory associated with <parameter>path</parameter>. After a call
to <link linkend="cairo-path-destroy"><function>cairo_path_destroy()</function></link> the <parameter>path</parameter> pointer is no longer valid and
should not be used further.
</para>
<para>
NOTE: cairo_path_destroy function should only be called with a
pointer to a <link linkend="cairo-path-t"><type>cairo_path_t</type></link> returned by a cairo function. Any path
that is created manually (ie. outside of cairo) should be destroyed
manually as well.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>path</parameter>&nbsp;:</term>
<listitem><simpara> a path previously returned by either <link linkend="cairo-copy-path"><function>cairo_copy_path()</function></link> or
<link linkend="cairo-copy-path-flat"><function>cairo_copy_path_flat()</function></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="cairo-append-path" role="function"/>cairo_append_path ()</title>
<indexterm><primary>cairo_append_path</primary></indexterm><programlisting><link linkend="void">void</link>        cairo_append_path               (<link linkend="cairo-t">cairo_t</link> *cr,
                                             <link linkend="cairo-path-t">cairo_path_t</link> *path);</programlisting>
<para>
Append the <parameter>path</parameter> onto the current path. The <parameter>path</parameter> may be either the
return value from one of <link linkend="cairo-copy-path"><function>cairo_copy_path()</function></link> or
<link linkend="cairo-copy-path-flat"><function>cairo_copy_path_flat()</function></link> or it may be constructed manually.  See
<link linkend="cairo-path-t"><type>cairo_path_t</type></link> for details on how the path data structure should be
initialized, and note that <literal>path->status</literal> must be
initialized to <link linkend="CAIRO-STATUS-SUCCESS:CAPS"><literal>CAIRO_STATUS_SUCCESS</literal></link>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>cr</parameter>&nbsp;:</term>
<listitem><simpara> a cairo context
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>path</parameter>&nbsp;:</term>
<listitem><simpara> path to be appended
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="cairo-get-current-point" role="function"/>cairo_get_current_point ()</title>
<indexterm><primary>cairo_get_current_point</primary></indexterm><programlisting><link linkend="void">void</link>        cairo_get_current_point         (<link linkend="cairo-t">cairo_t</link> *cr,
                                             <link linkend="double">double</link> *x,
                                             <link linkend="double">double</link> *y);</programlisting>
<para>
Gets the current point of the current path, which is
conceptually the final point reached by the path so far.
</para>
<para>
The current point is returned in the user-space coordinate
system. If there is no defined current point then <parameter>x</parameter> and <parameter>y</parameter> will
both be set to 0.0.
</para>
<para>
Most path construction functions alter the current point. See the
following for details on how they affect the current point:
</para>
<para>
<link linkend="cairo-new-path"><function>cairo_new_path()</function></link>, <link linkend="cairo-move-to"><function>cairo_move_to()</function></link>, <link linkend="cairo-line-to"><function>cairo_line_to()</function></link>,
<link linkend="cairo-curve-to"><function>cairo_curve_to()</function></link>, <link linkend="cairo-arc"><function>cairo_arc()</function></link>, <link linkend="cairo-rel-move-to"><function>cairo_rel_move_to()</function></link>,
<link linkend="cairo-rel-line-to"><function>cairo_rel_line_to()</function></link>, <link linkend="cairo-rel-curve-to"><function>cairo_rel_curve_to()</function></link>, <link linkend="cairo-arc"><function>cairo_arc()</function></link>,
<link linkend="cairo-text-path"><function>cairo_text_path()</function></link>, <link linkend="cairo-stroke-to-path"><function>cairo_stroke_to_path()</function></link></para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>cr</parameter>&nbsp;:</term>
<listitem><simpara> a cairo context
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>x</parameter>&nbsp;:</term>
<listitem><simpara> return value for X coordinate of the current point
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>y</parameter>&nbsp;:</term>
<listitem><simpara> return value for Y coordinate of the current point
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="cairo-new-path" role="function"/>cairo_new_path ()</title>
<indexterm><primary>cairo_new_path</primary></indexterm><programlisting><link linkend="void">void</link>        cairo_new_path                  (<link linkend="cairo-t">cairo_t</link> *cr);</programlisting>
<para>
Clears the current path. After this call there will be no path and
no current point.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>cr</parameter>&nbsp;:</term>
<listitem><simpara> a cairo context
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="cairo-new-sub-path" role="function" condition="since:1.2"/>cairo_new_sub_path ()</title>
<indexterm role="1.2"><primary>cairo_new_sub_path</primary></indexterm><programlisting><link linkend="void">void</link>        cairo_new_sub_path              (<link linkend="cairo-t">cairo_t</link> *cr);</programlisting>
<para>
Begin a new sub-path. Note that the existing path is not
affected. After this call there will be no current point.
</para>
<para>
In many cases, this call is not needed since new sub-paths are
frequently started with <link linkend="cairo-move-to"><function>cairo_move_to()</function></link>.
</para>
<para>
A call to <link linkend="cairo-new-sub-path"><function>cairo_new_sub_path()</function></link> is particularly useful when
beginning a new sub-path with one of the <link linkend="cairo-arc"><function>cairo_arc()</function></link> calls. This
makes things easier as it is no longer necessary to manually
compute the arc's initial coordinates for a call to
<link linkend="cairo-move-to"><function>cairo_move_to()</function></link>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>cr</parameter>&nbsp;:</term>
<listitem><simpara> a cairo context
</simpara></listitem></varlistentry>
</variablelist><para>Since  1.2
</para></refsect2>
<refsect2>
<title><anchor id="cairo-close-path" role="function"/>cairo_close_path ()</title>
<indexterm><primary>cairo_close_path</primary></indexterm><programlisting><link linkend="void">void</link>        cairo_close_path                (<link linkend="cairo-t">cairo_t</link> *cr);</programlisting>
<para>
Adds a line segment to the path from the current point to the
beginning of the current sub-path, (the most recent point passed to
<link linkend="cairo-move-to"><function>cairo_move_to()</function></link>), and closes this sub-path. After this call the
current point will be at the joined endpoint of the sub-path.
</para>
<para>
The behavior of <link linkend="cairo-close-path"><function>cairo_close_path()</function></link> is distinct from simply calling
<link linkend="cairo-line-to"><function>cairo_line_to()</function></link> with the equivalent coordinate in the case of
stroking. When a closed sub-path is stroked, there are no caps on
the ends of the sub-path. Instead, there is a line join connecting
the final and initial segments of the sub-path.
</para>
<para>
If there is no current point before the call to cairo_close_path,
this function will have no effect.
</para>
<para>
Note: As of cairo version 1.2.4 any call to cairo_close_path will
place an explicit MOVE_TO element into the path immediately after
the CLOSE_PATH element, (which can be seen in <link linkend="cairo-copy-path"><function>cairo_copy_path()</function></link> for
example). This can simplify path processing in some cases as it may
not be necessary to save the "last move_to point" during processing
as the MOVE_TO immediately after the CLOSE_PATH will provide that
point.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>cr</parameter>&nbsp;:</term>
<listitem><simpara> a cairo context
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="cairo-arc" role="function"/>cairo_arc ()</title>
<indexterm><primary>cairo_arc</primary></indexterm><programlisting><link linkend="void">void</link>        cairo_arc                       (<link linkend="cairo-t">cairo_t</link> *cr,
                                             <link linkend="double">double</link> xc,
                                             <link linkend="double">double</link> yc,
                                             <link linkend="double">double</link> radius,
                                             <link linkend="double">double</link> angle1,
                                             <link linkend="double">double</link> angle2);</programlisting>
<para>
Adds a circular arc of the given <parameter>radius</parameter> to the current path.  The
arc is centered at (<parameter>xc</parameter>, <parameter>yc</parameter>), begins at <parameter>angle1</parameter> and proceeds in
the direction of increasing angles to end at <parameter>angle2</parameter>. If <parameter>angle2</parameter> is
less than <parameter>angle1</parameter> it will be progressively increased by 2*M_PI
until it is greater than <parameter>angle1</parameter>.
</para>
<para>
If there is a current point, an initial line segment will be added
to the path to connect the current point to the beginning of the
arc.
</para>
<para>
Angles are measured in radians. An angle of 0.0 is in the direction
of the positive X axis (in user space). An angle of <link linkend="M-PI:CAPS"><literal>M_PI</literal></link>/2.0 radians
(90 degrees) is in the direction of the positive Y axis (in
user space). Angles increase in the direction from the positive X
axis toward the positive Y axis. So with the default transformation
matrix, angles increase in a clockwise direction.
</para>
<para>
(To convert from degrees to radians, use <literal>degrees * (M_PI /
180.)</literal>.)
</para>
<para>
This function gives the arc in the direction of increasing angles;
see <link linkend="cairo-arc-negative"><function>cairo_arc_negative()</function></link> to get the arc in the direction of
decreasing angles.
</para>
<para>
The arc is circular in user space. To achieve an elliptical arc,
you can scale the current transformation matrix by different
amounts in the X and Y directions. For example, to draw an ellipse
in the box given by <parameter>x</parameter>, <parameter>y</parameter>, <parameter>width</parameter>, <parameter>height</parameter>:
</para>
<para>
<informalexample><programlisting>
cairo_save (cr);
cairo_translate (cr, x + width / 2., y + height / 2.);
cairo_scale (cr, 1. / (height / 2.), 1. / (width / 2.));
cairo_arc (cr, 0., 0., 1., 0., 2 * M_PI);
cairo_restore (cr);
</programlisting></informalexample></para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>cr</parameter>&nbsp;:</term>
<listitem><simpara> a cairo context
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>xc</parameter>&nbsp;:</term>
<listitem><simpara> X position of the center of the arc
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>yc</parameter>&nbsp;:</term>
<listitem><simpara> Y position of the center of the arc
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>radius</parameter>&nbsp;:</term>
<listitem><simpara> the radius of the arc
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>angle1</parameter>&nbsp;:</term>
<listitem><simpara> the start angle, in radians
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>angle2</parameter>&nbsp;:</term>
<listitem><simpara> the end angle, in radians
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="cairo-arc-negative" role="function"/>cairo_arc_negative ()</title>
<indexterm><primary>cairo_arc_negative</primary></indexterm><programlisting><link linkend="void">void</link>        cairo_arc_negative              (<link linkend="cairo-t">cairo_t</link> *cr,
                                             <link linkend="double">double</link> xc,
                                             <link linkend="double">double</link> yc,
                                             <link linkend="double">double</link> radius,
                                             <link linkend="double">double</link> angle1,
                                             <link linkend="double">double</link> angle2);</programlisting>
<para>
Adds a circular arc of the given <parameter>radius</parameter> to the current path.  The
arc is centered at (<parameter>xc</parameter>, <parameter>yc</parameter>), begins at <parameter>angle1</parameter> and proceeds in
the direction of decreasing angles to end at <parameter>angle2</parameter>. If <parameter>angle2</parameter> is
greater than <parameter>angle1</parameter> it will be progressively decreased by 2*M_PI
until it is greater than <parameter>angle1</parameter>.
</para>
<para>
See <link linkend="cairo-arc"><function>cairo_arc()</function></link> for more details. This function differs only in the
direction of the arc between the two angles.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>cr</parameter>&nbsp;:</term>
<listitem><simpara> a cairo context
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>xc</parameter>&nbsp;:</term>
<listitem><simpara> X position of the center of the arc
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>yc</parameter>&nbsp;:</term>
<listitem><simpara> Y position of the center of the arc
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>radius</parameter>&nbsp;:</term>
<listitem><simpara> the radius of the arc
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>angle1</parameter>&nbsp;:</term>
<listitem><simpara> the start angle, in radians
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>angle2</parameter>&nbsp;:</term>
<listitem><simpara> the end angle, in radians
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="cairo-curve-to" role="function"/>cairo_curve_to ()</title>
<indexterm><primary>cairo_curve_to</primary></indexterm><programlisting><link linkend="void">void</link>        cairo_curve_to                  (<link linkend="cairo-t">cairo_t</link> *cr,
                                             <link linkend="double">double</link> x1,
                                             <link linkend="double">double</link> y1,
                                             <link linkend="double">double</link> x2,
                                             <link linkend="double">double</link> y2,
                                             <link linkend="double">double</link> x3,
                                             <link linkend="double">double</link> y3);</programlisting>
<para>
Adds a cubic Bézier spline to the path from the current point to
position (<parameter>x3</parameter>, <parameter>y3</parameter>) in user-space coordinates, using (<parameter>x1</parameter>, <parameter>y1</parameter>) and
(<parameter>x2</parameter>, <parameter>y2</parameter>) as the control points. After this call the current point
will be (<parameter>x3</parameter>, <parameter>y3</parameter>).
</para>
<para>
If there is no current point before the call to <link linkend="cairo-curve-to"><function>cairo_curve_to()</function></link>
this function will behave as if preceded by a call to
cairo_move_to (<parameter>cr</parameter>, <parameter>x1</parameter>, <parameter>y1</parameter>).</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>cr</parameter>&nbsp;:</term>
<listitem><simpara> a cairo context
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>x1</parameter>&nbsp;:</term>
<listitem><simpara> the X coordinate of the first control point
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>y1</parameter>&nbsp;:</term>
<listitem><simpara> the Y coordinate of the first control point
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>x2</parameter>&nbsp;:</term>
<listitem><simpara> the X coordinate of the second control point
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>y2</parameter>&nbsp;:</term>
<listitem><simpara> the Y coordinate of the second control point
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>x3</parameter>&nbsp;:</term>
<listitem><simpara> the X coordinate of the end of the curve
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>y3</parameter>&nbsp;:</term>
<listitem><simpara> the Y coordinate of the end of the curve
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="cairo-line-to" role="function"/>cairo_line_to ()</title>
<indexterm><primary>cairo_line_to</primary></indexterm><programlisting><link linkend="void">void</link>        cairo_line_to                   (<link linkend="cairo-t">cairo_t</link> *cr,
                                             <link linkend="double">double</link> x,
                                             <link linkend="double">double</link> y);</programlisting>
<para>
Adds a line to the path from the current point to position (<parameter>x</parameter>, <parameter>y</parameter>)
in user-space coordinates. After this call the current point
will be (<parameter>x</parameter>, <parameter>y</parameter>).
</para>
<para>
If there is no current point before the call to <link linkend="cairo-line-to"><function>cairo_line_to()</function></link>
this function will behave as cairo_move_to (<parameter>cr</parameter>, <parameter>x</parameter>, <parameter>y</parameter>).</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>cr</parameter>&nbsp;:</term>
<listitem><simpara> a cairo context
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>x</parameter>&nbsp;:</term>
<listitem><simpara> the X coordinate of the end of the new line
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>y</parameter>&nbsp;:</term>
<listitem><simpara> the Y coordinate of the end of the new line
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="cairo-move-to" role="function"/>cairo_move_to ()</title>
<indexterm><primary>cairo_move_to</primary></indexterm><programlisting><link linkend="void">void</link>        cairo_move_to                   (<link linkend="cairo-t">cairo_t</link> *cr,
                                             <link linkend="double">double</link> x,
                                             <link linkend="double">double</link> y);</programlisting>
<para>
Begin a new sub-path. After this call the current point will be (<parameter>x</parameter>,
<parameter>y</parameter>).</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>cr</parameter>&nbsp;:</term>
<listitem><simpara> a cairo context
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>x</parameter>&nbsp;:</term>
<listitem><simpara> the X coordinate of the new position
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>y</parameter>&nbsp;:</term>
<listitem><simpara> the Y coordinate of the new position
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="cairo-rectangle" role="function"/>cairo_rectangle ()</title>
<indexterm><primary>cairo_rectangle</primary></indexterm><programlisting><link linkend="void">void</link>        cairo_rectangle                 (<link linkend="cairo-t">cairo_t</link> *cr,
                                             <link linkend="double">double</link> x,
                                             <link linkend="double">double</link> y,
                                             <link linkend="double">double</link> width,
                                             <link linkend="double">double</link> height);</programlisting>
<para>
Adds a closed sub-path rectangle of the given size to the current
path at position (<parameter>x</parameter>, <parameter>y</parameter>) in user-space coordinates.
</para>
<para>
This function is logically equivalent to:
<informalexample><programlisting>
cairo_move_to (cr, x, y);
cairo_rel_line_to (cr, width, 0);
cairo_rel_line_to (cr, 0, height);
cairo_rel_line_to (cr, -width, 0);
cairo_close_path (cr);
</programlisting></informalexample></para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>cr</parameter>&nbsp;:</term>
<listitem><simpara> a cairo context
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>x</parameter>&nbsp;:</term>
<listitem><simpara> the X coordinate of the top left corner of the rectangle
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>y</parameter>&nbsp;:</term>
<listitem><simpara> the Y coordinate to the top left corner of the rectangle
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>width</parameter>&nbsp;:</term>
<listitem><simpara> the width of the rectangle
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>height</parameter>&nbsp;:</term>
<listitem><simpara> the height of the rectangle
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="cairo-glyph-path" role="function"/>cairo_glyph_path ()</title>
<indexterm><primary>cairo_glyph_path</primary></indexterm><programlisting><link linkend="void">void</link>        cairo_glyph_path                (<link linkend="cairo-t">cairo_t</link> *cr,
                                             <link linkend="cairo-glyph-t">cairo_glyph_t</link> *glyphs,
                                             <link linkend="int">int</link> num_glyphs);</programlisting>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>cr</parameter>&nbsp;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>glyphs</parameter>&nbsp;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>num_glyphs</parameter>&nbsp;:</term>
<listitem><simpara>


</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="cairo-text-path" role="function"/>cairo_text_path ()</title>
<indexterm><primary>cairo_text_path</primary></indexterm><programlisting><link linkend="void">void</link>        cairo_text_path                 (<link linkend="cairo-t">cairo_t</link> *cr,
                                             const <link linkend="char">char</link> *utf8);</programlisting>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>cr</parameter>&nbsp;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>utf8</parameter>&nbsp;:</term>
<listitem><simpara>


</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="cairo-rel-curve-to" role="function"/>cairo_rel_curve_to ()</title>
<indexterm><primary>cairo_rel_curve_to</primary></indexterm><programlisting><link linkend="void">void</link>        cairo_rel_curve_to              (<link linkend="cairo-t">cairo_t</link> *cr,
                                             <link linkend="double">double</link> dx1,
                                             <link linkend="double">double</link> dy1,
                                             <link linkend="double">double</link> dx2,
                                             <link linkend="double">double</link> dy2,
                                             <link linkend="double">double</link> dx3,
                                             <link linkend="double">double</link> dy3);</programlisting>
<para>
Relative-coordinate version of <link linkend="cairo-curve-to"><function>cairo_curve_to()</function></link>. All offsets are
relative to the current point. Adds a cubic Bézier spline to the
path from the current point to a point offset from the current
point by (<parameter>dx3</parameter>, <parameter>dy3</parameter>), using points offset by (<parameter>dx1</parameter>, <parameter>dy1</parameter>) and
(<parameter>dx2</parameter>, <parameter>dy2</parameter>) as the control points. After this call the current
point will be offset by (<parameter>dx3</parameter>, <parameter>dy3</parameter>).
</para>
<para>
Given a current point of (x, y), cairo_rel_curve_to (<parameter>cr</parameter>, <parameter>dx1</parameter>,
<parameter>dy1</parameter>, <parameter>dx2</parameter>, <parameter>dy2</parameter>, <parameter>dx3</parameter>, <parameter>dy3</parameter>) is logically equivalent to
cairo_curve_to (<parameter>cr</parameter>, x + <parameter>dx1</parameter>, y + <parameter>dy1</parameter>, x + <parameter>dx2</parameter>, y + <parameter>dy2</parameter>, x +
<parameter>dx3</parameter>, y + <parameter>dy3</parameter>).
</para>
<para>
It is an error to call this function with no current point. Doing
so will cause <parameter>cr</parameter> to shutdown with a status of
CAIRO_STATUS_NO_CURRENT_POINT.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>cr</parameter>&nbsp;:</term>
<listitem><simpara> a cairo context
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>dx1</parameter>&nbsp;:</term>
<listitem><simpara> the X offset to the first control point
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>dy1</parameter>&nbsp;:</term>
<listitem><simpara> the Y offset to the first control point
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>dx2</parameter>&nbsp;:</term>
<listitem><simpara> the X offset to the second control point
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>dy2</parameter>&nbsp;:</term>
<listitem><simpara> the Y offset to the second control point
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>dx3</parameter>&nbsp;:</term>
<listitem><simpara> the X offset to the end of the curve
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>dy3</parameter>&nbsp;:</term>
<listitem><simpara> the Y offset to the end of the curve
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="cairo-rel-line-to" role="function"/>cairo_rel_line_to ()</title>
<indexterm><primary>cairo_rel_line_to</primary></indexterm><programlisting><link linkend="void">void</link>        cairo_rel_line_to               (<link linkend="cairo-t">cairo_t</link> *cr,
                                             <link linkend="double">double</link> dx,
                                             <link linkend="double">double</link> dy);</programlisting>
<para>
Relative-coordinate version of <link linkend="cairo-line-to"><function>cairo_line_to()</function></link>. Adds a line to the
path from the current point to a point that is offset from the
current point by (<parameter>dx</parameter>, <parameter>dy</parameter>) in user space. After this call the
current point will be offset by (<parameter>dx</parameter>, <parameter>dy</parameter>).
</para>
<para>
Given a current point of (x, y), cairo_rel_line_to(<parameter>cr</parameter>, <parameter>dx</parameter>, <parameter>dy</parameter>)
is logically equivalent to cairo_line_to (<parameter>cr</parameter>, x + <parameter>dx</parameter>, y + <parameter>dy</parameter>).
</para>
<para>
It is an error to call this function with no current point. Doing
so will cause <parameter>cr</parameter> to shutdown with a status of
CAIRO_STATUS_NO_CURRENT_POINT.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>cr</parameter>&nbsp;:</term>
<listitem><simpara> a cairo context
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>dx</parameter>&nbsp;:</term>
<listitem><simpara> the X offset to the end of the new line
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>dy</parameter>&nbsp;:</term>
<listitem><simpara> the Y offset to the end of the new line
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="cairo-rel-move-to" role="function"/>cairo_rel_move_to ()</title>
<indexterm><primary>cairo_rel_move_to</primary></indexterm><programlisting><link linkend="void">void</link>        cairo_rel_move_to               (<link linkend="cairo-t">cairo_t</link> *cr,
                                             <link linkend="double">double</link> dx,
                                             <link linkend="double">double</link> dy);</programlisting>
<para>
Begin a new sub-path. After this call the current point will offset
by (<parameter>x</parameter>, <parameter>y</parameter>).
</para>
<para>
Given a current point of (x, y), cairo_rel_move_to(<parameter>cr</parameter>, <parameter>dx</parameter>, <parameter>dy</parameter>)
is logically equivalent to cairo_move_to (<parameter>cr</parameter>, x + <parameter>dx</parameter>, y + <parameter>dy</parameter>).
</para>
<para>
It is an error to call this function with no current point. Doing
so will cause <parameter>cr</parameter> to shutdown with a status of
CAIRO_STATUS_NO_CURRENT_POINT.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>cr</parameter>&nbsp;:</term>
<listitem><simpara> a cairo context
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>dx</parameter>&nbsp;:</term>
<listitem><simpara> the X offset
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>dy</parameter>&nbsp;:</term>
<listitem><simpara> the Y offset
</simpara></listitem></varlistentry>
</variablelist></refsect2>

</refsect1>




</refentry>