jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: cairo_matrix_t: Cairo: A Vector Graphics Library jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68:
jpayne@68:
jpayne@68:
jpayne@68: jpayne@68: jpayne@68:
jpayne@68:

cairo_matrix_t

jpayne@68:

cairo_matrix_t — Generic matrix operations

jpayne@68:
jpayne@68:
jpayne@68:

Functions

jpayne@68:
jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68:
jpayne@68: void jpayne@68: jpayne@68: cairo_matrix_init () jpayne@68:
jpayne@68: void jpayne@68: jpayne@68: cairo_matrix_init_identity () jpayne@68:
jpayne@68: void jpayne@68: jpayne@68: cairo_matrix_init_translate () jpayne@68:
jpayne@68: void jpayne@68: jpayne@68: cairo_matrix_init_scale () jpayne@68:
jpayne@68: void jpayne@68: jpayne@68: cairo_matrix_init_rotate () jpayne@68:
jpayne@68: void jpayne@68: jpayne@68: cairo_matrix_translate () jpayne@68:
jpayne@68: void jpayne@68: jpayne@68: cairo_matrix_scale () jpayne@68:
jpayne@68: void jpayne@68: jpayne@68: cairo_matrix_rotate () jpayne@68:
jpayne@68: cairo_status_t jpayne@68: jpayne@68: cairo_matrix_invert () jpayne@68:
jpayne@68: void jpayne@68: jpayne@68: cairo_matrix_multiply () jpayne@68:
jpayne@68: void jpayne@68: jpayne@68: cairo_matrix_transform_distance () jpayne@68:
jpayne@68: void jpayne@68: jpayne@68: cairo_matrix_transform_point () jpayne@68:
jpayne@68:
jpayne@68:
jpayne@68:

Types and Values

jpayne@68:
jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68:
 cairo_matrix_t
jpayne@68:
jpayne@68:
jpayne@68:

Description

jpayne@68:

cairo_matrix_t is used throughout cairo to convert between different jpayne@68: coordinate spaces. A cairo_matrix_t holds an affine transformation, jpayne@68: such as a scale, rotation, shear, or a combination of these. jpayne@68: The transformation of a point (x,y) jpayne@68: is given by:

jpayne@68:
jpayne@68: x_new = xx * x + xy * y + x0;
jpayne@68: y_new = yx * x + yy * y + y0;
jpayne@68: 
jpayne@68:

The current transformation matrix of a cairo_t, represented as a jpayne@68: cairo_matrix_t, defines the transformation from user-space jpayne@68: coordinates to device-space coordinates. See cairo_get_matrix() and jpayne@68: cairo_set_matrix().

jpayne@68:
jpayne@68:
jpayne@68:

Functions

jpayne@68:
jpayne@68:

cairo_matrix_init ()

jpayne@68:
void
jpayne@68: cairo_matrix_init (cairo_matrix_t *matrix,
jpayne@68:                    double xx,
jpayne@68:                    double yx,
jpayne@68:                    double xy,
jpayne@68:                    double yy,
jpayne@68:                    double x0,
jpayne@68:                    double y0);
jpayne@68:

Sets matrix jpayne@68: to be the affine transformation given by jpayne@68: xx jpayne@68: , yx jpayne@68: , xy jpayne@68: , yy jpayne@68: , x0 jpayne@68: , y0 jpayne@68: . The transformation is given jpayne@68: by:

jpayne@68:
jpayne@68:  x_new = xx * x + xy * y + x0;
jpayne@68:  y_new = yx * x + yy * y + y0;
jpayne@68: 
jpayne@68:
jpayne@68:

Parameters

jpayne@68:
jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68:

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

 
jpayne@68:
jpayne@68:

Since: 1.0

jpayne@68:
jpayne@68:
jpayne@68:
jpayne@68:

cairo_matrix_init_identity ()

jpayne@68:
void
jpayne@68: cairo_matrix_init_identity (cairo_matrix_t *matrix);
jpayne@68:

Modifies matrix jpayne@68: to be an identity transformation.

jpayne@68:
jpayne@68:

Parameters

jpayne@68:
jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68:

matrix

a cairo_matrix_t

 
jpayne@68:
jpayne@68:

Since: 1.0

jpayne@68:
jpayne@68:
jpayne@68:
jpayne@68:

cairo_matrix_init_translate ()

jpayne@68:
void
jpayne@68: cairo_matrix_init_translate (cairo_matrix_t *matrix,
jpayne@68:                              double tx,
jpayne@68:                              double ty);
jpayne@68:

Initializes matrix jpayne@68: to a transformation that translates by tx jpayne@68: and jpayne@68: ty jpayne@68: in the X and Y dimensions, respectively.

jpayne@68:
jpayne@68:

Parameters

jpayne@68:
jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68:

matrix

a cairo_matrix_t

 

tx

amount to translate in the X direction

 

ty

amount to translate in the Y direction

 
jpayne@68:
jpayne@68:

