cairomm: Cairo::Matrix Class Reference

Public Member Functions | Related Functions

# Cairo::Matrix Class Reference

A Transformation matrix. More...

Inherits cairo_matrix_t.

List of all members.

## Public Member Functions
| Matrix ()
| Creates an uninitialized matrix.
| Matrix (double xx, double yx, double xy, double yy, double x0, double y0)
| Creates a matrix Sets to be the affine transformation given by xx, yx, xy, yy, x0, y0.
void | translate (double tx, double ty)
| Applies a translation by tx, ty to the transformation in matrix.
void | scale (double sx, double sy)
| Applies scaling by sx, sy to the transformation in matrix.
void | rotate (double radians)
| Applies rotation by radians to the transformation in matrix.
void | invert ()
| Changes matrix to be the inverse of it's original value.
void | multiply (Matrix& a, Matrix& b)
| Multiplies the affine transformations in a and b together and stores the result in this matrix.
void | transform_distance (double& dx, double& dy) const
| Transforms the distance vector (dx,dy) by matrix.
void | transform_point (double& x, double& y) const
| Transforms the point (x, y) by this matrix.
## Related Functions
(Note that these are not member functions.)
Matrix | identity_matrix ()
| Returns a Matrix initialized to the identity matrix.
Matrix | translation_matrix (double tx, double ty)
| Returns a Matrix initialized to a transformation that translates by tx and ty in the X and Y dimensions, respectively.
Matrix | scaling_matrix (double sx, double sy)
| Returns a Matrix initialized to a transformation that scales by sx and sy in the X and Y dimensions, respectively.
Matrix | rotation_matrix (double radians)
| Returns a Matrix initialized to a transformation that rotates by radians.
Matrix | operator* (const Matrix& a, const Matrix& b)
| Multiplies the affine transformations in a and b together and returns the result.

## Detailed Description

A Transformation matrix.

Cairo::Matrix is used throughout cairomm to convert between different coordinate spaces. A Matrix 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 Context, represented as a Matrix, defines the transformation from user-space coordinates to device-space coordinates.

See also:
  Context::get_matrix()
  Context::set_matrix()

## Constructor & Destructor Documentation

Cairo::Matrix::Matrix | ( |  | ) |

Creates an uninitialized matrix.

If you want a matrix initialized to a certain value, either specify the values explicitly with the other constructor or use one of the free functions for initializing matrices with specific scales, rotations, etc.

See also:
  identity_matrix()
  rotation_matrix()
  translation_matrix()
  scaling_matrix()

Cairo::Matrix::Matrix | ( | double | xx,
|  | double | yx,
|  | double | xy,
|  | double | yy,
|  | double | x0,
|  | double | y0 |
| ) |  |  |

Creates a matrix Sets 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:

  | 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

## Member Function Documentation

void Cairo::Matrix::invert | ( |  | ) |

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 throw an exception.

void Cairo::Matrix::multiply | ( | Matrix& | a,
|  | Matrix& | b |
| ) |  |  |

Multiplies the affine transformations in a and b together and stores the result in this matrix.

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:

  | a | a Matrix
  | b | a Matrix

See also:
  operator*()

void Cairo::Matrix::rotate | ( | 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:

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

void Cairo::Matrix::scale | ( | 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:

  | sx | scale factor in the X direction
  | sy | scale factor in the Y direction

void Cairo::Matrix::transform_distance | ( | double & | dx,
|  | double & | dy |
| ) |  |  | const

Transforms the distance vector (dx,dy) by matrix.

This is similar to 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:

  | dx | X component of a distance vector. An in/out parameter
  | dy | Y component of a distance vector. An in/out parameter

void Cairo::Matrix::transform_point | ( | double & | x,
|  | double & | y |
| ) |  |  | const

Transforms the point (x, y) by this matrix.

Parameters:

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

void Cairo::Matrix::translate | ( | 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:

  | tx | amount to translate in the X direction
  | ty | amount to translate in the Y direction

## Friends And Related Function Documentation

Matrix identity_matrix | ( |  | ) | `[related]`

Returns a Matrix initialized to the identity matrix.

Matrix operator* | ( | const Matrix& | a,
|  | const Matrix& | b |
| ) |  |  | `[related]`

Multiplies the affine transformations in a and b together and returns the 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:

  | a | a Matrix
  | b | a Matrix

Matrix rotation_matrix | ( | double | radians | ) | `[related]`

Returns a Matrix initialized to a transformation that rotates by radians.

Parameters:

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

Matrix scaling_matrix | ( | double | sx,
|  | double | sy |
| ) |  |  | `[related]`

Returns a Matrix initialized to a transformation that scales by sx and sy in the X and Y dimensions, respectively.

Parameters:

  | sx | scale factor in the X direction
  | sy | scale factor in the Y direction

Matrix translation_matrix | ( | double | tx,
|  | double | ty |
| ) |  |  | `[related]`

Returns a Matrix initialized to a transformation that translates by tx and ty in the X and Y dimensions, respectively.

Parameters:

  | tx | amount to translate in the X direction
  | ty | amount to translate in the Y direction

The documentation for this class was generated from the following file:

- cairomm/matrix.h