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

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

 matrix

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

 matrix

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

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:

```dx_new = xx * dx + xy * dy;
dy_new = yx * dx + yy * dy;
```

#### Parameters

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