xtd::drawing::drawing_2d::matrix Class Reference

Definition

Encapsulates a 3-by-3 affine matrix that represents a geometric transform. This class cannot be inherited.

class drawing_export_ matrix final : public object

Inheritance

xtd::object → xtd::drawing::drawing_2d/::matrix

Namespace

xtd::drawing::drawing_2d/

Library

xtd.drawing

Remarks

In GDI+ you can store an affine transformation in a xtd::drawing::drawing_2d/::matrix object. Because the third column of a matrix that represents an affine transformation is always (0, 0, 1), you specify only the six numbers in the first two columns when you construct a xtd::drawing::drawing_2d/::matrix object. The statement xtd::drawing::drawing_2d/::matrix myMatrix = new xtd::drawing::drawing_2d/::matrix(0, 1, -1, 0, 3, 4) constructs the matrix shown in the following figure.

Composite Transformations

A composite transformation is a sequence of transformations, one followed by the other. Consider the matrices and transformations in the following list:

matrix A

Rotate 90 degrees

matrix B

Scale by a factor of 2 in the x direction

matrix C

Translate 3 units in the y direction </tbody>

If we start with the point (2, 1) - represented by the matrix [2 1 1] - and multiply by A, then B, then C, the point (2, 1) will undergo the three transformations in the order listed.

[2 1 1]ABC = [-2 5 1]

Rather than store the three parts of the composite transformation in three separate matrices, you can multiply A, B, and C together to get a single 3×3 matrix that stores the entire composite transformation. Suppose ABC = D. Then a point multiplied by D gives the same result as a point multiplied by A, then B, then C.

[2 1 1]D = [-2 5 1]

The following illustration shows the matrices A, B, C, and D.

The fact that the matrix of a composite transformation can be formed by multiplying the individual transformation matrices means that any sequence of affine transformations can be stored in a single xtd::drawing::drawing_2d/::matrix object. Caution: The order of a composite transformation is important. In general, rotate, then scale, then translate is not the same as scale, then rotate, then translate. Similarly, the order of matrix multiplication is important. In general, ABC is not the same as BAC.

The xtd::drawing::drawing_2d/::matrix class provides several methods for building a composite transformation: xtd::drawing::drawing_2d/matrix::multiply, xtd::drawing::drawing_2d/::matrix::rotate, xtd::drawing::drawing_2d/::matrix::rotate_at, xtd::drawing::drawing_2d/::matrix::scale, xtd::drawing::drawing_2d/::matrix::shear, and xtd::drawing::drawing_2d/::matrix::translate. The following example creates the matrix of a composite transformation that first rotates 30 degrees, then scales by a factor of 2 in the y direction, and then translates 5 units in the x direction:

matrix my_matrix;
my_matrix.rotate(30);
my_matrix.scale(1, 2, matrix_order::append);
my_matrix.translate(5, 0, matrix_order::append);

Constructors
	matrix ()
	Initializes a new instance of the xtd::drawing::drawing_2d/::matrix class as the identity matrix. More...
	matrix (float m11, float m12, float m21, float m22, float dx, float dy)
	Initializes a new instance of the xtd::drawing::drawing_2d/::matrix class with the specified elements. More...
	matrix (const xtd::drawing::rectangle &rect, const std::vector< xtd::drawing::point > &plgpts)
	Initializes a new instance of the xtd::drawing::drawing_2d/::matrix class to the geometric transform defined by the specified rectangle and array of points. More...
	matrix (const xtd::drawing::rectangle_f &rect, const std::vector< xtd::drawing::point_f > &plgpts)
	Initializes a new instance of the xtd::drawing::drawing_2d/::matrix class to the geometric transform defined by the specified rectangle and array of points. More...

Properties
std::vector< float >	elements () const
	Gets an array of floating-point values that represents the elements of this xtd::drawing::drawing_2d/::matrix. More...
intptr	handle () const noexcept
	Gets the handle of the matrix. More...
bool	is_identity () const
	Gets a value indicating whether this xtd::drawing::drawing_2d/::matrix is the identity matrix. More...
