## cairo_matrix_t cairo_matrix_t — Generic matrix operations |

## Synopsis

                        cairo_matrix_t;
    void                cairo_matrix_init                   (cairo_matrix_t *matrix,
                                                             double xx,
                                                             double yx,
                                                             double xy,
                                                             double yy,
                                                             double x0,
                                                             double y0);
    void                cairo_matrix_init_identity          (cairo_matrix_t *matrix);
    void                cairo_matrix_init_translate         (cairo_matrix_t *matrix,
                                                             double tx,
                                                             double ty);
    void                cairo_matrix_init_scale             (cairo_matrix_t *matrix,
                                                             double sx,
                                                             double sy);
    void                cairo_matrix_init_rotate            (cairo_matrix_t *matrix,
                                                             double radians);
    void                cairo_matrix_translate              (cairo_matrix_t *matrix,
                                                             double tx,
                                                             double ty);
    void                cairo_matrix_scale                  (cairo_matrix_t *matrix,
                                                             double sx,
                                                             double sy);
    void                cairo_matrix_rotate                 (cairo_matrix_t *matrix,
                                                             double radians);
    cairo_status_t      cairo_matrix_invert                 (cairo_matrix_t *matrix);
    void                cairo_matrix_multiply               (cairo_matrix_t *result,
                                                             const cairo_matrix_t *a,
                                                             const cairo_matrix_t *b);
    void                cairo_matrix_transform_distance     (const cairo_matrix_t *matrix,
                                                             double *dx,
                                                             double *dy);
    void                cairo_matrix_transform_point        (const cairo_matrix_t *matrix,
                                                             double *x,
                                                             double *y);

## Description

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()`.

## Details

### cairo_matrix_t

    typedef struct {
        double xx; double yx;
        double xy; double yy;
        double x0; double y0;
    } cairo_matrix_t;

A cairo_matrix_t holds an affine transformation, such as a scale, rotation, shear, or a combination of those. The transformation of a point (x, y) is given by:

        x_new = xx * x + xy * y + x0;
        y_new = yx * x + yy * y + y0;

double `xx`; | xx component of the affine transformation
double `yx`; | yx component of the affine transformation
double `xy`; | xy component of the affine transformation
double `yy`; | yy component of the affine transformation
double `x0`; | X translation component of the affine transformation
double `y0`; | Y translation component of the affine transformation

### cairo_matrix_init ()

    void                cairo_matrix_init                   (cairo_matrix_t *matrix,
                                                             double xx,
                                                             double yx,
                                                             double xy,
                                                             double yy,
                                                             double x0,
                                                             double y0);

Sets `matrix` to be the affine transformation given by `xx`, `yx`, `xy`, `yy`, `x0`, `y0`. The transformation is given by:

     x_new = xx * x + xy * y + x0;
     y_new = yx * x + yy * y + y0;

`matrix` : | a cairo_matrix_t
`xx` : | xx component of the affine transformation
`yx` : | yx component of the affine transformation
`xy` : | xy component of the affine transformation
`yy` : | yy component of the affine transformation
`x0` : | X translation component of the affine transformation
`y0` : | Y translation component of the affine transformation

### cairo_matrix_init_identity ()

    void                cairo_matrix_init_identity          (cairo_matrix_t *matrix);

Modifies `matrix` to be an identity transformation.

`matrix` : | a cairo_matrix_t

### cairo_matrix_init_translate ()

    void                cairo_matrix_init_translate         (cairo_matrix_t *matrix,
                                                             double tx,
                                                             double ty);

Initializes `matrix` to a transformation that translates by `tx` and `ty` in the X and Y dimensions, respectively.

`matrix` : | a cairo_matrix_t
`tx` : | amount to translate in the X direction
`ty` : | amount to translate in the Y direction

### cairo_matrix_init_scale ()

    void                cairo_matrix_init_scale             (cairo_matrix_t *matrix,
                                                             double sx,
                                                             double sy);

Initializes `matrix` to a transformation that scales by `sx` and `sy` in the X and Y dimensions, respectively.

`matrix` : | a cairo_matrix_t
`sx` : | scale factor in the X direction
`sy` : | scale factor in the Y direction

### cairo_matrix_init_rotate ()

    void                cairo_matrix_init_rotate            (cairo_matrix_t *matrix,
                                                             double radians);

Initialized `matrix` to a transformation that rotates by `radians`.

`matrix` : | a cairo_matrix_t
`radians` : | angle of rotation, in radians. The direction of rotation is defined such that positive angles rotate in the direction from the positive X axis toward the positive Y axis. With the default axis orientation of cairo, positive angles rotate in a clockwise direction.

### cairo_matrix_translate ()

    void                cairo_matrix_translate              (cairo_matrix_t *matrix,
                                                             double tx,
                                                             double 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.

`matrix` : | a cairo_matrix_t
`tx` : | amount to translate in the X direction
`ty` : | amount to translate in the Y direction

### cairo_matrix_scale ()

    void                cairo_matrix_scale                  (cairo_matrix_t *matrix,
                                                             double sx,
                                                             double 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.

`matrix` : | a cairo_matrix_t
`sx` : | scale factor in the X direction
`sy` : | scale factor in the Y direction

### cairo_matrix_rotate ()

    void                cairo_matrix_rotate                 (cairo_matrix_t *matrix,
                                                             double 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.

`matrix` : | a cairo_matrix_t
`radians` : | angle of rotation, in radians. The direction of rotation is defined such that positive angles rotate in the direction from the positive X axis toward the positive Y axis. With the default axis orientation of cairo, positive angles rotate in a clockwise direction.

### cairo_matrix_invert ()

    cairo_status_t      cairo_matrix_invert                 (cairo_matrix_t *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 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
Returns : | `CAIRO_STATUS_INVALID_MATRIX`.

### cairo_matrix_multiply ()

    void                cairo_matrix_multiply               (cairo_matrix_t *result,
                                                             const cairo_matrix_t *a,
                                                             const cairo_matrix_t *b);

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

### cairo_matrix_transform_distance ()

    void                cairo_matrix_transform_distance     (const cairo_matrix_t *matrix,
                                                             double *dx,
                                                             double *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`.

`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

### cairo_matrix_transform_point ()

    void                cairo_matrix_transform_point        (const cairo_matrix_t *matrix,
                                                             double *x,
                                                             double *y);

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