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 the matrix is simple, 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