path: root/libs/cairo-1.16.0/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 role="top_of_page" id="cairo-Paths.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>
</refnamediv>

<refsect1 id="cairo-Paths.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-path-t"><returnvalue>cairo_path_t</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="cairo-copy-path">cairo_copy_path</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="cairo-path-t"><returnvalue>cairo_path_t</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="cairo-copy-path-flat">cairo_copy_path_flat</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="cairo-path-destroy">cairo_path_destroy</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="cairo-append-path">cairo_append_path</link>&#160;<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-has-current-point">cairo_has_current_point</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="cairo-get-current-point">cairo_get_current_point</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="cairo-new-path">cairo_new_path</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="cairo-new-sub-path">cairo_new_sub_path</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="cairo-close-path">cairo_close_path</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="cairo-arc">cairo_arc</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="cairo-arc-negative">cairo_arc_negative</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="cairo-curve-to">cairo_curve_to</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="cairo-line-to">cairo_line_to</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="cairo-move-to">cairo_move_to</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="cairo-rectangle">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="cairo-glyph-path">cairo_glyph_path</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="cairo-text-path">cairo_text_path</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="cairo-rel-curve-to">cairo_rel_curve_to</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="cairo-rel-line-to">cairo_rel_line_to</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="cairo-rel-move-to">cairo_rel_move_to</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="cairo-path-extents">cairo_path_extents</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>

</tbody>
</tgroup>
</informaltable>
</refsect1>
<refsect1 id="cairo-Paths.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="datatype_keyword"></entry><entry role="function_name"><link linkend="cairo-path-t">cairo_path_t</link></entry></row>
<row><entry role="datatype_keyword">union</entry><entry role="function_name"><link linkend="cairo-path-data-t">cairo_path_data_t</link></entry></row>
<row><entry role="datatype_keyword">enum</entry><entry role="function_name"><link linkend="cairo-path-data-type-t">cairo_path_data_type_t</link></entry></row>

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


<refsect1 id="cairo-Paths.description" role="desc">
<title role="desc.title">Description</title>
<para>Paths are the most basic drawing tools and are primarily used to implicitly
generate simple masks.</para>

</refsect1>
<refsect1 id="cairo-Paths.functions_details" role="details">
<title role="details.title">Functions</title>
<refsect2 id="cairo-copy-path" role="function" condition="since:1.0">
<title>cairo_copy_path&#160;()</title>
<indexterm zone="cairo-copy-path" role="1.0"><primary sortas="copy_path">cairo_copy_path</primary></indexterm>
<programlisting language="C"><link linkend="cairo-path-t"><returnvalue>cairo_path_t</returnvalue></link>&#160;*
cairo_copy_path (<parameter><link linkend="cairo-t"><type>cairo_t</type></link> *cr</parameter>);</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==<link linkend="NULL:CAPS"><literal>NULL</literal></link></literal> and
<literal>num_data==0</literal>), if either of the following
conditions hold:</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>
<refsect3 id="cairo-copy-path.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>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="cairo-copy-path.returns" role="returns">
<title>Returns</title>
<para> 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.</para>
</refsect3><para role="since">Since: <link linkend="api-index-1.0">1.0</link></para></refsect2>
<refsect2 id="cairo-copy-path-flat" role="function" condition="since:1.0">
<title>cairo_copy_path_flat&#160;()</title>
<indexterm zone="cairo-copy-path-flat" role="1.0"><primary sortas="copy_path_flat">cairo_copy_path_flat</primary></indexterm>
<programlisting language="C"><link linkend="cairo-path-t"><returnvalue>cairo_path_t</returnvalue></link>&#160;*
cairo_copy_path_flat (<parameter><link linkend="cairo-t"><type>cairo_t</type></link> *cr</parameter>);</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==<link linkend="NULL:CAPS"><literal>NULL</literal></link></literal> and
<literal>num_data==0</literal>), if either of the following
conditions hold:</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>
<refsect3 id="cairo-copy-path-flat.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>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="cairo-copy-path-flat.returns" role="returns">
<title>Returns</title>
<para> 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.</para>
</refsect3><para role="since">Since: <link linkend="api-index-1.0">1.0</link></para></refsect2>
<refsect2 id="cairo-path-destroy" role="function" condition="since:1.0">
<title>cairo_path_destroy&#160;()</title>
<indexterm zone="cairo-path-destroy" role="1.0"><primary sortas="path_destroy">cairo_path_destroy</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
cairo_path_destroy (<parameter><link linkend="cairo-path-t"><type>cairo_path_t</type></link> *path</parameter>);</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: <link linkend="cairo-path-destroy"><function>cairo_path_destroy()</function></link> 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>
<refsect3 id="cairo-path-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>path</para></entry>
<entry role="parameter_description"><para>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>.</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-append-path" role="function" condition="since:1.0">
<title>cairo_append_path&#160;()</title>
<indexterm zone="cairo-append-path" role="1.0"><primary sortas="append_path">cairo_append_path</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
cairo_append_path (<parameter><link linkend="cairo-t"><type>cairo_t</type></link> *cr</parameter>,
                   <parameter>const <link linkend="cairo-path-t"><type>cairo_path_t</type></link> *path</parameter>);</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>
