Matrices

Matrices — Fuctions for initializing and manipulating 4x4 matrices

Synopsis

struct              CoglMatrix;
void                cogl_matrix_init_identity           (CoglMatrix *matrix);
void                cogl_matrix_frustum                 (CoglMatrix *matrix,
                                                         float left,
                                                         float right,
                                                         float bottom,
                                                         float top,
                                                         float z_near,
                                                         float z_far);
void                cogl_matrix_ortho                   (CoglMatrix *matrix,
                                                         float left,
                                                         float right,
                                                         float bottom,
                                                         float top,
                                                         float z_near,
                                                         float z_far);
void                cogl_matrix_perspective             (CoglMatrix *matrix,
                                                         float fov_y,
                                                         float aspect,
                                                         float z_near,
                                                         float z_far);
void                cogl_matrix_transform_point         (const CoglMatrix *matrix,
                                                         float *x,
                                                         float *y,
                                                         float *z,
                                                         float *w);
void                cogl_matrix_multiply                (CoglMatrix *result,
                                                         const CoglMatrix *a,
                                                         const CoglMatrix *b);
void                cogl_matrix_rotate                  (CoglMatrix *matrix,
                                                         float angle,
                                                         float x,
                                                         float y,
                                                         float z);
void                cogl_matrix_translate               (CoglMatrix *matrix,
                                                         float x,
                                                         float y,
                                                         float z);
void                cogl_matrix_scale                   (CoglMatrix *matrix,
                                                         float sx,
                                                         float sy,
                                                         float sz);
void                cogl_matrix_init_from_array         (CoglMatrix *matrix,
                                                         const float *array);
const float *       cogl_matrix_get_array               (const CoglMatrix *matrix);
gboolean            cogl_matrix_get_inverse             (const CoglMatrix *matrix,
                                                         CoglMatrix *inverse);

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.

Details

struct CoglMatrix

struct CoglMatrix {
  /* 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;
};

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

Note

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


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;

matrix :

A 4x4 transformation matrix

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.

matrix :

A 4x4 transformation matrix

left :

coord of left vertical clipping plane

right :

coord of right vertical clipping plane

bottom :

coord of bottom horizontal clipping plane

top :

coord of top horizontal clipping plane

z_near :

positive distance to near depth clipping plane

z_far :

positive distance to far depth clipping plane

cogl_matrix_ortho ()

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

Multiplies matrix by a parallel projection matrix.

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

z_near :

The coordinate for the near clipping plane (may be negative if the plane is behind the viewer)

z_far :

The coordinate for the far clipping plane (may 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

Note

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.

matrix :

A 4x4 transformation matrix

fov_y :

A field of view angle for the Y axis

aspect :

The ratio of width to height determining the field of view angle for the x axis.

z_near :

The distance to the near clip plane. Never pass 0 and always pass a positive number.

z_far :

The distance to the far clip plane. (Should always be positive)

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.

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

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.

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.

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.

matrix :

A 4x4 transformation matrix

sx :

The X scale factor

sy :

The Y scale factor

sz :

The Z scale factor

cogl_matrix_init_from_array ()

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

Initializes matrix with the contents of array

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.

matrix :

A 4x4 transformation matrix

Returns :

a pointer to the float array

cogl_matrix_get_inverse ()

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

Note

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.

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