Matrix: Graphene Reference Manual

## Matrix Matrix — 4x4 matrices |

## Functions

graphene_matrix_t * | graphene_matrix_alloc ()
void | graphene_matrix_free ()
graphene_matrix_t * | graphene_matrix_init_identity ()
graphene_matrix_t * | graphene_matrix_init_from_float ()
graphene_matrix_t * | graphene_matrix_init_from_vec4 ()
graphene_matrix_t * | graphene_matrix_init_from_matrix ()
graphene_matrix_t * | graphene_matrix_init_from_2d ()
graphene_matrix_t * | graphene_matrix_init_perspective ()
graphene_matrix_t * | graphene_matrix_init_ortho ()
graphene_matrix_t * | graphene_matrix_init_look_at ()
graphene_matrix_t * | graphene_matrix_init_frustum ()
graphene_matrix_t * | graphene_matrix_init_scale ()
graphene_matrix_t * | graphene_matrix_init_translate ()
graphene_matrix_t * | graphene_matrix_init_rotate ()
graphene_matrix_t * | graphene_matrix_init_skew ()
bool | graphene_matrix_is_identity ()
bool | graphene_matrix_is_2d ()
bool | graphene_matrix_is_backface_visible ()
bool | graphene_matrix_is_singular ()
void | graphene_matrix_to_float ()
bool | graphene_matrix_to_2d ()
void | graphene_matrix_get_row ()
float | graphene_matrix_get_value ()
void | graphene_matrix_multiply ()
float | graphene_matrix_determinant ()
void | graphene_matrix_transform_vec4 ()
void | graphene_matrix_transform_vec3 ()
void | graphene_matrix_transform_point ()
void | graphene_matrix_transform_point3d ()
void | graphene_matrix_transform_rect ()
void | graphene_matrix_transform_bounds ()
void | graphene_matrix_transform_box ()
void | graphene_matrix_transform_sphere ()
void | graphene_matrix_transform_ray ()
void | graphene_matrix_project_point ()
void | graphene_matrix_project_rect_bounds ()
void | graphene_matrix_project_rect ()
bool | graphene_matrix_untransform_point ()
void | graphene_matrix_untransform_bounds ()
void | graphene_matrix_unproject_point3d ()
void | graphene_matrix_translate ()
void | graphene_matrix_rotate ()
void | graphene_matrix_rotate_x ()
void | graphene_matrix_rotate_y ()
void | graphene_matrix_rotate_z ()
void | graphene_matrix_rotate_quaternion ()
void | graphene_matrix_rotate_euler ()
void | graphene_matrix_scale ()
void | graphene_matrix_skew_xy ()
void | graphene_matrix_skew_xz ()
void | graphene_matrix_skew_yz ()
void | graphene_matrix_transpose ()
bool | graphene_matrix_inverse ()
void | graphene_matrix_perspective ()
void | graphene_matrix_normalize ()
float | graphene_matrix_get_x_scale ()
float | graphene_matrix_get_y_scale ()
float | graphene_matrix_get_z_scale ()
void | graphene_matrix_interpolate ()
void | graphene_matrix_print ()

## Types and Values

| graphene_matrix_t

## Includes

    #include <graphene.h>

## Description

graphene_matrix_t is a type that provides a 4x4 square matrix, useful for representing 3D transformations.

The matrix is treated as row-major, i.e. it has four vectors (x, y, z, and w) representing rows, and elements of each vector are a column:

    1
    2
    3
    4
    | x |    | x.x   x.y   x.z   x.w |
    | y | -\ | y.x   y.y   y.z   y.w |
    | z | -/ | z.x   z.y   z.z   z.w |
    | w |    | w.x   w.y   w.z   w.w |

It is possible to easily convert a graphene_matrix_t to and from an array of floating point values that can be used with other libraries.

The contents of a graphene_matrix_t are private, and direct access is not possible. You can modify and read the contents of a graphene_matrix_t only through the provided API.

## Functions

### graphene_matrix_alloc ()

    graphene_matrix_t *
    graphene_matrix_alloc (void);

Allocates a new graphene_matrix_t.

[constructor]

#### Returns

the newly allocated matrix.

[transfer full]

Since: 1.0

### graphene_matrix_free ()

    void
    graphene_matrix_free (graphene_matrix_t *m);

Frees the resources allocated by `graphene_matrix_alloc()`.