<refsect3 id="cairo-append-path.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>path</para></entry>
<entry role="parameter_description"><para>path to be appended</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-has-current-point" role="function" condition="since:1.6">
<title>cairo_has_current_point&#160;()</title>
<indexterm zone="cairo-has-current-point" role="1.6"><primary sortas="has_current_point">cairo_has_current_point</primary></indexterm>
<programlisting language="C"><link linkend="cairo-bool-t"><returnvalue>cairo_bool_t</returnvalue></link>
cairo_has_current_point (<parameter><link linkend="cairo-t"><type>cairo_t</type></link> *cr</parameter>);</programlisting>
<para>Returns whether a current point is defined on the current path.
See <link linkend="cairo-get-current-point"><function>cairo_get_current_point()</function></link> for details on the current point.</para>
<refsect3 id="cairo-has-current-point.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>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="cairo-has-current-point.returns" role="returns">
<title>Returns</title>
<para> whether a current point is defined.</para>
</refsect3><para role="since">Since: <link linkend="api-index-1.6">1.6</link></para></refsect2>
<refsect2 id="cairo-get-current-point" role="function" condition="since:1.0">
<title>cairo_get_current_point&#160;()</title>
<indexterm zone="cairo-get-current-point" role="1.0"><primary sortas="get_current_point">cairo_get_current_point</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
cairo_get_current_point (<parameter><link linkend="cairo-t"><type>cairo_t</type></link> *cr</parameter>,
                         <parameter><link linkend="double"><type>double</type></link> *x</parameter>,
                         <parameter><link linkend="double"><type>double</type></link> *y</parameter>);</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 or if <parameter>cr</parameter>
 is in an
error status, <parameter>x</parameter>
 and <parameter>y</parameter>
 will both be set to 0.0. It is possible to
