Matrices

Matrices — Functions for initializing and manipulating 4x4 matrices

Types and Values

Description

Matrices are used in Cogl to describe affine model-view transforms, texture transforms, and projective transforms. This exposes a utility API that can be used for direct manipulation of these matrices.

Functions

cogl_matrix_init_identity ()

void
cogl_matrix_init_identity (CoglMatrix *matrix);

Resets matrix to the identity matrix:

1
2
3
4
.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;

Parameters

matrix

A 4x4 transformation matrix

 

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 .

Parameters

matrix

A 4x4 transformation matrix you want to copy

 

Returns

A newly allocated CoglMatrix which should be freed using cogl_matrix_free().

[transfer full]

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.

Parameters

v1

A 4x4 transformation matrix

 

v2

A 4x4 transformation matrix

 

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().

Parameters

matrix

A 4x4 transformation matrix you want to free

 

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.

Parameters

matrix

A 4x4 transformation matrix

 

left

X position of the left clipping plane where it intersects the near clipping plane

 

right

X position of the right clipping plane where it intersects the near clipping plane

 

bottom

Y position of the bottom clipping plane where it intersects the near clipping plane

 

top

Y position of the top clipping plane where it intersects the near clipping plane

 

z_near

The distance to the near clipping plane (Must be positive)

 

z_far

The distance to the far clipping plane (Must be positive)

 

cogl_matrix_ortho ()

void
cogl_matrix_ortho (CoglMatrix *matrix,
                   float left,
                   float right,
                   float bottom,
                   float top,
                   float near,
                   float far);

cogl_matrix_ortho has been deprecated since version 1.10 and should not be used in newly-written code.

Use cogl_matrix_orthographic()

Multiplies matrix by a parallel projection matrix.

Parameters

matrix

A 4x4 transformation matrix

 

left

The coordinate for the left clipping plane

 

right

The coordinate for the right clipping plane

 

bottom

The coordinate for the bottom clipping plane

 

top

The coordinate for the top clipping plane

 

near

The distance to the near clipping plane (will be negative if the plane is behind the viewer)

 

far

The distance to the far clipping plane (will be negative if the plane is behind the viewer)

 

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

You should be careful not to have to great a z_far / z_near ratio since that will reduce the effectiveness of depth testing since there wont be enough precision to identify the depth of objects near to each other.

Parameters

matrix

A 4x4 transformation matrix

 

fov_y

Vertical field of view angle in degrees.

 

aspect

The (width over height) aspect ratio for display

 

z_near

The distance to the near clipping plane (Must be positive, and must not be 0)

 

z_far

The distance to the far clipping plane (Must be positive)

 

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 .

It is possible to multiply the a matrix in-place, so result can be equal to a but can't be equal to b.

Parameters

result

The address of a 4x4 matrix to store the result in

 

a

A 4x4 transformation matrix

 

b

A 4x4 transformation matrix

 

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.

Parameters

matrix

A 4x4 transformation matrix

 

angle

The angle you want to rotate in degrees

 

x

X component of your rotation vector

 

y

Y component of your rotation vector

 

z

Z component of your rotation vector

 

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.

Parameters

matrix

A 4x4 transformation matrix

 

x

The X translation you want to apply

 

y

The Y translation you want to apply

 

z

The Z translation you want to apply

 

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.

Parameters

matrix

A 4x4 transformation matrix

 

sx

The X scale factor

 

sy

The Y scale factor

 

sz

The Z scale factor

 

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.

Parameters

matrix

A CoglMatrix

 

Since: 1.10


cogl_matrix_init_from_array ()

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

Initializes matrix with the contents of array

Parameters

matrix

A 4x4 transformation matrix

 

array

A linear array of 16 floats (column-major order)

 

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.

Parameters

matrix

A 4x4 transformation matrix

 

Returns

a pointer to the float array


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.

Although the first parameter is annotated as const to indicate that the transform it represents isn't modified this function may technically save a copy of the inverse transform within the given CoglMatrix so that subsequent requests for the inverse transform may avoid costly inversion calculations.

Parameters

matrix

A 4x4 transformation matrix

 

inverse

The destination for a 4x4 inverse transformation matrix.

[out]

Returns

TRUE if the inverse was successfully calculated or FALSE for degenerate transformations that can't be inverted (in this case the inverse matrix will simply be initialized with the identity matrix)

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.

Parameters

matrix

A 4x4 transformation matrix

 

x

The X component of your points position.

[inout]

y

The Y component of your points position.

[inout]

z

The Z component of your points position.

[inout]

w

The W component of your points position.

[inout]

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
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);

Parameters

matrix

A projection matrix

 

n_components

The number of position components for each input point. (either 2, 3 or 4)

 

stride_in

The stride in bytes between input points.

 

points_in

A pointer to the first component of the first input point.

 

stride_out

The stride in bytes between output points.

 

points_out

A pointer to the first component of the first output point.

 

n_points

The number of points to transform.

 

Stability Level: Unstable


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
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);

Parameters

matrix

A transformation matrix

 

n_components

The number of position components for each input point. (either 2 or 3)

 

stride_in

The stride in bytes between input points.

 

points_in

A pointer to the first component of the first input point.

 

stride_out

The stride in bytes between output points.

 

points_out

A pointer to the first component of the first output point.

 

n_points

The number of points to transform.

 

Stability Level: Unstable


cogl_matrix_is_identity ()

CoglBool
cogl_matrix_is_identity (const CoglMatrix *matrix);

Determines if the given matrix is an identity matrix.

Parameters

matrix

A CoglMatrix

 

Returns

TRUE if matrix is an identity matrix else FALSE

Since: 1.8

Types and Values

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
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

You must consider the members of the CoglMatrix structure read only, and all matrix modifications must be done via the cogl_matrix API. This allows Cogl to annotate the matrices internally. Violation of this will give undefined results. If you need to initialize a matrix with a constant other than the identity matrix you can use cogl_matrix_init_from_array().