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.73.2">
<link rel="start" href="index.html" title="Cairo: A Vector Graphics Library">
<link rel="up" href="cairo-drawing.html" title="Drawing">
<link rel="prev" href="cairo-pattern.html" title="cairo_pattern_t">
<link rel="next" href="cairo-text.html" title="Text">
<meta name="generator" content="GTK-Doc V1.11 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
<link rel="chapter" href="cairo-drawing.html" title="Drawing">
<link rel="chapter" href="cairo-fonts.html" title="Fonts">
<link rel="chapter" href="cairo-surfaces.html" title="Surfaces">
<link rel="chapter" href="cairo-support.html" title="Utilities">
<link rel="index" href="index-all.html" title="Index">
<link rel="index" href="index-1.2.html" title="Index of new symbols in 1.2">
<link rel="index" href="index-1.4.html" title="Index of new symbols in 1.4">
<link rel="index" href="index-1.6.html" title="Index of new symbols in 1.6">
<link rel="index" href="index-1.8.html" title="Index of new symbols in 1.8">
<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-pattern.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" lang="en">
<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">
<a name="cairo-transformations.synopsis"></a><h2>Synopsis</h2>
<pre class="synopsis">
void <a class="link" href="cairo-transformations.html#cairo-translate" title="cairo_translate ()">cairo_translate</a> (<a class="link" href="cairo-context.html#cairo-t" title="cairo_t">cairo_t</a> *cr,
double tx,
double ty);
void <a class="link" href="cairo-transformations.html#cairo-scale" title="cairo_scale ()">cairo_scale</a> (<a class="link" href="cairo-context.html#cairo-t" title="cairo_t">cairo_t</a> *cr,
double sx,
double sy);
void <a class="link" href="cairo-transformations.html#cairo-rotate" title="cairo_rotate ()">cairo_rotate</a> (<a class="link" href="cairo-context.html#cairo-t" title="cairo_t">cairo_t</a> *cr,
double angle);
void <a class="link" href="cairo-transformations.html#cairo-transform" title="cairo_transform ()">cairo_transform</a> (<a class="link" href="cairo-context.html#cairo-t" title="cairo_t">cairo_t</a> *cr,
const <a class="link" href="cairo-matrix.html#cairo-matrix-t" title="cairo_matrix_t">cairo_matrix_t</a> *matrix);
void <a class="link" href="cairo-transformations.html#cairo-set-matrix" title="cairo_set_matrix ()">cairo_set_matrix</a> (<a class="link" href="cairo-context.html#cairo-t" title="cairo_t">cairo_t</a> *cr,
const <a class="link" href="cairo-matrix.html#cairo-matrix-t" title="cairo_matrix_t">cairo_matrix_t</a> *matrix);
void <a class="link" href="cairo-transformations.html#cairo-get-matrix" title="cairo_get_matrix ()">cairo_get_matrix</a> (<a class="link" href="cairo-context.html#cairo-t" title="cairo_t">cairo_t</a> *cr,
<a class="link" href="cairo-matrix.html#cairo-matrix-t" title="cairo_matrix_t">cairo_matrix_t</a> *matrix);
void <a class="link" href="cairo-transformations.html#cairo-identity-matrix" title="cairo_identity_matrix ()">cairo_identity_matrix</a> (<a class="link" href="cairo-context.html#cairo-t" title="cairo_t">cairo_t</a> *cr);
void <a class="link" href="cairo-transformations.html#cairo-user-to-device" title="cairo_user_to_device ()">cairo_user_to_device</a> (<a class="link" href="cairo-context.html#cairo-t" title="cairo_t">cairo_t</a> *cr,
double *x,
double *y);
void <a class="link" href="cairo-transformations.html#cairo-user-to-device-distance" title="cairo_user_to_device_distance ()">cairo_user_to_device_distance</a> (<a class="link" href="cairo-context.html#cairo-t" title="cairo_t">cairo_t</a> *cr,
double *dx,
double *dy);
void <a class="link" href="cairo-transformations.html#cairo-device-to-user" title="cairo_device_to_user ()">cairo_device_to_user</a> (<a class="link" href="cairo-context.html#cairo-t" title="cairo_t">cairo_t</a> *cr,
double *x,
double *y);
void <a class="link" href="cairo-transformations.html#cairo-device-to-user-distance" title="cairo_device_to_user_distance ()">cairo_device_to_user_distance</a> (<a class="link" href="cairo-context.html#cairo-t" title="cairo_t">cairo_t</a> *cr,
double *dx,
double *dy);
</pre>
</div>
<div class="refsect1" lang="en">
<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" lang="en">
<a name="cairo-transformations.details"></a><h2>Details</h2>
<div class="refsect2" lang="en">
<a name="cairo-translate"></a><h3>cairo_translate ()</h3>
<pre class="programlisting">void cairo_translate (<a class="link" href="cairo-context.html#cairo-t" title="cairo_t">cairo_t</a> *cr,
double tx,
double ty);</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>
<p>
</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" lang="en">
<a name="cairo-scale"></a><h3>cairo_scale ()</h3>
<pre class="programlisting">void cairo_scale (<a class="link" href="cairo-context.html#cairo-t" title="cairo_t">cairo_t</a> *cr,
double sx,
double sy);</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>
<p>
</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" lang="en">
<a name="cairo-rotate"></a><h3>cairo_rotate ()</h3>
<pre class="programlisting">void cairo_rotate (<a class="link" href="cairo-context.html#cairo-t" title="cairo_t">cairo_t</a> *cr,
double angle);</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>
<p>
</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" lang="en">
<a name="cairo-transform"></a><h3>cairo_transform ()</h3>
<pre class="programlisting">void cairo_transform (<a class="link" href="cairo-context.html#cairo-t" title="cairo_t">cairo_t</a> *cr,
const <a class="link" href="cairo-matrix.html#cairo-matrix-t" title="cairo_matrix_t">cairo_matrix_t</a> *matrix);</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>
<p>
</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" lang="en">
<a name="cairo-set-matrix"></a><h3>cairo_set_matrix ()</h3>
<pre class="programlisting">void cairo_set_matrix (<a class="link" href="cairo-context.html#cairo-t" title="cairo_t">cairo_t</a> *cr,
const <a class="link" href="cairo-matrix.html#cairo-matrix-t" title="cairo_matrix_t">cairo_matrix_t</a> *matrix);</pre>
<p>
Modifies the current transformation matrix (CTM) by setting it
equal to <em class="parameter"><code>matrix</code></em>.</p>
<p>
</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" lang="en">
<a name="cairo-get-matrix"></a><h3>cairo_get_matrix ()</h3>
<pre class="programlisting">void cairo_get_matrix (<a class="link" href="cairo-context.html#cairo-t" title="cairo_t">cairo_t</a> *cr,
<a class="link" href="cairo-matrix.html#cairo-matrix-t" title="cairo_matrix_t">cairo_matrix_t</a> *matrix);</pre>
<p>
Stores the current transformation matrix (CTM) into <em class="parameter"><code>matrix</code></em>.</p>
<p>
</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" lang="en">
<a name="cairo-identity-matrix"></a><h3>cairo_identity_matrix ()</h3>
<pre class="programlisting">void cairo_identity_matrix (<a class="link" href="cairo-context.html#cairo-t" title="cairo_t">cairo_t</a> *cr);</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>
<p>
</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" lang="en">
<a name="cairo-user-to-device"></a><h3>cairo_user_to_device ()</h3>
<pre class="programlisting">void cairo_user_to_device (<a class="link" href="cairo-context.html#cairo-t" title="cairo_t">cairo_t</a> *cr,
double *x,
double *y);</pre>
<p>
Transform a coordinate from user space to device space by
multiplying the given point by the current transformation matrix
(CTM).</p>
<p>
</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" lang="en">
<a name="cairo-user-to-device-distance"></a><h3>cairo_user_to_device_distance ()</h3>
<pre class="programlisting">void cairo_user_to_device_distance (<a class="link" href="cairo-context.html#cairo-t" title="cairo_t">cairo_t</a> *cr,
double *dx,
double *dy);</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>
<p>
</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" lang="en">
<a name="cairo-device-to-user"></a><h3>cairo_device_to_user ()</h3>
<pre class="programlisting">void cairo_device_to_user (<a class="link" href="cairo-context.html#cairo-t" title="cairo_t">cairo_t</a> *cr,
double *x,
double *y);</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>
<p>
</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" lang="en">
<a name="cairo-device-to-user-distance"></a><h3>cairo_device_to_user_distance ()</h3>
<pre class="programlisting">void cairo_device_to_user_distance (<a class="link" href="cairo-context.html#cairo-t" title="cairo_t">cairo_t</a> *cr,
double *dx,
double *dy);</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>
<p>
</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" lang="en">
<a name="cairo-transformations.see-also"></a><h2>See Also</h2>
<p>
</p>
<div class="itemizedlist"><ul type="disc"><li><a class="link" href="cairo-matrix.html#cairo-matrix-t" title="cairo_matrix_t"><span class="type">cairo_matrix_t</span></a></li></ul></div>
<p>
</p>
</div>
</div>
<div class="footer">
<hr>
Generated by GTK-Doc V1.11</div>
</body>
</html>