#### Parameters

m | a graphene_matrix_t |

Since: 1.0

### graphene_matrix_init_identity ()

    graphene_matrix_t *
    graphene_matrix_init_identity (graphene_matrix_t *m);

Initializes a graphene_matrix_t with the identity matrix.

#### Parameters

m | a graphene_matrix_t |

#### Returns

the initialized matrix.

[transfer none]

Since: 1.0

### graphene_matrix_init_from_float ()

    graphene_matrix_t *
    graphene_matrix_init_from_float (graphene_matrix_t *m,
                                     const float *v);

Initializes a graphene_matrix_t with the given array of floating point values.

#### Parameters

m | a graphene_matrix_t |
v | an array of at least 16 floating point values. | [array fixed-size=16]

#### Returns

the initialized matrix.

[transfer none]

Since: 1.0

### graphene_matrix_init_from_vec4 ()

    graphene_matrix_t *
    graphene_matrix_init_from_vec4 (graphene_matrix_t *m,
                                    const graphene_vec4_t *v0,
                                    const graphene_vec4_t *v1,
                                    const graphene_vec4_t *v2,
                                    const graphene_vec4_t *v3);

Initializes a graphene_matrix_t with the given four row vectors.

#### Parameters

m | a graphene_matrix_t |
v0 | the first row vector |
v1 | the second row vector |
v2 | the third row vector |
v3 | the fourth row vector |

#### Returns

the initialized matrix.

[transfer none]

Since: 1.0

### graphene_matrix_init_from_matrix ()

    graphene_matrix_t *
    graphene_matrix_init_from_matrix (graphene_matrix_t *m,
                                      const graphene_matrix_t *src);

Initializes a graphene_matrix_t using the values of the given matrix.

#### Parameters

m | a graphene_matrix_t |
src | a graphene_matrix_t |

#### Returns

the initialized matrix.

[transfer none]

Since: 1.0

### graphene_matrix_init_from_2d ()

    graphene_matrix_t *
    graphene_matrix_init_from_2d (graphene_matrix_t *m,
                                  double xx,
                                  double yx,
                                  double xy,
                                  double yy,
                                  double x_0,
                                  double y_0);

Initializes a graphene_matrix_t from the values of an affine transformation matrix.

The arguments map to the following matrix layout:

    1
    2
    3
    | xx yx |   |  a  b  0 |
    | xy yy | = |  c  d  0 |
    | x0 y0 |   | tx ty  1 |

This function can be used to convert between a matrix type from other libraries and a graphene_matrix_t.

#### Parameters

m | a graphene_matrix_t |
xx | the xx member |
yx | the yx member |
xy | the xy member |
yy | the yy member |
x_0 | the x0 member |
y_0 | the y0 member |

#### Returns

the initialized matrix.

[transfer none]

Since: 1.0

### graphene_matrix_init_perspective ()

    graphene_matrix_t *
    graphene_matrix_init_perspective (graphene_matrix_t *m,
                                      float fovy,
                                      float aspect,
                                      float z_near,
                                      float z_far);

Initializes a graphene_matrix_t with a perspective projection.

#### Parameters

m | a graphene_matrix_t |
fovy | the field of view angle, in degrees |
aspect | the aspect value |
z_near | the near Z plane |
z_far | the far Z plane |

#### Returns

the initialized matrix.

[transfer none]

Since: 1.0

### graphene_matrix_init_ortho ()

    graphene_matrix_t *
    graphene_matrix_init_ortho (graphene_matrix_t *m,
                                float left,
                                float right,
                                float top,
                                float bottom,
                                float z_near,
                                float z_far);

Initializes a graphene_matrix_t with an orthographic projection.

#### Parameters

m | a graphene_matrix_t |
left | the left edge of the clipping plane |
right | the right edge of the clipping plane |
top | the top edge of the clipping plane |
bottom | the bottom edge of the clipping plane |
z_near | the distance of the near clipping plane |
z_far | the distance of the far clipping plane |

#### Returns

the initialized matrix.

[transfer none]

Since: 1.0

### graphene_matrix_init_look_at ()

    graphene_matrix_t *
    graphene_matrix_init_look_at (graphene_matrix_t *m,
                                  const graphene_vec3_t *eye,
                                  const graphene_vec3_t *center,
                                  const graphene_vec3_t *up);

