cairo_matrix_t: Cairo: A Vector Graphics Library

## cairo_matrix_t cairo_matrix_t — Generic matrix operations |

## Functions

void | cairo_matrix_init ()
void | cairo_matrix_init_identity ()
void | cairo_matrix_init_translate ()
void | cairo_matrix_init_scale ()
void | cairo_matrix_init_rotate ()
void | cairo_matrix_translate ()
void | cairo_matrix_scale ()
void | cairo_matrix_rotate ()
cairo_status_t | cairo_matrix_invert ()
void | cairo_matrix_multiply ()
void | cairo_matrix_transform_distance ()
void | cairo_matrix_transform_point ()

## Types and Values

| cairo_matrix_t

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

## Functions

### 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;

#### Parameters

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 |

Since: 1.0

### cairo_matrix_init_identity ()

    void
    cairo_matrix_init_identity (cairo_matrix_t *matrix);

Modifies `matrix` to be an identity transformation.

#### Parameters

matrix | a cairo_matrix_t |

Since: 1.0

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

#### Parameters

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

Since: 1.0

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

#### Parameters

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

Since: 1.0

### cairo_matrix_init_rotate ()

    void
    cairo_matrix_init_rotate (cairo_matrix_t *matrix,
                              double radians);

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

#### Parameters

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

Since: 1.0

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

#### Parameters

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

Since: 1.0

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

#### Parameters

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

Since: 1.0

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

#### Parameters

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

Since: 1.0

### cairo_matrix_invert ()

    cairo_status_t
    cairo_matrix_invert (cairo_matrix_t *matrix);

Changes `matrix` to be the inverse of its 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.

#### Parameters

matrix | a cairo_matrix_t |

#### Returns

If `matrix` has an inverse, modifies `matrix` to be the inverse matrix and returns `CAIRO_STATUS_SUCCESS`. Otherwise, returns `CAIRO_STATUS_INVALID_MATRIX`.

Since: 1.0

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

#### Parameters

result | a cairo_matrix_t in which to store the result |
a | a cairo_matrix_t |
b | a cairo_matrix_t |

Since: 1.0

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

#### Parameters

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 |

Since: 1.0

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

#### Parameters

matrix | a cairo_matrix_t |
x | X position. An in/out parameter |
y | Y position. An in/out parameter |

Since: 1.0

## Types and Values

### 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;

#### Members

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 |

Since: 1.0

## See Also

cairo_t