Next: , Previous: SVG Surfaces, Up: Top

17 cairo_matrix_t

Generic matrix operations

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

17.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 it's 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.

Returns: If matrix has an inverse, modifies matrix to be the inverse matrix and returns `CAIRO_STATUS_SUCCESS'. Otherwise,

matrix
a <cairo-matrix-t>
ret
`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