Initializes a graphene_matrix_t so that it positions the "camera" at the given `eye` coordinates towards an object at the `center` coordinates. The top of the camera is aligned to the direction of the `up` vector.

#### Parameters

m | a graphene_matrix_t |
eye | the vector describing the position to look from |
center | the vector describing the position to look at |
up | the vector describing the world's upward direction; usually, this is the `graphene_vec3_y_axis()` vector |

#### Returns

the initialized matrix.

[transfer none]

Since: 1.0

### graphene_matrix_init_frustum ()

    graphene_matrix_t *
    graphene_matrix_init_frustum (graphene_matrix_t *m,
                                  float left,
                                  float right,
                                  float bottom,
                                  float top,
                                  float z_near,
                                  float z_far);

Initializes a graphene_matrix_t compatible with graphene_frustum_t.

See also: `graphene_frustum_init_from_matrix()`

#### Parameters

m | a graphene_matrix_t |
left | distance of the left clipping plane |
right | distance of the right clipping plane |
bottom | distance of the bottom clipping plane |
top | distance of the top clipping plane |
z_near | distance of the near clipping plane |
z_far | distance of the far clipping plane |

#### Returns

the initialized matrix.

[transfer none]

Since: 1.2

### graphene_matrix_init_scale ()

    graphene_matrix_t *
    graphene_matrix_init_scale (graphene_matrix_t *m,
                                float x,
                                float y,
                                float z);

Initializes a graphene_matrix_t with the given scaling factors.

#### Parameters

m | a graphene_matrix_t |
x | the scale factor on the X axis |
y | the scale factor on the Y axis |
z | the scale factor on the Z axis |

#### Returns

the initialized matrix.

[transfer none]

Since: 1.0

### graphene_matrix_init_translate ()

    graphene_matrix_t *
    graphene_matrix_init_translate (graphene_matrix_t *m,
                                    const graphene_point3d_t *p);

Initializes a graphene_matrix_t with a translation to the given coordinates.

#### Parameters

m | a graphene_matrix_t |
p | the translation coordinates |

#### Returns

the initialized matrix.

[transfer none]

Since: 1.0

### graphene_matrix_init_rotate ()

    graphene_matrix_t *
    graphene_matrix_init_rotate (graphene_matrix_t *m,
                                 float angle,
                                 const graphene_vec3_t *axis);

Initializes `m` to represent a rotation of `angle` degrees on the axis represented by the `axis` vector.

#### Parameters

m | a graphene_matrix_t |
angle | the rotation angle, in degrees |
axis | the axis vector as a graphene_vec3_t |

#### Returns

the initialized matrix.

[transfer none]

Since: 1.0

### graphene_matrix_init_skew ()

    graphene_matrix_t *
    graphene_matrix_init_skew (graphene_matrix_t *m,
                               float x_skew,
                               float y_skew);

Initializes a graphene_matrix_t with a skew transformation with the given factors.

#### Parameters

m | a graphene_matrix_t |
x_skew | skew factor on the X axis |
y_skew | skew factor on the Y axis |

#### Returns

the initialized matrix.

[transfer none]

Since: 1.0

### graphene_matrix_is_identity ()

    bool
    graphene_matrix_is_identity (const graphene_matrix_t *m);

Checks whether the given graphene_matrix_t is the identity matrix.

#### Parameters

m | a graphene_matrix_t |

#### Returns

`true` if the matrix is the identity matrix

Since: 1.0

### graphene_matrix_is_2d ()

    bool
    graphene_matrix_is_2d (const graphene_matrix_t *m);

Checks whether the given graphene_matrix_t is compatible with an a 2D affine transformation matrix.

#### Parameters

m | a graphene_matrix_t |

#### Returns

`true` if the matrix is compatible with an affine transformation matrix

Since: 1.0

### graphene_matrix_is_backface_visible ()

    bool
    graphene_matrix_is_backface_visible (const graphene_matrix_t *m);

Checks whether a graphene_matrix_t has a visible back face.

#### Parameters

m | a graphene_matrix_t |

#### Returns

`true` if the back face of the matrix is visible

Since: 1.0

### graphene_matrix_is_singular ()

    bool
    graphene_matrix_is_singular (const graphene_matrix_t *m);

Checks whether a matrix is singular.

#### Parameters

m | a graphene_matrix_t |

#### Returns

`true` if the matrix is singular

Since: 1.0

