GimpMatrix: GIMP Math Library Reference Manual

## GimpMatrix GimpMatrix — Utilities to set up and manipulate 3x3 transformation matrices. |

## Functions

void | gimp_matrix2_identity ()
void | gimp_matrix2_mult ()
gdouble | gimp_matrix2_determinant ()
void | gimp_matrix2_invert ()
void | gimp_matrix2_transform_point ()
void | gimp_matrix3_identity ()
void | gimp_matrix3_mult ()
void | gimp_matrix3_translate ()
void | gimp_matrix3_scale ()
void | gimp_matrix3_rotate ()
void | gimp_matrix3_xshear ()
void | gimp_matrix3_yshear ()
void | gimp_matrix3_affine ()
void | gimp_matrix3_transform_point ()
gdouble | gimp_matrix3_determinant ()
void | gimp_matrix3_invert ()
gboolean | gimp_matrix3_is_identity ()
gboolean | gimp_matrix3_is_diagonal ()
gboolean | gimp_matrix3_is_affine ()
gboolean | gimp_matrix3_is_simple ()
gboolean | gimp_matrix3_equal ()
void | gimp_matrix4_identity ()
void | gimp_matrix4_mult ()
void | gimp_matrix4_to_deg ()
gdouble | gimp_matrix4_transform_point ()
#define | GIMP_IS_PARAM_SPEC_MATRIX2()
GParamSpec * | gimp_param_spec_matrix2 ()
#define | GIMP_VALUE_HOLDS_MATRIX2()
#define | GIMP_IS_PARAM_SPEC_MATRIX3()
GParamSpec * | gimp_param_spec_matrix3 ()
#define | GIMP_VALUE_HOLDS_MATRIX3()

## Types and Values

struct | GimpMatrix2
struct | GimpMatrix3
struct | GimpMatrix4
#define | GIMP_TYPE_MATRIX2
#define | GIMP_TYPE_PARAM_MATRIX2
#define | GIMP_TYPE_MATRIX3
#define | GIMP_TYPE_PARAM_MATRIX3

## Description

When doing image manipulation you will often need 3x3 transformation matrices that define translation, rotation, scaling, shearing and arbitrary perspective transformations using a 3x3 matrix. Here you'll find a set of utility functions to set up those matrices and to perform basic matrix manipulations and tests.

Each matrix class has a 2 dimensional gdouble coeff member. The element for row r and column c of the matrix is coeffr.

## Functions

### gimp_matrix2_identity ()

    void
    gimp_matrix2_identity (GimpMatrix2 *matrix);

Sets the matrix to the identity matrix.

#### Parameters

matrix | A matrix. |

### gimp_matrix2_mult ()

    void
    gimp_matrix2_mult (const GimpMatrix2 *matrix1,
                       GimpMatrix2 *matrix2);

Multiplies two matrices and puts the result into the second one.

#### Parameters

matrix1 | The first input matrix. |
matrix2 | The second input matrix which will be overwritten by the result. |

### gimp_matrix2_determinant ()

    gdouble
    gimp_matrix2_determinant (const GimpMatrix2 *matrix);

Calculates the determinant of the given matrix.

#### Parameters

matrix | The input matrix. |

#### Returns

The determinant.

Since: 2.10.16

### gimp_matrix2_invert ()

    void
    gimp_matrix2_invert (GimpMatrix2 *matrix);

Inverts the given matrix.

#### Parameters

matrix | The matrix that is to be inverted. |

Since: 2.10.16

### gimp_matrix2_transform_point ()

    void
    gimp_matrix2_transform_point (const GimpMatrix2 *matrix,
                                  gdouble x,
                                  gdouble y,
                                  gdouble *newx,
                                  gdouble *newy);

Transforms a point in 2D as specified by the transformation matrix.

#### Parameters

matrix | The transformation matrix. |
x | The source X coordinate. |
y | The source Y coordinate. |
newx | The transformed X coordinate. |
newy | The transformed Y coordinate. |

Since: 2.10.16

### gimp_matrix3_identity ()

    void
    gimp_matrix3_identity (GimpMatrix3 *matrix);

Sets the matrix to the identity matrix.

#### Parameters

matrix | A matrix. |

### gimp_matrix3_mult ()

    void
    gimp_matrix3_mult (const GimpMatrix3 *matrix1,
                       GimpMatrix3 *matrix2);

Multiplies two matrices and puts the result into the second one.

#### Parameters

matrix1 | The first input matrix. |
matrix2 | The second input matrix which will be overwritten by the result. |

### gimp_matrix3_translate ()

    void
    gimp_matrix3_translate (GimpMatrix3 *matrix,
                            gdouble x,
                            gdouble y);

Translates the matrix by x and y.

#### Parameters