Since: 1.0

jpayne@68:
jpayne@68:
jpayne@68:
jpayne@68:

cairo_matrix_init_scale ()

jpayne@68:
void
jpayne@68: cairo_matrix_init_scale (cairo_matrix_t *matrix,
jpayne@68:                          double sx,
jpayne@68:                          double sy);
jpayne@68:

Initializes matrix jpayne@68: to a transformation that scales by sx jpayne@68: and sy jpayne@68: jpayne@68: in the X and Y dimensions, respectively.

jpayne@68:
jpayne@68:

Parameters

jpayne@68:
jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68:

matrix

a cairo_matrix_t

 

sx

scale factor in the X direction

 

sy

scale factor in the Y direction

 
jpayne@68:
jpayne@68:

Since: 1.0

jpayne@68:
jpayne@68:
jpayne@68:
jpayne@68:

cairo_matrix_init_rotate ()

jpayne@68:
void
jpayne@68: cairo_matrix_init_rotate (cairo_matrix_t *matrix,
jpayne@68:                           double radians);
jpayne@68:

Initialized matrix jpayne@68: to a transformation that rotates by radians jpayne@68: .

jpayne@68:
jpayne@68:

Parameters

jpayne@68:
jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68:

matrix

a cairo_matrix_t

 

radians

angle of rotation, in radians. The direction of rotation jpayne@68: is defined such that positive angles rotate in the direction from jpayne@68: the positive X axis toward the positive Y axis. With the default jpayne@68: axis orientation of cairo, positive angles rotate in a clockwise jpayne@68: direction.

 
jpayne@68:
jpayne@68:

Since: 1.0

jpayne@68:
jpayne@68:
jpayne@68:
jpayne@68:

cairo_matrix_translate ()

jpayne@68:
void
jpayne@68: cairo_matrix_translate (cairo_matrix_t *matrix,
jpayne@68:                         double tx,
jpayne@68:                         double ty);
jpayne@68:

Applies a translation by tx jpayne@68: , ty jpayne@68: to the transformation in jpayne@68: matrix jpayne@68: . The effect of the new transformation is to first translate jpayne@68: the coordinates by tx jpayne@68: and ty jpayne@68: , then apply the original transformation jpayne@68: to the coordinates.

jpayne@68:
jpayne@68:

Parameters

jpayne@68:
jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68:

matrix

a cairo_matrix_t

 

tx

amount to translate in the X direction

 

ty

amount to translate in the Y direction

 
jpayne@68:
jpayne@68:

Since: 1.0

jpayne@68:
jpayne@68:
jpayne@68:
jpayne@68:

cairo_matrix_scale ()

jpayne@68:
void
jpayne@68: cairo_matrix_scale (cairo_matrix_t *matrix,
jpayne@68:                     double sx,
jpayne@68:                     double sy);
jpayne@68:

Applies scaling by sx jpayne@68: , sy jpayne@68: to the transformation in matrix jpayne@68: . The jpayne@68: effect of the new transformation is to first scale the coordinates jpayne@68: by sx jpayne@68: and sy jpayne@68: , then apply the original transformation to the coordinates.

jpayne@68:
jpayne@68:

Parameters

jpayne@68:
jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68:

matrix

a cairo_matrix_t

 

sx

scale factor in the X direction

 

sy

scale factor in the Y direction

 
jpayne@68:
jpayne@68:

Since: 1.0

jpayne@68:
jpayne@68:
jpayne@68:
jpayne@68:

cairo_matrix_rotate ()

jpayne@68:
void
jpayne@68: cairo_matrix_rotate (cairo_matrix_t *matrix,
jpayne@68:                      double radians);
jpayne@68:

Applies rotation by radians jpayne@68: to the transformation in jpayne@68: matrix jpayne@68: . The effect of the new transformation is to first rotate the jpayne@68: coordinates by radians jpayne@68: , then apply the original transformation jpayne@68: to the coordinates.

jpayne@68:
jpayne@68:

Parameters

jpayne@68:
jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68:

matrix

a cairo_matrix_t

 

radians

angle of rotation, in radians. The direction of rotation jpayne@68: is defined such that positive angles rotate in the direction from jpayne@68: the positive X axis toward the positive Y axis. With the default jpayne@68: axis orientation of cairo, positive angles rotate in a clockwise jpayne@68: direction.

 
jpayne@68:
jpayne@68:

Since: 1.0

jpayne@68:
jpayne@68:
jpayne@68:
jpayne@68:

cairo_matrix_invert ()

jpayne@68:
cairo_status_t
jpayne@68: cairo_matrix_invert (cairo_matrix_t *matrix);
jpayne@68:

Changes matrix jpayne@68: to be the inverse of its original value. Not jpayne@68: all transformation matrices have inverses; if the matrix jpayne@68: collapses points together (it is degenerate), jpayne@68: then it has no inverse and this function will fail.

jpayne@68:
jpayne@68:

Parameters

jpayne@68:
jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68:

matrix

a cairo_matrix_t

 
jpayne@68:
jpayne@68:
jpayne@68:

Returns

jpayne@68:

If matrix jpayne@68: has an inverse, modifies matrix jpayne@68: to jpayne@68: be the inverse matrix and returns CAIRO_STATUS_SUCCESS. Otherwise, jpayne@68: returns CAIRO_STATUS_INVALID_MATRIX.

jpayne@68:
jpayne@68:

Since: 1.0

jpayne@68:
jpayne@68:
jpayne@68:
jpayne@68:

cairo_matrix_multiply ()

jpayne@68:
void
jpayne@68: cairo_matrix_multiply (cairo_matrix_t *result,
jpayne@68:                        const cairo_matrix_t *a,
jpayne@68:                        const cairo_matrix_t *b);
jpayne@68:

Multiplies the affine transformations in a jpayne@68: and b jpayne@68: together jpayne@68: and stores the result in result jpayne@68: . The effect of the resulting jpayne@68: transformation is to first apply the transformation in a jpayne@68: to the jpayne@68: coordinates and then apply the transformation in b jpayne@68: to the jpayne@68: coordinates.

jpayne@68:

It is allowable for result jpayne@68: to be identical to either a jpayne@68: or b jpayne@68: .

jpayne@68:
jpayne@68:

Parameters

jpayne@68:
jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68:

result

a cairo_matrix_t in which to store the result

 

a

a cairo_matrix_t

 

b

a cairo_matrix_t

 
jpayne@68:
jpayne@68:

Since: 1.0

jpayne@68:
jpayne@68:
jpayne@68:
jpayne@68:

cairo_matrix_transform_distance ()

jpayne@68:
void
jpayne@68: cairo_matrix_transform_distance (const cairo_matrix_t *matrix,
jpayne@68:                                  double *dx,
jpayne@68:                                  double *dy);
jpayne@68:

Transforms the distance vector (dx jpayne@68: ,dy jpayne@68: ) by matrix jpayne@68: . This is jpayne@68: similar to cairo_matrix_transform_point() except that the translation jpayne@68: components of the transformation are ignored. The calculation of jpayne@68: the returned vector is as follows:

jpayne@68:
jpayne@68: dx2 = dx1 * a + dy1 * c;
jpayne@68: dy2 = dx1 * b + dy1 * d;
jpayne@68: 
jpayne@68:

Affine transformations are position invariant, so the same vector jpayne@68: always transforms to the same vector. If (x1 jpayne@68: ,y1 jpayne@68: ) transforms jpayne@68: to (x2 jpayne@68: ,y2 jpayne@68: ) then (x1 jpayne@68: +dx1 jpayne@68: ,y1 jpayne@68: +dy1 jpayne@68: ) will transform to jpayne@68: (x1 jpayne@68: +dx2 jpayne@68: ,y1 jpayne@68: +dy2 jpayne@68: ) for all values of x1 jpayne@68: and x2 jpayne@68: .

jpayne@68:
jpayne@68:

Parameters

jpayne@68:
jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68:

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

 
jpayne@68:
jpayne@68:

Since: 1.0

jpayne@68:
jpayne@68:
jpayne@68:
jpayne@68:

cairo_matrix_transform_point ()

jpayne@68:
void
jpayne@68: cairo_matrix_transform_point (const cairo_matrix_t *matrix,
jpayne@68:                               double *x,
jpayne@68:                               double *y);
jpayne@68:

Transforms the point (x jpayne@68: , y jpayne@68: ) by matrix jpayne@68: .

jpayne@68:
jpayne@68:

Parameters

jpayne@68:
jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68:

matrix

a cairo_matrix_t

 

x

X position. An in/out parameter

 

y

Y position. An in/out parameter

 
jpayne@68:
jpayne@68:

Since: 1.0

jpayne@68:
jpayne@68:
jpayne@68:
jpayne@68:

Types and Values

jpayne@68:
jpayne@68:

cairo_matrix_t

jpayne@68:
typedef struct {
jpayne@68:     double xx; double yx;
jpayne@68:     double xy; double yy;
jpayne@68:     double x0; double y0;
jpayne@68: } cairo_matrix_t;
jpayne@68: 
jpayne@68:

A cairo_matrix_t holds an affine transformation, such as a scale, jpayne@68: rotation, shear, or a combination of those. The transformation of jpayne@68: a point (x, y) is given by:

jpayne@68:
jpayne@68:     x_new = xx * x + xy * y + x0;
jpayne@68:     y_new = yx * x + yy * y + y0;
jpayne@68: 
jpayne@68:
jpayne@68:

Members

jpayne@68:
jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68:

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

 
jpayne@68:
jpayne@68:

Since: 1.0

jpayne@68:
jpayne@68:
jpayne@68:
jpayne@68:

See Also

jpayne@68:

cairo_t

jpayne@68:
jpayne@68:
jpayne@68: jpayne@68: jpayne@68: