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.
- ~IGrafMatrix
public:
virtual ~IGrafMatrix()
- Destroys the matrix.
- Supported Platforms
Windows |
OS/2 |
AIX |
Yes |
Yes |
Yes |
- 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.
- 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.
- 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 |
- 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 |
- 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.
- 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 |
- 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 |
- 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 |
- makeAdjoint
public:
virtual void makeAdjoint()
- Converts this IGrafMatrix to its classical adjoint.
- Supported Platforms
Windows |
OS/2 |
AIX |
Yes |
Yes |
Yes |
- 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 |
- 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 |
- 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 |
- 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 |
- 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 |
- 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 |
- 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 |
- 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 |
- 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 |
- 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 |
- 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 |
- 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 |
- 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 |
- 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.
- 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 |
- 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 |
- 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 |
- 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 |
- 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 |
- 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 |
- 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 |
- 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 |
- 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 |
- 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.
- 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 |
- setToIdentity
public:
virtual void setToIdentity()
- Sets this IGrafMatrix to an identity matrix.
- Supported Platforms
Windows |
OS/2 |
AIX |
Yes |
Yes |
Yes |
- 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 |
- 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 |
- 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 |
- 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 |
- resetTimeStamp
protected:
void resetTimeStamp()
- Resets the matrix time stamp.
- Supported Platforms
Windows |
OS/2 |
AIX |
Yes |
Yes |
Yes |
- 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.
- 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 |
- 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 |
- 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 |
- 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.
- 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 |
- 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
- updateTimeStamp
protected:
void updateTimeStamp()
- Updates the matrix object time stamp.
- Supported Platforms
Windows |
OS/2 |
AIX |
Yes |
Yes |
Yes |
- 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 |
- 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