Home COM GDI+ WebBrowser Data Access 

Matrix Functions (GDI+)

 

 

A Matrix object represents a 3 ×3 matrix that, in turn, represents an affine transformation. A Matrix object stores only six of the 9 numbers in a 3 ×3 matrix because all 3 ×3 matrices that represent affine transformations have the same third column (0, 0, 1).

 

Return Values

If the function succeeds, it returns Ok, which is an element of the Status enumeration.

 

If the function fails, it returns one of the other elements of the Status enumeration.

 

GdipCloneMatrix

 

Description

Creates a new Matrix object that is a copy of this Matrix object.

Syntax

GpStatus WINGDIPAPI GdipCloneMatrix(

    GpMatrix *matrix,

    GpMatrix **cloneMatrix

);

PowerBASIC Syntax

DECLARE FUNCTION GdipCloneMatrix ( _

    BYVAL matrix AS DWORD, _

    BYREF cloneMatrix AS DWORD _

) AS LONG

Parameters

 

matrix

[in] Pointer to the Matrix object.

cloneMatrix

[out] Pointer to a variable that receives a pointer to the new Matrix object.

 

GdipCreateMatrix

 

Description

Creates and initializes a Matrix object that represents the identity matrix.

Syntax

GpStatus WINGDIPAPI GdipCreateMatrix(

    GpMatrix **matrix

);

PowerBASIC Syntax

DECLARE FUNCTION GdipCreateMatrix ( _

    BYREF matrix AS DWORD _

) AS LONG

Parameters

 

matrix

[out] Pointer to a variable that receives a pointer to the new created Matrix object.

 

GdipCreateMatrix2

 

Description

Creates and initializes a Matrix object based on six numbers that define an affine transformation.

Syntax

GpStatus WINGDIPAPI GdipCreateMatrix2(

    REAL m11,

    REAL m12,

    REAL m21,

    REAL m22,

    REAL dx,

    REAL dy,

    GpMatrix **matrix

);

PowerBASIC Syntax

DECLARE FUNCTION GdipCreateMatrix2 ( _

    BYVAL m11 AS SINGLE, _

    BYVAL m12 AS SINGLE, _

    BYVAL m21 AS SINGLE, _

    BYVAL m22 AS SINGLE, _

    BYVAL dx AS SINGLE, _

    BYVAL dy AS SINGLE, _

    BYREF matrix AS DWORD _

) AS LONG

Parameters

 

m11

[in] Simple prevision value that specifies the element in the first row, first column.

m12

[in] Simple prevision value that specifies the element in the first row, second column.

m21

[in] Simple prevision value that specifies the element in the second row, first column.

m22

[in] Simple prevision value that specifies the element in the second row, second column.

dx

[in] Simple prevision value that specifies the element in the third row, first column.

dy

[in] Simple prevision value that specifies the element in the third row, second column.

matrix

[out] Pointer to a variable that receives a pointer to the new created Matrix object.

 

GdipCreateMatrix3

 

Description

Creates a Matrix object based on a rectangle and a point.

Syntax

GpStatus WINGDIPAPI GdipCreateMatrix3(

    GDIPCONST GpRectF *rect,

    GDIPCONST GpPointF *dstplg,

    GpMatrix **matrix

);

PowerBASIC Syntax

DECLARE FUNCTION GdipCreateMatrix3 ( _

    BYREF pRect AS RectF, _

    BYREF dstplg AS PointF, _

    BYREF matrix AS DWORD _

) AS LONG

Parameters

 

rect

[in] Reference to a RectF structure. The X data member of the rectangle specifies the matrix element in row 1, column 1. The Y data member of the rectangle specifies the matrix element in row 1, column 2. The Width data member of the rectangle specifies the matrix element in row 2, column 1. The Height data member of the rectangle specifies the matrix element in row 2, column 2.

dstplg

