## Transformations

Transformations — Manipulating the current transformation matrix

## Functions

void | cairo_translate ()
void | cairo_scale ()
void | cairo_rotate ()
void | cairo_transform ()
void | cairo_set_matrix ()
void | cairo_get_matrix ()
void | cairo_identity_matrix ()
void | cairo_user_to_device ()
void | cairo_user_to_device_distance ()
void | cairo_device_to_user ()
void | cairo_device_to_user_distance ()

## Description

The current transformation matrix, ctm, is a two-dimensional affine transformation that maps all coordinates and other drawing instruments from the user space into the surface's canonical coordinate system, also known as the device space.

## Functions

### cairo_translate ()

    void
    cairo_translate (cairo_t *cr,
                     double tx,
                     double ty);

Modifies the current transformation matrix (CTM) by translating the user-space origin by (`tx` , `ty` ). This offset is interpreted as a user-space coordinate according to the CTM in place before the new call to `cairo_translate()`. In other words, the translation of the user-space origin takes place after any existing transformation.

#### Parameters

cr | a cairo context |
tx | amount to translate in the X direction |
ty | amount to translate in the Y direction |

Since: 1.0

### cairo_scale ()

    void
    cairo_scale (cairo_t *cr,
                 double sx,
                 double sy);

Modifies the current transformation matrix (CTM) by scaling the X and Y user-space axes by `sx` and `sy` respectively. The scaling of the axes takes place after any existing transformation of user space.

#### Parameters

cr | a cairo context |
sx | scale factor for the X dimension |
sy | scale factor for the Y dimension |

Since: 1.0

### cairo_rotate ()

    void
    cairo_rotate (cairo_t *cr,
                  double angle);

Modifies the current transformation matrix (CTM) by rotating the user-space axes by `angle` radians. The rotation of the axes takes places after any existing transformation of user space. The rotation direction for positive angles is from the positive X axis toward the positive Y axis.

#### Parameters

cr | a cairo context |
angle | angle (in radians) by which the user-space axes will be rotated |

Since: 1.0

### cairo_transform ()

    void
    cairo_transform (cairo_t *cr,
                     const cairo_matrix_t *matrix);

Modifies the current transformation matrix (CTM) by applying `matrix` as an additional transformation. The new transformation of user space takes place after any existing transformation.

#### Parameters

cr | a cairo context |
matrix | a transformation to be applied to the user-space axes |

Since: 1.0

### cairo_set_matrix ()

    void
    cairo_set_matrix (cairo_t *cr,
                      const cairo_matrix_t *matrix);

Modifies the current transformation matrix (CTM) by setting it equal to `matrix` .

#### Parameters

cr | a cairo context |
matrix | a transformation matrix from user space to device space |

Since: 1.0

### cairo_get_matrix ()

    void
    cairo_get_matrix (cairo_t *cr,
                      cairo_matrix_t *matrix);

Stores the current transformation matrix (CTM) into `matrix` .

#### Parameters

cr | a cairo context |
matrix | return value for the matrix |

Since: 1.0

### cairo_identity_matrix ()

    void
    cairo_identity_matrix (cairo_t *cr);

Resets the current transformation matrix (CTM) by setting it equal to the identity matrix. That is, the user-space and device-space axes will be aligned and one user-space unit will transform to one device-space unit.

#### Parameters

cr | a cairo context |

Since: 1.0

### cairo_user_to_device ()

    void
    cairo_user_to_device (cairo_t *cr,
                          double *x,
                          double *y);

Transform a coordinate from user space to device space by multiplying the given point by the current transformation matrix (CTM).

#### Parameters

cr | a cairo context |
x | X value of coordinate (in/out parameter) |
y | Y value of coordinate (in/out parameter) |

Since: 1.0

### cairo_user_to_device_distance ()

    void
    cairo_user_to_device_distance (cairo_t *cr,
                                   double *dx,
                                   double *dy);

Transform a distance vector from user space to device space. This function is similar to `cairo_user_to_device()` except that the translation components of the CTM will be ignored when transforming (`dx` ,`dy` ).

#### Parameters

cr | a cairo context |
dx | X component of a distance vector (in/out parameter) |
dy | Y component of a distance vector (in/out parameter) |

Since: 1.0

### cairo_device_to_user ()

    void
    cairo_device_to_user (cairo_t *cr,
                          double *x,
                          double *y);

Transform a coordinate from device space to user space by multiplying the given point by the inverse of the current transformation matrix (CTM).

#### Parameters

cr | a cairo |
x | X value of coordinate (in/out parameter) |
y | Y value of coordinate (in/out parameter) |

Since: 1.0

### cairo_device_to_user_distance ()

    void
    cairo_device_to_user_distance (cairo_t *cr,
                                   double *dx,
                                   double *dy);

Transform a distance vector from device space to user space. This function is similar to `cairo_device_to_user()` except that the translation components of the inverse CTM will be ignored when transforming (`dx` ,`dy` ).

#### Parameters

cr | a cairo context |
dx | X component of a distance vector (in/out parameter) |
dy | Y component of a distance vector (in/out parameter) |

Since: 1.0

## See Also

cairo_matrix_t