check this in advance with <link linkend="cairo-has-current-point"><function>cairo_has_current_point()</function></link>.</para>
<para>Most path construction functions alter the current point. See the
following for details on how they affect the current point:
<link linkend="cairo-new-path"><function>cairo_new_path()</function></link>, <link linkend="cairo-new-sub-path"><function>cairo_new_sub_path()</function></link>,
<link linkend="cairo-append-path"><function>cairo_append_path()</function></link>, <link linkend="cairo-close-path"><function>cairo_close_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-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-arc-negative"><function>cairo_arc_negative()</function></link>, <link linkend="cairo-rectangle"><function>cairo_rectangle()</function></link>,
<link linkend="cairo-text-path"><function>cairo_text_path()</function></link>, <link linkend="cairo-glyph-path"><function>cairo_glyph_path()</function></link>, <link linkend="cairo-stroke-to-path"><function>cairo_stroke_to_path()</function></link>.</para>
<para>Some functions use and alter the current point but do not
otherwise change current path:
<link linkend="cairo-show-text"><function>cairo_show_text()</function></link>.</para>
<para>Some functions unset the current path and as a result, current point:
<link linkend="cairo-fill"><function>cairo_fill()</function></link>, <link linkend="cairo-stroke"><function>cairo_stroke()</function></link>.</para>
<refsect3 id="cairo-get-current-point.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>x</para></entry>
<entry role="parameter_description"><para>return value for X coordinate of the current point</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>y</para></entry>
<entry role="parameter_description"><para>return value for Y coordinate of the current point</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-new-path" role="function" condition="since:1.0">
<title>cairo_new_path&#160;()</title>
<indexterm zone="cairo-new-path" role="1.0"><primary sortas="new_path">cairo_new_path</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
cairo_new_path (<parameter><link linkend="cairo-t"><type>cairo_t</type></link> *cr</parameter>);</programlisting>
<para>Clears the current path. After this call there will be no path and
no current point.</para>
<refsect3 id="cairo-new-path.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>
</tbody></tgroup></informaltable>
</refsect3><para role="since">Since: <link linkend="api-index-1.0">1.0</link></para></refsect2>
<refsect2 id="cairo-new-sub-path" role="function" condition="since:1.2">
<title>cairo_new_sub_path&#160;()</title>
<indexterm zone="cairo-new-sub-path" role="1.2"><primary sortas="new_sub_path">cairo_new_sub_path</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
cairo_new_sub_path (<parameter><link linkend="cairo-t"><type>cairo_t</type></link> *cr</parameter>);</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>
<refsect3 id="cairo-new-sub-path.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>
</tbody></tgroup></informaltable>
</refsect3><para role="since">Since: <link linkend="api-index-1.2">1.2</link></para></refsect2>
<refsect2 id="cairo-close-path" role="function" condition="since:1.0">
<title>cairo_close_path&#160;()</title>
<indexterm zone="cairo-close-path" role="1.0"><primary sortas="close_path">cairo_close_path</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
cairo_close_path (<parameter><link linkend="cairo-t"><type>cairo_t</type></link> *cr</parameter>);</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 <link linkend="cairo-close-path"><function>cairo_close_path()</function></link>,
this function will have no effect.</para>
<para>Note: As of cairo version 1.2.4 any call to <link linkend="cairo-close-path"><function>cairo_close_path()</function></link> 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>
<refsect3 id="cairo-close-path.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>
</tbody></tgroup></informaltable>
</refsect3><para role="since">Since: <link linkend="api-index-1.0">1.0</link></para></refsect2>
<refsect2 id="cairo-arc" role="function" condition="since:1.0">
<title>cairo_arc&#160;()</title>
<indexterm zone="cairo-arc" role="1.0"><primary sortas="arc">cairo_arc</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
cairo_arc (<parameter><link linkend="cairo-t"><type>cairo_t</type></link> *cr</parameter>,
           <parameter><link linkend="double"><type>double</type></link> xc</parameter>,
           <parameter><link linkend="double"><type>double</type></link> yc</parameter>,
           <parameter><link linkend="double"><type>double</type></link> radius</parameter>,
           <parameter><link linkend="double"><type>double</type></link> angle1</parameter>,
           <parameter><link linkend="double"><type>double</type></link> angle2</parameter>);</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
<literal>2*M_PI</literal> 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. If this initial line is undesired, it can be avoided by
calling <link linkend="cairo-new-sub-path"><function>cairo_new_sub_path()</function></link> before calling <link linkend="cairo-arc"><function>cairo_arc()</function></link>.</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
<literal>M_PI/2.0</literal> 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>
<informalexample><programlisting>
cairo_save (cr);
cairo_translate (cr, x + width / 2., y + height / 2.);
cairo_scale (cr, width / 2., height / 2.);
cairo_arc (cr, 0., 0., 1., 0., 2 * M_PI);
cairo_restore (cr);
</programlisting></informalexample>
<refsect3 id="cairo-arc.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>xc</para></entry>
<entry role="parameter_description"><para>X position of the center of the arc</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>yc</para></entry>
<entry role="parameter_description"><para>Y position of the center of the arc</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>radius</para></entry>
<entry role="parameter_description"><para>the radius of the arc</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>angle1</para></entry>
<entry role="parameter_description"><para>the start angle, in radians</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>angle2</para></entry>
<entry role="parameter_description"><para>the end angle, in radians</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-arc-negative" role="function" condition="since:1.0">
<title>cairo_arc_negative&#160;()</title>
<indexterm zone="cairo-arc-negative" role="1.0"><primary sortas="arc_negative">cairo_arc_negative</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
cairo_arc_negative (<parameter><link linkend="cairo-t"><type>cairo_t</type></link> *cr</parameter>,
                    <parameter><link linkend="double"><type>double</type></link> xc</parameter>,
                    <parameter><link linkend="double"><type>double</type></link> yc</parameter>,
                    <parameter><link linkend="double"><type>double</type></link> radius</parameter>,
                    <parameter><link linkend="double"><type>double</type></link> angle1</parameter>,
                    <parameter><link linkend="double"><type>double</type></link> angle2</parameter>);</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