bool	is_invertible () const
	Gets a value indicating whether this xtd::drawing::drawing_2d/::matrix is invertible. More...
float	offset_x () const
	Gets the x translation value (the dx value, or the element in the third row and first column) of this xtd::drawing::drawing_2d/::matrix. More...
float	offset_y () const
	Gets the y translation value (the dy value, or the element in the third row and second column) of this xtd::drawing::drawing_2d/::matrix. More...

Methods
bool	equals (const xtd::drawing::drawing_2d::matrix &value) const noexcept override
void	invert ()
	Inverts this xtd::drawing::drawing_2d/::matrix, if it is invertible. More...
void	multiply (const xtd::drawing::drawing_2d::matrix &matrix)
	Multiplies this xtd::drawing::drawing_2d/::matrix by the matrix specified in the matrix parameter, by prepending the specified xtd::drawing::drawing_2d/::matrix. More...
void	multiply (const xtd::drawing::drawing_2d::matrix &matrix, xtd::drawing::drawing_2d::matrix_order order)
	Multiplies this xtd::drawing::drawing_2d/::matrix by the matrix specified in the matrix parameter, and in the order specified in the order parameter. More...
void	reset ()
	Resets this xtd::drawing::drawing_2d/::matrix to have the elements of the identity matrix. More...
void	rotate (float angle)
	repend to this xtd::drawing::drawing_2d/::matrix a clockwise rotation, around the origin and by the specified angle. More...
void	rotate (float angle, xtd::drawing::drawing_2d::matrix_order order)
	Applies a clockwise rotation of an amount specified in the angle parameter, around the origin (zero x and y coordinates) for this xtd::drawing::drawing_2d/::matrix. More...
void	rotate_at (float angle, const xtd::drawing::point_f &point)
	Applies a clockwise rotation to this xtd::drawing::drawing_2d/::matrix around the point specified in the point parameter, and by prepending the rotation. More...
void	rotate_at (float angle, const xtd::drawing::point_f &point, xtd::drawing::drawing_2d::matrix_order order)
	Applies a clockwise rotation about the specified point to this xtd::drawing::drawing_2d/::matrix in the specified order. More...
void	scale (float scale_x, float scale_y)
	Applies the specified scale vector to this xtd::drawing::drawing_2d/::matrix by prepending the scale vector. More...
void	scale (float scale_x, float scale_y, xtd::drawing::drawing_2d::matrix_order order)
	Applies the specified scale vector (scale_x and scale_y) to this xtd::drawing::drawing_2d/::matrix using the specified order. More...
void	shear (float scale_x, float scale_y)
	Applies the specified shear vector to this xtd::drawing::drawing_2d/::matrix. More...
void	shear (float scale_x, float scale_y, xtd::drawing::drawing_2d::matrix_order order)
	Applies the specified shear vector to this xtd::drawing::drawing_2d/::matrix in the specified order. More...
void	transform_points (std::vector< xtd::drawing::point > &points)
	Applies the geometric transform represented by this xtd::drawing::drawing_2d/::matrix to a specified array of points. More...
void	transform_points (std::vector< xtd::drawing::point_f > &points)
	Applies the geometric transform represented by this xtd::drawing::drawing_2d/::matrix to a specified array of points. More...
void	transform_vectors (std::vector< xtd::drawing::point > &points)
	Applies only the scale and rotate components of this xtd::drawing::drawing_2d/::matrix to the specified array of points. More...
void	transform_vectors (std::vector< xtd::drawing::point_f > &points)
	Applies only the scale and rotate components of this xtd::drawing::drawing_2d/::matrix to the specified array of points. More...
void	translate (float offset_x, float offset_y)
	Applies the specified translation vector (offset_x and offset_y) to this xtd::drawing::drawing_2d/::matrix by prepending the translation vector. More...
void	translate (float offset_x, float offset_y, xtd::drawing::drawing_2d::matrix_order order)
	Applies the specified translation vector (offset_x and offset_y) to this xtd::drawing::drawing_2d/::matrix in the specified order. More...
