# Module `Cairo.Matrix`

This is used throughout cairo to convert between different coordinate spaces.

`type t`

`= matrix`

`val init_identity : unit -> t`

`init_identity()`

returns the identity transformation.

`val init_translate : float -> float -> t`

`init_translate tx ty`

return a transformation that translates by`tx`

and`ty`

in the X and Y dimensions, respectively.

`val init_scale : float -> float -> t`

`init_scale sx sy`

return a transformation that scales by`sx`

and`sy`

in the X and Y dimensions, respectively.

`val init_rotate : float -> t`

`init_rotate radians`

returns a a transformation that rotates by`radians`

.

`val translate : t -> float -> float -> unit`

`translate matrix tx 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.

`val scale : t -> float -> float -> unit`

`scale matrix sx 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.

`val rotate : t -> float -> unit`

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

`val invert : t -> unit`

`invert matrix`

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 raise`Error INVALID_MATRIX`

.

`val multiply : t -> t -> t`

`multiply a b`

multiplies the affine transformations in`a`

and`b`

together and return the 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.

`val transform_distance : t -> dx:float -> dy:float -> float * float`

`transform_distance matrix dx 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.

`val transform_point : t -> float -> float -> float * float`

`transform_point matrix x y`

transforms the point (`x`

,`y`

) by`matrix`

.