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