IGrafMatrix

IGrafMatrix provides a transformation matrix that performs 2-D linear transformations for homogeneous spaces. IGrafMatrix can be instantiated directly. All of the public methods of IGrafMatrix can be called directly.


IGrafMatrix - Member Functions and Data by Group

Constructors & Destructor

Use the functions in this group to construct or destroy a matrix object of class IGrafMatrix.


[view class]
~IGrafMatrix
public:
virtual ~IGrafMatrix()
Destroys the matrix.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
IGrafMatrix
Constructs a matrix object of class IGrafMatrix.


Overload 1
Creates a translation matrix.
public:
IGrafMatrix(const IGPoint2D& delta)
Use this constructor to create a translation matrix based on the given point.

delta
A constant reference to a point which specify the increments in the X and Y direction by which the matrix is to be translated.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
Creates a matrix from an array of values.
public:
IGrafMatrix(const GCoordinate matrix [ ])
Use this constructor to creates a matrix from an array of matrix elements.

matrix
The nine-element array to be converted into a matrix.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
Default constructor. Creates an identity matrix.
public:
IGrafMatrix()
Use this constructor to create an identity matrix.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 4
Copy constructor.
public:
IGrafMatrix(const IGrafMatrix& matrix)
Use this constructor to create a matrix object which is a copy of the given one.

matrix
A constant reference to the matrix to be copied.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 5
Creates a matrix of rotation around the specified point.
public:
IGrafMatrix( const GDegrees& angle, const IGPoint2D& centerOfRotate )
Use this constructor to create a matrix of rotation about a given point.

angle
The angle of rotation in degrees. +ve values specify counter clockwise rotation.
centerOfRotate
A constant reference to the center of rotation point.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 6
Creates a matrix that scales about a specified point.
public:
IGrafMatrix( const IGPoint2D& scale, const IGPoint2D& centerOfScale )
Use this constructor to create a matrix that scales about a given point. This point serves as the center and uses the specified scaling factor.

scale
A constant reference to the scaling factor.
centerOfScale
A constant reference to the center point for the scaling operation.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 7
Creates a matrix from the perspective mapping of the given quadrilaterals.
public:
IGrafMatrix( const IGQuadrilateral& fromQuadrilateral, const IGQuadrilateral& toQuadrilateral )
Use this constructor to create a matrix from the perspective mapping of one quadrilateral to another.

fromQuadrilateral
A constant reference to the quadrilateral that represents the graphic before transformation.
toQuadrilateral
A constant reference to the quadrilateral that represents the graphic after transformation.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 8
Creates a matrix from a set of matrix elements.
public:
IGrafMatrix( const GCoordinate scaleX, const GCoordinate shearY, const GCoordinate perspectiveX, const GCoordinate shearX, const GCoordinate scaleY, const GCoordinate perspectiveY, const GCoordinate translateX, const GCoordinate translateY, const GCoordinate homogeneous )
Use this constructor to create a matrix from a set of matrix elements specified as GCoordinates.

scaleX
The scaling factor for the x-coordinate.
shearY
The shearing factor for the y-coordinate.
perspectiveX
The perspective factor for the x-coordinate.
shearX
The shearing factor for the x-coordinate.
scaleY
The scaling factor for the y-coordinate.
perspectiveY
The perspective factor for the y-coordinate.
translateX
The translation factor for the x-coordinate.
translateY
The translation factor for the y-coordinate.
homogeneous
The homogeneous factor for the matrix.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Assignment Operator

Use this function to assign the given graphics matrix object to the target object.


[view class]
operator =
public:
IGrafMatrix& operator =(const IGrafMatrix& source)
Assignment operator.

source
A constant reference to the object to be copied.

Return
A non-const reference to the left-hand side object.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Creating Matrices Using Other Matrices and Values

Use the functions in this group to create scale, translation, and rotation matrices from specified values, such as delta values, scaling factors, and rotation factors preconcatenated with the current matrix.


[view class]
preRotateBy
The rotation is about the specified center of rotation. The angle is measured in degrees from the positive x axis to the positive y axis.
public:
virtual void preRotateBy( GDegrees degrees, const IGPoint2D& centerOfRotate = IGPoint2D::origin ( ) )
Constructs a rotation matrix out of the specified rotation factor and preconcatenates with this matrix.

degrees
The rotation factor.
centerOfRotate
A constant reference to the center of the rotation. Default value is set to IGPoint2D::origin().

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
preScaleBy
public:
virtual void preScaleBy( const IGPoint2D& scale, const IGPoint2D& centerOfScale = IGPoint2D::origin ( ) )
Constructs a scale matrix out of the specified scaling factor and pre-concatenates with this matrix. The scaling is centered around the specified point.

