Class: TGrafMatrix

Declaration: Transforms.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

MCollectible

Inherited By:

None.

Purpose:

TGrafMatrix provides a transformation matrix that performs 2-D linear transformations for homogeneous spaces. Transformation matrices are used to move, resize, and reshape 2-D graphical objects. A 2-D transformation matrix is an array of numbers with three rows and three columns, used to perform algebraic operations on a set of coordinates that define a graphical object. For example, translation, scaling, and rotation are simple 2-D transformations. Translation means moving an object in the 2-D coordinate plane without changing its shape, size, or orientation; scaling means changing an object's size and possibly its shape by multiplying its x-coordinates by some number and its y-coordinates by some other number; rotation means changing an object's orientation (for example, turning it upside down) without changing its size or shape. Successive matrix operations can be performed on an object. In general, the result depends on the order in which the operations are performed. Any sequence of translation, scaling, and rotation produces a result in which parallel lines are preserved, but angles and line segment lengths might not be preserved; such sequences are known as affine transformations. A shear transformation is an affine transformation in which the amount by which every point's x-coordinate is changed is proportional to its y-coordinate, which remains unchanged--or, similarly, a transformation in which every y-coordinate is changed in proportion to an unchanged x-coordinate. TGrafMatrix transforms objects in homogeneous space. Points in homogeneous space are rational points, represented by TGRPoints rather than TGPoints. They have three coordinates, even though they represent 2-D spaces. The third coordinate, called w, is used by TGrafMatrix for creating a perspective effect and for rotation around an arbitrary point. (TGPoints have an implied w of 1.0.) Homogeneous linear transformations are different from general linear transformations in that they allow translations and perspective transformations. (General linear transformations, which use a regular, non-homogeneous space, only allow scale, shear, and rotate as multiplicative operations. Translation requires matrix addition. In a homogeneous space, by contrast, translation is performed by multiplication, as are the other transformations, allowing a uniform and consistent approach.) It is important to note that scaling a homogeneous matrix by a scalar does not change how it transforms a TGPoint. On the other hand, rational points exist in homogeneous space, so scaling a homogeneous matrix by a scalar does change how it transforms a TGRPoint. TGrafMatrix supplies several ready-made member functions so that you can specify transformations without being concerned with the actual numbers in the matrix. For example, TranslateBy sets up the matrix so that it translates points by the specified vector--you don't need to figure out what 3 x 3 matrix actually performs this translation. Similarly, ScaleBy sets up a matrix that scales objects by the given horizontal and vertical scalars, and RotateBy sets up a matrix that rotates objects by an angle specified in degrees. To set up a transformation that first translates and then rotates and object, you just call TranslateBy, followed by RotateBy. The TGrafMatrix itself stores the cumulative transformation, so you can apply this single TGrafMatrix to various objects instead of having to translate and then rotate each one explicitly. To create a sequence of arbitrary transformations (rather than just translation, scaling, and rotation), use TGrafMatrix::ConcatWith. This function concatenates two transformation matrices, so that during a transformation, each point passes first through one matrix, then the next. In this way, a TGrafMatrix can represent any number of concatenated transformations. ConcatWith places the specified transformation matrix after the existing transformation. Because transformations are generally not commutative (that is, it matters what order they occur in), TGrafMatrix::PreConcatWith is supplied. TGrafMatrix::PreConcatWith places the specified transformation matrix before the existing one, so that the specified transformation is performed before the transformation (or sequence of transformations) that was previously set for this TGrafMatrix. An easy way to define a transformation matrix is by specifying what a convex quadrilateral (four-sided polygon) looks like before and after the transformation. This technique is known as a perspective map. TGrafMatrix provides a ready-made member function called SetToPerspectiveMap for this purpose. You can use a perspective map to define all of the standard transformations. For example, you can define translation by specifying a source quadrilateral, along with a destination quadrilateral that is the same as the source, but moved some distance horizontally and vertically. Similarly, scaling can be defined by making the destination quadrilateral larger or smaller than the source, and a rotation matrix can be defined by rotating the quadrilateral. You can even easily describe shear transformations. However, the real power of this member function lies in its ability to describe arbitrary affine transformations and perspective transformations. If the source and destination are parallelograms, the resulting matrix is affine. If the sides are not parallel, the matrix is a perspective matrix, and the point of intersection is the vanishing point. By using the ready-made member functions, you can (in most cases) avoid having to specify or even know about the numbers in the matrix itself. However, for advanced uses, one of the TGrafMatrix constructors takes a specified array of numbers, and TGrafMatrix::GetMatrix, TGrafMatrix::GetElement, and TGrafMatrix::SetElement provide access to the matrix. The array elements are laid out as follows: the three elements in the top row are scaleX, shearY, and perspectiveX; the second row is shearX, scaleY, and perspectiveY, and the bottom row is translateX, translateY, and homogeneous. Applying the matrix to a rational point (x,y,w) yields a point (x',y',w'), where x' =x*scaleX + y*shearX+ w*translateX; y' =x*shearY + y*scaleY + w*translateY; and w' =x*perspectiveX + y*perspectiveY + w*homogeneous. Note that TGrafMatrix does not provide a general linear algebra package. For instance, it does not solve sets of linear equations or eigenvalue problems, and it does not have arbitrary dimension. Instead, it is designed specifically for the kinds of linear transformations needed by Taligent's geometries, rendering pipeline, MGraphics, and GrafEdit. TGrafMatrix can be instantiated directly. All of the public member functions of TGrafMatrix can be called directly.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

None. Derivation is not recommended because TGrafMatrix contains built-in acceleration that is likely to be forfeited if you override its member functions.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TGrafMatrix::GetIdentity

static const TGrafMatrix & GetIdentity ()

Interface Category:

API.

Purpose:

Allows the client to efficiently specify an identity matrix.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

A static reference to a constant identity matrix.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafMatrix::TGrafMatrix

TGrafMatrix ()
TGrafMatrix (const TGrafMatrix & matrix)
TGrafMatrix (const GCoordinate matrix [])
TGrafMatrix (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)
TGrafMatrix (const TGPoint & delta)
TGrafMatrix (const TGPoint & scale, const TGPoint & centerOfScale)
TGrafMatrix (const GDegrees & angle, const TGPoint & centerOfRotate)
TGrafMatrix (const TGQuadrilateral & fromQuadrilateral, const TGQuadrilateral & toQuadrilateral)

Interface Category:

API.

Purpose:

Default constructor.
Copy constructor.
Creates a matrix from an array of matrix elements.
Creates a matrix from a set of matrix elements.
Creates a translation matrix.
Creates a matrix that scales around the specified point.
Creates a matrix that rotates around the specified point.
Creates a matrix from the perspective mapping of the first parameter to the second one.

Calling Context:

Called by the stream-in operators. You can also call this function directly.
Called to copy an object. You can also call this function directly.
Call this function directly.
Call this function directly.
Call this function directly.
Call this function directly.
Call this function directly.
Call this function directly.

Parameters:

Takes no parameters.
const TGrafMatrix & matrix -The matrix to be copied.
const GCoordinate matrix [] -The nine-element array to be converted into a matrix.
const GCoordinate scaleX -The scaling factor for the x-coordinate.
const GCoordinate shearY -The shearing factor for the y-coordinate.
const GCoordinate perspectiveX -The perspective factor for the x-coordinate.
const GCoordinate shearX -The shearing factor for the x-coordinate.
const GCoordinate scaleY -The scaling factor for the y-coordinate.
const GCoordinate perspectiveY -The perspective factor for the y-coordinate.
const GCoordinate translateX -The translation factor for the x-coordinate.
const GCoordinate translateY -The translation factor for the y-coordinate.
const GCoordinate homogeneous -The homogeneous factor for the matrix.
const TGPoint & delta -The point that the matrix is to be translated to.
const TGPoint & scale -The scaling factor. If the scale is greater than 1, the graphic is enlarged, if the factor is between 0 and 1, it is reduced, and if less than 0, it is mirrored.
const TGPoint & centerOfScale -The center point for the scaling operation.
const GDegrees & angle -The degree to rotate the graphic by.
const TGPoint & centerOfRotate -The center point for the rotation operation.
const TGQuadrilateral & fromQuadrilateral -The quadrilateral that represents the graphic before transformation.
const TGQuadrilateral & toQuadrilateral -The quadrilateral that represents the graphic after transformation.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.
Throws no exceptions, passes all exceptions through.
Throws no exceptions, passes all exceptions through.
Throws no exceptions, passes all exceptions through.
Throws no exceptions, passes all exceptions through.
Throws no exceptions, passes all exceptions through.
Throws no exceptions, passes all exceptions through.
Throws a kSingularTransform TTransformException exception if either of the quadrilaterals is degenerate.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafMatrix::~TGrafMatrix

virtual ~ TGrafMatrix ()

Interface Category:

API.

Purpose:

Destructor.

Calling Context:

Called to destroy an object.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafMatrix::TransformPoint

virtual TGRPoint TransformPoint (const TGRPoint & source) const
virtual TGPoint TransformPoint (const TGPoint & source) const

Interface Category:

API.

Purpose:

Transforms a rational point to another rational point.
Transforms a point to another point.

Calling Context:

Call this function directly.
Call this function directly.

Parameters:

const TGRPoint & source -The rational point to be transformed.
const TGPoint & source -The point to be transformed.

Return Value:

The transformed point.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafMatrix::UntransformPoint

virtual TGRPoint UntransformPoint (const TGRPoint & source) const
virtual TGPoint UntransformPoint (const TGPoint & source) const

Interface Category:

API.

Purpose:

Passes a rational point backwards through this transformation matrix. If the transform is not invertible, it raises a kSingularTransform TTransformException.
Passes a point backwards through this transformation matrix. If the transform is not invertible, it raises a kSingularTransform TTransformException.

Calling Context:

Call this function directly.
Call this function directly.

Parameters:

const TGRPoint & source -The rational point to untransform.
const TGPoint & source -The point to untransform.

Return Value:

The untransformed point.

Exceptions:

Throws kSingularTransform TTransformException if the matrix is not invertible.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafMatrix::TransformPoints

virtual void TransformPoints (const TGRPoint points [], TGRPoint transformPoints [], unsigned long count =1) const
virtual void TransformPoints (TGRPointArray & points) const
virtual void TransformPoints (const TGPoint points [], TGPoint transformPoints [], unsigned long count =1) const
virtual void TransformPoints (TGPointArray & points) const

Interface Category:

API.

Purpose:

Transforms the first array of rational points efficiently. Returns the transformed points in the second parameter.
Transforms the specified array of rational points.
Transform an array of points efficiently. Returns the transformed points in the second parameter.
Transforms the specified array of points.

Calling Context:

Call this function directly.
Call this function directly.
Call this function directly.
Call this function directly.

Parameters:

const TGRPoint points [] -The source array of rational points.
TGRPoint transformPoints [] -The destination array of rational points. The destination array can be the same as the array of source points. You must allocate the array before you make the call.
unsigned long count =1 -The number of points in the array.
TGRPointArray & points -The array of rational points to be transformed and returned.
const TGPoint points [] -The source array of points.
TGRPoint transformPoints [] -The destination array of points. The destination array can be the same as the array of source points. You must allocate the array before you make the call.
unsigned long count =1 -The number of points in the array.
TGPointArray & points -The array of points to be transformed and returned.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafMatrix::TransformVector

virtual TGPoint TransformVector (const TGPoint & source) const

Interface Category:

API.

Purpose:

Interprets TGPoint as a vector. It only transforms the magnitude and direction of the vector.

Calling Context:

Call this function directly.

Parameters:

const TGPoint & source -The vector to transform.

Return Value:

The transformed vector.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafMatrix::UntransformVector

virtual TGPoint UntransformVector (const TGPoint & source) const

Interface Category:

API.

Purpose:

Passes a vector backwards through the transformation.

Calling Context:

Call this function directly.

Parameters:

const TGPoint & source -The vector to transform.

Return Value:

The transformed vector.

Exceptions:

Throws kSingularTransform TTransformException if the matrix is not invertible.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafMatrix::TransformBounds

virtual TGRect TransformBounds (const TGRect & r) const

Interface Category:

API.

Purpose:

Transforms the corners of the specified TGRect, and finds the bounding box of these corners.

Calling Context:

Call this function directly.

Parameters:

const TGRect & r -The rectangle to be transformed.

Return Value:

The transformed rectangle.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafMatrix::UntransformBounds

virtual TGRect UntransformBounds (const TGRect & r) const

Interface Category:

API.

Purpose:

Passes the specified TGRect backwards through the transformation.

Calling Context:

Call this function directly.

Parameters:

const TGRect & r -The rectangle to be untransformed.

Return Value:

The untransformed rectangle.

Exceptions:

Throws eSingularTransform TTransformException exception if the matrix is singular, or an assertion that fails if the matrix is of an unknown type.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafMatrix::ConcatWith

virtual void ConcatWith (const TGrafMatrix & matrix)

Interface Category:

API.

Purpose:

Multiplies this matrix by another matrix. Concatenation is not commutative.

Calling Context:

Call this function directly.

Parameters:

const TGrafMatrix & matrix -The matrix to be concatenated to this one.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafMatrix::TranslateBy

virtual void TranslateBy (const TGPoint & delta)

Interface Category:

API.

Purpose:

Concatenates this matrix by a translation matrix that has translation values set to delta.

Calling Context:

Call this function directly.

Parameters:

const TGPoint & delta -The translation amount.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafMatrix::ScaleBy

virtual void ScaleBy (const TGPoint & scale, const TGPoint & centerOfScale =TGPoint :: kOrigin)

Interface Category:

API.

Purpose:

Concatenates this matrix by a scale matrix. The scaling is about the specified center of scale.

Calling Context:

Call this function directly.

Parameters:

const TGPoint & scale -The scaling factor.
const TGPoint & centerOfScale =TGPoint :: kOrigin -The center point of the scaling transformation.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafMatrix::RotateBy

virtual void RotateBy (GDegrees degrees, const TGPoint & centerOfRotate =TGPoint :: kOrigin)

Interface Category:

API.

Purpose:

Concatenates this matrix with a rotate matrix. The rotation is about the specified center of rotation.

Calling Context:

Call this function directly.

Parameters:

GDegrees degrees -The degrees of the rotation.
const TGPoint & centerOfRotate =TGPoint :: kOrigin -The center point of the rotation transformation.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafMatrix::PreConcatWith

virtual void PreConcatWith (const TGrafMatrix & matrix)

Interface Category:

API.

Purpose:

Sets this matrix to another matrix, multiplied by this matrix. Concatenation is not commutative.

Calling Context:

Call this function directly.

Parameters:

const TGrafMatrix & matrix -The other matrix.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafMatrix::PreTranslateBy

virtual void PreTranslateBy (const TGPoint & delta)

Interface Category:

API.

Purpose:

Constructs a translation matrix out of the specified delta values and preconcatenates with this matrix.

Calling Context:

Call this function directly.

Parameters:

const TGPoint & delta -The translation factor.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafMatrix::PreScaleBy

virtual void PreScaleBy (const TGPoint & scale, const TGPoint & centerOfScale =TGPoint :: kOrigin)

Interface Category:

API.

Purpose:

Constructs a scale matrix out of the specified scaling factor and preconcatenates with this matrix. The scaling is centered around the specified point.

Calling Context:

Call this function directly.

Parameters:

const TGPoint & scale -The scaling factor.
const TGPoint & centerOfScale =TGPoint :: kOrigin -The center of the scaling transformation.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafMatrix::PreRotateBy

virtual void PreRotateBy (GDegrees degrees, const TGPoint & centerOfRotate =TGPoint :: kOrigin)

Interface Category:

API.

Purpose:

Constructs a rotation matrix out of the specified rotation factor and preconcatenates with this matrix. The rotation is centered around the specified point.

Calling Context:

Call this function directly.

Parameters:

GDegrees degrees -The degrees of the rotation.
const TGPoint & centerOfRotate =TGPoint :: kOrigin -The center of the rotation transformation.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None,

Member Function: TGrafMatrix::SetToIdentity

virtual void SetToIdentity ()

Interface Category:

API.

Purpose:

Sets this TGrafMatrix to an identity matrix (that is, one that does nothing to a point).

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafMatrix::SetToTranslate

virtual void SetToTranslate (const TGPoint & delta)

Interface Category:

API.

Purpose:

Sets this TGrafMatrix so that its translation components (kTranslateX and kTranslateY) are set to the coordinates of the specified TGPoint.

Calling Context:

Call this function directly.

Parameters:

const TGPoint & delta -The new location.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafMatrix::SetToScale

virtual void SetToScale (const TGPoint & scale, const TGPoint & centerOfScale =TGPoint :: kOrigin)

Interface Category:

API.

Purpose:

Sets this TGrafMatrix so that its scaling components (kScaleX and kScaleY) are equal to the coordinates of the specified TGPoint.

Calling Context:

Call this function directly.

Parameters:

const TGPoint & scale -The scaling factor.
const TGPoint & centerOfScale =TGPoint :: kOrigin -The center of the scaling transformation.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafMatrix::SetToRotate

virtual void SetToRotate (GDegrees degrees, const TGPoint & centerOfRotate =TGPoint :: kOrigin)

Interface Category:

API.

Purpose:

Resets this TGrafMatrix to one that rotates around the specified point.

Calling Context:

Call this function directly.

Parameters:

GDegrees degrees -The rotation angle in degrees.
const TGPoint & centerOfRotate =TGPoint :: kOrigin -The center of the rotation transformation.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafMatrix::SetToPerspectiveMap

virtual void SetToPerspectiveMap (const TGQuadrilateral & fromQuadrilateral, const TGQuadrilateral & toQuadrilateral)

Interface Category:

API.

Purpose:

Sets this matrix to one that transforms the first TGQuadrilateral into the second one. If the source and destination are parallelograms, the resulting matrix is affine. If the sides are not parallel, the matrix is a perspective matrix, and the point of intersection is the vanishing point.

Calling Context:

Call this function directly.

Parameters:

const TGQuadrilateral & fromQuadrilateral -The source quadrilateral.
const TGQuadrilateral & toQuadrilateral -The destination quadrilateral.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

The quadrilaterals must be convex (that is, having no lines that intersect).

Member Function: TGrafMatrix::GetMatrix

virtual GCoordinate * GetMatrix (GCoordinate matrix []) const

Interface Category:

API.

Purpose:

Fills in a nine-element array with matrix element values. You must preallocate the array before making this call. Use EMatrixIndex to access the matrix elements.

Calling Context:

Call this function directly.

Parameters:

GCoordinate matrix [] -The array for the elements of the matrix.

Return Value:

Returns a pointer to the array that contains the elements of the matrix.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafMatrix::GetRotate

virtual bool GetRotate (GDegrees & degrees, TGPoint & centerOfRotate) const

Interface Category:

API.

Purpose:

Returns the angle of rotation (between 0 and 360 degrees) and the center of rotation in the respective parameters. It returns true if and only if the matrix is a rotation matrix.

Calling Context:

Call this function directly.

Parameters:

GDegrees & degrees -The degrees of rotation of the matrix.
TGPoint & centerOfRotate -The center of the rotation.

Return Value:

Returns true if the matrix is a rotation matrix.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafMatrix::GetType

virtual EMatrixType GetType () const

Interface Category:

API.

Purpose:

Determines what type of matrix this is (that is, either kIdentity, kTranslate, kScale, kRotate, kAffine, or kPerspective).

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns the type of matrix.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

If the TGrafMatrix is uninitialized, the type kIdentity is returned.

Member Function: TGrafMatrix::IsIdentity

virtual bool IsIdentity () const

Interface Category:

API.

Purpose:

Determines whether this TGrafMatrix is an identity matrix (that is, does not transform the matrix).

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns true if the matrix is of type kIdentity or is a kRotate matrix with 0 degrees rotation.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafMatrix::IsTranslate

virtual bool IsTranslate () const

Interface Category:

API.

Purpose:

Determines whether this TGrafMatrix is a translate matrix.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns true if the matrix is of type kTranslate. It also returns true if the matrix is of type kIdentity or a kRotate matrix with 0 degrees rotation.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafMatrix::IsAffine

virtual bool IsAffine () const

Interface Category:

API.

Purpose:

Determines whether the matrix is affine (that is, perspectiveX =0, perspectiveY =0, and homogeneous =1.0). A rectangle passed through an affine matrix is a parallelogram.

Calling Context:

Call this function directly.

Return Value:

Returns true if the matrix is affine.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafMatrix::IsRectilinear

virtual bool IsRectilinear () const

Interface Category:

API.

Purpose:

Determines whether a rectangle passed through the matrix is still a rectangle.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns true if a rectangle passed through the matrix is still a rectangle.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafMatrix::Invert

virtual void Invert ()

Interface Category:

API.

Purpose:

Inverts this TGrafMatrix.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws a kSingularTransform TTransformException if a matrix is not invertible.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafMatrix::GetDeterminant

virtual GCoordinate GetDeterminant () const

Interface Category:

API.

Purpose:

Gets the determinant of this TGrafMatrix. If the determinant is 0, a matrix is not invertible.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

The determinant of the matrix.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafMatrix::Transpose

virtual void Transpose ()

Interface Category:

API.

Purpose:

Transposes this TGrafMatrix (that is, swaps the rows and columns of the matrix).

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafMatrix::MakeAdjoint

virtual void MakeAdjoint ()

Interface Category:

API.

Purpose:

Converts this TGrafMatrix to its Classical Adjoint.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafMatrix::Normalize

virtual bool Normalize ()

Interface Category:

API.

Purpose:

Divides the TGrafMatrix by the homogeneous value.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns true if the homogenous value is nonzero.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafMatrix::GetElement

virtual GCoordinate GetElement (EMatrixIndex) const

Interface Category:

API.

Purpose:

Uses EMatrixIndex to get a particular element out of the TGrafMatrix.

Calling Context:

Call this function directly.

Parameters:

EMatrixIndex -The index of the particular element.

Return Value:

The element at the specified index.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafMatrix::SetElement

virtual void SetElement (EMatrixIndex, GCoordinate element)

Interface Category:

API.

Purpose:

Sets the specified element in the TGrafMatrix.

Calling Context:

Call this function directly.

Parameters:

EMatrixIndex -The index of the particular element.
GCoordinate element -The new value for the element.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Do not use this member function unless the provided TGrafMatrix interface is insufficient. Calling this member function can hurt the operations that are performed later to this matrix.

Member Function: TGrafMatrix::operator=

TGrafMatrix & operator =(const TGrafMatrix & source)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Called when an object is assigned to another compatible object. You can also call this function by using the operator in an assignment statement.

Parameters:

const TGrafMatrix & source -The object to be copied.

Return Value:

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

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafMatrix::operator*=

TGrafMatrix & operator *= (const TGrafMatrix & matrix)

Interface Category:

API.

Purpose:

Concatenates the left operand by the right operand and sets the left operand to the new value.

Calling Context:

Call this function by using the operator in an assignment statement.

Parameters:

const TGrafMatrix & matrix -The matrix to be concatenated with this one.

Return Value:

The concatenated matrix.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This is just a pseudonym for TGrafMatrix::ConcatWith.

Member Function: TGrafMatrix::GetTimeStamp

TPseudoTimeStamp GetTimeStamp () const

Interface Category:

API.

Purpose:

Returns the time stamp for this TGrafMatrix.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

The time stamp.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafMatrix::Hash

virtual long Hash () const

Interface Category:

API.

Purpose:

Returns a hashing key for this TGrafMatrix.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

The hashing key.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafMatrix::operator>>=

virtual TStream & operator >>=(TStream & towhere) const

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Called to stream out data.

Parameters:

TStream & towhere -The stream that the object is streamed out to.

Return Value:

Returns a reference to the stream the object streams itself out to.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafMatrix::operator<<=

virtual TStream & operator <<= (TStream & fromwhere)

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Called to stream in data.

Parameters:

TStream & fromwhere -The stream that the object is streamed in from.

Return Value:

Returns a reference to the stream the object streams itself in from.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafMatrix::UpdateTimeStamp

void UpdateTimeStamp ()

Interface Category:

API.

Purpose:

Increments the seed value.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafMatrix::ResetTimeStamp

void ResetTimeStamp ()

Interface Category:

API.

Purpose:

Resets the seed value to zero.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafMatrix::SetTimeStamp

void SetTimeStamp (TPseudoTimeStamp)

Interface Category:

API.

Purpose:

Sets the seed value of the TGrafMatrix.

Calling Context:

Call this function directly.

Parameters:

TPseudoTimeStamp -The new seed value.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Click the icon to mail questions or corrections about this material to Taligent personnel.