### graphene_matrix_to_float ()

    void
    graphene_matrix_to_float (const graphene_matrix_t *m,
                              float *v);

Converts a graphene_matrix_t to an array of floating point values.

#### Parameters

m | a graphene_matrix_t |
v | return location for an array of floating point values. The array must be capable of holding at least 16 values. | [array fixed-size=16][out caller-allocates]

Since: 1.0

### graphene_matrix_to_2d ()

    bool
    graphene_matrix_to_2d (const graphene_matrix_t *m,
                           double *xx,
                           double *yx,
                           double *xy,
                           double *yy,
                           double *x_0,
                           double *y_0);

Converts a graphene_matrix_t to an affine transformation matrix, if the given matrix is compatible.

The returned values have the following layout:

    1
    2
    3
    | xx yx |   |  a  b  0 |
    | xy yy | = |  c  d  0 |
    | x0 y0 |   | tx ty  1 |

This function can be used to convert between a graphene_matrix_t and a matrix type from other libraries.

#### Parameters

m | a graphene_matrix_t |
xx | return location for the xx member. | [out]
yx | return location for the yx member. | [out]
xy | return location for the xy member. | [out]
yy | return location for the yy member. | [out]
x_0 | return location for the x0 member. | [out]
y_0 | return location for the y0 member. | [out]

#### Returns

`true` if the matrix is compatible with an affine transformation matrix

Since: 1.0

### graphene_matrix_get_row ()

    void
    graphene_matrix_get_row (const graphene_matrix_t *m,
                             unsigned int index_,
                             graphene_vec4_t *res);

Retrieves the given row vector at `index_` inside a matrix.

#### Parameters

m | a graphene_matrix_t |
index_ | the index of the row vector, between 0 and 3 |
res | return location for the graphene_vec4_t that is used to store the row vector. | [out caller-allocates]

Since: 1.0

### graphene_matrix_get_value ()

    float
    graphene_matrix_get_value (const graphene_matrix_t *m,
                               unsigned int row,
                               unsigned int col);

Retrieves the value at the given `row` and `col` index.

#### Parameters

m | a graphene_matrix_t |
row | the row index |
col | the column index |

#### Returns

the value at the given indices

Since: 1.0

### graphene_matrix_multiply ()

    void
    graphene_matrix_multiply (const graphene_matrix_t *a,
                              const graphene_matrix_t *b,
                              graphene_matrix_t *res);

Multiplies two graphene_matrix_t.

Remember: matrix multiplication is not commutative, except for the identity matrix; the product of this multiplication is (A * B).

#### Parameters

a | a graphene_matrix_t |
b | a graphene_matrix_t |
res | return location for the matrix result. | [out caller-allocates]

Since: 1.0

### graphene_matrix_determinant ()

    float
    graphene_matrix_determinant (const graphene_matrix_t *m);

Computes the determinant of the given matrix.

#### Parameters

m | a graphene_matrix_t |

#### Returns

the value of the determinant

Since: 1.0

### graphene_matrix_transform_vec4 ()

    void
    graphene_matrix_transform_vec4 (const graphene_matrix_t *m,
                                    const graphene_vec4_t *v,
                                    graphene_vec4_t *res);

Transforms the given graphene_vec4_t using the matrix `m` .

#### Parameters

m | a graphene_matrix_t |
v | a graphene_vec4_t |
res | return location for a graphene_vec4_t. | [out caller-allocates]

Since: 1.0

### graphene_matrix_transform_vec3 ()

    void
    graphene_matrix_transform_vec3 (const graphene_matrix_t *m,
                                    const graphene_vec3_t *v,
                                    graphene_vec3_t *res);

Transforms the given graphene_vec3_t using the matrix `m` .

#### Parameters

m | a graphene_matrix_t |
v | a graphene_vec3_t |
res | return location for a graphene_vec3_t. | [out caller-allocates]

Since: 1.0

### graphene_matrix_transform_point ()

    void
    graphene_matrix_transform_point (const graphene_matrix_t *m,
                                     const graphene_point_t *p,
                                     graphene_point_t *res);

Transforms the given graphene_point_t using the matrix `m` .

#### Parameters

m | a graphene_matrix_t |
p | a graphene_point_t |
res | return location for the transformed graphene_point_t. | [out caller-allocates]

Since: 1.0

