← Back to branch summary

~oem-solutions-group/unity-2d/clutter-1.0

« back to all changes in this revision

Viewing changes to clutter/cogl/cogl-matrix.h

  • Committer: Bazaar Package Importer
  • Author(s): Emilio Pozuelo Monfort
  • Date: 2010-03-21 13:27:56 UTC
  • mto: (2.1.3 experimental)
  • mto: This revision was merged to the branch mainline in revision 8.
  • Revision ID: james.westby@ubuntu.com-20100321132756-nf8yd30yxo3zzwcm
Tags: upstream-1.2.2
Import upstream version 1.2.2

Show diffs side-by-side

added added

removed removed

Lines of Context:
clutter/cogl/cogl-matrix.h
1
 
/*
2
 
 * Cogl
3
 
 *
4
 
 * An object oriented GL/GLES Abstraction/Utility Layer
5
 
 *
6
 
 * Copyright (C) 2008,2009 Intel Corporation.
7
 
 *
8
 
 * This library is free software; you can redistribute it and/or
9
 
 * modify it under the terms of the GNU Lesser General Public
10
 
 * License as published by the Free Software Foundation; either
11
 
 * version 2 of the License, or (at your option) any later version.
12
 
 *
13
 
 * This library is distributed in the hope that it will be useful,
14
 
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
15
 
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
16
 
 * Lesser General Public License for more details.
17
 
 *
18
 
 * You should have received a copy of the GNU Lesser General Public
19
 
 * License along with this library; if not, write to the
20
 
 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
21
 
 * Boston, MA 02111-1307, USA.
22
 
 *
23
 
 * Authors:
24
 
 *   Robert Bragg <robert@linux.intel.com>
25
 
 */
26
 
 
27
 
#ifndef __COGL_MATRIX_H
28
 
#define __COGL_MATRIX_H
29
 
 
30
 
#include <glib.h>
31
 
 
32
 
G_BEGIN_DECLS
33
 
 
34
 
/**
35
 
 * SECTION:cogl-matrix
36
 
 * @short_description: Fuctions for initializing and manipulating 4x4
37
 
 *                     matrices.
38
 
 *
39
 
 * Matrices are used in Cogl to describe affine model-view transforms, texture
40
 
 * transforms, and projective transforms. This exposes a utility API that can
41
 
 * be used for direct manipulation of these matrices.
42
 
 */
43
 
 
44
 
typedef struct _CoglMatrix      CoglMatrix;
45
 
 
46
 
/**
47
 
 * CoglMatrix:
48
 
 *
49
 
 * A CoglMatrix holds a 4x4 transform matrix. This is a single precision,
50
 
 * column-major matrix which means it is compatible with what OpenGL expects.
51
 
 *
52
 
 * A CoglMatrix can represent transforms such as, rotations, scaling,
53
 
 * translation, sheering, and linear projections. You can combine these
54
 
 * transforms by multiplying multiple matrices in the order you want them
55
 
 * applied.
56
 
 *
57
 
 * The transformation of a vertex (x, y, z, w) by a CoglMatrix is given by:
58
 
 *
59
 
 * |[
60
 
 *   x_new = xx * x + xy * y + xz * z + xw * w
61
 
 *   y_new = yx * x + yy * y + yz * z + yw * w
62
 
 *   z_new = zx * x + zy * y + zz * z + zw * w
63
 
 *   w_new = wx * x + wy * y + wz * z + ww * w
64
 
 * ]|
65
 
 *
66
 
 * Where w is normally 1
67
 
 *
68
 
 * <note>You must consider the members of the CoglMatrix structure read only,
69
 
 * and all matrix modifications must be done via the cogl_matrix API. This
70
 
 * allows Cogl to annotate the matrices internally. Violation of this will give
71
 
 * undefined results. If you need to initialize a matrix with a constant other
72
 
 * than the identity matrix you can use cogl_matrix_init_from_array().</note>
73
 
 */
74
 
struct _CoglMatrix
75
 