void	vector_transform_points (std::vector< xtd::drawing::point > &points)
	Multiplies each vector in an array by the matrix. The translation elements of this matrix (third row) are ignored. More...
xtd::ustring	to_string () const noexcept override
	Returns a sxd::ustring that represents the current object. More...

Additional Inherited Members
Public Member Functions inherited from xtd::object
	object ()=default
	Create a new instance of the ultimate base class object. More...
bool	equals (const object &obj) const noexcept
	Determines whether the specified object is equal to the current object. More...
virtual size_t	get_hash_code () const noexcept
	Serves as a hash function for a particular type. More...
virtual type_object	get_type () const noexcept
	Gets the type of the current instance. More...
template<typename object_t >
std::unique_ptr< object_t >	memberwise_clone () const noexcept
	Creates a shallow copy of the current object. More...
Public Member Functions inherited from xtd::iequatable< matrix >
virtual bool	equals (const matrix &) const noexcept=0
	Indicates whether the current object is equal to another object of the same type. More...
Static Public Member Functions inherited from xtd::object
static bool	equals (const object &object_a, const object &object_b) noexcept
	Determines whether the specified object instances are considered equal. More...
static bool	reference_equals (const object &object_a, const object &object_b) noexcept
	Determines whether the specified object instances are the same instance. More...

Constructor & Destructor Documentation

matrix() [1/4]

xtd::drawing::drawing_2d::matrix::matrix

(

)

Initializes a new instance of the xtd::drawing::drawing_2d/::matrix class as the identity matrix.

matrix() [2/4]

xtd::drawing::drawing_2d::matrix::matrix	(	float	m11,
		float	m12,
		float	m21,
		float	m22,
		float	dx,
		float	dy
	)

Initializes a new instance of the xtd::drawing::drawing_2d/::matrix class with the specified elements.

Parameters

m11	The value in the first row and first column of the new xtd::drawing::drawing_2d/::matrix.
m12	The value in the first row and second column of the new xtd::drawing::drawing_2d/::matrix.
m21	The value in the second row and first column of the new xtd::drawing::drawing_2d/::matrix.
m22	The value in the second row and second column of the new xtd::drawing::drawing_2d/::matrix.
dx	The value in the third row and first column of the new xtd::drawing::drawing_2d/::matrix.
dy	The value in the third row and second column of the new xtd::drawing::drawing_2d/::matrix.

matrix() [3/4]

xtd::drawing::drawing_2d::matrix::matrix	(	const xtd::drawing::rectangle &	rect,
		const std::vector< xtd::drawing::point > &	plgpts
	)

Initializes a new instance of the xtd::drawing::drawing_2d/::matrix class to the geometric transform defined by the specified rectangle and array of points.

Parameters

rect	A xtd::drawing::rectangle structure that represents the rectangle to be transformed.
plgpts	An array of three xtd::drawing::point structures that represents the points of a parallelogram to which the upper-left, upper-right, and lower-left corners of the rectangle is to be transformed. The lower-right corner of the parallelogram is implied by the first three corners.

Remarks

This method initializes the new xtd::drawing::drawing_2d/::matrix such that it represents the geometric transform that maps the rectangle specified by the rect parameter to the parallelogram defined by the three points in the plgpts parameter. The upper-left corner of the rectangle is mapped to the first point in the plgpts array, the upper-right corner is mapped to the second point, and the lower-left corner is mapped to the third point. The lower-right point of the parallelogram is implied by the first three.

matrix() [4/4]

xtd::drawing::drawing_2d::matrix::matrix	(	const xtd::drawing::rectangle_f &	rect,
		const std::vector< xtd::drawing::point_f > &	plgpts
	)

Initializes a new instance of the xtd::drawing::drawing_2d/::matrix class to the geometric transform defined by the specified rectangle and array of points.

Parameters