[in] Pointer to a PointF structure. The X data member of the point specifies the matrix element in row 3, column 1. The Y data member of the point specifies the matrix element in row 3, column 2.

matrix

[out] Pointer to a variable that receives a pointer to the new created Matrix object.

 

GdipCreateMatrix3I

 

Description

Creates a Matrix object based on a rectangle and a point.

Syntax

GpStatus WINGDIPAPI GdipCreateMatrix3I(

    GDIPCONST GpRect *rect,

    GDIPCONST GpPoint *dstplg,

    GpMatrix **matrix

);

PowerBASIC Syntax

DECLARE FUNCTION GdipCreateMatrix3I ( _

    BYREF pRect AS RECTL, _

    BYREF dstplg AS PointL, _

    BYREF matrix AS DWORD _

) AS LONG

Parameters

 

rect

[in] Reference to a Rect structure. The X data member of the rectangle specifies the matrix element in row 1, column 1. The Y data member of the rectangle specifies the matrix element in row 1, column 2. The Width data member of the rectangle specifies the matrix element in row 2, column 1. The Height data member of the rectangle specifies the matrix element in row 2, column 2.

dstplg

[in] Pointer to a PointL structure. The X data member of the point specifies the matrix element in row 3, column 1. The Y data member of the point specifies the matrix element in row 3, column 2.

matrix

[out] Pointer to a variable that receives a pointer to the new created Matrix object.

 

GdipDeleteMatrix

 

Description

Deletes the specified Matrix object.

Syntax

GpStatus WINGDIPAPI GdipDeleteMatrix(

    GpMatrix *matrix

);

PowerBASIC Syntax

DECLARE FUNCTION GdipDeleteMatrix ( _

    BYVAL matrix AS DWORD _

) AS LONG

Parameters

 

matrix

[in] Pointer to the Matrix object.

 

GdipGetMatrixElements

 

Description

Gets the elements of this matrix. The elements are placed in an array in the order m11, m12, m21, m22, m31, m32, where mij denotes the element in row i, column j.

Syntax

GpStatus WINGDIPAPI GdipGetMatrixElements(

    GDIPCONST GpMatrix *matrix,

    REAL *matrixOut

);

PowerBASIC Syntax

DECLARE FUNCTION GdipGetMatrixElements ( _

    BYVAL matrix AS DWORD, _

    BYREF matrixOut AS SINGLE _

) AS LONG

Parameters

 

matrix

[in] Pointer to the Matrix object.

matrixOut

[out] Pointer to an array that receives the matrix elements. The size of the array should be 6 sizeof(REAL), i.e. 24.

 

GdipInvertMatrix

 

Description

If the matrix is invertible, this function replaces its elements  with the elements of its inverse.

Syntax

GpStatus WINGDIPAPI GdipInvertMatrix(

    GpMatrix *matrix

);

PowerBASIC Syntax

DECLARE FUNCTION GdipInvertMatrix ( _

    BYVAL matrix AS DWORD _

) AS LONG

Parameters

 

matrix

[in] Pointer to the Matrix object.

 

GdipIsMatrixEqual

 

Description

Determines whether the elements of this matrix are equal to the elements of another matrix.

Syntax

GpStatus WINGDIPAPI GdipIsMatrixEqual(

    GDIPCONST GpMatrix *matrix,

    GDIPCONST GpMatrix *matrix2,

    BOOL *result

);

PowerBASIC Syntax

DECLARE FUNCTION GdipIsMatrixEqual ( _

    BYVAL matrix AS DWORD, _

    BYVAL matrix2 AS DWORD, _

    BYREF result AS LONG _

) AS LONG

Parameters

 

matrix

[in] Pointer to the Matrix object.

matrix2

[in] Pointer to a Matrix object that is compared with this Matrix object.

result

[out] Pointer to a variable thatg receives a boolean value indicating whether the elements of the two matrices are the same (TRUE) or not (FALSE).

 

