Next: , Previous: Patterns, Up: Top


4 Transformations

Manipulating the current transformation matrix

4.1 Overview

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.

4.2 Usage

— Function: cairo-translate (cr <cairo-t>) (tx <double>) (ty <double>)

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.

cr
a cairo context
tx
amount to translate in the X direction
ty
amount to translate in the Y direction
— Function: cairo-scale (cr <cairo-t>) (sx <double>) (sy <double>)

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.

cr
a cairo context
sx
scale factor for the X dimension
sy
scale factor for the Y dimension
— Function: cairo-rotate (cr <cairo-t>) (angle <double>)

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.

cr
a cairo context
angle
angle (in radians) by which the user-space axes will be rotated
— Function: cairo-transform (cr <cairo-t>) (matrix <cairo-matrix-t>)

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.

cr
a cairo context
matrix
a transformation to be applied to the user-space axes
— Function: cairo-set-matrix (cr <cairo-t>) (matrix <cairo-matrix-t>)

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

cr
a cairo context
matrix
a transformation matrix from user space to device space
— Function: cairo-get-matrix (cr <cairo-t>) (matrix <cairo-matrix-t>)

Stores the current transformation matrix (CTM) into matrix.

cr
a cairo context
matrix
return value for the matrix
— Function: cairo-identity-matrix (cr <cairo-t>)

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.

cr
a cairo context
— Function: cairo-user-to-device (cr <cairo-t>) ⇒  (<double>) (<double>)

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

cr
a cairo context
x
X value of coordinate (in/out parameter)
y
Y value of coordinate (in/out parameter)
— Function: cairo-user-to-device-distance (cr <cairo-t>) ⇒  (dx <double>) (dy <double>)

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

cr
a cairo context
dx
X component of a distance vector (in/out parameter)
dy
Y component of a distance vector (in/out parameter)
— Function: cairo-device-to-user (cr <cairo-t>) ⇒  (<double>) (<double>)

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

cr
a cairo
x
X value of coordinate (in/out parameter)
y
Y value of coordinate (in/out parameter)
— Function: cairo-device-to-user-distance (cr <cairo-t>) ⇒  (dx <double>) (dy <double>)

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

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