### graphene_matrix_transform_point3d ()

    void
    graphene_matrix_transform_point3d (const graphene_matrix_t *m,
                                       const graphene_point3d_t *p,
                                       graphene_point3d_t *res);

Transforms the given graphene_point3d_t using the matrix `m` .

Unlike `graphene_matrix_transform_vec3()`, this function will take into account the fourth row vector of the graphene_matrix_t.

#### Parameters

m | a graphene_matrix_t |
p | a graphene_point3d_t |
res | return location for the result. | [out caller-allocates]

Since: 1.2

### graphene_matrix_transform_rect ()

    void
    graphene_matrix_transform_rect (const graphene_matrix_t *m,
                                    const graphene_rect_t *r,
                                    graphene_quad_t *res);

Transforms a graphene_rect_t using the given matrix `m` . The result is a coplanar quad.

#### Parameters

m | a graphene_matrix_t |
r | a graphene_rect_t |
res | return location for the transformed quad. | [out caller-allocates]

Since: 1.0

### graphene_matrix_transform_bounds ()

    void
    graphene_matrix_transform_bounds (const graphene_matrix_t *m,
                                      const graphene_rect_t *r,
                                      graphene_rect_t *res);

Transforms a graphene_rect_t using the given matrix `m` . The result is the bounding box containing the coplanar quad.

#### Parameters

m | a graphene_matrix_t |
r | a graphene_rect_t |
res | return location for the bounds of the transformed rectangle. | [out caller-allocates]

Since: 1.0

### graphene_matrix_transform_box ()

    void
    graphene_matrix_transform_box (const graphene_matrix_t *m,
                                   const graphene_box_t *b,
                                   graphene_box_t *res);

Transforms a graphene_box_t using the given matrix `m` . The result is the bounding box containing the transformed box.

#### Parameters

m | a graphene_matrix_t |
b | a graphene_box_t |
res | return location for the bounds of the transformed box. | [out caller-allocates]

Since: 1.2

### graphene_matrix_transform_sphere ()

    void
    graphene_matrix_transform_sphere (const graphene_matrix_t *m,
                                      const graphene_sphere_t *s,
                                      graphene_sphere_t *res);

Transforms a graphene_sphere_t using the given matrix `m` . The result is the bounding sphere containing the transformed sphere.

#### Parameters

m | a graphene_matrix_t |
s | a graphene_sphere_t |
res | return location for the bounds of the transformed sphere. | [out caller-allocates]

Since: 1.2

### graphene_matrix_transform_ray ()

    void
    graphene_matrix_transform_ray (const graphene_matrix_t *m,
                                   const graphene_ray_t *r,
                                   graphene_ray_t *res);

Transform a graphene_ray_t using the given matrix `m` .

#### Parameters

m | a graphene_matrix_t |
r | a graphene_ray_t |
res | return location for the transformed ray. | [out caller-allocates]

Since: 1.4

### graphene_matrix_project_point ()

    void
    graphene_matrix_project_point (const graphene_matrix_t *m,
                                   const graphene_point_t *p,
                                   graphene_point_t *res);

Projects a graphene_point_t using the matrix `m` .

#### Parameters

m | a graphene_matrix_t |
p | a graphene_point_t |
res | return location for the projected point. | [out caller-allocates]

Since: 1.0

### graphene_matrix_project_rect_bounds ()

    void
    graphene_matrix_project_rect_bounds (const graphene_matrix_t *m,
                                         const graphene_rect_t *r,
                                         graphene_rect_t *res);

Projects a graphene_rect_t using the given matrix.

The resulting rectangle is the bounding box capable of containing fully the projected rectangle.

#### Parameters

m | a graphene_matrix_t |
r | a graphene_rect_t |
res | return location for the projected rectangle. | [out caller-allocates]

Since: 1.0

### graphene_matrix_project_rect ()

    void
    graphene_matrix_project_rect (const graphene_matrix_t *m,
                                  const graphene_rect_t *r,
                                  graphene_quad_t *res);

Projects a graphene_rect_t using the given matrix.

#### Parameters

m | a graphene_matrix_t |
r | a graphene_rect_t |
res | return location for the projected rectangle. | [out caller-allocates]

Since: 1.2

### graphene_matrix_untransform_point ()

    bool
    graphene_matrix_untransform_point (const graphene_matrix_t *m,
                                       const graphene_point_t *p,
                                       const graphene_rect_t *bounds,
                                       graphene_point_t *res);