GdipIsMatrixIdentity

 

Description

Determines whether this matrix is the identity matrix.

Syntax

GpStatus WINGDIPAPI GdipIsMatrixIdentity(

    GDIPCONST GpMatrix *matrix,

    BOOL *result

);

PowerBASIC Syntax

DECLARE FUNCTION GdipIsMatrixIdentity ( _

    BYVAL matrix AS DWORD, _

    BYREF result AS LONG _

) AS LONG

Parameters

 

matrix

[in] Pointer to the Matrix object.

result

[out] Pointer to a variable thatg receives a boolean value indicating whether this matrix is the identity matrix (TRUE) or not (FALSE).

 

GdipIsMatrixInvertible

 

Description

Determines whether this matrix is invertible.

Syntax

GpStatus WINGDIPAPI GdipIsMatrixInvertible(

    GDIPCONST GpMatrix *matrix,

    BOOL *result

);

PowerBASIC Syntax

DECLARE FUNCTION GdipIsMatrixInvertible ( _

    BYVAL matrix AS DWORD, _

    BYREF result AS LONG _

) AS LONG

Parameters

 

matrix

[in] Pointer to the Matrix object.

result

[out] Pointer to a variable thatg receives a boolean value indicating whether this matrix is invertible (TRUE) or not (FALSE).

 

GdipMultiplyMatrix

 

Description

Updates this matrix with the product of itself and another matrix.

Syntax

GpStatus WINGDIPAPI GdipMultiplyMatrix(

    GpMatrix *matrix,

    GpMatrix* matrix2,

    GpMatrixOrder order

);

PowerBASIC Syntax

DECLARE FUNCTION GdipMultiplyMatrix ( _

    BYVAL matrix AS DWORD, _

    BYVAL matrix2 AS DWORD, _

    BYVAL order AS LONG _

) AS LONG

Parameters

 

matrix

[in] Pointer to the Matrix object.

matrix2

[in] Pointer to a matrix that will be multiplied by this matrix.

order

[in] Element of the MatrixOrder enumeration that specifies the order of the multiplication. MatrixOrderPrepend specifies that the passed matrix is on the left, and MatrixOrderAppend specifies that the passed matrix is on the right. The default value is MatrixOrderPrepend.

 

GdipRotateMatrix

 

Description

Updates this matrix with the product of itself and a rotation matrix.

Syntax

GpStatus WINGDIPAPI GdipRotateMatrix(

    GpMatrix *matrix,

    REAL angle,

    GpMatrixOrder order

);

PowerBASIC Syntax

DECLARE FUNCTION GdipRotateMatrix ( _

    BYVAL matrix AS DWORD, _

    BYVAL angle AS SINGLE, _

    BYVAL order AS LONG _

) AS LONG

Parameters

 

matrix

[in] Pointer to the Matrix object.

angle

[in] Simple precision value that specifies the angle of rotation in degrees. Positive values specify clockwise rotation.

order

[in] Element of the MatrixOrder enumeration that specifies the order of the multiplication. MatrixOrderPrepend specifies that the rotation matrix is on the left, and MatrixOrderAppend specifies that the rotation matrix is on the right. The default value is MatrixOrderPrepend.

 

GdipScaleMatrix

 

Description

Updates this matrix with the product of itself and a scaling matrix.

Syntax

GpStatus WINGDIPAPI GdipScaleMatrix(

    GpMatrix *matrix,

    REAL scaleX,

    REAL scaleY,

    GpMatrixOrder order

);

PowerBASIC Syntax

DECLARE FUNCTION GdipScaleMatrix ( _

    BYVAL matrix AS DWORD, _

    BYVAL scaleX AS SINGLE, _

    BYVAL scaleY AS SINGLE, _

    BYVAL order AS LONG _

) AS LONG

Parameters

 

matrix

[in] Pointer to the Matrix object.

scaleX

[in] Simple precision value that specifies the horizontal scale factor.

