GimpMatrix

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

## Synopsis

    struct              GimpMatrix2;
    struct              GimpMatrix3;
    struct              GimpMatrix4;
    void                gimp_matrix2_identity               (GimpMatrix2 *matrix);
    void                gimp_matrix2_mult                   (const GimpMatrix2 *matrix1,
                                                             GimpMatrix2 *matrix2);
    void                gimp_matrix3_identity               (GimpMatrix3 *matrix);
    void                gimp_matrix3_mult                   (const GimpMatrix3 *matrix1,
                                                             GimpMatrix3 *matrix2);
    void                gimp_matrix3_translate              (GimpMatrix3 *matrix,
                                                             gdouble x,
                                                             gdouble y);
    void                gimp_matrix3_scale                  (GimpMatrix3 *matrix,
                                                             gdouble x,
                                                             gdouble y);
    void                gimp_matrix3_rotate                 (GimpMatrix3 *matrix,
                                                             gdouble theta);
    void                gimp_matrix3_xshear                 (GimpMatrix3 *matrix,
                                                             gdouble amount);
    void                gimp_matrix3_yshear                 (GimpMatrix3 *matrix,
                                                             gdouble amount);
    void                gimp_matrix3_affine                 (GimpMatrix3 *matrix,
                                                             gdouble a,
                                                             gdouble b,
                                                             gdouble c,
                                                             gdouble d,
                                                             gdouble e,
                                                             gdouble f);
    void                gimp_matrix3_transform_point        (const GimpMatrix3 *matrix,
                                                             gdouble x,
                                                             gdouble y,
                                                             gdouble *newx,
                                                             gdouble *newy);
    gdouble             gimp_matrix3_determinant            (const GimpMatrix3 *matrix);
    void                gimp_matrix3_invert                 (GimpMatrix3 *matrix);
    gboolean            gimp_matrix3_is_identity            (const GimpMatrix3 *matrix);
    gboolean            gimp_matrix3_is_diagonal            (const GimpMatrix3 *matrix);
    gboolean            gimp_matrix3_is_affine              (const GimpMatrix3 *matrix);
    gboolean            gimp_matrix3_is_simple              (const GimpMatrix3 *matrix);
    void                gimp_matrix4_to_deg                 (const GimpMatrix4 *matrix,
                                                             gdouble *a,
                                                             gdouble *b,
                                                             gdouble *c);
    #define             GIMP_TYPE_MATRIX2
    #define             GIMP_TYPE_PARAM_MATRIX2
    #define             GIMP_IS_PARAM_SPEC_MATRIX2          (pspec)
    GParamSpec *        gimp_param_spec_matrix2             (const gchar *name,
                                                             const gchar *nick,
                                                             const gchar *blurb,
                                                             const GimpMatrix2 *default_value,
                                                             GParamFlags flags);
    #define             GIMP_VALUE_HOLDS_MATRIX2            (value)
    #define             GIMP_TYPE_MATRIX3
    #define             GIMP_TYPE_PARAM_MATRIX3
    #define             GIMP_IS_PARAM_SPEC_MATRIX3          (pspec)
    GParamSpec *        gimp_param_spec_matrix3             (const gchar *name,
                                                             const gchar *nick,
                                                             const gchar *blurb,
                                                             const GimpMatrix3 *default_value,
                                                             GParamFlags flags);
    #define             GIMP_VALUE_HOLDS_MATRIX3            (value)

## 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 coeff[r][c].

## Details

### struct GimpMatrix2

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

A two by two matrix.

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

### struct GimpMatrix3

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

A three by three matrix.

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

### struct GimpMatrix4

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

A four by four matrix.

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

### gimp_matrix2_identity ()

    void                gimp_matrix2_identity               (GimpMatrix2 *matrix);

Sets the matrix to the identity matrix.

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

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

### gimp_matrix3_identity ()

    void                gimp_matrix3_identity               (GimpMatrix3 *matrix);

Sets the matrix to the identity matrix.

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

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

`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

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

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

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

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

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

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

`matrix` : | The input matrix.
Returns : | The determinant.

### gimp_matrix3_invert ()

    void                gimp_matrix3_invert                 (GimpMatrix3 *matrix);

Inverts the given matrix.

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

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

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

`matrix` : | The matrix that is to be tested.
Returns : | `TRUE` if the matrix defines an affine transformation, `FALSE` otherwise

Since GIMP 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.

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

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

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

`name` : | Canonical name of the param
`nick` : | Nickname of the param
`blurb` : | Brief desciption of param.
`default_value` : | Value to use if none is assigned.
`flags` : | a combination of GParamFlags
Returns : | a newly allocated GParamSpec instance

Since GIMP 2.4

### GIMP_VALUE_HOLDS_MATRIX2()

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

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

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

`name` : | Canonical name of the param
`nick` : | Nickname of the param
`blurb` : | Brief desciption of param.
`default_value` : | Value to use if none is assigned.
`flags` : | a combination of GParamFlags
Returns : | a newly allocated GParamSpec instance

Since GIMP 2.8

### GIMP_VALUE_HOLDS_MATRIX3()

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

## See Also

GimpVector2, GimpVector3, GimpVector4