xtd 0.2.0
Loading...
Searching...
No Matches
xtd::drawing::drawing_2d::matrix Class Referencefinal
Inheritance diagram for xtd::drawing::drawing_2d::matrix:
xtd::object xtd::iequatable< matrix > xtd::interface

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
Encapsulates a 3-by-3 affine matrix that represents a geometric transform. This class cannot be inher...
Definition matrix.h:73
Supports all classes in the xtd class hierarchy and provides low-level services to derived classes....
Definition object.h:32
#define drawing_export_
Define shared library export.
Definition drawing_export.h:13
Inheritance
xtd::objectxtd::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 = 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
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);
void translate(float offset_x, float offset_y)
Applies the specified translation vector (offset_x and offset_y) to this xtd::drawing::drawing_2d::ma...
void scale(float scale_x, float scale_y)
Applies the specified scale vector to this xtd::drawing::drawing_2d::matrix by prepending the scale v...
void rotate(float angle)
repend to this xtd::drawing::drawing_2d::matrix a clockwise rotation, around the origin and by the sp...
@ append
The new operation is applied after the old operation.

Public Constructors

 matrix ()
 Initializes a new instance of the xtd::drawing::drawing_2d::matrix class as the identity 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.
 
 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.
 
 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.
 

Public Properties

std::vector< float > elements () const
 Gets an array of floating-point values that represents the elements of this xtd::drawing::drawing_2d::matrix.
 
intptr handle () const noexcept
 Gets the handle of the matrix.
 
bool is_identity () const
 Gets a value indicating whether this xtd::drawing::drawing_2d::matrix is the identity matrix.
 
bool is_invertible () const
 Gets a value indicating whether this xtd::drawing::drawing_2d::matrix is invertible.
 
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.
 
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.
 

Public 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.
 
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.
 
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.
 
void reset ()
 Resets this xtd::drawing::drawing_2d::matrix to have the elements of the identity matrix.
 
void rotate (float angle)
 repend to this xtd::drawing::drawing_2d::matrix a clockwise rotation, around the origin and by the specified angle.
 
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.
 
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.
 
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.
 
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.
 
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.
 
void shear (float scale_x, float scale_y)
 Applies the specified shear vector to this xtd::drawing::drawing_2d::matrix.
 
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.
 
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.
 
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.
 
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.
 
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.
 
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.
 
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.
 
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.
 
xtd::ustring to_string () const noexcept override
 Returns a xtd::ustring that represents the current object.
 

Additional Inherited Members

- Public Member Functions inherited from xtd::object
 object ()=default
 Create a new instance of the ultimate base class object.
 
bool equals (const object &obj) const noexcept
 Determines whether the specified object is equal to the current object.
 
virtual size_t get_hash_code () const noexcept
 Serves as a hash function for a particular type.
 
virtual type_object get_type () const noexcept
 Gets the type of the current instance.
 
template<typename object_t >
std::unique_ptr< object_t > memberwise_clone () const noexcept
 Creates a shallow copy of the current object.
 
- 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.
 
- 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.
 
static bool reference_equals (const object &object_a, const object &object_b) noexcept
 Determines whether the specified object instances are the same instance.
 

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
m11The value in the first row and first column of the new xtd::drawing::drawing_2d::matrix.
m12The value in the first row and second column of the new xtd::drawing::drawing_2d::matrix.
m21The value in the second row and first column of the new xtd::drawing::drawing_2d::matrix.
m22The value in the second row and second column of the new xtd::drawing::drawing_2d::matrix.
dxThe value in the third row and first column of the new xtd::drawing::drawing_2d::matrix.
dyThe 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
rectA xtd::drawing::rectangle structure that represents the rectangle to be transformed.
plgptsAn 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
rectA xtd::drawing::rectangle_f structure that represents the rectangle to be transformed.
plgptsAn 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
matrixThe 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
matrixThe xtd::drawing::drawing_2d::matrix by which this xtd::drawing::drawing_2d::matrix is to be multiplied.
orderThe 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
angleThe 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
angleThe angle (extent) of the rotation, in degrees.
orderA 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
angleThe angle (extent) of the rotation, in degrees.
pointA 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
angleThe angle (extent) of the rotation, in degrees.
pointA xtd::drawing::point_f that represents the center of the rotation.
orderA 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_xThe value by which to scale this xtd::drawing::drawing_2d::matrix in the x-axis direction.
scale_yThe 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_xThe value by which to scale this xtd::drawing::drawing_2d::matrix in the x-axis direction.
scale_yThe value by which to scale this xtd::drawing::drawing_2d::matrix in the y-axis direction.
orderA 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_xThe horizontal shear factor.
scale_yThe 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_xThe horizontal shear factor.
scale_yThe vertical shear factor.
orderA 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 xtd::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
pointsAn 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
pointsAn 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
pointsAn 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
pointsAn 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_xThe x value by which to translate this xtd::drawing::drawing_2d::matrix.
offset_yThe 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_xThe x value by which to translate this xtd::drawing::drawing_2d::matrix.
offset_yThe y value by which to translate this xtd::drawing::drawing_2d::matrix.
orderA 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
pointsAn array of xtd::drawing::point structures that represents the points to transform.

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