scale
The scaling factor.
centerOfScale
A constant reference to the center of the scaling transformation. Default value is IGPoint2D::origin().

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
preTranslateBy
public:
virtual void preTranslateBy(const IGPoint2D& delta)
Constructs a translation matrix out of the specified delta values and pre-concatenates with this matrix.

delta
A constant reference to a IGPoint2D object representing the translation factor in X and Y directions.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Manipulating Matrices and Matrix Values

Use the functions in this group to modify the matrix in various ways. For example, you can multiply one matrix by another, invert the matrix, convert it to its Classical Adjoint, normalize it, and concatenate it with a rotate matrix or by a scale. These functions also allow you to rotate the matrix, multiply it by delta translation, and swap its rows and columns. You can also use the functions in this group to transform the corners of the given rectangle, transform an array of points, and interpret the given IGPoint2D as a vector.


[view class]
concatWith
public:
virtual void concatWith(const IGrafMatrix& matrix)
Post multiplies the given matrix by itself. Concatenation is not commutative.

matrix
The matrix to be post-concatenated to this one.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
identity
public:
static const IGrafMatrix& identity()
Allows the client to efficiently specify an identity matrix.

Return
A constant reference to a identity matrix.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
invert
public:
virtual void invert()
Inverts this IGrafMatrix.

Exception

Throws

a kSingularTransform ITransformException if a matrix is not invertible.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
makeAdjoint
public:
virtual void makeAdjoint()
Converts this IGrafMatrix to its classical adjoint.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
normalize
public:
virtual bool normalize()
Divides the IGrafMatrix by the homogeneous value.

Return
True if the homogenous value is nonzero.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
operator *=
public:
IGrafMatrix& operator *=(const IGrafMatrix& matrix)
Concatenates the left operand by the right operand and sets the left operand to the new value.

source
A constant reference to the matrix to be post-concatenated with this one.

Return
A reference to itself.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
preConcatWith
public:
virtual void preConcatWith(const IGrafMatrix& matrix)
Modify the current matrix by pre-mutiplying with the given matrix. Concatenation is not commutative.

matrix
A constant reference to the other matrix.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
rotateBy
public:
virtual void rotateBy( GDegrees degrees, const IGPoint2D& centerOfRotate = IGPoint2D::origin ( ) )
The rotation is about the specified center of rotation. The angle is measured in degrees from the positive x axis to the positive y axis. Post-concatenates the rotate matrix with the current one.

degrees
The degrees of the rotation.
centerOfRotate
A constant reference to the center point of the rotation. Default value is IGPoint2D::origin().

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
scaleBy
public:
virtual void scaleBy( const IGPoint2D& scale, const IGPoint2D& centerOfScale = IGPoint2D::origin ( ) )
Concatenates this matrix by a scale. The scaling is about the specified centerOfScale point.

scale
A constant reference to a IGPoint2D object specifying the X and Y scaling factors.
centerOfScale
A constant reference to the center point of the scaling transformation. Default value is IGPoint2D::origin().

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
transformBounds
Transforms the corners of the specified IGRect2D.
public:
virtual IGRect2D transformBounds(const IGRect2D& r) const
Subclasses can override this to improve performance.

r
A constant reference to the rectangle to be transformed.

Return
The transformed rectangle.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
transformPoint
Transforms a point to another point.


Overload 1
Transforms a point of class IGPoint2D.
public:
virtual IGPoint2D transformPoint( const IGPoint2D& source ) const
Use this function to transform one point to another. By default, transformPoint (singular) calls transformPoints (array). Subclasses can override transformPoint to improve performance.

source
A constant reference to the point to be transformed.

Return
The transformed point.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
Transforms a point of class IGRPoint2D.
public:
virtual IGRPoint2D transformPoint( const IGRPoint2D& source ) const
Use this function to transform one rational point to another. Subclasses can override this method to improve performance.

source
A constant reference to the rational point to be transformed.

Return
The transformed point.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
transformPoints
Transforms an array of points efficiently.


Overload 1
Transforms an array of IGPoint points.
public:
virtual void transformPoints(IGPoint2DArray& points) const
Use this function to transform the specified array of points of class IGPoint2D. Subclasses must define transformPoints for rational points.

points
The array of points to be transformed and returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
virtual void transformPoints( const IGPoint2D points [ ], IGPoint2D transformPoints [ ], unsigned long count = 1 ) const
Use this function to transform an array of points. This function returns the transformed points in the second parameter. Subclasses must define transformPoints for points.

