|
Server : Apache/2.2.17 (Unix) mod_ssl/2.2.17 OpenSSL/0.9.8e-fips-rhel5 DAV/2 PHP/5.2.17 System : Linux localhost 2.6.18-419.el5 #1 SMP Fri Feb 24 22:47:42 UTC 2017 x86_64 User : nobody ( 99) PHP Version : 5.2.17 Disable Function : NONE Directory : /usr/share/gtk-doc/html/cairo/ |
Upload File : |
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Paths</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.68.1">
<link rel="start" href="index.html" title="Cairo: A Vector Graphics Library">
<link rel="up" href="Drawing.html" title="Drawing">
<link rel="prev" href="cairo-cairo-t.html" title="cairo_t">
<link rel="next" href="cairo-Patterns.html" title="Patterns">
<meta name="generator" content="GTK-Doc V1.7 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
<link rel="part" href="pt01.html" title="Part I. Tutorial">
<link rel="part" href="pt02.html" title="Part II. Reference">
<link rel="chapter" href="Drawing.html" title="Drawing">
<link rel="chapter" href="Fonts.html" title="Fonts">
<link rel="chapter" href="Surfaces.html" title="Surfaces">
<link rel="chapter" href="Support.html" title="Utilities">
<link rel="index" href="ix01.html" title="Index">
<link rel="index" href="ix02.html" title="Index of new symbols in 1.2">
<link rel="appendix" href="language-bindings.html" title="Appendix A. Creating a language binding for cairo">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2">
<tr valign="middle">
<td><a accesskey="p" href="cairo-cairo-t.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
<td><a accesskey="u" href="Drawing.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
<th width="100%" align="center">Cairo: A Vector Graphics Library</th>
<td><a accesskey="n" href="cairo-Patterns.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
</tr>
<tr><td colspan="5" class="shortcuts"><nobr><a href="#id2542233" class="shortcut">Top</a>
 | 