rect	A xtd::drawing::rectangle_f structure that represents the rectangle to be transformed.
plgpts	An array of three xtd::drawing::point_f structures that represents the points of a parallelogram to which the upper-left, upper-right, and lower-left corners of the rectangle is to be transformed. The lower-right corner of the parallelogram is implied by the first three corners.

Remarks

This method initializes the new xtd::drawing::drawing_2d/::matrix such that it represents the geometric transform that maps the rectangle specified by the rect parameter to the parallelogram defined by the three points in the plgpts parameter. The upper-left corner of the rectangle is mapped to the first point in the plgpts array, the upper-right corner is mapped to the second point, and the lower-left corner is mapped to the third point. The lower-right point of the parallelogram is implied by the first three.

Member Function Documentation

elements()

std::vector<float> xtd::drawing::drawing_2d::matrix::elements

(

)

const

Gets an array of floating-point values that represents the elements of this xtd::drawing::drawing_2d/::matrix.

Returns

An array of floating-point values that represents the elements of this xtd::drawing::drawing_2d/::matrix.

Remarks

The elements m11, m12, m21, m22, dx, and dy of the xtd::drawing::drawing_2d/::matrix are represented by the values in the array in that order.

handle()

intptr xtd::drawing::drawing_2d::matrix::handle ( ) const

noexcept

Gets the handle of the matrix.

Returns

An intptr that contains the handle of the matrix.

invert()

void xtd::drawing::drawing_2d::matrix::invert

(

)

Inverts this xtd::drawing::drawing_2d/::matrix, if it is invertible.

is_identity()

bool xtd::drawing::drawing_2d::matrix::is_identity

(

)

const

Gets a value indicating whether this xtd::drawing::drawing_2d/::matrix is the identity matrix.

Returns

This property is true if this xtd::drawing::drawing_2d/::matrix is identity; otherwise, false.

is_invertible()

bool xtd::drawing::drawing_2d::matrix::is_invertible

(

)

const

Gets a value indicating whether this xtd::drawing::drawing_2d/::matrix is invertible.

Returns

This property is true if this xtd::drawing::drawing_2d/::matrix is invertible; otherwise, false.

multiply() [1/2]

void xtd::drawing::drawing_2d::matrix::multiply

(

const xtd::drawing::drawing_2d::matrix &

matrix

)

Multiplies this xtd::drawing::drawing_2d/::matrix by the matrix specified in the matrix parameter, by prepending the specified xtd::drawing::drawing_2d/::matrix.

Parameters

matrix

The xtd::drawing::drawing_2d/::matrix by which this xtd::drawing::drawing_2d/::matrix is to be multiplied.

multiply() [2/2]

void xtd::drawing::drawing_2d::matrix::multiply	(	const xtd::drawing::drawing_2d::matrix &	matrix,
		xtd::drawing::drawing_2d::matrix_order	order
	)

Multiplies this xtd::drawing::drawing_2d/::matrix by the matrix specified in the matrix parameter, and in the order specified in the order parameter.

Parameters

matrix	The xtd::drawing::drawing_2d/::matrix by which this xtd::drawing::drawing_2d/::matrix is to be multiplied.
order	The xtd::drawing::drawing_2d/matrix_order that represents the order of the multiplication.

offset_x()

float xtd::drawing::drawing_2d::matrix::offset_x

(

)

const

Gets the x translation value (the dx value, or the element in the third row and first column) of this xtd::drawing::drawing_2d/::matrix.

Returns

The x translation value of this xtd::drawing::drawing_2d/::matrix.

offset_y()

float xtd::drawing::drawing_2d::matrix::offset_y

(

)

const

Gets the y translation value (the dy value, or the element in the third row and second column) of this xtd::drawing::drawing_2d/::matrix.

Returns

The y translation value of this xtd::drawing::drawing_2d/::matrix.

reset()

void xtd::drawing::drawing_2d::matrix::reset

(

)

Resets this xtd::drawing::drawing_2d/::matrix to have the elements of the identity matrix.

Remarks

The elements on the main diagonal of the identity matrix are 1. All other elements of the identity matrix are 0.

rotate() [1/2]

