Module org.freedesktop.cairo

Package org.freedesktop.cairo

Class Matrix

java.lang.Object

io.github.jwharm.cairobindings.Proxy

org.freedesktop.cairo.Matrix

public class Matrix
extends Proxy

Generic matrix operations.

Matrix is used throughout cairo 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:

 xNew = xx * x + xy * y + x0;
 yNew = 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 Context.getMatrix(org.freedesktop.cairo.Matrix) and Context.setMatrix(Matrix).

Since:

1.0

Constructor Summary

Constructors

Constructor	Description
Matrix(MemorySegment address)	Constructor used internally to instantiate a java Matrix object for a native cairo_matrix_t instance

Method Summary

Modifier and Type	Method	Description
static Matrix	create(Arena arena)	Allocate a new, uninitialized caio_matrix_t
Matrix	init(double xx, double yx, double xy, double yy, double x0, double y0)	Sets the matrix to be the affine transformation given by xx, yx, xy, yy, x0, y0.
Matrix	initIdentity()	Modifies the matrix to be an identity transformation.
Matrix	initTranslate(double tx, double ty)	Initializes the matrix to a transformation that translates by tx and ty in the X and Y dimensions, respectively.
void	invert()	Changes the matrix to be the inverse of its original value.
void	multiply(Matrix a, Matrix b)	Multiplies the affine transformations in this matrix and the provided matrix together and stores the result in the resulting matrix.
void	rotate(double radians)	Applies rotation by radians to the transformation in the matrix.
void	scale(double sx, double sy)	Applies scaling by sx, sy to the transformation in the matrix.
String	toString()	String representation of this Matrix
Point	transformDistance(Point distanceVector)	Transforms the distance vector (dx, dy) by the matrix.
Point	transformPoint(Point point)	Transforms the point (x, y) by the matrix.
void	translate(double tx, double ty)	Applies a translation by tx, ty to the transformation in the matrix.
double	x0()	Get the x0 value of the Matrix
double	xx()	Get the xx value of the Matrix
double	xy()	Get the xy value of the Matrix
double	y0()	Get the y0 value of the Matrix
double	yx()	Get the yx value of the Matrix
double	yy()	Get the yy value of the Matrix

Methods inherited from class io.github.jwharm.cairobindings.Proxy

equals, handle, hashCode

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Details

Matrix

public Matrix(MemorySegment address)

Constructor used internally to instantiate a java Matrix object for a native cairo_matrix_t instance

Parameters:

address - the memory address of the native cairo_matrix_t instance

Method Details

xx

public double xx()

Get the xx value of the Matrix

Returns:

the xx value

yx

public double yx()

Get the yx value of the Matrix

Returns:

the yx value

xy

public double xy()

Get the xy value of the Matrix

Returns:

the xy value

yy

public double yy()

Get the yy value of the Matrix

Returns:

the yy value

x0

public double x0()

Get the x0 value of the Matrix

Returns:

the x0 value

y0

public double y0()

Get the y0 value of the Matrix

Returns:

the y0 value

create

public static Matrix create(Arena arena)

Allocate a new, uninitialized caio_matrix_t

Parameters:

arena - the arena in which the Matrix will be allocated

Returns:

the newly allocated, uninitialized Matrix object

init

public Matrix init(double xx,
 double yx,
 double xy,
 double yy,
 double x0,
 double y0)

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

 xNew = xx * x + xy * y + x0;
 yNew = 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

Returns:

the resulting Matrix

Since:

1.0

initIdentity

public Matrix initIdentity()

Modifies the matrix to be an identity transformation.

Returns:

the matrix

Since:

1.0

initTranslate

public Matrix initTranslate(double tx,
 double ty)

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

Returns:

the matrix

Since:

1.0

translate

public void translate(double tx,
 double ty)

Applies a translation by tx, ty to the transformation in the 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

Since:

1.0

scale

public void scale(double sx,
 double sy)

Applies scaling by sx, sy to the transformation in the 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 X direction

Since:

1.0

rotate

public void rotate(double radians)

Applies rotation by radians to the transformation in the 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.

Since:

1.0

invert

public void invert()
            throws IllegalArgumentException

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

Throws:

IllegalArgumentException - if the matrix has no inverse. See Status.INVALID_MATRIX.

multiply

public void multiply(Matrix a,
 Matrix b)

Multiplies the affine transformations in this matrix and the provided matrix together and stores the result in the resulting 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 the resulting matrix to be identical to either a or b.

Parameters:

a - a matrix

b - a matrix

Since:

1.0

transformDistance

public Point transformDistance(Point distanceVector)

Transforms the distance vector (dx, dy) by the matrix. This is similar to transformPoint(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;
 

Parameters:

distanceVector - X and Y component of a distance vector

Returns:

the transformed X and Y component

Since:

1.0

transformPoint

public Point transformPoint(Point point)

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

Parameters:

point - X and Y position

Returns:

the transformed X and Y position

Since:

1.0

toString

public String toString()

String representation of this Matrix

Overrides:

toString in class Object

Returns:

a String representation of this Matrix