cairo_matrix_t

cairo_matrix_t — Generic matrix operations

Functions

Types and Values

Object Hierarchy


Description

cairo_matrix_t is used throughout cairo to convert between different coordinate spaces. A cairo_matrix_t holds an affine transformation, such as a scale, rotation, shear, or a combination of these. The transformation of a point (x,y) is given by:

x_new = xx * x + xy * y + x0;
y_new = yx * x + yy * y + y0;

The current transformation matrix of a cairo_t, represented as a cairo_matrix_t, defines the transformation from user-space coordinates to device-space coordinates. See cairo_get_matrix() and cairo_set_matrix().

Functions

cairo_matrix_init ()

void
cairo_matrix_init (cairo_matrix_t *matrix,
                   double xx,
                   double yx,
                   double xy,
                   double yy,
                   double x0,
                   double y0);

Sets matrix to be the affine transformation given by xx , yx , xy , yy , x0 , y0 . The transformation is given by:

 x_new = xx * x + xy * y + x0;
 y_new = yx * x + yy * y + y0;

Parameters

matrix

a cairo_matrix_t

 

xx

xx component of the affine transformation

 

yx

yx component of the affine transformation

 

xy

xy component of the affine transformation

 

yy

yy component of the affine transformation

 

x0

X translation component of the affine transformation

 

y0

Y translation component of the affine transformation

 

Since 1.0


cairo_matrix_init_identity ()

void
cairo_matrix_init_identity (cairo_matrix_t *matrix);

Modifies matrix to be an identity transformation.

Parameters

matrix

a cairo_matrix_t

 

Since 1.0


cairo_matrix_init_translate ()

void
cairo_matrix_init_translate (cairo_matrix_t *matrix,
                             double tx,
                             double ty);

Initializes matrix to a transformation that translates by tx and ty in the X and Y dimensions, respectively.

Parameters

matrix

a cairo_matrix_t

 

tx

amount to translate in the X direction

 

ty

amount to translate in the Y direction

 

Since 1.0


cairo_matrix_init_scale ()

void
cairo_matrix_init_scale (cairo_matrix_t *matrix,
                         double sx,
                         double sy);

Initializes matrix to a transformation that scales by sx and sy in the X and Y dimensions, respectively.

Parameters

matrix

a cairo_matrix_t

 

sx

scale factor in the X direction

 

sy

scale factor in the Y direction

 

Since 1.0


cairo_matrix_init_rotate ()

void
cairo_matrix_init_rotate (cairo_matrix_t *matrix,
                          double radians);

Initialized matrix to a transformation that rotates by radians .

Parameters

matrix

a cairo_matrix_t

 

radians

angle of rotation, in radians. The direction of rotation is defined such that positive angles rotate in the direction from the positive X axis toward the positive Y axis. With the default axis orientation of cairo, positive angles rotate in a clockwise direction.

 

Since 1.0


cairo_matrix_translate ()

void
cairo_matrix_translate (cairo_matrix_t *matrix,
                        double tx,
                        double ty);

Applies a translation by tx , ty to the transformation in matrix . The effect of the new transformation is to first translate the coordinates by tx and ty , then apply the original transformation to the coordinates.

Parameters

matrix

a cairo_matrix_t

 

tx

amount to translate in the X direction

 

ty

amount to translate in the Y direction

 

Since 1.0


cairo_matrix_scale ()

void
cairo_matrix_scale (cairo_matrix_t *matrix,
                    double sx,
                    double sy);

Applies scaling by sx , sy to the transformation in matrix . The effect of the new transformation is to first scale the coordinates by sx and sy , then apply the original transformation to the coordinates.

Parameters

matrix

a cairo_matrix_t

 

sx

scale factor in the X direction

 

sy

scale factor in the Y direction

 

Since 1.0


cairo_matrix_rotate ()

void
cairo_matrix_rotate (cairo_matrix_t *matrix,
                     double radians);

Applies rotation by radians to the transformation in matrix . The effect of the new transformation is to first rotate the coordinates by radians , then apply the original transformation to the coordinates.

Parameters

matrix

a cairo_matrix_t

 

radians

angle of rotation, in radians. The direction of rotation is defined such that positive angles rotate in the direction from the positive X axis toward the positive Y axis. With the default axis orientation of cairo, positive angles rotate in a clockwise direction.

 

Since 1.0


cairo_matrix_invert ()

cairo_status_t
cairo_matrix_invert (cairo_matrix_t *matrix);

Changes matrix to be the inverse of its original value. Not all transformation matrices have inverses; if the matrix collapses points together (it is degenerate), then it has no inverse and this function will fail.

Parameters

matrix

a cairo_matrix_t

 

Returns

If matrix has an inverse, modifies matrix to be the inverse matrix and returns CAIRO_STATUS_SUCCESS. Otherwise, returns CAIRO_STATUS_INVALID_MATRIX.

Since 1.0


cairo_matrix_multiply ()

void
cairo_matrix_multiply (cairo_matrix_t *result,
                       const cairo_matrix_t *a,
                       const cairo_matrix_t *b);

Multiplies the affine transformations in a and b together and stores the result in result . The effect of the resulting transformation is to first apply the transformation in a to the coordinates and then apply the transformation in b to the coordinates.

It is allowable for result to be identical to either a or b .

Parameters

result

a cairo_matrix_t in which to store the result

 

a

a cairo_matrix_t

 

b

a cairo_matrix_t

 

Since 1.0


cairo_matrix_transform_distance ()

void
cairo_matrix_transform_distance (const cairo_matrix_t *matrix,
                                 double *dx,
                                 double *dy);

Transforms the distance vector (dx ,dy ) by matrix . This is similar to cairo_matrix_transform_point() except that the translation components of the transformation are ignored. The calculation of the returned vector is as follows:

dx2 = dx1 * a + dy1 * c;
dy2 = dx1 * b + dy1 * d;

Affine transformations are position invariant, so the same vector always transforms to the same vector. If (x1 ,y1 ) transforms to (x2 ,y2 ) then (x1 +dx1 ,y1 +dy1 ) will transform to (x1 +dx2 ,y1 +dy2 ) for all values of x1 and x2 .

Parameters

matrix

a cairo_matrix_t

 

dx

X component of a distance vector. An in/out parameter

 

dy

Y component of a distance vector. An in/out parameter

 

Since 1.0


cairo_matrix_transform_point ()

void
cairo_matrix_transform_point (const cairo_matrix_t *matrix,
                              double *x,
                              double *y);

Transforms the point (x , y ) by matrix .

Parameters

matrix

a cairo_matrix_t

 

x

X position. An in/out parameter

 

y

Y position. An in/out parameter

 

Since 1.0

Types and Values

cairo_matrix_t

typedef struct {
    double xx; double yx;
    double xy; double yy;
    double x0; double y0;
} cairo_matrix_t;

A cairo_matrix_t holds an affine transformation, such as a scale, rotation, shear, or a combination of those. The transformation of a point (x, y) is given by:

    x_new = xx * x + xy * y + x0;
    y_new = yx * x + yy * y + y0;

Members

double xx;

xx component of the affine transformation

 

double yx;

yx component of the affine transformation

 

double xy;

xy component of the affine transformation

 

double yy;

yy component of the affine transformation

 

double x0;

X translation component of the affine transformation

 

double y0;

Y translation component of the affine transformation

 

Since 1.0

See Also

cairo_t