Undoes the transformation of a graphene_point_t using the given matrix, within the given rectangular `bounds` .

#### Parameters

m | a graphene_matrix_t |
p | a graphene_point_t |
bounds | the bounds of the transformation |
res | return location for the untransformed point. | [out caller-allocates]

#### Returns

`true` if the point was successfully untransformed

Since: 1.0

### graphene_matrix_untransform_bounds ()

    void
    graphene_matrix_untransform_bounds (const graphene_matrix_t *m,
                                        const graphene_rect_t *r,
                                        const graphene_rect_t *bounds,
                                        graphene_rect_t *res);

Undoes the transformation on the points of a graphene_rect_t using the given matrix, within the given rectangular `bounds` .

#### Parameters

m | a graphene_matrix_t |
r | a graphene_rect_t |
bounds | the bounds of the transformation |
res | return location for the untransformed rectangle. | [out caller-allocates]

Since: 1.0

### graphene_matrix_unproject_point3d ()

    void
    graphene_matrix_unproject_point3d (const graphene_matrix_t *projection,
                                       const graphene_matrix_t *modelview,
                                       const graphene_point3d_t *point,
                                       graphene_point3d_t *res);

Unprojects the given `point` using the `projection` matrix and a `modelview` matrix.

#### Parameters

projection | a graphene_matrix_t for the projection matrix |
modelview | a graphene_matrix_t for the modelview matrix; this is the inverse of the modelview used when projecting the point |
point | a graphene_point3d_t with the coordinates of the point |
res | return location for the unprojected point. | [out caller-allocates]

Since: 1.2

### graphene_matrix_translate ()

    void
    graphene_matrix_translate (graphene_matrix_t *m,
                               const graphene_point3d_t *pos);

Adds a translation transformation to `m` using the coordinates of the given graphene_point3d_t.

#### Parameters

m | a graphene_matrix_t |
pos | a graphene_point3d_t |

Since: 1.0

### graphene_matrix_rotate ()

    void
    graphene_matrix_rotate (graphene_matrix_t *m,
                            float angle,
                            const graphene_vec3_t *axis);

Adds a rotation transformation to `m` , using the given `angle` and `axis` vector.

#### Parameters

m | a graphene_matrix_t |
angle | the rotation angle, in degrees |
axis | the rotation axis, as a graphene_vec3_t |

Since: 1.0

### graphene_matrix_rotate_x ()

    void
    graphene_matrix_rotate_x (graphene_matrix_t *m,
                              float angle);

Adds a rotation transformation around the X axis to `m` , using the given `angle` .

#### Parameters

m | a graphene_matrix_t |
angle | the rotation angle, in degrees |

Since: 1.0

### graphene_matrix_rotate_y ()

    void
    graphene_matrix_rotate_y (graphene_matrix_t *m,
                              float angle);

Adds a rotation transformation around the Y axis to `m` , using the given `angle` .

#### Parameters

m | a graphene_matrix_t |
angle | the rotation angle, in degrees |

Since: 1.0

### graphene_matrix_rotate_z ()

    void
    graphene_matrix_rotate_z (graphene_matrix_t *m,
                              float angle);

Adds a rotation transformation around the Z axis to `m` , using the given `angle` .

#### Parameters

m | a graphene_matrix_t |
angle | the rotation angle, in degrees |

Since: 1.0

### graphene_matrix_rotate_quaternion ()

    void
    graphene_matrix_rotate_quaternion (graphene_matrix_t *m,
                                       const graphene_quaternion_t *q);

Adds a rotation transformation to `m` , using the given graphene_quaternion_t.

#### Parameters

m | a graphene_matrix_t |
q | a rotation described by a graphene_quaternion_t |

Since: 1.2

### graphene_matrix_rotate_euler ()

    void
    graphene_matrix_rotate_euler (graphene_matrix_t *m,
                                  const graphene_euler_t *e);

Adds a rotation transformation to `m` , using the given graphene_euler_t.

#### Parameters

m | a graphene_matrix_t |
e | a rotation described by a graphene_euler_t |

Since: 1.2

### graphene_matrix_scale ()

    void
    graphene_matrix_scale (graphene_matrix_t *m,
                           float factor_x,
                           float factor_y,
                           float factor_z);

Adds a scaling transformation to `m` , using the three given factors.

#### Parameters