<literal>2*M_PI</literal> until it is less 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>
<refsect3 id="cairo-arc-negative.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>xc</para></entry>
<entry role="parameter_description"><para>X position of the center of the arc</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>yc</para></entry>
<entry role="parameter_description"><para>Y position of the center of the arc</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>radius</para></entry>
<entry role="parameter_description"><para>the radius of the arc</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>angle1</para></entry>
<entry role="parameter_description"><para>the start angle, in radians</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>angle2</para></entry>
<entry role="parameter_description"><para>the end angle, in radians</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-curve-to" role="function" condition="since:1.0">
<title>cairo_curve_to&#160;()</title>
<indexterm zone="cairo-curve-to" role="1.0"><primary sortas="curve_to">cairo_curve_to</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
cairo_curve_to (<parameter><link linkend="cairo-t"><type>cairo_t</type></link> *cr</parameter>,
                <parameter><link linkend="double"><type>double</type></link> x1</parameter>,
                <parameter><link linkend="double"><type>double</type></link> y1</parameter>,
                <parameter><link linkend="double"><type>double</type></link> x2</parameter>,
                <parameter><link linkend="double"><type>double</type></link> y2</parameter>,
                <parameter><link linkend="double"><type>double</type></link> x3</parameter>,
                <parameter><link linkend="double"><type>double</type></link> y3</parameter>);</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>
<refsect3 id="cairo-curve-to.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>x1</para></entry>
<entry role="parameter_description"><para>the X coordinate of the first control point</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>y1</para></entry>
<entry role="parameter_description"><para>the Y coordinate of the first control point</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>x2</para></entry>
<entry role="parameter_description"><para>the X coordinate of the second control point</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>y2</para></entry>
<entry role="parameter_description"><para>the Y coordinate of the second control point</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>x3</para></entry>
<entry role="parameter_description"><para>the X coordinate of the end of the curve</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>y3</para></entry>
<entry role="parameter_description"><para>the Y coordinate of the end of the curve</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-line-to" role="function" condition="since:1.0">
<title>cairo_line_to&#160;()</title>
<indexterm zone="cairo-line-to" role="1.0"><primary sortas="line_to">cairo_line_to</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
cairo_line_to (<parameter><link linkend="cairo-t"><type>cairo_t</type></link> *cr</parameter>,
               <parameter><link linkend="double"><type>double</type></link> x</parameter>,
               <parameter><link linkend="double"><type>double</type></link> y</parameter>);</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>
<refsect3 id="cairo-line-to.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>x</para></entry>
<entry role="parameter_description"><para>the X coordinate of the end of the new line</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>y</para></entry>
<entry role="parameter_description"><para>the Y coordinate of the end of the new line</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-move-to" role="function" condition="since:1.0">
<title>cairo_move_to&#160;()</title>
<indexterm zone="cairo-move-to" role="1.0"><primary sortas="move_to">cairo_move_to</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
cairo_move_to (<parameter><link linkend="cairo-t"><type>cairo_t</type></link> *cr</parameter>,
               <parameter><link linkend="double"><type>double</type></link> x</parameter>,
               <parameter><link linkend="double"><type>double</type></link> y</parameter>);</programlisting>