scaleY

[in] Simple precision value that specifies the vertical scale factor.

order

[in] Element of the MatrixOrder enumeration that specifies the order of the multiplication. MatrixOrderPrepend specifies that the scaling matrix is on the left, and MatrixOrderAppend specifies that the scaling matrix is on the right. The default value is MatrixOrderPrepend.

 

GdipSetMatrixElements

 

Description

Sets the elements of this matrix.

Syntax

GpStatus WINGDIPAPI GdipSetMatrixElements(

    GpMatrix *matrix,

    REAL m11,

    REAL m12,

    REAL m21,

    REAL m22,

    REAL dx,

    REAL dy

);

PowerBASIC Syntax

DECLARE FUNCTION GdipSetMatrixElements ( _

    BYVAL matrix AS DWORD, _

    BYVAL m11 AS SINGLE, _

    BYVAL m12 AS SINGLE, _

    BYVAL m21 AS SINGLE, _

    BYVAL m22 AS SINGLE, _

    BYVAL dx AS SINGLE, _

    BYVAL dy AS SINGLE _

) AS LONG

Parameters

 

matrix

[in] Pointer to the Matrix object.

m11

[in] Simple precision value that specifies the element in the first row, first column.

m12

[in] Simple precision value that specifies the element in the first row, second column.

m21

[in] Simple precision value that specifies the element in the second row, first column.

m22

[in] Simple precision value that specifies the element in the second row, second column.

dx

[in] Simple precision value that specifies the element in the third row, first column.

dy

[in] Real number that specifies the element in the third row, second column.

 

GdipShearMatrix

 

Description

Updates this matrix with the product of itself and a shearing matrix.

Syntax

GpStatus WINGDIPAPI GdipShearMatrix(

    GpMatrix *matrix,

    REAL shearX,

    REAL shearY,

    GpMatrixOrder order

);

PowerBASIC Syntax

DECLARE FUNCTION GdipShearMatrix ( _

    BYVAL matrix AS DWORD, _

    BYVAL shearX AS SINGLE, _

    BYVAL shearY AS SINGLE, _

    BYVAL order AS LONG _

) AS LONG

Parameters

 

matrix

[in] Pointer to the Matrix object.

shearX

[in] Simple precision value that specifies the horizontal shear factor.

shearY

[in] Simple precision value that specifies the vertical shear factor.

order

[in] Element of the MatrixOrder enumeration that specifies the order of the multiplication. MatrixOrderPrepend specifies that the shearing matrix is on the left, and MatrixOrderAppend specifies that the shearing matrix is on the right. The default value is MatrixOrderPrepend.

 

GdipTransformMatrixPoints

 

Description

Multiplies each point in an array by this matrix. Each point is treated as a row matrix. The multiplication is performed with the row matrix on the left and this matrix on the right.

Syntax

GpStatus WINGDIPAPI GdipTransformMatrixPoints(

    GpMatrix *matrix,

    GpPointF *pts,

    INT count

);

PowerBASIC Syntax

DECLARE FUNCTION GdipTransformMatrixPoints ( _

    BYVAL matrix AS DWORD, _

    BYREF pts AS PointF, _

    BYVAL count AS LONG _

) AS LONG

Parameters

 

matrix

[in] Pointer to the Matrix object.

pts

[in, out] Pointer to an array of PointF structures that, on input, contains the points to be transformed and, on output, receives the transformed points. Each point in the array is transformed (multiplied by this matrix) and updated with the result of the transformation.

count

[in] Long integer value that specifies the number of points to be transformed. The default value is 1.

 

GdipTransformMatrixPointsI

 

Description

Multiplies each point in an array by this matrix. Each point is treated as a row matrix. The multiplication is performed with the row matrix on the left and this matrix on the right.

Syntax

GpStatus WINGDIPAPI GdipTransformMatrixPointsI(

    GpMatrix *matrix,

    GpPoint *pts,

    INT count

);