m | a graphene_matrix_t |
factor_x | scaling factor on the X axis |
factor_y | scaling factor on the Y axis |
factor_z | scaling factor on the Z axis |

Since: 1.0

### graphene_matrix_skew_xy ()

    void
    graphene_matrix_skew_xy (graphene_matrix_t *m,
                             float factor);

Adds a skew of `factor` on the X and Y axis to the given matrix.

#### Parameters

m | a graphene_matrix_t |
factor | skew factor |

Since: 1.0

### graphene_matrix_skew_xz ()

    void
    graphene_matrix_skew_xz (graphene_matrix_t *m,
                             float factor);

Adds a skew of `factor` on the X and Z axis to the given matrix.

#### Parameters

m | a graphene_matrix_t |
factor | skew factor |

Since: 1.0

### graphene_matrix_skew_yz ()

    void
    graphene_matrix_skew_yz (graphene_matrix_t *m,
                             float factor);

Adds a skew of `factor` on the Y and Z axis to the given matrix.

#### Parameters

m | a graphene_matrix_t |
factor | skew factor |

Since: 1.0

### graphene_matrix_transpose ()

    void
    graphene_matrix_transpose (const graphene_matrix_t *m,
                               graphene_matrix_t *res);

Transposes the given matrix.

#### Parameters

m | a graphene_matrix_t |
res | return location for the transposed matrix. | [out caller-allocates]

Since: 1.0

### graphene_matrix_inverse ()

    bool
    graphene_matrix_inverse (const graphene_matrix_t *m,
                             graphene_matrix_t *res);

Inverts the given matrix.

#### Parameters

m | a graphene_matrix_t |
res | return location for the inverse matrix. | [out caller-allocates]

#### Returns

`true` if the matrix is invertible

Since: 1.0

### graphene_matrix_perspective ()

    void
    graphene_matrix_perspective (const graphene_matrix_t *m,
                                 float depth,
                                 graphene_matrix_t *res);

Applies a perspective of `depth` to the matrix.

#### Parameters

m | a graphene_matrix_t |
depth | the depth of the perspective |
res | return location for the perspective matrix. | [out caller-allocates]

Since: 1.0

### graphene_matrix_normalize ()

    void
    graphene_matrix_normalize (const graphene_matrix_t *m,
                               graphene_matrix_t *res);

Normalizes the given graphene_matrix_t.

#### Parameters

m | a graphene_matrix_t |
res | return location for the normalized matrix. | [out caller-allocates]

Since: 1.0

### graphene_matrix_get_x_scale ()

    float
    graphene_matrix_get_x_scale (const graphene_matrix_t *m);

Retrieves the scaling factor on the X axis in `m` .

#### Parameters

m | a graphene_matrix_t |

#### Returns

the value of the scaling factor

Since: 1.0

### graphene_matrix_get_y_scale ()

    float
    graphene_matrix_get_y_scale (const graphene_matrix_t *m);

Retrieves the scaling factor on the Y axis in `m` .

#### Parameters

m | a graphene_matrix_t |

#### Returns

the value of the scaling factor

Since: 1.0

### graphene_matrix_get_z_scale ()

    float
    graphene_matrix_get_z_scale (const graphene_matrix_t *m);

Retrieves the scaling factor on the Z axis in `m` .

#### Parameters

m | a graphene_matrix_t |

#### Returns

the value of the scaling factor

Since: 1.0

### graphene_matrix_interpolate ()

    void
    graphene_matrix_interpolate (const graphene_matrix_t *a,
                                 const graphene_matrix_t *b,
                                 double factor,
                                 graphene_matrix_t *res);

Linearly interpolates the two given graphene_matrix_t by interpolating the decomposed transformations separately.

If either matrix cannot be reduced to their transformations then the interpolation cannot be performed, and this function will return an identity matrix.

#### Parameters

a | a graphene_matrix_t |
b | a graphene_matrix_t |
factor | the linear interpolation factor |
res | return location for the interpolated matrix. | [out caller-allocates]

Since: 1.0

### graphene_matrix_print ()

    void
    graphene_matrix_print (const graphene_matrix_t *m);

Prints the contents of a matrix.

#### Parameters

m | The matrix to print |

Since: 1.0

## Types and Values

### graphene_matrix_t

    typedef struct {
    } graphene_matrix_t;

A structure capable of holding a 4x4 matrix.

The contents of the graphene_matrix_t structure are private and should never be accessed directly.