### 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

### IGrafMatrix - Enumerations

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

  - None

#### Inherited Public Data

  - None

#### Inherited Protected Functions

  - None

#### Inherited Protected Data

  - None