points
The source array of points.
transformPoints
The destination array of points. It can be the same as the source array.
count
The number of points in the array. Default value is 1.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
transformVector
public:
virtual IGPoint2D transformVector( const IGPoint2D& source ) const
Interprets IGPoint2D as a vector. It only transforms the magnitude and direction of the vector. By default, transformVector calls transformPoint. Subclasses can override transformVector to improve performance.

source
A constant reference to the vector to transform.

Return
The transformed vector.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
translateBy
public:
virtual void translateBy(const IGPoint2D& delta)
Multiplies this matrix by delta translation. Concatenation is not commutative.

delta
A constant reference to the translation amount.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
transpose
public:
virtual void transpose()
Transposes this IGrafMatrix (that is, swaps the rows and columns of the matrix).

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
untransformBounds
public:
virtual IGRect2D untransformBounds(const IGRect2D& r) const
Passes the specified IGRect2D backwards through the transformation.

r
The rectangle to be untransformed.

Return
The untransformed rectangle.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
untransformPoint
Passes a point backwards through this transformation matrix. By default, untransformPoint clones and inverts the transform. Subclasses can override untransformPoint to improve performance. The matrix is not changed.


Overload 1
public:
virtual IGRPoint2D untransformPoint( const IGRPoint2D& source ) const

source
The rational point to be transformed.

Return
The untransformed point.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
virtual IGPoint2D untransformPoint( const IGPoint2D& source ) const

source
A constant reference to the point to be transformed.

Return
The untransformed point.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
untransformVector
public:
virtual IGPoint2D untransformVector( const IGPoint2D& source ) const
Passes a vector backwards through the transformation.

source
A constant reference to the vector to untransform.

Return
The untransformed vector.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Obtaining Information About the Matrix Object

Use the functions in this group to obtain information about a matrix object, such as its determinant, its time stamp, and the matrix type, that is, whether the matrix is an identity matrix, an affine matrix, or a translate matrix, and so forth. This group also includes a function you can use to obtain an element belonging to the matrix.


[view class]
determinant
public:
virtual GCoordinate determinant() const
Gets the determinant of this IGrafMatrix. If the determinant is 0, a matrix is not invertible.

Return
The determinant of the matrix.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
element
public:
virtual GCoordinate element(EMatrixIndex) const
Uses EMatrixIndex to get a particular element out of the IGrafMatrix.

index
The enum position of the particular element.

Return
The element at the specified index.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
isAffine
public:
virtual bool isAffine() const
Determines whether the matrix is affine (that is, perspectiveX =0, perspectiveY =0, and homogeneous =1.0).

Return
True if the matrix is affine.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
isIdentity
public:
virtual bool isIdentity() const
Determines whether this IGrafMatrix is an identity matrix.

Return
True if the matrix is of type kIdentity or is a kRotate matrix with 0 degrees rotation.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
isRectilinear
public:
virtual bool isRectilinear() const
Determines whether a rectangle passed through the matrix is still a rectangle.

Return
True if a rectangle passed through the matrix is still a rectangle.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
isTranslate
public:
virtual bool isTranslate() const
Determines whether this IGrafMatrix is a translate matrix.

Return
True if the matrix is of type kTranslate or is of type kIdentity or kRotate matrix with 0 degrees rotation.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
matrix
public:
virtual GCoordinate* matrix(GCoordinate matrix [ ]) const
Fills in a nine-element array with matrix element values. You must preallocate the array before making this call.

matrix
The array for the elements of the matrix.

Return
A pointer to the array that contains the elements of the matrix.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
rotate
public:
virtual bool rotate( GDegrees& degrees, IGPoint2D& centerOfRotate ) const
Returns the angle (between 0 and 360 degrees) and the center of rotation in the respective parameters.

degrees
The degrees of rotation of this matrix.
centerOfRotate
The center of the rotation.

Return
True if the matrix is a rotation matrix.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
timeStamp
public:
unsigned long timeStamp() const
Returns the time stamp for this IGrafMatrix.

Return
The time stamp.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
type
public:
virtual EMatrixType type() const
Determines what type of matrix this is (that is, either kIdentity, kTranslate, kScale, kRotate, kAffine, or kPerspective).

Return
The type of matrix.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Setting Matrix Values

Use the functions in this group to set matrix values, such as its type, an element of the matrix, its scaling component, and so forth.


[view class]
setElement
public:
virtual void setElement(EMatrixIndex, GCoordinate element)
Sets the specified element in the IGrafMatrix.

