2
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
3
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
4
<!ENTITY version "1.0.8">
6
<refentry id="cogl-Matrices">
8
<refentrytitle role="top_of_page" id="cogl-Matrices.top_of_page">Matrices</refentrytitle>
9
<manvolnum>3</manvolnum>
10
<refmiscinfo>COGL Library</refmiscinfo>
14
<refname>Matrices</refname>
15
<refpurpose>Fuctions for initializing and manipulating 4x4
16
matrices.</refpurpose>
19
<refsynopsisdiv id="cogl-Matrices.synopsis" role="synopsis">
20
<title role="synopsis.title">Synopsis</title>
23
<link linkend="CoglMatrix">CoglMatrix</link>;
24
<link linkend="void">void</link> <link linkend="cogl-matrix-init-identity">cogl_matrix_init_identity</link> (<link linkend="CoglMatrix">CoglMatrix</link> *matrix);
25
<link linkend="void">void</link> <link linkend="cogl-matrix-frustum">cogl_matrix_frustum</link> (<link linkend="CoglMatrix">CoglMatrix</link> *matrix,
26
<link linkend="float">float</link> left,
27
<link linkend="float">float</link> right,
28
<link linkend="float">float</link> bottom,
29
<link linkend="float">float</link> top,
30
<link linkend="float">float</link> z_near,
31
<link linkend="float">float</link> z_far);
32
<link linkend="void">void</link> <link linkend="cogl-matrix-ortho">cogl_matrix_ortho</link> (<link linkend="CoglMatrix">CoglMatrix</link> *matrix,
33
<link linkend="float">float</link> left,
34
<link linkend="float">float</link> right,
35
<link linkend="float">float</link> bottom,
36
<link linkend="float">float</link> top,
37
<link linkend="float">float</link> z_near,
38
<link linkend="float">float</link> z_far);
39
<link linkend="void">void</link> <link linkend="cogl-matrix-perspective">cogl_matrix_perspective</link> (<link linkend="CoglMatrix">CoglMatrix</link> *matrix,
40
<link linkend="float">float</link> fov_y,
41
<link linkend="float">float</link> aspect,
42
<link linkend="float">float</link> z_near,
43
<link linkend="float">float</link> z_far);
44
<link linkend="void">void</link> <link linkend="cogl-matrix-transform-point">cogl_matrix_transform_point</link> (const <link linkend="CoglMatrix">CoglMatrix</link> *matrix,
45
<link linkend="float">float</link> *x,
46
<link linkend="float">float</link> *y,
47
<link linkend="float">float</link> *z,
48
<link linkend="float">float</link> *w);
49
<link linkend="void">void</link> <link linkend="cogl-matrix-multiply">cogl_matrix_multiply</link> (<link linkend="CoglMatrix">CoglMatrix</link> *result,
50
const <link linkend="CoglMatrix">CoglMatrix</link> *a,
51
const <link linkend="CoglMatrix">CoglMatrix</link> *b);
52
<link linkend="void">void</link> <link linkend="cogl-matrix-rotate">cogl_matrix_rotate</link> (<link linkend="CoglMatrix">CoglMatrix</link> *matrix,
53
<link linkend="float">float</link> angle,
54
<link linkend="float">float</link> x,
55
<link linkend="float">float</link> y,
56
<link linkend="float">float</link> z);
57
<link linkend="void">void</link> <link linkend="cogl-matrix-translate">cogl_matrix_translate</link> (<link linkend="CoglMatrix">CoglMatrix</link> *matrix,
58
<link linkend="float">float</link> x,
59
<link linkend="float">float</link> y,
60
<link linkend="float">float</link> z);
61
<link linkend="void">void</link> <link linkend="cogl-matrix-scale">cogl_matrix_scale</link> (<link linkend="CoglMatrix">CoglMatrix</link> *matrix,
62
<link linkend="float">float</link> sx,
63
<link linkend="float">float</link> sy,
64
<link linkend="float">float</link> sz);
65
<link linkend="void">void</link> <link linkend="cogl-matrix-init-from-array">cogl_matrix_init_from_array</link> (<link linkend="CoglMatrix">CoglMatrix</link> *matrix,
66
const <link linkend="float">float</link> *array);
67
const <link linkend="float">float</link> * <link linkend="cogl-matrix-get-array">cogl_matrix_get_array</link> (const <link linkend="CoglMatrix">CoglMatrix</link> *matrix);
79
<refsect1 id="cogl-Matrices.description" role="desc">
80
<title role="desc.title">Description</title>
82
Matrices are used in Cogl to describe affine model-view transforms, texture
83
transforms, and projective transforms. This exposes a utility API that can
84
be used for direct manipulation of these matrices.</para>
89
<refsect1 id="cogl-Matrices.details" role="details">
90
<title role="details.title">Details</title>
91
<refsect2 id="CoglMatrix" role="struct">
92
<title>CoglMatrix</title>
93
<indexterm zone="CoglMatrix"><primary sortas="Matrix">CoglMatrix</primary></indexterm><programlisting>typedef struct {
97
A CoglMatrix holds a 4x4 transform matrix. This is a single precision,
98
column-major matrix which means it is compatible with what OpenGL expects.
101
A CoglMatrix can represent transforms such as, rotations, scaling,
102
translation, sheering, and linear projections. You can combine these
103
transforms by multiplying multiple matrices in the order you want them
107
The transformation of a vertex (x, y, z, w) by a CoglMatrix is given by:
110
<informalexample><programlisting>
111
x_new = xx * x + xy * y + xz * z + xw * w
112
y_new = yx * x + yy * y + yz * z + yw * w
113
z_new = zx * x + zy * y + zz * z + zw * w
114
w_new = wx * x + wy * y + wz * z + ww * w
115
</programlisting></informalexample>
118
Where w is normally 1
121
<note>You must consider the members of the CoglMatrix structure read only,
122
and all matrix modifications must be done via the cogl_matrix API. This
123
allows Cogl to annotate the matrices internally. Violation of this will give
124
undefined results. If you need to initialize a matrix with a constant other
125
than the identity matrix you can use <link linkend="cogl-matrix-init-from-array"><function>cogl_matrix_init_from_array()</function></link>.</note></para>
128
<refsect2 id="cogl-matrix-init-identity" role="function">
129
<title>cogl_matrix_init_identity ()</title>
130
<indexterm zone="cogl-matrix-init-identity"><primary sortas="matrix_init_identity">cogl_matrix_init_identity</primary></indexterm><programlisting><link linkend="void">void</link> cogl_matrix_init_identity (<link linkend="CoglMatrix">CoglMatrix</link> *matrix);</programlisting>
132
Resets matrix to the identity matrix:
134
.xx=1; .xy=0; .xz=0; .xw=0;
135
.yx=0; .yy=1; .yz=0; .yw=0;
136
.zx=0; .zy=0; .zz=1; .zw=0;
137
.wx=0; .wy=0; .wz=0; .ww=1;
138
</programlisting></para>
140
</para><variablelist role="params">
141
<varlistentry><term><parameter>matrix</parameter> :</term>
142
<listitem><simpara> A 4x4 transformation matrix
143
</simpara></listitem></varlistentry>
144
</variablelist></refsect2>
145
<refsect2 id="cogl-matrix-frustum" role="function">
146
<title>cogl_matrix_frustum ()</title>
147
<indexterm zone="cogl-matrix-frustum"><primary sortas="matrix_frustum">cogl_matrix_frustum</primary></indexterm><programlisting><link linkend="void">void</link> cogl_matrix_frustum (<link linkend="CoglMatrix">CoglMatrix</link> *matrix,
148
<link linkend="float">float</link> left,
149
<link linkend="float">float</link> right,
150
<link linkend="float">float</link> bottom,
151
<link linkend="float">float</link> top,
152
<link linkend="float">float</link> z_near,
153
<link linkend="float">float</link> z_far);</programlisting>
155
Multiplies the matrix by the given frustum perspective matrix.</para>
157
</para><variablelist role="params">
158
<varlistentry><term><parameter>matrix</parameter> :</term>
159
<listitem><simpara> A 4x4 transformation matrix
160
</simpara></listitem></varlistentry>
161
<varlistentry><term><parameter>left</parameter> :</term>
162
<listitem><simpara> coord of left vertical clipping plane
163
</simpara></listitem></varlistentry>
164
<varlistentry><term><parameter>right</parameter> :</term>
165
<listitem><simpara> coord of right vertical clipping plane
166
</simpara></listitem></varlistentry>
167
<varlistentry><term><parameter>bottom</parameter> :</term>
168
<listitem><simpara> coord of bottom horizontal clipping plane
169
</simpara></listitem></varlistentry>
170
<varlistentry><term><parameter>top</parameter> :</term>
171
<listitem><simpara> coord of top horizontal clipping plane
172
</simpara></listitem></varlistentry>
173
<varlistentry><term><parameter>z_near</parameter> :</term>
174
<listitem><simpara> positive distance to near depth clipping plane
175
</simpara></listitem></varlistentry>
176
<varlistentry><term><parameter>z_far</parameter> :</term>
177
<listitem><simpara> positive distance to far depth clipping plane
178
</simpara></listitem></varlistentry>
179
</variablelist></refsect2>
180
<refsect2 id="cogl-matrix-ortho" role="function">
181
<title>cogl_matrix_ortho ()</title>
182
<indexterm zone="cogl-matrix-ortho"><primary sortas="matrix_ortho">cogl_matrix_ortho</primary></indexterm><programlisting><link linkend="void">void</link> cogl_matrix_ortho (<link linkend="CoglMatrix">CoglMatrix</link> *matrix,
183
<link linkend="float">float</link> left,
184
<link linkend="float">float</link> right,
185
<link linkend="float">float</link> bottom,
186
<link linkend="float">float</link> top,
187
<link linkend="float">float</link> z_near,
188
<link linkend="float">float</link> z_far);</programlisting>
190
Multiples the matrix by a parallel projection matrix.</para>
192
</para><variablelist role="params">
193
<varlistentry><term><parameter>matrix</parameter> :</term>
194
<listitem><simpara> A 4x4 transformation matrix
195
</simpara></listitem></varlistentry>
196
<varlistentry><term><parameter>left</parameter> :</term>
197
<listitem><simpara> The coordinate for the left clipping plane
198
</simpara></listitem></varlistentry>
199
<varlistentry><term><parameter>right</parameter> :</term>
200
<listitem><simpara> The coordinate for the right clipping plane
201
</simpara></listitem></varlistentry>
202
<varlistentry><term><parameter>bottom</parameter> :</term>
203
<listitem><simpara> The coordinate for the bottom clipping plane
204
</simpara></listitem></varlistentry>
205
<varlistentry><term><parameter>top</parameter> :</term>
206
<listitem><simpara> The coordinate for the top clipping plane
207
</simpara></listitem></varlistentry>
208
<varlistentry><term><parameter>z_near</parameter> :</term>
209
<listitem><simpara> The coordinate for the near clipping plane (may be negative if
210
the plane is behind the viewer)
211
</simpara></listitem></varlistentry>
212
<varlistentry><term><parameter>z_far</parameter> :</term>
213
<listitem><simpara> The coordinate for the far clipping plane (may be negative if
214
the plane is behind the viewer)
215
</simpara></listitem></varlistentry>
216
</variablelist></refsect2>
217
<refsect2 id="cogl-matrix-perspective" role="function">
218
<title>cogl_matrix_perspective ()</title>
219
<indexterm zone="cogl-matrix-perspective"><primary sortas="matrix_perspective">cogl_matrix_perspective</primary></indexterm><programlisting><link linkend="void">void</link> cogl_matrix_perspective (<link linkend="CoglMatrix">CoglMatrix</link> *matrix,
220
<link linkend="float">float</link> fov_y,
221
<link linkend="float">float</link> aspect,
222
<link linkend="float">float</link> z_near,
223
<link linkend="float">float</link> z_far);</programlisting>
225
Multiplies the matrix by the described perspective matrix
228
Note: you should be careful not to have to great a <parameter>z_far</parameter> / <parameter>z_near</parameter> ratio
229
since that will reduce the effectiveness of depth testing since there wont
230
be enough precision to identify the depth of objects near to each other.</para>
232
</para><variablelist role="params">
233
<varlistentry><term><parameter>matrix</parameter> :</term>
234
<listitem><simpara> A 4x4 transformation matrix
235
</simpara></listitem></varlistentry>
236
<varlistentry><term><parameter>fov_y</parameter> :</term>
237
<listitem><simpara> A field of view angle for the Y axis
238
</simpara></listitem></varlistentry>
239
<varlistentry><term><parameter>aspect</parameter> :</term>
240
<listitem><simpara> The ratio of width to height determining the field of view angle
242
</simpara></listitem></varlistentry>
243
<varlistentry><term><parameter>z_near</parameter> :</term>
244
<listitem><simpara> The distance to the near clip plane.
245
Never pass 0 and always pass a positive number.
246
</simpara></listitem></varlistentry>
247
<varlistentry><term><parameter>z_far</parameter> :</term>
248
<listitem><simpara> The distance to the far clip plane. (Should always be positive)
249
</simpara></listitem></varlistentry>
250
</variablelist></refsect2>
251
<refsect2 id="cogl-matrix-transform-point" role="function">
252
<title>cogl_matrix_transform_point ()</title>
253
<indexterm zone="cogl-matrix-transform-point"><primary sortas="matrix_transform_point">cogl_matrix_transform_point</primary></indexterm><programlisting><link linkend="void">void</link> cogl_matrix_transform_point (const <link linkend="CoglMatrix">CoglMatrix</link> *matrix,
254
<link linkend="float">float</link> *x,
255
<link linkend="float">float</link> *y,
256
<link linkend="float">float</link> *z,
257
<link linkend="float">float</link> *w);</programlisting>
259
This transforms a point whos position is given and returned
260
as four float components.</para>
262
</para><variablelist role="params">
263
<varlistentry><term><parameter>matrix</parameter> :</term>
264
<listitem><simpara> A 4x4 transformation matrix
265
</simpara></listitem></varlistentry>
266
<varlistentry><term><parameter>x</parameter> :</term>
267
<listitem><simpara> The X component of your points position [in:out]
268
</simpara></listitem></varlistentry>
269
<varlistentry><term><parameter>y</parameter> :</term>
270
<listitem><simpara> The Y component of your points position [in:out]
271
</simpara></listitem></varlistentry>
272
<varlistentry><term><parameter>z</parameter> :</term>
273
<listitem><simpara> The Z component of your points position [in:out]
274
</simpara></listitem></varlistentry>
275
<varlistentry><term><parameter>w</parameter> :</term>
276
<listitem><simpara> The W component of your points position [in:out]
277
</simpara></listitem></varlistentry>
278
</variablelist></refsect2>
279
<refsect2 id="cogl-matrix-multiply" role="function">
280
<title>cogl_matrix_multiply ()</title>
281
<indexterm zone="cogl-matrix-multiply"><primary sortas="matrix_multiply">cogl_matrix_multiply</primary></indexterm><programlisting><link linkend="void">void</link> cogl_matrix_multiply (<link linkend="CoglMatrix">CoglMatrix</link> *result,
282
const <link linkend="CoglMatrix">CoglMatrix</link> *a,
283
const <link linkend="CoglMatrix">CoglMatrix</link> *b);</programlisting>
285
This function multiples the two supplied matricies together and stores
286
the result in <parameter>result</parameter></para>
288
</para><variablelist role="params">
289
<varlistentry><term><parameter>result</parameter> :</term>
290
<listitem><simpara> The address of a 4x4 matrix to store the result in
291
</simpara></listitem></varlistentry>
292
<varlistentry><term><parameter>a</parameter> :</term>
293
<listitem><simpara> A 4x4 transformation matrix
294
</simpara></listitem></varlistentry>
295
<varlistentry><term><parameter>b</parameter> :</term>
296
<listitem><simpara> A 4x4 transformation matrix
297
</simpara></listitem></varlistentry>
298
</variablelist></refsect2>
299
<refsect2 id="cogl-matrix-rotate" role="function">
300
<title>cogl_matrix_rotate ()</title>
301
<indexterm zone="cogl-matrix-rotate"><primary sortas="matrix_rotate">cogl_matrix_rotate</primary></indexterm><programlisting><link linkend="void">void</link> cogl_matrix_rotate (<link linkend="CoglMatrix">CoglMatrix</link> *matrix,
302
<link linkend="float">float</link> angle,
303
<link linkend="float">float</link> x,
304
<link linkend="float">float</link> y,
305
<link linkend="float">float</link> z);</programlisting>
307
This function multiples your matrix with a rotation matrix that applies
308
a rotation of <link linkend="angle"><type>angle</type></link> degrees around the specified 3D vector.</para>
310
</para><variablelist role="params">
311
<varlistentry><term><parameter>matrix</parameter> :</term>
312
<listitem><simpara> A 4x4 transformation matrix
313
</simpara></listitem></varlistentry>
314
<varlistentry><term><parameter>angle</parameter> :</term>
315
<listitem><simpara> The angle you want to rotate in degrees
316
</simpara></listitem></varlistentry>
317
<varlistentry><term><parameter>x</parameter> :</term>
318
<listitem><simpara> X component of your rotation vector
319
</simpara></listitem></varlistentry>
320
<varlistentry><term><parameter>y</parameter> :</term>
321
<listitem><simpara> Y component of your rotation vector
322
</simpara></listitem></varlistentry>
323
<varlistentry><term><parameter>z</parameter> :</term>
324
<listitem><simpara> Z component of your rotation vector
325
</simpara></listitem></varlistentry>
326
</variablelist></refsect2>
327
<refsect2 id="cogl-matrix-translate" role="function">
328
<title>cogl_matrix_translate ()</title>
329
<indexterm zone="cogl-matrix-translate"><primary sortas="matrix_translate">cogl_matrix_translate</primary></indexterm><programlisting><link linkend="void">void</link> cogl_matrix_translate (<link linkend="CoglMatrix">CoglMatrix</link> *matrix,
330
<link linkend="float">float</link> x,
331
<link linkend="float">float</link> y,
332
<link linkend="float">float</link> z);</programlisting>
334
</para><variablelist role="params">
335
<varlistentry><term><parameter>matrix</parameter> :</term>
337
</simpara></listitem></varlistentry>
338
<varlistentry><term><parameter>x</parameter> :</term>
340
</simpara></listitem></varlistentry>
341
<varlistentry><term><parameter>y</parameter> :</term>
343
</simpara></listitem></varlistentry>
344
<varlistentry><term><parameter>z</parameter> :</term>
346
</simpara></listitem></varlistentry>
347
</variablelist></refsect2>
348
<refsect2 id="cogl-matrix-scale" role="function">
349
<title>cogl_matrix_scale ()</title>
350
<indexterm zone="cogl-matrix-scale"><primary sortas="matrix_scale">cogl_matrix_scale</primary></indexterm><programlisting><link linkend="void">void</link> cogl_matrix_scale (<link linkend="CoglMatrix">CoglMatrix</link> *matrix,
351
<link linkend="float">float</link> sx,
352
<link linkend="float">float</link> sy,
353
<link linkend="float">float</link> sz);</programlisting>
355
This function multiples your matrix with a transform matrix that scales
356
along the X, Y and Z axis.</para>
358
</para><variablelist role="params">
359
<varlistentry><term><parameter>matrix</parameter> :</term>
360
<listitem><simpara> A 4x4 transformation matrix
361
</simpara></listitem></varlistentry>
362
<varlistentry><term><parameter>sx</parameter> :</term>
363
<listitem><simpara> The X scale factor
364
</simpara></listitem></varlistentry>
365
<varlistentry><term><parameter>sy</parameter> :</term>
366
<listitem><simpara> The Y scale factor
367
</simpara></listitem></varlistentry>
368
<varlistentry><term><parameter>sz</parameter> :</term>
369
<listitem><simpara> The Z scale factor
370
</simpara></listitem></varlistentry>
371
</variablelist></refsect2>
372
<refsect2 id="cogl-matrix-init-from-array" role="function">
373
<title>cogl_matrix_init_from_array ()</title>
374
<indexterm zone="cogl-matrix-init-from-array"><primary sortas="matrix_init_from_array">cogl_matrix_init_from_array</primary></indexterm><programlisting><link linkend="void">void</link> cogl_matrix_init_from_array (<link linkend="CoglMatrix">CoglMatrix</link> *matrix,
375
const <link linkend="float">float</link> *array);</programlisting>
377
This initialises <parameter>matrix</parameter> with the contents of <parameter>array</parameter></para>
379
</para><variablelist role="params">
380
<varlistentry><term><parameter>matrix</parameter> :</term>
381
<listitem><simpara> A 4x4 transformation matrix
382
</simpara></listitem></varlistentry>
383
<varlistentry><term><parameter>array</parameter> :</term>
384
<listitem><simpara> A linear array of 16 floats (column-major order)
385
</simpara></listitem></varlistentry>
386
</variablelist></refsect2>
387
<refsect2 id="cogl-matrix-get-array" role="function">
388
<title>cogl_matrix_get_array ()</title>
389
<indexterm zone="cogl-matrix-get-array"><primary sortas="matrix_get_array">cogl_matrix_get_array</primary></indexterm><programlisting>const <link linkend="float">float</link> * cogl_matrix_get_array (const <link linkend="CoglMatrix">CoglMatrix</link> *matrix);</programlisting>
391
This casts a CoglMatrix to a float array which can be directly passed to
394
</para><variablelist role="params">
395
<varlistentry><term><parameter>matrix</parameter> :</term>
396
<listitem><simpara> A 4x4 transformation matrix
397
</simpara></listitem></varlistentry>
398
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a pointer to the float array
399
</simpara></listitem></varlistentry>
400
</variablelist></refsect2>
added
removed
doc/reference/cogl/xml/cogl-matrix.xml