PowerBASIC Syntax

DECLARE FUNCTION GdipTransformMatrixPointsI ( _

    BYVAL matrix AS DWORD, _

    BYREF pts AS PointL, _

    BYVAL count AS LONG _

) AS LONG

Parameters

 

matrix

[in] Pointer to the Matrix object.

pts

[in, out] Pointer to an array of PointL structures that, on input, contains the points to be transformed and, on output, receives the transformed points. Each point in the array is transformed (multiplied by this matrix) and updated with the result of the transformation.

count

[in] Long integer that specifies the number of points to be transformed. The default value is 1.

 

GdipTranslateMatrix

 

Description

Updates this matrix with the product of itself and a translation matrix.

Syntax

GpStatus WINGDIPAPI GdipTranslateMatrix(

    GpMatrix *matrix,

    REAL offsetX,

    REAL offsetY,

    GpMatrixOrder order

);

PowerBASIC Syntax

DECLARE FUNCTION GdipTranslateMatrix ( _

    BYVAL matrix AS DWORD, _

    BYVAL offsetX AS SINGLE, _

    BYVAL offsetY AS SINGLE, _

    BYVAL order AS LONG _

) AS LONG

Parameters

 

matrix

[in] Pointer to the Matrix object.

offsetX

[in] Single precision value that specifies the horizontal component of the translation.

offsetY

[in] Single precision value that specifies the vertical component of the translation.

order

[in] Element of the MatrixOrder enumeration that specifies the order of the multiplication. MatrixOrderPrepend specifies that the translation matrix is on the left, and MatrixOrderAppend specifies that the translation matrix is on the right. The default value is MatrixOrderPrepend.

 

GdipVectorTransformMatrixPoints

 

Description

Multiplies each vector in an array by this matrix. The translation elements of this matrix (third row) are ignored. Each vector is treated as a row matrix. The multiplication is performed with the row matrix on the left and this matrix on the right.

Syntax

GpStatus WINGDIPAPI GdipVectorTransformMatrixPoints(

    GpMatrix *matrix,

    GpPointF *pts,

    INT count

);

PowerBASIC Syntax

DECLARE FUNCTION GdipVectorTransformMatrixPoints ( _

    BYVAL matrix AS DWORD, _

    BYREF pts AS PointF, _

    BYVAL count AS LONG _

) AS LONG

Parameters

 

matrix

[in] Pointer to the Matrix object.

pts

[in, out] Pointer to an array of PointF objects that, on input, contains the vectors to be transformed and, on output, receives the transformed vectors. Each vector in the array is transformed (multiplied by this matrix) and updated with the result of the transformation.

count

[in] Long integer value that specifies the number of points to be transformed. The default value is 1.

 

GdipVectorTransformMatrixPointsI

 

Description

Multiplies each vector in an array by this matrix. The translation elements of this matrix (third row) are ignored. Each vector is treated as a row matrix. The multiplication is performed with the row matrix on the left and this matrix on the right.

Syntax

GpStatus WINGDIPAPI GdipVectorTransformMatrixPointsI(

    GpMatrix *matrix,

    GpPoint *pts,

    INT count

);

PowerBASIC Syntax

DECLARE FUNCTION GdipVectorTransformMatrixPointsI ( _

    BYVAL matrix AS DWORD, _

    BYREF pts AS PointL, _

    BYVAL count AS LONG _

) AS LONG

Parameters

 

matrix

[in] Pointer to the Matrix object.

pts

[in, out] Pointer to an array of PointL objects that, on input, contains the vectors to be transformed and, on output, receives the transformed vectors. Each vector in the array is transformed (multiplied by this matrix) and updated with the result of the transformation.

count

[in] Long integer value that specifies the number of points to be transformed. The default value is 1.

 

Page last updated on Monday, 11 December 2006 11:02:01 +0100