index
The index of the particular element.
element
The new value for the element.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setToIdentity
public:
virtual void setToIdentity()
Sets this IGrafMatrix to an identity matrix.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setToPerspectiveMap
public:
virtual void setToPerspectiveMap( const IGQuadrilateral& fromQuadrilateral, const IGQuadrilateral& toQuadrilateral )
Sets this matrix to one that transforms the first polygon into the second one. The source and destination polygons must be convex, and they must have four vertices (quadrilateral). It creates the following perspective mapping: fromQuadrilateral [0] --> toQuadrilateral [0] fromQuadrilateral [1] --> toQuadrilateral [1] fromQuadrilateral [2] --> toQuadrilateral [2] fromQuadrilateral [3] --> toQuadrilateral [3]

fromQuadrilateral
A constant reference to the original quadrilateral.
toQuadrilateral
A constant reference to the final quadrilateral.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setToRotate
public:
virtual void setToRotate( GDegrees degrees, const IGPoint2D& centerOfRotate = IGPoint2D::origin ( ) )
Resets this IGrafMatrix to one that rotates around the specified point.

degrees
The rotation angle in degrees.
centerOfRotate
The center of the rotation. Default value is IGPoint2D::origin().

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setToScale
public:
virtual void setToScale( const IGPoint2D& scale, const IGPoint2D& centerOfScale = IGPoint2D::origin ( ) )
Sets this IGrafMatrix so that its scaling components (kScaleX and kScaleY) are equal to the coordinates of the specified IGPoint2D.

scale
The scaling factor.
centerOfScale
The center of the scaling. Default value is IGPoint2D::origin().

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setToTranslate
public:
virtual void setToTranslate(const IGPoint2D& delta)
Sets this IGrafMatrix so that its translation components (kTranslateX and kTranslateY) are set to the coordinates of the specified IGPoint2D.

delta
A constant reference to a IGPoint2D object representing the X and Y translation values.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
resetTimeStamp
protected:
void resetTimeStamp()
Resets the matrix time stamp.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setTimeStamp
protected:
void setTimeStamp(unsigned long)
Sets the time stamp of the matrix object.

long
The new time stamp value.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Streaming a Matrix Object In and Out

Use the functions and operators in this group to stream a matrix object in and out.


[view class]
operator <<=
public:
IDataStream& operator <<=(IDataStream&)
Operator that streams in the graphics matrix object from the stream specified.

inStream
A reference to the stream from which the object is streamed in.

Return
A reference to the original data stream.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
operator >>=
public:
IDataStream& operator >>=(IDataStream&) const
Operator that streams out the graphics matrix object to the stream specified.

outStream
A reference to the stream to which the object is written.

Return
A reference to the original data stream.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
readFromStream
public:
void readFromStream(IDataStream& toWhere)
Streams the matrix object in from the stream specified by fromWhere.

fromWhere
The stream used to stream in the matrix object.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
writeToStream
public:
void writeToStream(IDataStream& toWhere) const
Writes the IGrafMatrix object out to the specified stream.

toWhere
A constant reference to the stream to be used.

Return
The original data stream.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Testing Two Matrices for Equality or Inequality

Use the operators in this group to test two matrices for equality.


[view class]
operator !=
public:
virtual bool operator !=(const IGrafMatrix&) const
Tests the two IGrafMatrix obiects for inequality.

rhs
A constant reference to the matrix to compare with.

Return
True if any corresponding elements in two matrices have different values.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
operator ==
public:
virtual bool operator ==(const IGrafMatrix&) const
Tests the two IGrafMatrix objects for equality.

rhs
A constant reference to the matrix to compare with.

Return
True if all the corresponding elements in two matrices are the same.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Miscellaneous Members


[view class]
updateTimeStamp
protected:
void updateTimeStamp()
Updates the matrix object time stamp.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


IGrafMatrix - Enumerations


[view class]
EMatrixIndex
enum EMatrixIndex { kScaleX=0, 
                    kShearY=1, 
                    kPerspectiveX=2, 
                    kShearX=3, 
                    kScaleY=4, 
                    kPerspectiveY=5, 
                    kTranslateX=6, 
                    kTranslateY=7, 
                    kHomogeneous=8 }
EMatrixIndex defines the index values for the nine-element matrix array

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
EMatrixType
enum EMatrixType { kIdentity, 
                   kRotate, 
                   kTranslate, 
                   kScale, 
                   kAffine, 
                   kPerspective }
EMatrixType defines the type of transformation matrix.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


IGrafMatrix - Inherited Member Functions and Data

Inherited Public Functions

Inherited Public Data

Inherited Protected Functions

Inherited Protected Data