CoglMatrix

typedef struct {
  /* column 0 */
  float xx;
  float yx;
  float zx;
  float wx;

  /* column 1 */
  float xy;
  float yy;
  float zy;
  float wy;

  /* column 2 */
  float xz;
  float yz;
  float zz;
  float wz;

  /* column 3 */
  float xw;
  float yw;
  float zw;
  float ww;
} CoglMatrix;

A CoglMatrix holds a 4x4 transform matrix. This is a single precision, column-major matrix which means it is compatible with what OpenGL expects.

A CoglMatrix can represent transforms such as, rotations, scaling, translation, sheering, and linear projections. You can combine these transforms by multiplying multiple matrices in the order you want them applied.

The transformation of a vertex (x, y, z, w) by a CoglMatrix is given by:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

x_new = xx * x + xy * y + xz * z + xw * w
  y_new = yx * x + yy * y + yz * z + yw * w
  z_new = zx * x + zy * y + zz * z + zw * w
  w_new = wx * x + wy * y + wz * z + ww * w

Where w is normally 1

cogl_matrix_init_identity ()

void                cogl_matrix_init_identity           (CoglMatrix *matrix);

Resets matrix to the identity matrix:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

.xx=1; .xy=0; .xz=0; .xw=0;
  .yx=0; .yy=1; .yz=0; .yw=0;
  .zx=0; .zy=0; .zz=1; .zw=0;
  .wx=0; .wy=0; .wz=0; .ww=1;

cogl_matrix_init_from_array ()

void                cogl_matrix_init_from_array         (CoglMatrix *matrix,
                                                         const float *array);

Initializes matrix with the contents of array

cogl_matrix_init_translation ()

void                cogl_matrix_init_translation        (CoglMatrix *matrix,
                                                         float tx,
                                                         float ty,
                                                         float tz);

Resets matrix to the (tx, ty, tz) translation matrix:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

.xx=1; .xy=0; .xz=0; .xw=tx;
  .yx=0; .yy=1; .yz=0; .yw=ty;
  .zx=0; .zy=0; .zz=1; .zw=tz;
  .wx=0; .wy=0; .wz=0; .ww=1;

Since 2.0

cogl_matrix_init_from_quaternion ()

void                cogl_matrix_init_from_quaternion    (CoglMatrix *matrix,
                                                         const CoglQuaternion *quaternion);

Initializes matrix from a CoglQuaternion rotation.

cogl_matrix_init_from_euler ()

void                cogl_matrix_init_from_euler         (CoglMatrix *matrix,
                                                         const CoglEuler *euler);

Initializes matrix from a CoglEuler rotation.

cogl_matrix_copy ()

CoglMatrix *        cogl_matrix_copy                    (const CoglMatrix *matrix);

Allocates a new CoglMatrix on the heap and initializes it with the same values as matrix.

Since 1.6

cogl_matrix_equal ()

CoglBool            cogl_matrix_equal                   (const void *v1,
                                                         const void *v2);

Compares two matrices to see if they represent the same transformation. Although internally the matrices may have different annotations associated with them and may potentially have a cached inverse matrix these are not considered in the comparison.

Since 1.4

cogl_matrix_free ()

void                cogl_matrix_free                    (CoglMatrix *matrix);

Frees a CoglMatrix that was previously allocated via a call to cogl_matrix_copy().

Since 1.6

cogl_matrix_frustum ()

void                cogl_matrix_frustum                 (CoglMatrix *matrix,
                                                         float left,
                                                         float right,
                                                         float bottom,
                                                         float top,
                                                         float z_near,
                                                         float z_far);

Multiplies matrix by the given frustum perspective matrix.

cogl_matrix_orthographic ()

void                cogl_matrix_orthographic            (CoglMatrix *matrix,
                                                         float x_1,
                                                         float y_1,
                                                         float x_2,
                                                         float y_2,
                                                         float near,
                                                         float far);

Multiplies matrix by a parallel projection matrix.

Since 1.10

Stability Level: Unstable

cogl_matrix_perspective ()

void                cogl_matrix_perspective             (CoglMatrix *matrix,
                                                         float fov_y,
                                                         float aspect,
                                                         float z_near,
                                                         float z_far);

Multiplies matrix by the described perspective matrix

cogl_matrix_look_at ()

void                cogl_matrix_look_at                 (CoglMatrix *matrix,
                                                         float eye_position_x,
                                                         float eye_position_y,
                                                         float eye_position_z,
                                                         float object_x,
                                                         float object_y,
                                                         float object_z,
                                                         float world_up_x,
                                                         float world_up_y,
                                                         float world_up_z);

Applies a view transform matrix that positions the camera at the coordinate (eye_position_x, eye_position_y, eye_position_z) looking towards an object at the coordinate (object_x, object_y, object_z). The top of the camera is aligned to the given world up vector, which is normally simply (0, 1, 0) to map up to the positive direction of the y axis.

Because there is a lot of missleading documentation online for gluLookAt regarding the up vector we want to try and be a bit clearer here.

The up vector should simply be relative to your world coordinates and does not need to change as you move the eye and object positions. Many online sources may claim that the up vector needs to be perpendicular to the vector between the eye and object position (partly because the man page is somewhat missleading) but that is not necessary for this function.