{
76
 
    /*< private >*/
77
 
 
78
 
    /* column 0 */
79
 
    float xx;
80
 
    float yx;
81
 
    float zx;
82
 
    float wx;
83
 
 
84
 
    /* column 1 */
85
 
    float xy;
86
 
    float yy;
87
 
    float zy;
88
 
    float wy;
89
 
 
90
 
    /* column 2 */
91
 
    float xz;
92
 
    float yz;
93
 
    float zz;
94
 
    float wz;
95
 
 
96
 
    /* column 3 */
97
 
    float xw;
98
 
    float yw;
99
 
    float zw;
100
 
    float ww;
101
 
 
102
 
    /* Note: we may want to extend this later with private flags
103
 
     * and a cache of the inverse transform matrix. */
104
 
    float   _padding0[16];
105
 
    gulong  _padding1;
106
 
    gulong  _padding2;
107
 
    gulong  _padding3;
108
 
};
109
 
 
110
 
/**
111
 
 * cogl_matrix_init_identity:
112
 
 * @matrix: A 4x4 transformation matrix
113
 
 *
114
 
 * Resets matrix to the identity matrix:
115
 
 * <programlisting>
116
 
 * .xx=1; .xy=0; .xz=0; .xw=0;
117
 
 * .yx=0; .yy=1; .yz=0; .yw=0;
118
 
 * .zx=0; .zy=0; .zz=1; .zw=0;
119
 
 * .wx=0; .wy=0; .wz=0; .ww=1;
120
 
 * </programlisting>
121
 
 */
122
 
void cogl_matrix_init_identity (CoglMatrix *matrix);
123
 
 
124
 
/**
125
 
 * cogl_matrix_multiply:
126
 
 * @result: The address of a 4x4 matrix to store the result in
127
 
 * @a: A 4x4 transformation matrix
128
 
 * @b: A 4x4 transformation matrix
129
 
 *
130
 
 * This function multiples the two supplied matricies together and stores
131
 
 * the result in @result
132
 
 */
133
 
void cogl_matrix_multiply (CoglMatrix *result,
134
 
                           const CoglMatrix *a,
135
 
                           const CoglMatrix *b);
136
 
 
137
 
/**
138
 
 * cogl_matrix_rotate:
139
 
 * @matrix: A 4x4 transformation matrix
140
 
 * @angle: The angle you want to rotate in degrees
141
 
 * @x: X component of your rotation vector
142
 
 * @y: Y component of your rotation vector
143
 
 * @z: Z component of your rotation vector
144
 
 *
145
 
 * This function multiples your matrix with a rotation matrix that applies
146
 
 * a rotation of #angle degrees around the specified 3D vector.
147
 
 */
148
 
void cogl_matrix_rotate (CoglMatrix *matrix,
149
 
                         float angle,
150
 
                         float x,
151
 
                         float y,
152
 
                         float z);
153
 
 
154
 
/* cogl_matrix_translate:
155
 
 * @matrix: A 4x4 transformation matrix
156
 
 * @x: The X translation you want to apply
157
 
 * @y: The Y translation you want to apply
158
 
 * @z: The Z translation you want to apply
159
 
 *
160
 
 * This function multiples your matrix with a transform matrix that translates
161
 
 * along the X, Y and Z axis.
162
 
 */
163
 
void cogl_matrix_translate (CoglMatrix *matrix,
164
 
                            float x,
165
 
                            float y,
166
 
                            float z);
167
 
 
168
 
/**
169
 
 * cogl_matrix_scale:
170
 
 * @matrix: A 4x4 transformation matrix
171
 
 * @sx: The X scale factor
172
 
 * @sy: The Y scale factor
173
 
 * @sz: The Z scale factor
174
 
 *
175
 
 * This function multiples your matrix with a transform matrix that scales
176
 
 * along the X, Y and Z axis.
177
 
 */
178
 
void cogl_matrix_scale (CoglMatrix *matrix,
179
 
                        float sx,
180
 
                        float sy,
181
 
                        float sz);
182
 
 
183
 
/**
184
 
 * cogl_matrix_frustum:
185
 
 * @matrix: A 4x4 transformation matrix
186
 
 * @left: coord of left vertical clipping plane
187
 
 * @right: coord of right vertical clipping plane
188
 
 * @bottom: coord of bottom horizontal clipping plane
189
 
 * @top: coord of top horizontal clipping plane
190
 
 * @z_near: positive distance to near depth clipping plane
191
 
 * @z_far: positive distance to far depth clipping plane
192
 
 *
193
 
 * Multiplies the matrix by the given frustum perspective matrix.
194
 
 */