<para>Begin a new sub-path. After this call the current point will be (<parameter>x</parameter>
,
<parameter>y</parameter>
).</para>
<refsect3 id="cairo-move-to.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>x</para></entry>
<entry role="parameter_description"><para>the X coordinate of the new position</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>y</para></entry>
<entry role="parameter_description"><para>the Y coordinate of the new position</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-rectangle" role="function" condition="since:1.0">
<title>cairo_rectangle&#160;()</title>
<indexterm zone="cairo-rectangle" role="1.0"><primary sortas="rectangle">cairo_rectangle</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
cairo_rectangle (<parameter><link linkend="cairo-t"><type>cairo_t</type></link> *cr</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>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:</para>
<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>
<refsect3 id="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>x</para></entry>
<entry role="parameter_description"><para>the X coordinate of the top left corner of the rectangle</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>y</para></entry>
<entry role="parameter_description"><para>the Y coordinate to the top left corner of the rectangle</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 rectangle</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 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-glyph-path" role="function" condition="since:1.0">
<title>cairo_glyph_path&#160;()</title>
<indexterm zone="cairo-glyph-path" role="1.0"><primary sortas="glyph_path">cairo_glyph_path</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
cairo_glyph_path (<parameter><link linkend="cairo-t"><type>cairo_t</type></link> *cr</parameter>,
                  <parameter>const <link linkend="cairo-glyph-t"><type>cairo_glyph_t</type></link> *glyphs</parameter>,
                  <parameter><link linkend="int"><type>int</type></link> num_glyphs</parameter>);</programlisting>
<para>Adds closed paths for the glyphs to the current path.  The generated
path if filled, achieves an effect similar to that of
<link linkend="cairo-show-glyphs"><function>cairo_show_glyphs()</function></link>.</para>
<refsect3 id="cairo-glyph-path.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>glyphs</para></entry>
<entry role="parameter_description"><para>array of glyphs to show</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>num_glyphs</para></entry>
<entry role="parameter_description"><para>number of glyphs to show</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-text-path" role="function" condition="since:1.0">
<title>cairo_text_path&#160;()</title>
<indexterm zone="cairo-text-path" role="1.0"><primary sortas="text_path">cairo_text_path</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
cairo_text_path (<parameter><link linkend="cairo-t"><type>cairo_t</type></link> *cr</parameter>,
                 <parameter>const <link linkend="char"><type>char</type></link> *utf8</parameter>);</programlisting>
<para>Adds closed paths for text to the current path.  The generated
path if filled, achieves an effect similar to that of
<link linkend="cairo-show-text"><function>cairo_show_text()</function></link>.</para>
<para>Text conversion and positioning is done similar to <link linkend="cairo-show-text"><function>cairo_show_text()</function></link>.</para>
<para>Like <link linkend="cairo-show-text"><function>cairo_show_text()</function></link>, After this call the current point is
moved to the origin of where the next glyph would be placed in
this same progression.  That is, the current point will be at
the origin of the final glyph offset by its advance values.
This allows for chaining multiple calls to to <link linkend="cairo-text-path"><function>cairo_text_path()</function></link>
without having to set current point in between.</para>
<para>Note: The <link linkend="cairo-text-path"><function>cairo_text_path()</function></link> function call is part of what the cairo
designers call the "toy" text API. It is convenient for short demos
and simple programs, but it is not expected to be adequate for
serious text-using applications. See <link linkend="cairo-glyph-path"><function>cairo_glyph_path()</function></link> for the
"real" text path API in cairo.</para>
<refsect3 id="cairo-text-path.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>utf8</para></entry>
<entry role="parameter_description"><para>a NUL-terminated string of text encoded in UTF-8, or <link linkend="NULL:CAPS"><literal>NULL</literal></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-rel-curve-to" role="function" condition="since:1.0">
<title>cairo_rel_curve_to&#160;()</title>
<indexterm zone="cairo-rel-curve-to" role="1.0"><primary sortas="rel_curve_to">cairo_rel_curve_to</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
cairo_rel_curve_to (<parameter><link linkend="cairo-t"><type>cairo_t</type></link> *cr</parameter>,
                    <parameter><link linkend="double"><type>double</type></link> dx1</parameter>,
                    <parameter><link linkend="double"><type>double</type></link> dy1</parameter>,
                    <parameter><link linkend="double"><type>double</type></link> dx2</parameter>,
                    <parameter><link linkend="double"><type>double</type></link> dy2</parameter>,
                    <parameter><link linkend="double"><type>double</type></link> dx3</parameter>,
                    <parameter><link linkend="double"><type>double</type></link> dy3</parameter>);</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
<link linkend="CAIRO-STATUS-NO-CURRENT-POINT:CAPS"><literal>CAIRO_STATUS_NO_CURRENT_POINT</literal></link>.</para>
<refsect3 id="cairo-rel-curve-to.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>dx1</para></entry>
<entry role="parameter_description"><para>the X offset to the first control point</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>dy1</para></entry>
<entry role="parameter_description"><para>the Y offset to the first control point</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>dx2</para></entry>
<entry role="parameter_description"><para>the X offset to the second control point</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>dy2</para></entry>
<entry role="parameter_description"><para>the Y offset to the second control point</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>dx3</para></entry>
<entry role="parameter_description"><para>the X offset to the end of the curve</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>dy3</para></entry>
<entry role="parameter_description"><para>the Y offset to the end of the curve</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-rel-line-to" role="function" condition="since:1.0">
<title>cairo_rel_line_to&#160;()</title>
<indexterm zone="cairo-rel-line-to" role="1.0"><primary sortas="rel_line_to">cairo_rel_line_to</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
cairo_rel_line_to (<parameter><link linkend="cairo-t"><type>cairo_t</type></link> *cr</parameter>,
                   <parameter><link linkend="double"><type>double</type></link> dx</parameter>,
                   <parameter><link linkend="double"><type>double</type></link> dy</parameter>);</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
<link linkend="CAIRO-STATUS-NO-CURRENT-POINT:CAPS"><literal>CAIRO_STATUS_NO_CURRENT_POINT</literal></link>.</para>
<refsect3 id="cairo-rel-line-to.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>dx</para></entry>
<entry role="parameter_description"><para>the X offset to the end of the new line</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>dy</para></entry>
<entry role="parameter_description"><para>the Y offset to the end of the new line</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-rel-move-to" role="function" condition="since:1.0">
<title>cairo_rel_move_to&#160;()</title>
<indexterm zone="cairo-rel-move-to" role="1.0"><primary sortas="rel_move_to">cairo_rel_move_to</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
cairo_rel_move_to (<parameter><link linkend="cairo-t"><type>cairo_t</type></link> *cr</parameter>,
                   <parameter><link linkend="double"><type>double</type></link> dx</parameter>,
                   <parameter><link linkend="double"><type>double</type></link> dy</parameter>);</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
<link linkend="CAIRO-STATUS-NO-CURRENT-POINT:CAPS"><literal>CAIRO_STATUS_NO_CURRENT_POINT</literal></link>.</para>
<refsect3 id="cairo-rel-move-to.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>dx</para></entry>
<entry role="parameter_description"><para>the X offset</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>dy</para></entry>
<entry role="parameter_description"><para>the Y offset</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-path-extents" role="function" condition="since:1.6">
<title>cairo_path_extents&#160;()</title>
<indexterm zone="cairo-path-extents" role="1.6"><primary sortas="path_extents">cairo_path_extents</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
cairo_path_extents (<parameter><link linkend="cairo-t"><type>cairo_t</type></link> *cr</parameter>,
                    <parameter><link linkend="double"><type>double</type></link> *x1</parameter>,
                    <parameter><link linkend="double"><type>double</type></link> *y1</parameter>,
                    <parameter><link linkend="double"><type>double</type></link> *x2</parameter>,
                    <parameter><link linkend="double"><type>double</type></link> *y2</parameter>);</programlisting>
<para>Computes a bounding box in user-space coordinates covering the
points on the current path. If the current path is empty, returns
an empty rectangle ((0,0), (0,0)). Stroke parameters, fill rule,
surface dimensions and clipping are not taken into account.</para>
<para>Contrast with <link linkend="cairo-fill-extents"><function>cairo_fill_extents()</function></link> and <link linkend="cairo-stroke-extents"><function>cairo_stroke_extents()</function></link> which
return the extents of only the area that would be "inked" by
the corresponding drawing operations.</para>
<para>The result of <link linkend="cairo-path-extents"><function>cairo_path_extents()</function></link> is defined as equivalent to the
limit of <link linkend="cairo-stroke-extents"><function>cairo_stroke_extents()</function></link> with <link linkend="CAIRO-LINE-CAP-ROUND:CAPS"><literal>CAIRO_LINE_CAP_ROUND</literal></link> as the
line width approaches 0.0, (but never reaching the empty-rectangle
returned by <link linkend="cairo-stroke-extents"><function>cairo_stroke_extents()</function></link> for a line width of 0.0).</para>
<para>Specifically, this means that zero-area sub-paths such as
<link linkend="cairo-move-to"><function>cairo_move_to()</function></link>;<link linkend="cairo-line-to"><function>cairo_line_to()</function></link> segments, (even degenerate cases
where the coordinates to both calls are identical), will be
considered as contributing to the extents. However, a lone
<link linkend="cairo-move-to"><function>cairo_move_to()</function></link> will not contribute to the results of
<link linkend="cairo-path-extents"><function>cairo_path_extents()</function></link>.</para>
<refsect3 id="cairo-path-extents.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>x1</para></entry>
<entry role="parameter_description"><para>left of the resulting extents</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>y1</para></entry>
<entry role="parameter_description"><para>top of the resulting extents</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>x2</para></entry>
<entry role="parameter_description"><para>right of the resulting extents</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>y2</para></entry>
<entry role="parameter_description"><para>bottom of the resulting extents</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>

</refsect1>
<refsect1 id="cairo-Paths.other_details" role="details">
<title role="details.title">Types and Values</title>
<refsect2 id="cairo-path-t" role="struct" condition="since:1.0">
<title>cairo_path_t</title>
<indexterm zone="cairo-path-t" role="1.0"><primary sortas="path_t">cairo_path_t</primary></indexterm>
<programlisting language="C">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>
<refsect3 id="cairo-path-t.members" role="struct_members">
<title>Members</title>
<informaltable role="struct_members_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="struct_members_name" colwidth="300px"/>
<colspec colname="struct_members_description"/>
<colspec colname="struct_members_annotations" colwidth="200px"/>
<tbody>
<row role="member"><entry role="struct_member_name"><para><link linkend="cairo-status-t"><type>cairo_status_t</type></link>&#160;<structfield id="cairo-path-t.status">status</structfield>;</para></entry>
<entry role="struct_member_description"><para>the current error status</para></entry>
<entry role="struct_member_annotations"></entry>
</row>
<row role="member"><entry role="struct_member_name"><para><link linkend="cairo-path-data-t"><type>cairo_path_data_t</type></link>&#160;*<structfield id="cairo-path-t.data">data</structfield>;</para></entry>
<entry role="struct_member_description"><para>the elements in the path</para></entry>
<entry role="struct_member_annotations"></entry>
</row>
<row role="member"><entry role="struct_member_name"><para><link linkend="int"><type>int</type></link>&#160;<structfield id="cairo-path-t.num-data">num_data</structfield>;</para></entry>
<entry role="struct_member_description"><para>the number of elements in the data array</para></entry>
<entry role="struct_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-path-data-t" role="union" condition="since:1.0">
<title>union cairo_path_data_t</title>
<indexterm zone="cairo-path-data-t" role="1.0"><primary sortas="path_data_t">cairo_path_data_t</primary></indexterm>
<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 is as follows:</para>
<programlisting>
    %CAIRO_PATH_MOVE_TO:     1 point
    %CAIRO_PATH_LINE_TO:     1 point
    %CAIRO_PATH_CURVE_TO:    3 points
    %CAIRO_PATH_CLOSE_PATH:  0 points
</programlisting>
<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>
<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:
             do_close_path_things ();
             break;
         }
     }
     cairo_path_destroy (path);