void xtd::drawing::drawing_2d::matrix::rotate

(

float

angle

)

repend to this xtd::drawing::drawing_2d/::matrix a clockwise rotation, around the origin and by the specified angle.

Parameters

angle

The angle of the rotation, in degrees.

rotate() [2/2]

void xtd::drawing::drawing_2d::matrix::rotate	(	float	angle,
		xtd::drawing::drawing_2d::matrix_order	order
	)

Applies a clockwise rotation of an amount specified in the angle parameter, around the origin (zero x and y coordinates) for this xtd::drawing::drawing_2d/::matrix.

Parameters

angle	The angle (extent) of the rotation, in degrees.
order	A xtd::drawing::drawing_2d/matrix_order that specifies the order (append or prepend) in which the rotation is applied to this xtd::drawing::drawing_2d/::matrix.

rotate_at() [1/2]

void xtd::drawing::drawing_2d::matrix::rotate_at	(	float	angle,
		const xtd::drawing::point_f &	point
	)

Applies a clockwise rotation to this xtd::drawing::drawing_2d/::matrix around the point specified in the point parameter, and by prepending the rotation.

Parameters

angle	The angle (extent) of the rotation, in degrees.
point	A xtd::drawing::point_f that represents the center of the rotation.

rotate_at() [2/2]

void xtd::drawing::drawing_2d::matrix::rotate_at	(	float	angle,
		const xtd::drawing::point_f &	point,
		xtd::drawing::drawing_2d::matrix_order	order
	)

Applies a clockwise rotation about the specified point to this xtd::drawing::drawing_2d/::matrix in the specified order.

Parameters

angle	The angle (extent) of the rotation, in degrees.
point	A xtd::drawing::point_f that represents the center of the rotation.
order	A xtd::drawing::drawing_2d/matrix_order that specifies the order (append or prepend) in which the rotation is applied.

scale() [1/2]

void xtd::drawing::drawing_2d::matrix::scale	(	float	scale_x,
		float	scale_y
	)

Applies the specified scale vector to this xtd::drawing::drawing_2d/::matrix by prepending the scale vector.

Parameters

scale_x	The value by which to scale this xtd::drawing::drawing_2d/::matrix in the x-axis direction.
scale_y	The value by which to scale this xtd::drawing::drawing_2d/::matrix in the y-axis direction.

scale() [2/2]

void xtd::drawing::drawing_2d::matrix::scale	(	float	scale_x,
		float	scale_y,
		xtd::drawing::drawing_2d::matrix_order	order
	)

Applies the specified scale vector (scale_x and scale_y) to this xtd::drawing::drawing_2d/::matrix using the specified order.

Parameters

scale_x	The value by which to scale this xtd::drawing::drawing_2d/::matrix in the x-axis direction.
scale_y	The value by which to scale this xtd::drawing::drawing_2d/::matrix in the y-axis direction.
order	A xtd::drawing::drawing_2d/matrix_order that specifies the order (append or prepend) in which the scale vector is applied to this xtd::drawing::drawing_2d/::matrix.

shear() [1/2]

void xtd::drawing::drawing_2d::matrix::shear	(	float	scale_x,
		float	scale_y
	)

Applies the specified shear vector to this xtd::drawing::drawing_2d/::matrix.

Parameters

scale_x	The horizontal shear factor.
scale_y	The vertical shear factor.

Remarks

The transformation applied in this method is a pure shear only if one of the parameters is 0. Applied to a rectangle at the origin, when the shear_y factor is 0, the transformation moves the bottom edge horizontally by shear_x times the height of the rectangle. When the shearX factor is 0, it moves the right edge vertically by shearY times the width of the rectangle. Caution is in order when both parameters are nonzero, because the results are hard to predict. For example, if both factors are 1, the transformation is singular (hence noninvertible), squeezing the entire plane to a single line.

shear() [2/2]

void xtd::drawing::drawing_2d::matrix::shear	(	float	scale_x,
		float	scale_y,
		xtd::drawing::drawing_2d::matrix_order	order
	)