195
 
void cogl_matrix_frustum (CoglMatrix *matrix,
196
 
                          float       left,
197
 
                          float       right,
198
 
                          float       bottom,
199
 
                          float       top,
200
 
                          float       z_near,
201
 
                          float       z_far);
202
 
 
203
 
/**
204
 
 * cogl_matrix_perspective:
205
 
 * @matrix: A 4x4 transformation matrix
206
 
 * @fov_y: A field of view angle for the Y axis
207
 
 * @aspect: The ratio of width to height determining the field of view angle
208
 
 *          for the x axis.
209
 
 * @z_near: The distance to the near clip plane.
210
 
 *          Never pass 0 and always pass a positive number.
211
 
 * @z_far: The distance to the far clip plane. (Should always be positive)
212
 
 *
213
 
 * Multiplies the matrix by the described perspective matrix
214
 
 *
215
 
 * Note: you should be careful not to have to great a @z_far / @z_near ratio
216
 
 * since that will reduce the effectiveness of depth testing since there wont
217
 
 * be enough precision to identify the depth of objects near to each other.
218
 
 */
219
 
void
220
 
cogl_matrix_perspective (CoglMatrix *matrix,
221
 
                         float       fov_y,
222
 
                         float       aspect,
223
 
                         float       z_near,
224
 
                         float       z_far);
225
 
 
226
 
/**
227
 
 * cogl_matrix_ortho:
228
 
 * @matrix: A 4x4 transformation matrix
229
 
 * @left: The coordinate for the left clipping plane
230
 
 * @right: The coordinate for the right clipping plane
231
 
 * @bottom: The coordinate for the bottom clipping plane
232
 
 * @top: The coordinate for the top clipping plane
233
 
 * @z_near: The coordinate for the near clipping plane (may be negative if
234
 
 *          the plane is behind the viewer)
235
 
 * @z_far: The coordinate for the far clipping plane (may be negative if
236
 
 *         the plane is behind the viewer)
237
 
 *
238
 
 * Multiples the matrix by a parallel projection matrix.
239
 
 */
240
 
void
241
 
cogl_matrix_ortho (CoglMatrix *matrix,
242
 
                   float       left,
243
 
                   float       right,
244
 
                   float       bottom,
245
 
                   float       top,
246
 
                   float       z_near,
247
 
                   float       z_far);
248
 
 
249
 
/**
250
 
 * cogl_matrix_init_from_array:
251
 
 * @matrix: A 4x4 transformation matrix
252
 
 * @array: A linear array of 16 floats (column-major order)
253
 
 *
254
 
 * This initialises @matrix with the contents of @array
255
 
 */
256
 
void cogl_matrix_init_from_array (CoglMatrix *matrix, const float *array);
257
 
 
258
 
/**
259
 
 * cogl_matrix_get_array:
260
 
 * @matrix: A 4x4 transformation matrix
261
 
 *
262
 
 * This casts a CoglMatrix to a float array which can be directly passed to
263
 
 * OpenGL.
264
 
 *
265
 
 * Return value: a pointer to the float array
266
 
 */
267
 
G_CONST_RETURN float *cogl_matrix_get_array (const CoglMatrix *matrix);
268
 
 
269
 
/**
270
 
 * cogl_matrix_transform_point:
271
 
 * @matrix: A 4x4 transformation matrix
272
 
 * @x: The X component of your points position [in:out]
273
 
 * @y: The Y component of your points position [in:out]
274
 
 * @z: The Z component of your points position [in:out]
275
 
 * @w: The W component of your points position [in:out]
276
 
 *
277
 
 * This transforms a point whos position is given and returned
278
 
 * as four float components.
279
 
 */
280
 
void
281
 
cogl_matrix_transform_point (const CoglMatrix *matrix,
282
 
                             float *x,
283
 
                             float *y,
284
 
                             float *z,
285
 
                             float *w);
286
 
 
287
 
G_END_DECLS
288
 
 
289
 
#endif /* __COGL_MATRIX_H */
290