</programlisting></informalexample>
<para>As of cairo 1.4, cairo does not mind if there are more elements in
a portion of the path than needed.  Such elements can be used by
users of the cairo API to hold extra values in the path data
structure.  For this reason, it is recommended that applications
always use <literal>data->header.length</literal> to
iterate over the path data, instead of hardcoding the number of
elements for each element type.</para>
<para role="since">Since: <link linkend="api-index-1.0">1.0</link></para></refsect2>
<refsect2 id="cairo-path-data-type-t" role="enum" condition="since:1.0">
<title>enum cairo_path_data_type_t</title>
<indexterm zone="cairo-path-data-type-t" role="1.0"><primary sortas="path_data_type_t">cairo_path_data_type_t</primary></indexterm>
<para><link linkend="cairo-path-data-t"><type>cairo_path_data_t</type></link> is used to describe the type of one portion
of a path when represented 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 details.</para>
<refsect3 id="cairo-path-data-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-PATH-MOVE-TO:CAPS">CAIRO_PATH_MOVE_TO</para></entry>
<entry role="enum_member_description"><para>A move-to operation, since 1.0</para>
</entry>
<entry role="enum_member_annotations"></entry>
</row>
<row role="constant"><entry role="enum_member_name"><para id="CAIRO-PATH-LINE-TO:CAPS">CAIRO_PATH_LINE_TO</para></entry>
<entry role="enum_member_description"><para>A line-to operation, since 1.0</para>
</entry>
<entry role="enum_member_annotations"></entry>
</row>
<row role="constant"><entry role="enum_member_name"><para id="CAIRO-PATH-CURVE-TO:CAPS">CAIRO_PATH_CURVE_TO</para></entry>
<entry role="enum_member_description"><para>A curve-to operation, since 1.0</para>
</entry>
<entry role="enum_member_annotations"></entry>
</row>
<row role="constant"><entry role="enum_member_name"><para id="CAIRO-PATH-CLOSE-PATH:CAPS">CAIRO_PATH_CLOSE_PATH</para></entry>
<entry role="enum_member_description"><para>A close-path operation, 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>

</refsect1>

</refentry>