Since 1.8

Stability Level: Unstable

cogl_matrix_multiply ()

void                cogl_matrix_multiply                (CoglMatrix *result,
                                                         const CoglMatrix *a,
                                                         const CoglMatrix *b);

Multiplies the two supplied matrices together and stores the resulting matrix inside result.

cogl_matrix_rotate ()

void                cogl_matrix_rotate                  (CoglMatrix *matrix,
                                                         float angle,
                                                         float x,
                                                         float y,
                                                         float z);

Multiplies matrix with a rotation matrix that applies a rotation of angle degrees around the specified 3D vector.

cogl_matrix_rotate_quaternion ()

void                cogl_matrix_rotate_quaternion       (CoglMatrix *matrix,
                                                         const CoglQuaternion *quaternion);

Multiplies matrix with a rotation transformation described by the given CoglQuaternion.

Since 2.0

cogl_matrix_rotate_euler ()

void                cogl_matrix_rotate_euler            (CoglMatrix *matrix,
                                                         const CoglEuler *euler);

Multiplies matrix with a rotation transformation described by the given CoglEuler.

Since 2.0

cogl_matrix_translate ()

void                cogl_matrix_translate               (CoglMatrix *matrix,
                                                         float x,
                                                         float y,
                                                         float z);

Multiplies matrix with a transform matrix that translates along the X, Y and Z axis.

cogl_matrix_scale ()

void                cogl_matrix_scale                   (CoglMatrix *matrix,
                                                         float sx,
                                                         float sy,
                                                         float sz);

Multiplies matrix with a transform matrix that scales along the X, Y and Z axis.

cogl_matrix_transpose ()

void                cogl_matrix_transpose               (CoglMatrix *matrix);

Replaces matrix with its transpose. Ie, every element (i,j) in the new matrix is taken from element (j,i) in the old matrix.

Since 1.10

cogl_matrix_get_array ()

const float *       cogl_matrix_get_array               (const CoglMatrix *matrix);

Casts matrix to a float array which can be directly passed to OpenGL.

cogl_matrix_get_inverse ()

CoglBool            cogl_matrix_get_inverse             (const CoglMatrix *matrix,
                                                         CoglMatrix *inverse);

Gets the inverse transform of a given matrix and uses it to initialize a new CoglMatrix.

Since 1.2

cogl_matrix_transform_point ()

void                cogl_matrix_transform_point         (const CoglMatrix *matrix,
                                                         float *x,
                                                         float *y,
                                                         float *z,
                                                         float *w);

Transforms a point whos position is given and returned as four float components.

cogl_matrix_transform_points ()

void                cogl_matrix_transform_points        (const CoglMatrix *matrix,
                                                         int n_components,
                                                         size_t stride_in,
                                                         const void *points_in,
                                                         size_t stride_out,
                                                         void *points_out,
                                                         int n_points);

Transforms an array of input points and writes the result to another array of output points. The input points can either have 2 or 3 components each. The output points always have 3 components. The output array can simply point to the input array to do the transform in-place.

If you need to transform 4 component points see cogl_matrix_project_points().

Here's an example with differing input/output strides:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49

typedef struct {
  float x,y;
  uint8_t r,g,b,a;
  float s,t,p;
} MyInVertex;
typedef struct {
  uint8_t r,g,b,a;
  float x,y,z;
} MyOutVertex;
MyInVertex vertices[N_VERTICES];
MyOutVertex results[N_VERTICES];
CoglMatrix matrix;

my_load_vertices (vertices);
my_get_matrix (&matrix);

cogl_matrix_transform_points (&matrix,
                              2,
                              sizeof (MyInVertex),
                              &vertices[0].x,
                              sizeof (MyOutVertex),
                              &results[0].x,
                              N_VERTICES);

Stability Level: Unstable

cogl_matrix_project_points ()

void                cogl_matrix_project_points          (const CoglMatrix *matrix,
                                                         int n_components,
                                                         size_t stride_in,
                                                         const void *points_in,
                                                         size_t stride_out,
                                                         void *points_out,
                                                         int n_points);

Projects an array of input points and writes the result to another array of output points. The input points can either have 2, 3 or 4 components each. The output points always have 4 components (known as homogenous coordinates). The output array can simply point to the input array to do the transform in-place.

Here's an example with differing input/output strides:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49

typedef struct {
  float x,y;
  uint8_t r,g,b,a;
  float s,t,p;
} MyInVertex;
typedef struct {
  uint8_t r,g,b,a;
  float x,y,z;
} MyOutVertex;
MyInVertex vertices[N_VERTICES];
MyOutVertex results[N_VERTICES];
CoglMatrix matrix;

my_load_vertices (vertices);
my_get_matrix (&matrix);

cogl_matrix_project_points (&matrix,
                            2,
                            sizeof (MyInVertex),
                            &vertices[0].x,
                            sizeof (MyOutVertex),
                            &results[0].x,
                            N_VERTICES);

Stability Level: Unstable

cogl_matrix_is_identity ()

CoglBool            cogl_matrix_is_identity             (const CoglMatrix *matrix);

Determines if the given matrix is an identity matrix.

Since 1.8