cairo-Transformations.html [plain text]
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Transformations</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
<link rel="home" href="index.html" title="Cairo: A Vector Graphics Library">
<link rel="up" href="cairo-drawing.html" title="Drawing">
<link rel="prev" href="cairo-Regions.html" title="Regions">
<link rel="next" href="cairo-text.html" title="text">
<meta name="generator" content="GTK-Doc V1.15 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
</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-Regions.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
<td><a accesskey="u" href="cairo-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-text.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
</tr>
<tr><td colspan="5" class="shortcuts">
<a href="#cairo-Transformations.synopsis" class="shortcut">Top</a>
|
<a href="#cairo-Transformations.description" class="shortcut">Description</a>
</td></tr>
</table>
<div class="refentry" title="Transformations">
<a name="cairo-Transformations"></a><div class="titlepage"></div>
<div class="refnamediv"><table width="100%"><tr>
<td valign="top">
<h2><span class="refentrytitle"><a name="cairo-Transformations.top_of_page"></a>Transformations</span></h2>
<p>Transformations — Manipulating the current transformation matrix</p>
</td>
<td valign="top" align="right"></td>
</tr></table></div>
<div class="refsynopsisdiv" title="Synopsis">
<a name="cairo-Transformations.synopsis"></a><h2>Synopsis</h2>
<pre class="synopsis"><span class="returnvalue">void</span> <a class="link" href="cairo-Transformations.html#cairo-translate" title="cairo_translate ()">cairo_translate</a> (<em class="parameter"><code><a class="link" href="cairo-cairo-t.html#cairo-t" title="cairo_t"><span class="type">cairo_t</span></a> *cr</code></em>,
<em class="parameter"><code><span class="type">double</span> tx</code></em>,
<em class="parameter"><code><span class="type">double</span> ty</code></em>);
<span class="returnvalue">void</span> <a class="link" href="cairo-Transformations.html#cairo-scale" title="cairo_scale ()">cairo_scale</a> (<em class="parameter"><code><a class="link" href="cairo-cairo-t.html#cairo-t" title="cairo_t"><span class="type">cairo_t</span></a> *cr</code></em>,
<em class="parameter"><code><span class="type">double</span> sx</code></em>,
<em class="parameter"><code><span class="type">double</span> sy</code></em>);
<span class="returnvalue">void</span> <a class="link" href="cairo-Transformations.html#cairo-rotate" title="cairo_rotate ()">cairo_rotate</a> (<em class="parameter"><code><a class="link" href="cairo-cairo-t.html#cairo-t" title="cairo_t"><span class="type">cairo_t</span></a> *cr</code></em>,
<em class="parameter"><code><span class="type">double</span> angle</code></em>);
<span class="returnvalue">void</span> <a class="link" href="cairo-Transformations.html#cairo-transform" title="cairo_transform ()">cairo_transform</a> (<em class="parameter"><code><a class="link" href="cairo-cairo-t.html#cairo-t" title="cairo_t"><span class="type">cairo_t</span></a> *cr</code></em>,
<em class="parameter"><code>const <a class="link" href="cairo-cairo-matrix-t.html#cairo-matrix-t" title="cairo_matrix_t"><span class="type">cairo_matrix_t</span></a> *matrix</code></em>);
<span class="returnvalue">void</span> <a class="link" href="cairo-Transformations.html#cairo-set-matrix" title="cairo_set_matrix ()">cairo_set_matrix</a> (<em class="parameter"><code><a class="link" href="cairo-cairo-t.html#cairo-t" title="cairo_t"><span class="type">cairo_t</span></a> *cr</code></em>,
<em class="parameter"><code>const <a class="link" href="cairo-cairo-matrix-t.html#cairo-matrix-t" title="cairo_matrix_t"><span class="type">cairo_matrix_t</span></a> *matrix</code></em>);
<span class="returnvalue">void</span> <a class="link" href="cairo-Transformations.html#cairo-get-matrix" title="cairo_get_matrix ()">cairo_get_matrix</a> (<em class="parameter"><code><a class="link" href="cairo-cairo-t.html#cairo-t" title="cairo_t"><span class="type">cairo_t</span></a> *cr</code></em>,
<em class="parameter"><code><a class="link" href="cairo-cairo-matrix-t.html#cairo-matrix-t" title="cairo_matrix_t"><span class="type">cairo_matrix_t</span></a> *matrix</code></em>);
<span class="returnvalue">void</span> <a class="link" href="cairo-Transformations.html#cairo-identity-matrix" title="cairo_identity_matrix ()">cairo_identity_matrix</a> (<em class="parameter"><code><a class="link" href="cairo-cairo-t.html#cairo-t" title="cairo_t"><span class="type">cairo_t</span></a> *cr</code></em>);
<span class="returnvalue">void</span> <a class="link" href="cairo-Transformations.html#cairo-user-to-device" title="cairo_user_to_device ()">cairo_user_to_device</a> (<em class="parameter"><code><a class="link" href="cairo-cairo-t.html#cairo-t" title="cairo_t"><span class="type">cairo_t</span></a> *cr</code></em>,
<em class="parameter"><code><span class="type">double</span> *x</code></em>,
<em class="parameter"><code><span class="type">double</span> *y</code></em>);
<span class="returnvalue">void</span> <a class="link" href="cairo-Transformations.html#cairo-user-to-device-distance" title="cairo_user_to_device_distance ()">cairo_user_to_device_distance</a> (<em class="parameter"><code><a class="link" href="cairo-cairo-t.html#cairo-t" title="cairo_t"><span class="type">cairo_t</span></a> *cr</code></em>,
<em class="parameter"><code><span class="type">double</span> *dx</code></em>,
<em class="parameter"><code><span class="type">double</span> *dy</code></em>);
<span class="returnvalue">void</span> <a class="link" href="cairo-Transformations.html#cairo-device-to-user" title="cairo_device_to_user ()">cairo_device_to_user</a> (<em class="parameter"><code><a class="link" href="cairo-cairo-t.html#cairo-t" title="cairo_t"><span class="type">cairo_t</span></a> *cr</code></em>,
<em class="parameter"><code><span class="type">double</span> *x</code></em>,
<em class="parameter"><code><span class="type">double</span> *y</code></em>);
<span class="returnvalue">void</span> <a class="link" href="cairo-Transformations.html#cairo-device-to-user-distance" title="cairo_device_to_user_distance ()">cairo_device_to_user_distance</a> (<em class="parameter"><code><a class="link" href="cairo-cairo-t.html#cairo-t" title="cairo_t"><span class="type">cairo_t</span></a> *cr</code></em>,
<em class="parameter"><code><span class="type">double</span> *dx</code></em>,
<em class="parameter"><code><span class="type">double</span> *dy</code></em>);
</pre>
</div>
<div class="refsect1" title="Description">
<a name="cairo-Transformations.description"></a><h2>Description</h2>
<p>
The current transformation matrix, <em class="firstterm">ctm</em>, is a
two-dimensional affine transformation that maps all coordinates and other
drawing instruments from the <em class="firstterm">user space</em> into the
surface's canonical coordinate system, also known as the <em class="firstterm">device
space</em>.
</p>
</div>
<div class="refsect1" title="Details">
<a name="cairo-Transformations.details"></a><h2>Details</h2>
<div class="refsect2" title="cairo_translate ()">
<a name="cairo-translate"></a><h3>cairo_translate ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span> cairo_translate (<em class="parameter"><code><a class="link" href="cairo-cairo-t.html#cairo-t" title="cairo_t"><span class="type">cairo_t</span></a> *cr</code></em>,
<em class="parameter"><code><span class="type">double</span> tx</code></em>,
<em class="parameter"><code><span class="type">double</span> ty</code></em>);</pre>
<p>
Modifies the current transformation matrix (CTM) by translating the
user-space origin by (<em class="parameter"><code>tx</code></em>, <em class="parameter"><code>ty</code></em>). This offset is interpreted as a
user-space coordinate according to the CTM in place before the new
call to <a class="link" href="cairo-Transformations.html#cairo-translate" title="cairo_translate ()"><code class="function">cairo_translate()</code></a>. In other words, the translation of the
user-space origin takes place after any existing transformation.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>cr</code></em> :</span></p></td>
<td>a cairo context
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>tx</code></em> :</span></p></td>
<td>amount to translate in the X direction
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>ty</code></em> :</span></p></td>
<td>amount to translate in the Y direction
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" title="cairo_scale ()">
<a name="cairo-scale"></a><h3>cairo_scale ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span> cairo_scale (<em class="parameter"><code><a class="link" href="cairo-cairo-t.html#cairo-t" title="cairo_t"><span class="type">cairo_t</span></a> *cr</code></em>,
<em class="parameter"><code><span class="type">double</span> sx</code></em>,
<em class="parameter"><code><span class="type">double</span> sy</code></em>);</pre>
<p>
Modifies the current transformation matrix (CTM) by scaling the X
and Y user-space axes by <em class="parameter"><code>sx</code></em> and <em class="parameter"><code>sy</code></em> respectively. The scaling of
the axes takes place after any existing transformation of user
space.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>cr</code></em> :</span></p></td>
<td>a cairo context
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>sx</code></em> :</span></p></td>
<td>scale factor for the X dimension
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>sy</code></em> :</span></p></td>
<td>scale factor for the Y dimension
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" title="cairo_rotate ()">
<a name="cairo-rotate"></a><h3>cairo_rotate ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span> cairo_rotate (<em class="parameter"><code><a class="link" href="cairo-cairo-t.html#cairo-t" title="cairo_t"><span class="type">cairo_t</span></a> *cr</code></em>,
<em class="parameter"><code><span class="type">double</span> angle</code></em>);</pre>
<p>
Modifies the current transformation matrix (CTM) by rotating the
user-space axes by <em class="parameter"><code>angle</code></em> radians. The rotation of the axes takes
places after any existing transformation of user space. The
rotation direction for positive angles is from the positive X axis
toward the positive Y axis.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>cr</code></em> :</span></p></td>
<td>a cairo context
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>angle</code></em> :</span></p></td>
<td>angle (in radians) by which the user-space axes will be
rotated
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" title="cairo_transform ()">
<a name="cairo-transform"></a><h3>cairo_transform ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span> cairo_transform (<em class="parameter"><code><a class="link" href="cairo-cairo-t.html#cairo-t" title="cairo_t"><span class="type">cairo_t</span></a> *cr</code></em>,
<em class="parameter"><code>const <a class="link" href="cairo-cairo-matrix-t.html#cairo-matrix-t" title="cairo_matrix_t"><span class="type">cairo_matrix_t</span></a> *matrix</code></em>);</pre>
<p>
Modifies the current transformation matrix (CTM) by applying
<em class="parameter"><code>matrix</code></em> as an additional transformation. The new transformation of
user space takes place after any existing transformation.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>cr</code></em> :</span></p></td>
<td>a cairo context
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>matrix</code></em> :</span></p></td>
<td>a transformation to be applied to the user-space axes
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" title="cairo_set_matrix ()">
<a name="cairo-set-matrix"></a><h3>cairo_set_matrix ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span> cairo_set_matrix (<em class="parameter"><code><a class="link" href="cairo-cairo-t.html#cairo-t" title="cairo_t"><span class="type">cairo_t</span></a> *cr</code></em>,
<em class="parameter"><code>const <a class="link" href="cairo-cairo-matrix-t.html#cairo-matrix-t" title="cairo_matrix_t"><span class="type">cairo_matrix_t</span></a> *matrix</code></em>);</pre>
<p>
Modifies the current transformation matrix (CTM) by setting it
equal to <em class="parameter"><code>matrix</code></em>.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>cr</code></em> :</span></p></td>
<td>a cairo context
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>matrix</code></em> :</span></p></td>
<td>a transformation matrix from user space to device space
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" title="cairo_get_matrix ()">
<a name="cairo-get-matrix"></a><h3>cairo_get_matrix ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span> cairo_get_matrix (<em class="parameter"><code><a class="link" href="cairo-cairo-t.html#cairo-t" title="cairo_t"><span class="type">cairo_t</span></a> *cr</code></em>,
<em class="parameter"><code><a class="link" href="cairo-cairo-matrix-t.html#cairo-matrix-t" title="cairo_matrix_t"><span class="type">cairo_matrix_t</span></a> *matrix</code></em>);</pre>
<p>
Stores the current transformation matrix (CTM) into <em class="parameter"><code>matrix</code></em>.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>cr</code></em> :</span></p></td>
<td>a cairo context
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>matrix</code></em> :</span></p></td>
<td>return value for the matrix
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" title="cairo_identity_matrix ()">
<a name="cairo-identity-matrix"></a><h3>cairo_identity_matrix ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span> cairo_identity_matrix (<em class="parameter"><code><a class="link" href="cairo-cairo-t.html#cairo-t" title="cairo_t"><span class="type">cairo_t</span></a> *cr</code></em>);</pre>
<p>
Resets the current transformation matrix (CTM) by setting it equal
to the identity matrix. That is, the user-space and device-space
axes will be aligned and one user-space unit will transform to one
device-space unit.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><em class="parameter"><code>cr</code></em> :</span></p></td>
<td>a cairo context
</td>
</tr></tbody>
</table></div>
</div>
<hr>
<div class="refsect2" title="cairo_user_to_device ()">
<a name="cairo-user-to-device"></a><h3>cairo_user_to_device ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span> cairo_user_to_device (<em class="parameter"><code><a class="link" href="cairo-cairo-t.html#cairo-t" title="cairo_t"><span class="type">cairo_t</span></a> *cr</code></em>,
<em class="parameter"><code><span class="type">double</span> *x</code></em>,
<em class="parameter"><code><span class="type">double</span> *y</code></em>);</pre>
<p>
Transform a coordinate from user space to device space by
multiplying the given point by the current transformation matrix
(CTM).
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>cr</code></em> :</span></p></td>
<td>a cairo context
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>x</code></em> :</span></p></td>
<td>X value of coordinate (in/out parameter)
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>y</code></em> :</span></p></td>
<td>Y value of coordinate (in/out parameter)
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" title="cairo_user_to_device_distance ()">
<a name="cairo-user-to-device-distance"></a><h3>cairo_user_to_device_distance ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span> cairo_user_to_device_distance (<em class="parameter"><code><a class="link" href="cairo-cairo-t.html#cairo-t" title="cairo_t"><span class="type">cairo_t</span></a> *cr</code></em>,
<em class="parameter"><code><span class="type">double</span> *dx</code></em>,
<em class="parameter"><code><span class="type">double</span> *dy</code></em>);</pre>
<p>
Transform a distance vector from user space to device space. This
function is similar to <a class="link" href="cairo-Transformations.html#cairo-user-to-device" title="cairo_user_to_device ()"><code class="function">cairo_user_to_device()</code></a> except that the
translation components of the CTM will be ignored when transforming
(<em class="parameter"><code>dx</code></em>,<em class="parameter"><code>dy</code></em>).
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>cr</code></em> :</span></p></td>
<td>a cairo context
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>dx</code></em> :</span></p></td>
<td>X component of a distance vector (in/out parameter)
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>dy</code></em> :</span></p></td>
<td>Y component of a distance vector (in/out parameter)
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" title="cairo_device_to_user ()">
<a name="cairo-device-to-user"></a><h3>cairo_device_to_user ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span> cairo_device_to_user (<em class="parameter"><code><a class="link" href="cairo-cairo-t.html#cairo-t" title="cairo_t"><span class="type">cairo_t</span></a> *cr</code></em>,
<em class="parameter"><code><span class="type">double</span> *x</code></em>,
<em class="parameter"><code><span class="type">double</span> *y</code></em>);</pre>
<p>
Transform a coordinate from device space to user space by
multiplying the given point by the inverse of the current
transformation matrix (CTM).
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>cr</code></em> :</span></p></td>
<td>a cairo
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>x</code></em> :</span></p></td>
<td>X value of coordinate (in/out parameter)
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>y</code></em> :</span></p></td>
<td>Y value of coordinate (in/out parameter)
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" title="cairo_device_to_user_distance ()">
<a name="cairo-device-to-user-distance"></a><h3>cairo_device_to_user_distance ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span> cairo_device_to_user_distance (<em class="parameter"><code><a class="link" href="cairo-cairo-t.html#cairo-t" title="cairo_t"><span class="type">cairo_t</span></a> *cr</code></em>,
<em class="parameter"><code><span class="type">double</span> *dx</code></em>,
<em class="parameter"><code><span class="type">double</span> *dy</code></em>);</pre>
<p>
Transform a distance vector from device space to user space. This
function is similar to <a class="link" href="cairo-Transformations.html#cairo-device-to-user" title="cairo_device_to_user ()"><code class="function">cairo_device_to_user()</code></a> except that the
translation components of the inverse CTM will be ignored when
transforming (<em class="parameter"><code>dx</code></em>,<em class="parameter"><code>dy</code></em>).
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>cr</code></em> :</span></p></td>
<td>a cairo context
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>dx</code></em> :</span></p></td>
<td>X component of a distance vector (in/out parameter)
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>dy</code></em> :</span></p></td>
<td>Y component of a distance vector (in/out parameter)
</td>
</tr>
</tbody>
</table></div>
</div>
</div>
<div class="refsect1" title="See Also">
<a name="cairo-Transformations.see-also"></a><h2>See Also</h2>
<a class="link" href="cairo-cairo-matrix-t.html#cairo-matrix-t" title="cairo_matrix_t"><span class="type">cairo_matrix_t</span></a>
</div>
</div>
<div class="footer">
<hr>
Generated by GTK-Doc V1.15</div>
</body>
</html>