<a href="#id2572231" class="shortcut">Description</a></nobr></td></tr>
</table>
<div class="refentry" lang="en">
<a name="cairo-Paths"></a><div class="titlepage"></div>
<div class="refnamediv"><table width="100%"><tr>
<td valign="top">
<h2>
<a name="id2542233"></a><span class="refentrytitle">Paths</span>
</h2>
<p>Paths — Creating paths and manipulating path data</p>
</td>
<td valign="top" align="right"></td>
</tr></table></div>
<div class="refsynopsisdiv">
<h2>Synopsis</h2>
<pre class="synopsis">
<a href="cairo-Paths.html#cairo-path-t">cairo_path_t</a>;
union <a href="cairo-Paths.html#cairo-path-data-t">cairo_path_data_t</a>;
enum <a href="cairo-Paths.html#cairo-path-data-type-t">cairo_path_data_type_t</a>;
<a href="cairo-Paths.html#cairo-path-t">cairo_path_t</a>* <a href="cairo-Paths.html#cairo-copy-path">cairo_copy_path</a> (<a href="cairo-cairo-t.html#cairo-t">cairo_t</a> *cr);
<a href="cairo-Paths.html#cairo-path-t">cairo_path_t</a>* <a href="cairo-Paths.html#cairo-copy-path-flat">cairo_copy_path_flat</a> (<a href="cairo-cairo-t.html#cairo-t">cairo_t</a> *cr);
void <a href="cairo-Paths.html#cairo-path-destroy">cairo_path_destroy</a> (<a href="cairo-Paths.html#cairo-path-t">cairo_path_t</a> *path);
void <a href="cairo-Paths.html#cairo-append-path">cairo_append_path</a> (<a href="cairo-cairo-t.html#cairo-t">cairo_t</a> *cr,
<a href="cairo-Paths.html#cairo-path-t">cairo_path_t</a> *path);
void <a href="cairo-Paths.html#cairo-get-current-point">cairo_get_current_point</a> (<a href="cairo-cairo-t.html#cairo-t">cairo_t</a> *cr,
double *x,
double *y);
void <a href="cairo-Paths.html#cairo-new-path">cairo_new_path</a> (<a href="cairo-cairo-t.html#cairo-t">cairo_t</a> *cr);
void <a href="cairo-Paths.html#cairo-new-sub-path">cairo_new_sub_path</a> (<a href="cairo-cairo-t.html#cairo-t">cairo_t</a> *cr);
void <a href="cairo-Paths.html#cairo-close-path">cairo_close_path</a> (<a href="cairo-cairo-t.html#cairo-t">cairo_t</a> *cr);
void <a href="cairo-Paths.html#cairo-arc">cairo_arc</a> (<a href="cairo-cairo-t.html#cairo-t">cairo_t</a> *cr,
double xc,
double yc,
double radius,
double angle1,
double angle2);
void <a href="cairo-Paths.html#cairo-arc-negative">cairo_arc_negative</a> (<a href="cairo-cairo-t.html#cairo-t">cairo_t</a> *cr,
double xc,
double yc,
double radius,
double angle1,
double angle2);
void <a href="cairo-Paths.html#cairo-curve-to">cairo_curve_to</a> (<a href="cairo-cairo-t.html#cairo-t">cairo_t</a> *cr,
double x1,
double y1,
double x2,
double y2,
double x3,
double y3);
void <a href="cairo-Paths.html#cairo-line-to">cairo_line_to</a> (<a href="cairo-cairo-t.html#cairo-t">cairo_t</a> *cr,
double x,
double y);
void <a href="cairo-Paths.html#cairo-move-to">cairo_move_to</a> (<a href="cairo-cairo-t.html#cairo-t">cairo_t</a> *cr,
double x,
double y);
void <a href="cairo-Paths.html#cairo-rectangle">cairo_rectangle</a> (<a href="cairo-cairo-t.html#cairo-t">cairo_t</a> *cr,
double x,
double y,
double width,
double height);
void <a href="cairo-Paths.html#cairo-glyph-path">cairo_glyph_path</a> (<a href="cairo-cairo-t.html#cairo-t">cairo_t</a> *cr,
<a href="cairo-Text.html#cairo-glyph-t">cairo_glyph_t</a> *glyphs,
int num_glyphs);
void <a href="cairo-Paths.html#cairo-text-path">cairo_text_path</a> (<a href="cairo-cairo-t.html#cairo-t">cairo_t</a> *cr,
const char *utf8);
void <a href="cairo-Paths.html#cairo-rel-curve-to">cairo_rel_curve_to</a> (<a href="cairo-cairo-t.html#cairo-t">cairo_t</a> *cr,
double dx1,
double dy1,
double dx2,
double dy2,
double dx3,
double dy3);
void <a href="cairo-Paths.html#cairo-rel-line-to">cairo_rel_line_to</a> (<a href="cairo-cairo-t.html#cairo-t">cairo_t</a> *cr,
double dx,
double dy);
void <a href="cairo-Paths.html#cairo-rel-move-to">cairo_rel_move_to</a> (<a href="cairo-cairo-t.html#cairo-t">cairo_t</a> *cr,
double dx,
double dy);
</pre>
</div>
<div class="refsect1" lang="en">
<a name="id2572231"></a><h2>Description</h2>
<p>
</p>
</div>
<div class="refsect1" lang="en">
<a name="id2572247"></a><h2>Details</h2>
<div class="refsect2" lang="en">
<a name="id2572258"></a><h3>
<a name="cairo-path-t"></a>cairo_path_t</h3>
<a class="indexterm" name="id2572270"></a><pre class="programlisting">typedef struct {
cairo_status_t status;
cairo_path_data_t *data;
int num_data;
} cairo_path_t;
</pre>
<p>
A data structure for holding a path. This data structure serves as
the return value for <a href="cairo-Paths.html#cairo-copy-path"><code class="function">cairo_copy_path()</code></a> and
<a href="cairo-Paths.html#cairo-copy-path-flat"><code class="function">cairo_copy_path_flat()</code></a> as well the input value for
<a href="cairo-Paths.html#cairo-append-path"><code class="function">cairo_append_path()</code></a>.
</p>
<p>
See <a href="cairo-Paths.html#cairo-path-data-t"><span class="type">cairo_path_data_t</span></a> for hints on how to iterate over the
actual data within the path.
</p>
<p>
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 <a href="cairo-Paths.html#cairo-path-data-type-t"><span class="type">cairo_path_data_type_t</span></a>), since the data
includes both headers and coordinates for each portion.</p>
<p>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><a href="cairo-Error-handling.html#cairo-status-t">cairo_status_t</a> <em class="structfield"><code>status</code></em>;</span></td>
<td> the current error status
</td>
</tr>
<tr>
<td>
<span class="term"><a href="cairo-Paths.html#cairo-path-data-t">cairo_path_data_t</a> *<em class="structfield"><code>data</code></em>;</span></td>
<td> the elements in the path
</td>
</tr>
<tr>
<td>
<span class="term">int <em class="structfield"><code>num_data</code></em>;</span></td>
<td> the number of elements in the data array
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2572411"></a><h3>
<a name="cairo-path-data-t"></a>union cairo_path_data_t</h3>
<a class="indexterm" name="id2572424"></a><pre class="programlisting">union cairo_path_data_t {
struct {
cairo_path_data_type_t type;
int length;
} header;
struct {
double x, y;
} point;
};
</pre>
<p>
<a href="cairo-Paths.html#cairo-path-data-t"><span class="type">cairo_path_data_t</span></a> is used to represent the path data inside a
<a href="cairo-Paths.html#cairo-path-t"><span class="type">cairo_path_t</span></a>.
</p>
<p>
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
<a href="cairo-Paths.html#cairo-path-data-t"><span class="type">cairo_path_data_t</span></a>, which is a union of headers and points.
</p>
<p>
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:
</p>
<p>
</p>
<pre class="programlisting">
<code class="literal">CAIRO_PATH_MOVE_TO</code>: 1 point
<code class="literal">CAIRO_PATH_LINE_TO</code>: 1 point
<code class="literal">CAIRO_PATH_CURVE_TO</code>: 3 points
<code class="literal">CAIRO_PATH_CLOSE_PATH</code>: 0 points
</pre>
<p>
</p>
<p>
The semantics and ordering of the coordinate values are consistent
with <a href="cairo-Paths.html#cairo-move-to"><code class="function">cairo_move_to()</code></a>, <a href="cairo-Paths.html#cairo-line-to"><code class="function">cairo_line_to()</code></a>, <a href="cairo-Paths.html#cairo-curve-to"><code class="function">cairo_curve_to()</code></a>, and
<a href="cairo-Paths.html#cairo-close-path"><code class="function">cairo_close_path()</code></a>.
</p>
<p>
Here is sample code for iterating through a <span class="type">cairo_path_t:</span>
</p>
<p>
</p>
<div class="informalexample"><pre class="programlisting">
int i;
cairo_path_t *path;
cairo_path_data_t *data;
 
