Matrices

## Matrices Matrices — Fuctions for initializing and manipulating 4x4 matrices |

## Synopsis

                        CoglMatrix;
    void                cogl_matrix_init_identity           (CoglMatrix *matrix);
    void                cogl_matrix_init_from_array         (CoglMatrix *matrix,
                                                             const float *array);
    CoglMatrix *        cogl_matrix_copy                    (const CoglMatrix *matrix);
    gboolean            cogl_matrix_equal                   (gconstpointer v1,
                                                             gconstpointer v2);
    void                cogl_matrix_free                    (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_orthographic            (CoglMatrix *matrix,
                                                             float x_1,
                                                             float y_1,
                                                             float x_2,
                                                             float y_2,
                                                             float near,
                                                             float far);
    void                cogl_matrix_perspective             (CoglMatrix *matrix,
                                                             float fov_y,
                                                             float aspect,
                                                             float z_near,
                                                             float z_far);
    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);
    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_transpose               (CoglMatrix *matrix);
    const float *       cogl_matrix_get_array               (const CoglMatrix *matrix);
    gboolean            cogl_matrix_get_inverse             (const CoglMatrix *matrix,
                                                             CoglMatrix *inverse);
    void                cogl_matrix_transform_point         (const CoglMatrix *matrix,
                                                             float *x,
                                                             float *y,
                                                             float *z,
                                                             float *w);
    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);
    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);
    gboolean            cogl_matrix_is_identity             (const CoglMatrix *matrix);

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

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

### 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_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_copy ()

    CoglMatrix *        cogl_matrix_copy                    (const CoglMatrix *matrix);

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

`matrix` : | A 4x4 transformation matrix you want to copy
Returns : | A newly allocated CoglMatrix which should be freed using `cogl_matrix_free()`

Since 1.6

### cogl_matrix_equal ()

    gboolean            cogl_matrix_equal                   (gconstpointer v1,
                                                             gconstpointer 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.

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

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

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

`matrix` : | A 4x4 transformation matrix
`x_1` : | The x coordinate for the first vertical clipping plane
`y_1` : | The y coordinate for the first horizontal clipping plane
`x_2` : | The x coordinate for the second vertical clipping plane
`y_2` : | The y coordinate for the second horizontal 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)

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

### 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` : | 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_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.

### Note

You should never look directly along the world-up vector.

### Note

It is assumed you are using a typical projection matrix where your origin maps to the center of your viewport.

### Note

Almost always when you use this function it should be the first transform applied to a new modelview transform

`matrix` : | A 4x4 transformation matrix
`eye_position_x` : | The X coordinate to look from
`eye_position_y` : | The Y coordinate to look from
`eye_position_z` : | The Z coordinate to look from
`object_x` : | The X coordinate of the object to look at
`object_y` : | The Y coordinate of the object to look at
`object_z` : | The Z coordinate of the object to look at
`world_up_x` : | The X component of the world's up direction vector
`world_up_y` : | The Y component of the world's up direction vector
`world_up_z` : | The Z component of the world's up direction vector

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

### Note

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

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

`matrix` : | A CoglMatrix

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.

`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

### 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_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;
      guint8 r,g,b,a;
      float s,t,p;
    } MyInVertex;
    typedef struct {
      guint8 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);

`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_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;
      guint8 r,g,b,a;
      float s,t,p;
    } MyInVertex;
    typedef struct {
      guint8 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);

`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_is_identity ()

    gboolean            cogl_matrix_is_identity             (const CoglMatrix *matrix);

Determines if the given matrix is an identity matrix.

`matrix` : | A CoglMatrix
Returns : | `TRUE` if `matrix` is an identity matrix else `FALSE`

Since 1.8