```{index} single: Cairo::Matrix ``` # Cairo::Matrix ```{pperl-module-badges} Cairo::Matrix ``` `Cairo::Matrix` - the affine transform every drawing operation goes through. A matrix holds the six numbers `(xx, yx, xy, yy, x0, y0)` of a 2D affine transform. The `Cairo::Matrix->init*` constructors build one, `translate`/`scale`/`rotate` modify it in place, `multiply` combines two, `invert` inverts it in place, and `transform_point` / `transform_distance` apply it to a coordinate pair. Unlike the other cairo objects a matrix is a plain value, not a shared reference-counted handle. Every method that hands one back - `Context::get_matrix`, `Pattern::get_matrix`, `ScaledFont::get_font_matrix` - returns a fresh copy, so changing the matrix you got back never changes the object it came from. The copy is released when Perl destroys it; nothing has to be freed by hand. The matrix API is stable since cairo 1.0, so no method here depends on a particular libcairo version. ## Functions ### Other Functions #### `init` Builds a new matrix from the six affine components, in cairo's order: `Cairo::Matrix->init($xx, $yx, $xy, $yy, $x0, $y0)`. All six are required; a shorter argument list croaks with a usage message. #### `init_identity` Builds a new matrix set to the identity transform: `Cairo::Matrix->init_identity`. #### `init_translate` Builds a new matrix that translates by `($tx, $ty)`: `Cairo::Matrix->init_translate($tx, $ty)`. #### `init_scale` Builds a new matrix that scales by `$sx` in x and `$sy` in y: `Cairo::Matrix->init_scale($sx, $sy)`. #### `init_rotate` Builds a new matrix that rotates by `$radians`: `Cairo::Matrix->init_rotate($radians)`. #### `translate` Applies a translation of `($tx, $ty)` to `$matrix` in place (cairo_matrix_translate). Returns nothing. #### `scale` Applies a scale of `($sx, $sy)` to `$matrix` in place (cairo_matrix_scale). Returns nothing. #### `rotate` Applies a rotation of `$radians` to `$matrix` in place (cairo_matrix_rotate). Returns nothing. #### `invert` Inverts `$matrix` in place (cairo_matrix_invert) and returns the outcome as a status nickname: `success`, or `invalid-matrix` if the matrix is not invertible. #### `multiply` Returns a **new** `Cairo::Matrix` holding the product of `$a` and `$b`. #### `transform_distance` Transforms the distance vector `($dx, $dy)` by `$matrix` and returns the transformed pair as a two-element list. Only the matrix's linear part is applied - the translation is ignored, which is what makes this a distance rather than a point. #### `transform_point` Transforms the point `($x, $y)` by `$matrix` and returns the transformed pair as a two-element list. The full affine transform is applied, translation included.