path = cairo_copy_path (cr);
 
for (i=0; i < path->num_data; i += path->data[i].header.length) {
data = &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:
<code class="function">do_close_path_things()</code>;
break;
}
}
cairo_path_destroy (path);
</pre></div>
<p>
</p>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2568954"></a><h3>
<a name="cairo-path-data-type-t"></a>enum cairo_path_data_type_t</h3>
<a class="indexterm" name="id2558127"></a><pre class="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;
</pre>
<p>
</p>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2529366"></a><h3>
<a name="cairo-copy-path"></a>cairo_copy_path ()</h3>
<a class="indexterm" name="id2529378"></a><pre class="programlisting"><a href="cairo-Paths.html#cairo-path-t">cairo_path_t</a>* cairo_copy_path (<a href="cairo-cairo-t.html#cairo-t">cairo_t</a> *cr);</pre>
<p>
Creates a copy of the current path and returns it to the user as a
<a href="cairo-Paths.html#cairo-path-t"><span class="type">cairo_path_t</span></a>. See <a href="cairo-Paths.html#cairo-path-data-t"><span class="type">cairo_path_data_t</span></a> for hints on how to iterate
over the returned data structure.
</p>
<p>
This function will always return a valid pointer, but the result
will have no data (<code class="literal">data==NULL</code> and
<code class="literal">num_data==0</code>), if either of the following
conditions hold:
</p>
<p>
</p>
<div class="orderedlist"><ol type="1">
<li>If there is insufficient memory to copy the path.</li>
<li>If <em class="parameter"><code>cr</code></em> is already in an error state.</li>
</ol></div>
<p>
</p>
<p>
In either case, <code class="literal">path->status</code> will be set to
<a href="cairo-Error-handling.html#CAIRO-STATUS-NO-MEMORY:CAPS"><code class="literal">CAIRO_STATUS_NO_MEMORY</code></a> (regardless of what the error status in
<em class="parameter"><code>cr</code></em> might have been).</p>
<p>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><em class="parameter"><code>cr</code></em> :</span></td>
<td> a cairo context
</td>
</tr>
<tr>
<td>
<span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
<td> the copy of the current path. The caller owns the
returned object and should call <a href="cairo-Paths.html#cairo-path-destroy"><code class="function">cairo_path_destroy()</code></a> when finished
with it.
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2529533"></a><h3>
<a name="cairo-copy-path-flat"></a>cairo_copy_path_flat ()</h3>
<a class="indexterm" name="id2529544"></a><pre class="programlisting"><a href="cairo-Paths.html#cairo-path-t">cairo_path_t</a>* cairo_copy_path_flat (<a href="cairo-cairo-t.html#cairo-t">cairo_t</a> *cr);</pre>
<p>
Gets a flattened copy of the current path and returns it to the
user as a <a href="cairo-Paths.html#cairo-path-t"><span class="type">cairo_path_t</span></a>. See <a href="cairo-Paths.html#cairo-path-data-t"><span class="type">cairo_path_data_t</span></a> for hints on
how to iterate over the returned data structure.
</p>
<p>
This function is like <a href="cairo-Paths.html#cairo-copy-path"><code class="function">cairo_copy_path()</code></a> 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 <code class="literal">CAIRO_PATH_CURVE_TO</code> which will instead be replaced by a
series of <code class="literal">CAIRO_PATH_LINE_TO</code> elements.
</p>
<p>
This function will always return a valid pointer, but the result
will have no data (<code class="literal">data==NULL</code> and
<code class="literal">num_data==0</code>), if either of the following
conditions hold:
</p>
<p>
</p>
<div class="orderedlist"><ol type="1">
<li>If there is insufficient memory to copy the path. In this
case <code class="literal">path->status</code> will be set to
<a href="cairo-Error-handling.html#CAIRO-STATUS-NO-MEMORY:CAPS"><code class="literal">CAIRO_STATUS_NO_MEMORY</code></a>.</li>
<li>If <em class="parameter"><code>cr</code></em> is already in an error state. In this case
<code class="literal">path->status</code> will contain the same status that
would be returned by <a href="cairo-cairo-t.html#cairo-status"><code class="function">cairo_status()</code></a>.</li>
</ol></div>
<p>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><em class="parameter"><code>cr</code></em> :</span></td>
<td> a cairo context
</td>
</tr>
<tr>
<td>
<span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td>
<td> the copy of the current path. The caller owns the
returned object and should call <a href="cairo-Paths.html#cairo-path-destroy"><code class="function">cairo_path_destroy()</code></a> when finished
with it.
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2529741"></a><h3>
<a name="cairo-path-destroy"></a>cairo_path_destroy ()</h3>
<a class="indexterm" name="id2529753"></a><pre class="programlisting">void cairo_path_destroy (<a href="cairo-Paths.html#cairo-path-t">cairo_path_t</a> *path);</pre>
<p>
Immediately releases all memory associated with <em class="parameter"><code>path</code></em>. After a call
to <a href="cairo-Paths.html#cairo-path-destroy"><code class="function">cairo_path_destroy()</code></a> the <em class="parameter"><code>path</code></em> pointer is no longer valid and
should not be used further.
</p>
<p>
NOTE: cairo_path_destroy function should only be called with a
pointer to a <a href="cairo-Paths.html#cairo-path-t"><span class="type">cairo_path_t</span></a> returned by a cairo function. Any path
that is created manually (ie. outside of cairo) should be destroyed
manually as well.</p>
<p>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td>
<span class="term"><em class="parameter"><code>path</code></em> :</span></td>
<td> a path previously returned by either <a href="cairo-Paths.html#cairo-copy-path"><code class="function">cairo_copy_path()</code></a> or
<a href="cairo-Paths.html#cairo-copy-path-flat"><code class="function">cairo_copy_path_flat()</code></a>.
</td>
</tr></tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2529858"></a><h3>
<a name="cairo-append-path"></a>cairo_append_path ()</h3>
<a class="indexterm" name="id2529870"></a><pre class="programlisting">void cairo_append_path (<a href="cairo-cairo-t.html#cairo-t">cairo_t</a> *cr,
<a href="cairo-Paths.html#cairo-path-t">cairo_path_t</a> *path);</pre>
<p>
Append the <em class="parameter"><code>path</code></em> onto the current path. The <em class="parameter"><code>path</code></em> may be either the
return value from one of <a href="cairo-Paths.html#cairo-copy-path"><code class="function">cairo_copy_path()</code></a> or
<a href="cairo-Paths.html#cairo-copy-path-flat"><code class="function">cairo_copy_path_flat()</code></a> or it may be constructed manually. See
<a href="cairo-Paths.html#cairo-path-t"><span class="type">cairo_path_t</span></a> for details on how the path data structure should be
initialized, and note that <code class="literal">path->status</code> must be
initialized to <a href="cairo-Error-handling.html#CAIRO-STATUS-SUCCESS:CAPS"><code class="literal">CAIRO_STATUS_SUCCESS</code></a>.</p>
<p>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><em class="parameter"><code>cr</code></em> :</span></td>
<td> a cairo context
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>path</code></em> :</span></td>
<td> path to be appended
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2529995"></a><h3>
<a name="cairo-get-current-point"></a>cairo_get_current_point ()</h3>
<a class="indexterm" name="id2530007"></a><pre class="programlisting">void cairo_get_current_point (<a href="cairo-cairo-t.html#cairo-t">cairo_t</a> *cr,
double *x,
double *y);</pre>
<p>
Gets the current point of the current path, which is
conceptually the final point reached by the path so far.
</p>
<p>
The current point is returned in the user-space coordinate
system. If there is no defined current point then <em class="parameter"><code>x</code></em> and <em class="parameter"><code>y</code></em> will
both be set to 0.0.
</p>
<p>
Most path construction functions alter the current point. See the
following for details on how they affect the current point:
</p>
<p>
<a href="cairo-Paths.html#cairo-new-path"><code class="function">cairo_new_path()</code></a>, <a href="cairo-Paths.html#cairo-move-to"><code class="function">cairo_move_to()</code></a>, <a href="cairo-Paths.html#cairo-line-to"><code class="function">cairo_line_to()</code></a>,
<a href="cairo-Paths.html#cairo-curve-to"><code class="function">cairo_curve_to()</code></a>, <a href="cairo-Paths.html#cairo-arc"><code class="function">cairo_arc()</code></a>, <a href="cairo-Paths.html#cairo-rel-move-to"><code class="function">cairo_rel_move_to()</code></a>,
<a href="cairo-Paths.html#cairo-rel-line-to"><code class="function">cairo_rel_line_to()</code></a>, <a href="cairo-Paths.html#cairo-rel-curve-to"><code class="function">cairo_rel_curve_to()</code></a>, <a href="cairo-Paths.html#cairo-arc"><code class="function">cairo_arc()</code></a>,
<a href="cairo-Paths.html#cairo-text-path"><code class="function">cairo_text_path()</code></a>, <code class="function">cairo_stroke_to_path()</code></p>
<p>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><em class="parameter"><code>cr</code></em> :</span></td>
<td> a cairo context
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>x</code></em> :</span></td>
<td> return value for X coordinate of the current point
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>y</code></em> :</span></td>
<td> return value for Y coordinate of the current point
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2530230"></a><h3>
<a name="cairo-new-path"></a>cairo_new_path ()</h3>
<a class="indexterm" name="id2530243"></a><pre class="programlisting">void cairo_new_path (<a href="cairo-cairo-t.html#cairo-t">cairo_t</a> *cr);</pre>
<p>
Clears the current path. After this call there will be no path and
no current point.</p>
<p>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td>
<span class="term"><em class="parameter"><code>cr</code></em> :</span></td>
<td> a cairo context
</td>
</tr></tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2530294"></a><h3>
<a name="cairo-new-sub-path"></a>cairo_new_sub_path ()</h3>
<a class="indexterm" name="id2530308"></a><pre class="programlisting">void cairo_new_sub_path (<a href="cairo-cairo-t.html#cairo-t">cairo_t</a> *cr);</pre>
<p>
Begin a new sub-path. Note that the existing path is not
affected. After this call there will be no current point.
</p>
<p>
In many cases, this call is not needed since new sub-paths are
frequently started with <a href="cairo-Paths.html#cairo-move-to"><code class="function">cairo_move_to()</code></a>.
</p>
<p>
A call to <a href="cairo-Paths.html#cairo-new-sub-path"><code class="function">cairo_new_sub_path()</code></a> is particularly useful when
beginning a new sub-path with one of the <a href="cairo-Paths.html#cairo-arc"><code class="function">cairo_arc()</code></a> calls. This
makes things easier as it is no longer necessary to manually
compute the arc's initial coordinates for a call to
<a href="cairo-Paths.html#cairo-move-to"><code class="function">cairo_move_to()</code></a>.</p>
<p>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td>
<span class="term"><em class="parameter"><code>cr</code></em> :</span></td>
<td> a cairo context
</td>
</tr></tbody>
</table></div>
<p>Since 1.2
</p>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2530414"></a><h3>
<a name="cairo-close-path"></a>cairo_close_path ()</h3>
<a class="indexterm" name="id2530426"></a><pre class="programlisting">void cairo_close_path (<a href="cairo-cairo-t.html#cairo-t">cairo_t</a> *cr);</pre>
<p>
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
<a href="cairo-Paths.html#cairo-move-to"><code class="function">cairo_move_to()</code></a>), and closes this sub-path. After this call the
current point will be at the joined endpoint of the sub-path.
</p>
<p>
The behavior of <a href="cairo-Paths.html#cairo-close-path"><code class="function">cairo_close_path()</code></a> is distinct from simply calling
<a href="cairo-Paths.html#cairo-line-to"><code class="function">cairo_line_to()</code></a> 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.
</p>
<p>
If there is no current point before the call to cairo_close_path,
this function will have no effect.
</p>
<p>
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 <a href="cairo-Paths.html#cairo-copy-path"><code class="function">cairo_copy_path()</code></a> 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.</p>
<p>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td>
<span class="term"><em class="parameter"><code>cr</code></em> :</span></td>
<td> a cairo context
</td>
</tr></tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2530541"></a><h3>
<a name="cairo-arc"></a>cairo_arc ()</h3>
<a class="indexterm" name="id2530553"></a><pre class="programlisting">void cairo_arc (<a href="cairo-cairo-t.html#cairo-t">cairo_t</a> *cr,
double xc,
double yc,
double radius,
double angle1,
double angle2);</pre>
<p>
Adds a circular arc of the given <em class="parameter"><code>radius</code></em> to the current path. The
arc is centered at (<em class="parameter"><code>xc</code></em>, <em class="parameter"><code>yc</code></em>), begins at <em class="parameter"><code>angle1</code></em> and proceeds in
the direction of increasing angles to end at <em class="parameter"><code>angle2</code></em>. If <em class="parameter"><code>angle2</code></em> is
less than <em class="parameter"><code>angle1</code></em> it will be progressively increased by 2*M_PI
until it is greater than <em class="parameter"><code>angle1</code></em>.
</p>
<p>
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.
</p>
<p>
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 <code class="literal">M_PI</code>/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.
</p>
<p>
(To convert from degrees to radians, use <code class="literal">degrees * (M_PI /
180.)</code>.)
</p>
<p>
This function gives the arc in the direction of increasing angles;
see <a href="cairo-Paths.html#cairo-arc-negative"><code class="function">cairo_arc_negative()</code></a> to get the arc in the direction of
decreasing angles.
</p>
<p>
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 <em class="parameter"><code>x</code></em>, <em class="parameter"><code>y</code></em>, <em class="parameter"><code>width</code></em>, <em class="parameter"><code>height</code></em>:
</p>
<p>
</p>
<div class="informalexample"><pre class="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);
</pre></div>
<p>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><em class="parameter"><code>cr</code></em> :</span></td>
<td> a cairo context
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>xc</code></em> :</span></td>
<td> X position of the center of the arc
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>yc</code></em> :</span></td>
<td> Y position of the center of the arc
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>radius</code></em> :</span></td>
<td> the radius of the arc
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>angle1</code></em> :</span></td>
<td> the start angle, in radians
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>angle2</code></em> :</span></td>
<td> the end angle, in radians
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2530852"></a><h3>
<a name="cairo-arc-negative"></a>cairo_arc_negative ()</h3>
<a class="indexterm" name="id2530864"></a><pre class="programlisting">void cairo_arc_negative (<a href="cairo-cairo-t.html#cairo-t">cairo_t</a> *cr,
double xc,
double yc,
double radius,
double angle1,
double angle2);</pre>
<p>
Adds a circular arc of the given <em class="parameter"><code>radius</code></em> to the current path. The
arc is centered at (<em class="parameter"><code>xc</code></em>, <em class="parameter"><code>yc</code></em>), begins at <em class="parameter"><code>angle1</code></em> and proceeds in
the direction of decreasing angles to end at <em class="parameter"><code>angle2</code></em>. If <em class="parameter"><code>angle2</code></em> is
greater than <em class="parameter"><code>angle1</code></em> it will be progressively decreased by 2*M_PI
until it is greater than <em class="parameter"><code>angle1</code></em>.
</p>
<p>
See <a href="cairo-Paths.html#cairo-arc"><code class="function">cairo_arc()</code></a> for more details. This function differs only in the
direction of the arc between the two angles.</p>
<p>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><em class="parameter"><code>cr</code></em> :</span></td>
<td> a cairo context
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>xc</code></em> :</span></td>
<td> X position of the center of the arc
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>yc</code></em> :</span></td>
<td> Y position of the center of the arc
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>radius</code></em> :</span></td>
<td> the radius of the arc
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>angle1</code></em> :</span></td>
<td> the start angle, in radians
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>angle2</code></em> :</span></td>
<td> the end angle, in radians
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2531084"></a><h3>
<a name="cairo-curve-to"></a>cairo_curve_to ()</h3>
<a class="indexterm" name="id2531097"></a><pre class="programlisting">void cairo_curve_to (<a href="cairo-cairo-t.html#cairo-t">cairo_t</a> *cr,
double x1,
double y1,
double x2,
double y2,
double x3,
double y3);</pre>
<p>
Adds a cubic Bézier spline to the path from the current point to
position (<em class="parameter"><code>x3</code></em>, <em class="parameter"><code>y3</code></em>) in user-space coordinates, using (<em class="parameter"><code>x1</code></em>, <em class="parameter"><code>y1</code></em>) and
(<em class="parameter"><code>x2</code></em>, <em class="parameter"><code>y2</code></em>) as the control points. After this call the current point
will be (<em class="parameter"><code>x3</code></em>, <em class="parameter"><code>y3</code></em>).
</p>
<p>
If there is no current point before the call to <a href="cairo-Paths.html#cairo-curve-to"><code class="function">cairo_curve_to()</code></a>
this function will behave as if preceded by a call to
cairo_move_to (<em class="parameter"><code>cr</code></em>, <em class="parameter"><code>x1</code></em>, <em class="parameter"><code>y1</code></em>).</p>
<p>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><em class="parameter"><code>cr</code></em> :</span></td>
<td> a cairo context
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>x1</code></em> :</span></td>
<td> the X coordinate of the first control point
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>y1</code></em> :</span></td>
<td> the Y coordinate of the first control point
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>x2</code></em> :</span></td>
<td> the X coordinate of the second control point
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>y2</code></em> :</span></td>
<td> the Y coordinate of the second control point
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>x3</code></em> :</span></td>
<td> the X coordinate of the end of the curve
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>y3</code></em> :</span></td>
<td> the Y coordinate of the end of the curve
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2531360"></a><h3>
<a name="cairo-line-to"></a>cairo_line_to ()</h3>
<a class="indexterm" name="id2531372"></a><pre class="programlisting">void cairo_line_to (<a href="cairo-cairo-t.html#cairo-t">cairo_t</a> *cr,
double x,
double y);</pre>
<p>
Adds a line to the path from the current point to position (<em class="parameter"><code>x</code></em>, <em class="parameter"><code>y</code></em>)
in user-space coordinates. After this call the current point
will be (<em class="parameter"><code>x</code></em>, <em class="parameter"><code>y</code></em>).
</p>
<p>
If there is no current point before the call to <a href="cairo-Paths.html#cairo-line-to"><code class="function">cairo_line_to()</code></a>
this function will behave as cairo_move_to (<em class="parameter"><code>cr</code></em>, <em class="parameter"><code>x</code></em>, <em class="parameter"><code>y</code></em>).</p>
<p>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><em class="parameter"><code>cr</code></em> :</span></td>
<td> a cairo context
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>x</code></em> :</span></td>
<td> the X coordinate of the end of the new line
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>y</code></em> :</span></td>
<td> the Y coordinate of the end of the new line
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2531524"></a><h3>
<a name="cairo-move-to"></a>cairo_move_to ()</h3>
<a class="indexterm" name="id2531536"></a><pre class="programlisting">void cairo_move_to (<a href="cairo-cairo-t.html#cairo-t">cairo_t</a> *cr,
double x,
double y);</pre>
<p>
Begin a new sub-path. After this call the current point will be (<em class="parameter"><code>x</code></em>,
<em class="parameter"><code>y</code></em>).</p>
<p>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><em class="parameter"><code>cr</code></em> :</span></td>
<td> a cairo context
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>x</code></em> :</span></td>
<td> the X coordinate of the new position
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>y</code></em> :</span></td>
<td> the Y coordinate of the new position
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2531642"></a><h3>
<a name="cairo-rectangle"></a>cairo_rectangle ()</h3>
<a class="indexterm" name="id2531654"></a><pre class="programlisting">void cairo_rectangle (<a href="cairo-cairo-t.html#cairo-t">cairo_t</a> *cr,
double x,
double y,
double width,
double height);</pre>
<p>
Adds a closed sub-path rectangle of the given size to the current
path at position (<em class="parameter"><code>x</code></em>, <em class="parameter"><code>y</code></em>) in user-space coordinates.
</p>
<p>
This function is logically equivalent to:
</p>
<div class="informalexample"><pre class="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);
</pre></div>
<p>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><em class="parameter"><code>cr</code></em> :</span></td>
<td> a cairo context
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>x</code></em> :</span></td>
<td> the X coordinate of the top left corner of the rectangle
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>y</code></em> :</span></td>
<td> the Y coordinate to the top left corner of the rectangle
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>width</code></em> :</span></td>
<td> the width of the rectangle
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>height</code></em> :</span></td>
<td> the height of the rectangle
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2531815"></a><h3>
<a name="cairo-glyph-path"></a>cairo_glyph_path ()</h3>
<a class="indexterm" name="id2531827"></a><pre class="programlisting">void cairo_glyph_path (<a href="cairo-cairo-t.html#cairo-t">cairo_t</a> *cr,
<a href="cairo-Text.html#cairo-glyph-t">cairo_glyph_t</a> *glyphs,
int num_glyphs);</pre>
<p>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><em class="parameter"><code>cr</code></em> :</span></td>
<td>
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>glyphs</code></em> :</span></td>
<td>
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>num_glyphs</code></em> :</span></td>
<td>
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2531916"></a><h3>
<a name="cairo-text-path"></a>cairo_text_path ()</h3>
<a class="indexterm" name="id2531928"></a><pre class="programlisting">void cairo_text_path (<a href="cairo-cairo-t.html#cairo-t">cairo_t</a> *cr,
const char *utf8);</pre>
<p>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><em class="parameter"><code>cr</code></em> :</span></td>
<td>
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>utf8</code></em> :</span></td>
<td>
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2584504"></a><h3>
<a name="cairo-rel-curve-to"></a>cairo_rel_curve_to ()</h3>
<a class="indexterm" name="id2584515"></a><pre class="programlisting">void cairo_rel_curve_to (<a href="cairo-cairo-t.html#cairo-t">cairo_t</a> *cr,
double dx1,
double dy1,
double dx2,
double dy2,
double dx3,
double dy3);</pre>
<p>
Relative-coordinate version of <a href="cairo-Paths.html#cairo-curve-to"><code class="function">cairo_curve_to()</code></a>. 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 (<em class="parameter"><code>dx3</code></em>, <em class="parameter"><code>dy3</code></em>), using points offset by (<em class="parameter"><code>dx1</code></em>, <em class="parameter"><code>dy1</code></em>) and
(<em class="parameter"><code>dx2</code></em>, <em class="parameter"><code>dy2</code></em>) as the control points. After this call the current
point will be offset by (<em class="parameter"><code>dx3</code></em>, <em class="parameter"><code>dy3</code></em>).
</p>
<p>
Given a current point of (x, y), cairo_rel_curve_to (<em class="parameter"><code>cr</code></em>, <em class="parameter"><code>dx1</code></em>,
<em class="parameter"><code>dy1</code></em>, <em class="parameter"><code>dx2</code></em>, <em class="parameter"><code>dy2</code></em>, <em class="parameter"><code>dx3</code></em>, <em class="parameter"><code>dy3</code></em>) is logically equivalent to
cairo_curve_to (<em class="parameter"><code>cr</code></em>, x + <em class="parameter"><code>dx1</code></em>, y + <em class="parameter"><code>dy1</code></em>, x + <em class="parameter"><code>dx2</code></em>, y + <em class="parameter"><code>dy2</code></em>, x +
<em class="parameter"><code>dx3</code></em>, y + <em class="parameter"><code>dy3</code></em>).
</p>
<p>
It is an error to call this function with no current point. Doing
so will cause <em class="parameter"><code>cr</code></em> to shutdown with a status of
CAIRO_STATUS_NO_CURRENT_POINT.</p>
<p>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><em class="parameter"><code>cr</code></em> :</span></td>
<td> a cairo context
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>dx1</code></em> :</span></td>
<td> the X offset to the first control point
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>dy1</code></em> :</span></td>
<td> the Y offset to the first control point
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>dx2</code></em> :</span></td>
<td> the X offset to the second control point
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>dy2</code></em> :</span></td>
<td> the Y offset to the second control point
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>dx3</code></em> :</span></td>
<td> the X offset to the end of the curve
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>dy3</code></em> :</span></td>
<td> the Y offset to the end of the curve
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2584820"></a><h3>
<a name="cairo-rel-line-to"></a>cairo_rel_line_to ()</h3>
<a class="indexterm" name="id2584830"></a><pre class="programlisting">void cairo_rel_line_to (<a href="cairo-cairo-t.html#cairo-t">cairo_t</a> *cr,
double dx,
double dy);</pre>
<p>
Relative-coordinate version of <a href="cairo-Paths.html#cairo-line-to"><code class="function">cairo_line_to()</code></a>. Adds a line to the
path from the current point to a point that is offset from the
current point by (<em class="parameter"><code>dx</code></em>, <em class="parameter"><code>dy</code></em>) in user space. After this call the
current point will be offset by (<em class="parameter"><code>dx</code></em>, <em class="parameter"><code>dy</code></em>).
</p>
<p>
Given a current point of (x, y), cairo_rel_line_to(<em class="parameter"><code>cr</code></em>, <em class="parameter"><code>dx</code></em>, <em class="parameter"><code>dy</code></em>)
is logically equivalent to cairo_line_to (<em class="parameter"><code>cr</code></em>, x + <em class="parameter"><code>dx</code></em>, y + <em class="parameter"><code>dy</code></em>).
</p>
<p>
It is an error to call this function with no current point. Doing
so will cause <em class="parameter"><code>cr</code></em> to shutdown with a status of
CAIRO_STATUS_NO_CURRENT_POINT.</p>
<p>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><em class="parameter"><code>cr</code></em> :</span></td>
<td> a cairo context
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>dx</code></em> :</span></td>
<td> the X offset to the end of the new line
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>dy</code></em> :</span></td>
<td> the Y offset to the end of the new line
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2584994"></a><h3>
<a name="cairo-rel-move-to"></a>cairo_rel_move_to ()</h3>
<a class="indexterm" name="id2585004"></a><pre class="programlisting">void cairo_rel_move_to (<a href="cairo-cairo-t.html#cairo-t">cairo_t</a> *cr,
double dx,
double dy);</pre>
<p>
Begin a new sub-path. After this call the current point will offset
by (<em class="parameter"><code>x</code></em>, <em class="parameter"><code>y</code></em>).
</p>
<p>
Given a current point of (x, y), cairo_rel_move_to(<em class="parameter"><code>cr</code></em>, <em class="parameter"><code>dx</code></em>, <em class="parameter"><code>dy</code></em>)
is logically equivalent to cairo_move_to (<em class="parameter"><code>cr</code></em>, x + <em class="parameter"><code>dx</code></em>, y + <em class="parameter"><code>dy</code></em>).
</p>
<p>
It is an error to call this function with no current point. Doing
so will cause <em class="parameter"><code>cr</code></em> to shutdown with a status of
CAIRO_STATUS_NO_CURRENT_POINT.</p>
<p>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td>
<span class="term"><em class="parameter"><code>cr</code></em> :</span></td>
<td> a cairo context
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>dx</code></em> :</span></td>
<td> the X offset
</td>
</tr>
<tr>
<td>
<span class="term"><em class="parameter"><code>dy</code></em> :</span></td>
<td> the Y offset
</td>
</tr>
</tbody>
</table></div>
</div>
</div>
</div>
</body>
</html>