matrix | The matrix that is to be translated. |
x | Translation in X direction. |
y | Translation in Y direction. |

### gimp_matrix3_scale ()

    void
    gimp_matrix3_scale (GimpMatrix3 *matrix,
                        gdouble x,
                        gdouble y);

Scales the matrix by x and y

#### Parameters

matrix | The matrix that is to be scaled. |
x | X scale factor. |
y | Y scale factor. |

### gimp_matrix3_rotate ()

    void
    gimp_matrix3_rotate (GimpMatrix3 *matrix,
                         gdouble theta);

Rotates the matrix by theta degrees.

#### Parameters

matrix | The matrix that is to be rotated. |
theta | The angle of rotation (in radians). |

### gimp_matrix3_xshear ()

    void
    gimp_matrix3_xshear (GimpMatrix3 *matrix,
                         gdouble amount);

Shears the matrix in the X direction.

#### Parameters

matrix | The matrix that is to be sheared. |
amount | X shear amount. |

### gimp_matrix3_yshear ()

    void
    gimp_matrix3_yshear (GimpMatrix3 *matrix,
                         gdouble amount);

Shears the matrix in the Y direction.

#### Parameters

matrix | The matrix that is to be sheared. |
amount | Y shear amount. |

### gimp_matrix3_affine ()

    void
    gimp_matrix3_affine (GimpMatrix3 *matrix,
                         gdouble a,
                         gdouble b,
                         gdouble c,
                         gdouble d,
                         gdouble e,
                         gdouble f);

Applies the affine transformation given by six values to `matrix` . The six values form define an affine transformation matrix as illustrated below:

( a c e ) ( b d f ) ( 0 0 1 )

#### Parameters

matrix | The input matrix. |
a | the 'a' coefficient |
b | the 'b' coefficient |
c | the 'c' coefficient |
d | the 'd' coefficient |
e | the 'e' coefficient |
f | the 'f' coefficient |

### gimp_matrix3_transform_point ()

    void
    gimp_matrix3_transform_point (const GimpMatrix3 *matrix,
                                  gdouble x,
                                  gdouble y,
                                  gdouble *newx,
                                  gdouble *newy);

Transforms a point in 2D as specified by the transformation matrix.

#### Parameters

matrix | The transformation matrix. |
x | The source X coordinate. |
y | The source Y coordinate. |
newx | The transformed X coordinate. |
newy | The transformed Y coordinate. |

### gimp_matrix3_determinant ()

    gdouble
    gimp_matrix3_determinant (const GimpMatrix3 *matrix);

Calculates the determinant of the given matrix.

#### Parameters

matrix | The input matrix. |

#### Returns

The determinant.

### gimp_matrix3_invert ()

    void
    gimp_matrix3_invert (GimpMatrix3 *matrix);

Inverts the given matrix.

#### Parameters

matrix | The matrix that is to be inverted. |

### gimp_matrix3_is_identity ()

    gboolean
    gimp_matrix3_is_identity (const GimpMatrix3 *matrix);

Checks if the given matrix is the identity matrix.

#### Parameters

matrix | The matrix that is to be tested. |

#### Returns

`TRUE` if the matrix is the identity matrix, `FALSE` otherwise

### gimp_matrix3_is_diagonal ()

    gboolean
    gimp_matrix3_is_diagonal (const GimpMatrix3 *matrix);

Checks if the given matrix is diagonal.

#### Parameters

matrix | The matrix that is to be tested. |

#### Returns

`TRUE` if the matrix is diagonal, `FALSE` otherwise

### gimp_matrix3_is_affine ()

    gboolean
    gimp_matrix3_is_affine (const GimpMatrix3 *matrix);

Checks if the given matrix defines an affine transformation.

#### Parameters

matrix | The matrix that is to be tested. |

#### Returns

`TRUE` if the matrix defines an affine transformation, `FALSE` otherwise

Since: 2.4

### gimp_matrix3_is_simple ()

    gboolean
    gimp_matrix3_is_simple (const GimpMatrix3 *matrix);

Checks if we'll need to interpolate when applying this matrix as a transformation.

#### Parameters

matrix | The matrix that is to be tested. |

#### Returns

`TRUE` if all entries of the upper left 2x2 matrix are either 0 or 1, `FALSE` otherwise

### gimp_matrix3_equal ()

    gboolean
    gimp_matrix3_equal (const GimpMatrix3 *matrix1,
                        const GimpMatrix3 *matrix2);

Checks if two matrices are equal.

#### Parameters

matrix1 | The first matrix |
matrix2 | The second matrix |

#### Returns

`TRUE` the matrices are equal, `FALSE` otherwise

Since: 2.10.16

### gimp_matrix4_identity ()

    void
    gimp_matrix4_identity (GimpMatrix4 *matrix);

Sets the matrix to the identity matrix.

#### Parameters

