cairo_matrix_t

## cairo_matrix_t cairo_matrix_t — Transformation matrices |

## 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 represents between different coordinates spaces. A cairo_matrix holds an affine transformation, such as a scale, rotation, or shear, or a combination of those. Mathematically, the effect of an affine transformation on a point (`x`,`y`) is given by:

        x_new = x * a + y * c + tx;
        y_new = x * b + y * d + ty;

The parameters `a`, `b`, `c`, `d`, `tx`, `ty` can be retrieved with `cairo_matrix_get_affine()` and set with `cairo_matrix_get_affine()`.

The primary use of transformation matrices in Cairo is as the current transformation matrix in a cairo_t. The current transformation matrix gives the transformation from user space coordinates to device coordinates. See `cairo_set_matrix()`, `cairo_current_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, or shear, or a combination of those.

### 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 `tx`, `ty` 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()` 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