Applies the specified shear vector to this xtd::drawing::drawing_2d/::matrix in the specified order.

Parameters

scale_x	The horizontal shear factor.
scale_y	The vertical shear factor.
order	A xtd::drawing::drawing_2d/matrix_order that specifies the order (append or prepend) in which the shear is applied.

Remarks

The transformation applied in this method is a pure shear only if one of the parameters is 0. Applied to a rectangle at the origin, when the shear_y factor is 0, the transformation moves the bottom edge horizontally by shear_x times the height of the rectangle. When the shearX factor is 0, it moves the right edge vertically by shearY times the width of the rectangle. Caution is in order when both parameters are nonzero, because the results are hard to predict. For example, if both factors are 1, the transformation is singular (hence noninvertible), squeezing the entire plane to a single line.

to_string()

xtd::ustring xtd::drawing::drawing_2d::matrix::to_string ( ) const

overridevirtualnoexcept

Returns a sxd::ustring that represents the current object.

Returns

A string that represents the current object.

Examples

The following code example demonstrates what to_string returns.

Reimplemented from xtd::object.

transform_points() [1/2]

void xtd::drawing::drawing_2d::matrix::transform_points

(

std::vector< xtd::drawing::point > &

points

)

Applies the geometric transform represented by this xtd::drawing::drawing_2d/::matrix to a specified array of points.

Parameters

points

An array of xtd::drawing::point structures that represents the points to transform.

transform_points() [2/2]

void xtd::drawing::drawing_2d::matrix::transform_points

(

std::vector< xtd::drawing::point_f > &

points

)

Applies the geometric transform represented by this xtd::drawing::drawing_2d/::matrix to a specified array of points.

Parameters

points

An array of xtd::drawing::point_f structures that represents the points to transform.

transform_vectors() [1/2]

void xtd::drawing::drawing_2d::matrix::transform_vectors

(

std::vector< xtd::drawing::point > &

points

)

Applies only the scale and rotate components of this xtd::drawing::drawing_2d/::matrix to the specified array of points.

Parameters

points

An array of xtd::drawing::point structures that represents the points to transform.

transform_vectors() [2/2]

void xtd::drawing::drawing_2d::matrix::transform_vectors

(

std::vector< xtd::drawing::point_f > &

points

)

Applies only the scale and rotate components of this xtd::drawing::drawing_2d/::matrix to the specified array of points.

Parameters

points

An array of xtd::drawing::point_f structures that represents the points to transform.

translate() [1/2]

void xtd::drawing::drawing_2d::matrix::translate	(	float	offset_x,
		float	offset_y
	)

Applies the specified translation vector (offset_x and offset_y) to this xtd::drawing::drawing_2d/::matrix by prepending the translation vector.

Parameters

offset_x	The x value by which to translate this xtd::drawing::drawing_2d/::matrix.
offset_y	The y value by which to translate this xtd::drawing::drawing_2d/::matrix.

translate() [2/2]

void xtd::drawing::drawing_2d::matrix::translate	(	float	offset_x,
		float	offset_y,
		xtd::drawing::drawing_2d::matrix_order	order
	)

Applies the specified translation vector (offset_x and offset_y) to this xtd::drawing::drawing_2d/::matrix in the specified order.

Parameters

offset_x	The x value by which to translate this xtd::drawing::drawing_2d/::matrix.
offset_y	The y value by which to translate this xtd::drawing::drawing_2d/::matrix.
order	A xtd::drawing::drawing_2d/matrix_order that specifies the order (append or prepend) in which the translation is applied to this xtd::drawing::drawing_2d/::matrix.

vector_transform_points()

void xtd::drawing::drawing_2d::matrix::vector_transform_points

(

std::vector< xtd::drawing::point > &

points

)

Multiplies each vector in an array by the matrix. The translation elements of this matrix (third row) are ignored.

Parameters

points

An array of xtd::drawing::point structures that represents the points to transform.

---

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

• xtd.drawing/include/xtd/drawing/drawing_2d/matrix.h