matrix | A matrix. |

Since: 2.10.16

### gimp_matrix4_mult ()

    void
    gimp_matrix4_mult (const GimpMatrix4 *matrix1,
                       GimpMatrix4 *matrix2);

Multiplies two matrices and puts the result into the second one.

#### Parameters

matrix1 | The first input matrix. |
matrix2 | The second input matrix which will be overwritten by the result. |

Since: 2.10.16

### gimp_matrix4_to_deg ()

    void
    gimp_matrix4_to_deg (const GimpMatrix4 *matrix,
                         gdouble *a,
                         gdouble *b,
                         gdouble *c);

### gimp_matrix4_transform_point ()

    gdouble
    gimp_matrix4_transform_point (const GimpMatrix4 *matrix,
                                  gdouble x,
                                  gdouble y,
                                  gdouble z,
                                  gdouble *newx,
                                  gdouble *newy,
                                  gdouble *newz);

Transforms a point in 3D as specified by the transformation matrix.

#### Parameters

matrix | The transformation matrix. |
x | The source X coordinate. |
y | The source Y coordinate. |
z | The source Z coordinate. |
newx | The transformed X coordinate. |
newy | The transformed Y coordinate. |
newz | The transformed Z coordinate. |

#### Returns

The transformed W coordinate.

Since: 2.10.16

### GIMP_IS_PARAM_SPEC_MATRIX2()

    #define GIMP_IS_PARAM_SPEC_MATRIX2(pspec)  (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), GIMP_TYPE_PARAM_MATRIX2))

### gimp_param_spec_matrix2 ()

    GParamSpec *
    gimp_param_spec_matrix2 (const gchar *name,
                             const gchar *nick,
                             const gchar *blurb,
                             const GimpMatrix2 *default_value,
                             GParamFlags flags);

Creates a param spec to hold a GimpMatrix2 value. See `g_param_spec_internal()` for more information.

#### Parameters

name | Canonical name of the param |
nick | Nickname of the param |
blurb | Brief description of param. |
default_value | Value to use if none is assigned. |
flags | a combination of GParamFlags |

#### Returns

a newly allocated GParamSpec instance

Since: 2.4

### GIMP_VALUE_HOLDS_MATRIX2()

    #define GIMP_VALUE_HOLDS_MATRIX2(value) (G_TYPE_CHECK_VALUE_TYPE ((value), GIMP_TYPE_MATRIX2))

### GIMP_IS_PARAM_SPEC_MATRIX3()

    #define GIMP_IS_PARAM_SPEC_MATRIX3(pspec)  (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), GIMP_TYPE_PARAM_MATRIX3))

### gimp_param_spec_matrix3 ()

    GParamSpec *
    gimp_param_spec_matrix3 (const gchar *name,
                             const gchar *nick,
                             const gchar *blurb,
                             const GimpMatrix3 *default_value,
                             GParamFlags flags);

Creates a param spec to hold a GimpMatrix3 value. See `g_param_spec_internal()` for more information.

#### Parameters

name | Canonical name of the param |
nick | Nickname of the param |
blurb | Brief description of param. |
default_value | Value to use if none is assigned. |
flags | a combination of GParamFlags |

#### Returns

a newly allocated GParamSpec instance

Since: 2.8

### GIMP_VALUE_HOLDS_MATRIX3()

    #define GIMP_VALUE_HOLDS_MATRIX3(value) (G_TYPE_CHECK_VALUE_TYPE ((value), GIMP_TYPE_MATRIX3))

## Types and Values

### struct GimpMatrix2

    struct GimpMatrix2 {
      gdouble coeff[2][2];
    };

A two by two matrix.

#### Members

gdouble `coeff`[2][2]; | the coefficients |

### struct GimpMatrix3

    struct GimpMatrix3 {
      gdouble coeff[3][3];
    };

A three by three matrix.

#### Members

gdouble `coeff`[3][3]; | the coefficients |

### struct GimpMatrix4

    struct GimpMatrix4 {
      gdouble coeff[4][4];
    };

A four by four matrix.

#### Members

gdouble `coeff`[4][4]; | the coefficients |

### GIMP_TYPE_MATRIX2

    #define GIMP_TYPE_MATRIX2               (gimp_matrix2_get_type ())

### GIMP_TYPE_PARAM_MATRIX2

    #define GIMP_TYPE_PARAM_MATRIX2            (gimp_param_matrix2_get_type ())

### GIMP_TYPE_MATRIX3

    #define GIMP_TYPE_MATRIX3               (gimp_matrix3_get_type ())

### GIMP_TYPE_PARAM_MATRIX3

    #define GIMP_TYPE_PARAM_MATRIX3            (gimp_param_matrix3_get_type ())

## See Also

GimpVector2, GimpVector3, GimpVector4