22 cairo_matrix_t

Generic matrix operations

22.1 Overview

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

22.2 Usage

Function: cairo-matrix-translate (matrix <cairo-matrix-t>) (tx <double>) (ty <double>)

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.

matrix

a <cairo-matrix-t>

tx

amount to translate in the X direction

ty

amount to translate in the Y direction

Function: cairo-matrix-invert (matrix <cairo-matrix-t>) ⇒  (ret <cairo-status-t>)

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.

matrix

a <cairo-matrix-t>

ret

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

Function: cairo-matrix-multiply (result <cairo-matrix-t>) (a <cairo-matrix-t>) (b <cairo-matrix-t>)

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.

result

a <cairo-matrix-t> in which to store the result

a

a <cairo-matrix-t>

b

a <cairo-matrix-t>

Function: cairo-matrix-transform-distance (matrix <cairo-matrix-t>) ⇒  (dx <double>) (dy <double>)

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.

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

Function: cairo-matrix-transform-point (matrix <cairo-matrix-t>) ⇒  (x <double>) (y <double>)

Transforms the point (x, y) by matrix.

matrix

a <cairo-matrix-t>

x

X position. An in/out parameter

y

Y position. An in/out parameter