Class: TGrafMatrix3D

Declaration: Transforms3D.h

Taxonomy Categories:

Member Functions:

TGrafMatrix3D
~TGrafMatrix3D
GetIdentity
GetMatrix
TransformPoint
TransformPoints
UntransformPoint
TransformVector
UntransformVector
TransformBounds
UntransformBounds
SetToIdentity
SetToTranslate
SetToScale
TranslateBy
ScaleBy
PreTranslateBy
PreScaleBy
ConcatWith
PreConcatWith
IsIdentity
IsTranslate
IsScale
IsRotate
IsAffine
Reorthogonalize
Transpose
MakeAdjoint
Normalize
Invert
GetDeterminant
GetElement
SetElement
operator=
operator*=
operator>>=
operator<<=
Hash
GetTimeStamp
UpdateTimeStamp
ResetTimeStamp
SetTimeStamp
PreRotateBy
RotateBy
SetToRotate

Interface Category:

API.

Inherits From:

MCollectible

Inherited By:

None.

Purpose:

TGrafMatrix3D provides general operations for use in 3-D transformation, just as TGrafMatrix provides 2-D transformations. TGrafMatrix3D is optimized for the 4 x 4 square matrix that is most often used by 3-D graphics. TGrafMatrix3D::GMatrix3D is supposed to be a 4 x 4 matrix; it is defined as: kScaleX kShearYX kShearZX kPerspectiveX kShearXY kScaleY kShearZY kPerspectiveY kShearXZ kShearYZ kScaleZ kPerspectiveZ kTranslateX kTranslateY kTranslateZ kHomogeneous When a TGrafMatrix3D is constructed, it is well defined. The empty constructor constructs the matrix as identity. The constructor also can take either a 2-D matrix or 3-D matrix. A 2-D matrix converts to a 3-D matrix as follows: kScaleX kShearY 0.0 kPerspectiveX kShearX kScaleY 0.0 kPerspectiveY

0.0 0.0 1.0 0.0

TGrafMatrix3D

TGrafMatrix

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

None.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TGrafMatrix3D::TGrafMatrix3D

TGrafMatrix3D ()
TGrafMatrix3D (const TGrafMatrix &)
TGrafMatrix3D (const GMatrix3D)
TGrafMatrix3D (const GCoordinate scaleX, const GCoordinate shearYX, const GCoordinate shearZX, const GCoordinate perspectiveX, const GCoordinate shearXY, const GCoordinate scaleY, const GCoordinate shearZY, const GCoordinate perspectiveY, const GCoordinate shearXZ, const GCoordinate shearYZ, const GCoordinate scaleZ, const GCoordinate perspectiveZ, const GCoordinate translateX, const GCoordinate translateY, const GCoordinate translateZ, const GCoordinate homogeneous)
TGrafMatrix3D (const TGrafMatrix3D &)
TGrafMatrix3D (const TGPoint3D & delta)
TGrafMatrix3D (const TGPoint3D & scale, const TGPoint3D & centerOfScale)
TGrafMatrix3D (GDegrees angle, EAxis axis)
TGrafMatrix3D (GDegrees angle, const TGLine3D & ray)
TGrafMatrix3D (const TGLine3D & vector0, const TGLine3D & vector1)

Interface Category:

API.

Purpose:

Default constructor.
Creates a matrix from the given 2-D matrix.
Creates a matrix from an array of matrix elements GMatrix3D.
Creates a matrix from a set of matrix elements.
Copy constructor.
Creates a translation matrix.
Creates a matrix that scales around the specified point.
Creates a matrix that rotates about the specified axis.
Creates a matrix that rotates about the specified ray.
Creates a matrix that rotates a given ray about another ray.

Calling Context:

Called by the stream-in operators. You can also call this function directly.
Call this function directly.
Call this function directly.
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.

Parameters:

Takes no parameters.
const TGrafMatrix & -The 2-D matrix used to construct the 3-D matrix.
const GMatrix3D -The array of sixteen elements to be converted into a matrix.
const GCoordinate scaleX -The scaling factor for the x-coordinate.
const GCoordinate shearYX -The shearing factor for the yx-coordinate.
const GCoordinate shearZX -The shearing factor for the zx-coordinate.
const GCoordinate perspectiveX -The perspective factor for the x-coordinate.
const GCoordinate shearXY -The shearing factor for the xy-coordinate.
const GCoordinate scaleY -The scaling factor for the y-coordinate.
const GCoordinate shearZY -The shearing factor for the zy-coordinate.
const GCoordinate perspectiveY -The perspective factor for the y-coordinate.
const GCoordinate shearXZ -The shearing factor for the xz-coordinate.
const GCoordinate shearYZ -The shearing factor for the yz-coordinate.
const GCoordinate scaleZ -The scaling factor for the z-coordinate.
const GCoordinate perspectiveZ -The perspective factor for the z-coordinate.
const GCoordinate translateX -The translation factor for the x-coordinate.
const GCoordinate translateY -The translation factor for the y-coordinate.
const GCoordinate translateZ -The translation factor for the z-coordinate.
const GCoordinate homogeneous -The homogeneous factor for the matrix.
const TGrafMatrix3D & -The matrix to be copied.
const TGPoint3D & delta -The point that the matrix is to be translated to.
const TGPoint3D & 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 TGPoint3D & centerOfScale -The center point for the scaling operation.
GDegrees angle -The degree to rotate the graphic by.
EAxis axis -The axis where the graphic is rotated about.
GDegrees angle -The degree to rotate the graphic by.
const TGLine3D & ray -The ray where the graphic is rotated about.
const TGLine3D & vector0 -The ray specifies how much the graphics is to be rotated.
const TGLine3D & vector1 -The ray where the graphic is rotated about.

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 no exceptions, passes all exceptions through.
Throws a eUndefined TTransformException exception if the axis is undefined.
Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafMatrix3D::~TGrafMatrix3D

virtual ~ TGrafMatrix3D ()

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: TGrafMatrix3D::GetIdentity

static const TGrafMatrix3D & GetIdentity ()

Interface Category:

API.

Purpose:

Allows you 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: TGrafMatrix3D::GetMatrix

virtual GMatrix3D & GetMatrix (GMatrix3D & matrix) const

Interface Category:

API.

Purpose:

Fills in a 16-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:

GMatrix3D & matrix -The array for the elements of the matrix.

Return Value:

Returns an object of type GMatrix3D that contains the elements of the matrix.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafMatrix3D::TransformPoint

virtual TGPoint3D TransformPoint (const TGPoint3D & source) const
virtual TGRPoint3D TransformPoint (const TGRPoint3D & 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 TGPoint3D & source -The rational point to be transformed.
const TGRPoint3D & 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: TGrafMatrix3D::TransformPoints

virtual void TransformPoints (const TGPoint3D points [], TGPoint3D transformPoints [], unsigned long n =1) const
virtual void TransformPoints (const TGRPoint3D points [], TGRPoint3D transformPoints [], unsigned long n =1) const
virtual void TransformPoints (TGPoint3DArray & points) const
virtual void TransformPoints (TGRPoint3DArray & points) const

Interface Category:

API.

Purpose:

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

Calling Context:

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

Parameters:

const TGPoint3D points [] -The source array of points.
TGPoint3D 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 n =1 -The number of points in the array.
const TGRPoint3D points [] -The source array of rational points.
TGRPoint3D 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 n =1 -The number of points in the array.
TGPoint3DArray & points -The array of points to be transformed and returned.
TGRPoint3DArray & points -The array of rational 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: TGrafMatrix3D::UntransformPoint

virtual TGPoint3D UntransformPoint (const TGPoint3D & source) const
virtual TGRPoint3D UntransformPoint (const TGRPoint3D & source) const

Interface Category:

API.

Purpose:

Passes a point backwards through this transformation matrix. If the transform is not invertible, it raises a kSingularTransform TTransformException.
Passes a rational 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 TGPoint3D & source -The point to untransform.
const TGRPoint3D & source -The rational point to untransform.

Return Value:

The untransformed point.

Exceptions:

If the transform is not invertible, it raises a kSingularTransform TTransformException.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafMatrix3D::TransformVector

virtual TGPoint3D TransformVector (const TGPoint3D & direction) const

Interface Category:

API.

Purpose:

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

Calling Context:

Call this function directly.

Parameters:

const TGPoint3D & direction -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: TGrafMatrix3D::UntransformVector

virtual TGPoint3D UntransformVector (const TGPoint3D & direction) const

Interface Category:

API.

Purpose:

Passes a vector backwards through the transformation.

Calling Context:

Call this function directly.

Parameters:

const TGPoint3D & direction -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: TGrafMatrix3D::TransformBounds

virtual TGBox3D TransformBounds (const TGBox3D & b) const

Interface Category:

API.

Purpose:

Transforms the two diagonals of an axis-aligned TGBox3D, and finds the bounding box of these corners.

Calling Context:

Call this function directly.

Parameters:

const TGBox3D & b -The box to be transformed.

Return Value:

The transformed box.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafMatrix3D::UntransformBounds

virtual TGBox3D UntransformBounds (const TGBox3D & b) const

Interface Category:

API.

Purpose:

Passes the specified TGBox3D backwards through the transformation.

Calling Context:

Call this function directly.

Parameters:

const TGBox3D & b -The box to be untransformed.

Return Value:

The untransformed box.

Exceptions:

Throws eSingularTransform TTransformException exception if the matrix is singular.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafMatrix3D::SetToIdentity

virtual void SetToIdentity ()

Interface Category:

API.

Purpose:

Sets this TGrafMatrix3D to an identity 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: TGrafMatrix3D::SetToTranslate

virtual void SetToTranslate (const TGPoint3D & newPosition)

Interface Category:

API.

Purpose:

Sets this TGrafMatrix3D so that its translation components (kTranslateX, kTranslateY, and kTranslateZ) are set to the coordinates of the specified TGPoint3D.

Calling Context:

Call this function directly.

Parameters:

const TGPoint3D & newPosition -The new position.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafMatrix3D::SetToScale

virtual void SetToScale (const TGPoint3D & scaleFactor, const TGPoint3D & centerOfScale =TGPoint3D :: kOrigin)

Interface Category:

API.

Purpose:

Sets this TGrafMatrix3D so that its scaling components (kScaleX, kScaleY, and kScaleZ) are set to the coordinates of the specified TGPoint3D.

Calling Context:

Call this function directly.

Parameters:

const TGPoint3D & scale -The scaling factor.
const TGPoint3D & centerOfScale =TGPoint3D :: 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: TGrafMatrix3D::TranslateBy

virtual void TranslateBy (const TGPoint3D & 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 TGPoint3D & delta -The translation amount.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafMatrix3D::ScaleBy

virtual void ScaleBy (const TGPoint3D & delta, const TGPoint3D & centerOfScale =TGPoint3D :: kOrigin)

Interface Category:

API.

Purpose:

Concatenates this matrix by a scale matrix that has scale factors set to delta. The scaling is about the specified center of scale.

Calling Context:

Call this function directly.

Parameters:

const TGPoint3D & scale -The scaling factor.
const TGPoint3D & 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: TGrafMatrix3D::PreTranslateBy

virtual void PreTranslateBy (const TGPoint3D & 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 TGPoint3D & delta -The translation factor.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafMatrix3D::PreScaleBy

virtual void PreScaleBy (const TGPoint3D & delta, const TGPoint3D & centerOfScale =TGPoint3D :: kOrigin)

Interface Category:

API.

Purpose:

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

Calling Context:

Call this function directly.

Parameters:

const TGPoint3D & scale -The scaling factor.
const TGPoint3D & centerOfScale =TGPoint3D :: 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: TGrafMatrix3D::ConcatWith

virtual void ConcatWith (const TGrafMatrix3D & matrix)

Interface Category:

API.

Purpose:

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

Calling Context:

Call this function directly.

Parameters:

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

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafMatrix3D::PreConcatWith

virtual void PreConcatWith (const TGrafMatrix3D & matrix)

Interface Category:

API.

Purpose:

Sets this matrix to another matrix, times this matrix. Concatenation is not commutative.

Calling Context:

Call this function directly.

Parameters:

const TGrafMatrix3D & matrix -The other matrix.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafMatrix3D::IsIdentity

virtual bool IsIdentity () const

Interface Category:

API.

Purpose:

Determines whether this TGrafMatrix3D is an identity matrix (that is, all diagonal entries are equal to 1, and all others are equal to 0).

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns true if the matrix is of type kIdentity.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafMatrix3D::IsTranslate

virtual bool IsTranslate () const

Interface Category:

API.

Purpose:

Determines whether this TGrafMatrix3D 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 or kIdentity.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafMatrix3D::IsScale

virtual bool IsScale () const

Interface Category:

API.

Purpose:

Determines whether this TGrafMatrix3D is a scale matrix.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns true if the matrix is of type kScale or kIdentity.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafMatrix3D::IsRotate

virtual bool IsRotate () const

Interface Category:

API.

Purpose:

Determines whether this TGrafMatrix3D is a rotate matrix.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns true if the matrix is of type kRotate or kIdentity.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafMatrix3D::IsAffine

virtual bool IsAffine () const

Interface Category:

API.

Purpose:

Determines whether the matrix is affine (that is, perspectiveX =0, perspectiveY =0, perspectiveZ =0, and homogeneous =1.0).

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: TGrafMatrix3D::Reorthogonalize

virtual void Reorthogonalize ()

Interface Category:

API.

Purpose:

Corrects a non-orthogonal matrix due to the successive composition of rotations. The succession of composing rotations can lead to skewing and scaling effects. This member function reorthogonalizes the matrix by computing the approximation to a correction 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:

Override this member function if you want a more accurate approximation. This member function uses Taylor serious expansion to 10 coefficients. Another approach to increase the accuracy is to repeatedly call this member function until a certain level of criteria is met.

Member Function: TGrafMatrix3D::Transpose

virtual void Transpose ()

Interface Category:

API.

Purpose:

Transposes this TGrafMatrix3D (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: TGrafMatrix3D::MakeAdjoint

virtual void MakeAdjoint ()

Interface Category:

API.

Purpose:

Converts this TGrafMatrix3D to its Classical Adjoint.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws an eSingularTransform TTransformException exception if the matrix is singular.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafMatrix3D::Normalize

virtual void Normalize ()

Interface Category:

API.

Purpose:

Divides the TGrafMatrix3D by the homogeneous value.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws an eUndefinedTransform TTransformException exception if the homogeneous value is 0.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafMatrix3D::Invert

virtual void Invert ()

Interface Category:

API.

Purpose:

Inverts this TGrafMatrix3D.

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: TGrafMatrix3D::GetDeterminant

virtual GCoordinate GetDeterminant () const

Interface Category:

API.

Purpose:

Gets the determinant of this TGrafMatrix3D. If the determinant is 0, the 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: TGrafMatrix3D::GetElement

virtual GCoordinate GetElement (EMatrixIndex index) const

Interface Category:

API.

Purpose:

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

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: TGrafMatrix3D::SetElement

virtual void SetElement (EMatrixIndex index, GCoordinate element)

Interface Category:

API.

Purpose:

Uses EMatrixIndex to set a particular element in the TGrafMatrix3D.

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 TGrafMatrix3D interface is insufficient. Calling this member function can hurt the operations that are performed later to this matrix.

Member Function: TGrafMatrix3D::operator=

TGrafMatrix3D & operator =(const TGrafMatrix3D & 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 TGrafMatrix3D & 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: TGrafMatrix3D::operator*=

TGrafMatrix3D & operator *= (const TGrafMatrix3D & 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 TGrafMatrix3D & 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 TGrafMatrix3D::ConcatWith.

Member Function: TGrafMatrix3D::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: TGrafMatrix3D::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: TGrafMatrix3D::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: TGrafMatrix3D::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: TGrafMatrix3D::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: TGrafMatrix3D::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: TGrafMatrix3D::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.

Member Function: TGrafMatrix3D::PreRotateBy

virtual void PreRotateBy (GDegrees angle, EAxis axis)
virtual void PreRotateBy (GDegrees angle, const TGLine3D & ray)
virtual void PreRotateBy (const TGLine3D & vector0, const TGLine3D & vector1)

Interface Category:

API.

Purpose:

Constructs a rotation matrix out of the specified rotation angle and preconcatenates with this matrix. The rotation takes places around the specified axis.
Constructs a rotation matrix out of the specified rotation angle and preconcatenates with this matrix. The rotation takes place around the specified ray (directional vector).
Constructs a rotation matrix so that it rotates the vector vector0 into the vector vector1

Calling Context:

You can call this function directly.
You can call this function directly.
You can call this function directly.

Parameters:

GDegrees angle -The rotation angle in degree.
EAxis axis -The axis of rotation.
GDegrees angle -The rotation angle in degree.
const TGLine3D & ray -The ray where the axis of rotation is taken place.
const TGLine3D & vector0 -The vector defines where the rotation will start off.
const TGLine3D & vector1 -The vector defines where the rotation will end up.

Return Value:

None.

Exceptions:

Throws an eUndefined TTransformException exception if the axis is unknown.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafMatrix3D::RotateBy

virtual void RotateBy (GDegrees angle, EAxis axis)
virtual void RotateBy (GDegrees angle, const TGLine3D & ray)
virtual void RotateBy (const TGLine3D & vector0, const TGLine3D & vector1)

Interface Category:

API.

Purpose:

Concatenates this matrix with a rotate matrix with rotation amount set to angle and the axis of rotation is specified.
Concatenates this matrix with a rotation matrix with rotation amount set to angle and the axis of rotation is about an arbitrary ray(vector).
Concatenates this matrix with a rotation matrix with rotation amount set to the vector vector0 being rotated into vector vector1.

Calling Context:

You can call this function directly.
You can call this function directly.
You can call this function directly.

Parameters:

GDegrees angle -The rotation angle in degree.
EAxis axis -The axis of rotation.
GDegrees angle -The rotation angle in degree.
const TGLine3D & ray -The ray where the axis of rotation is taken place.
const TGLine3D & vector0 -The vector defines where the rotation will start off.
const TGLine3D & vector1 -The vector defines where the rotation will end up.

Return Value:

None.

Exceptions:

Throws an eUndefined TTransformException exception if the axis is unknown.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGrafMatrix3D::SetToRotate

virtual void SetToRotate (GDegrees angle, EAxis axis)
virtual void SetToRotate (GDegrees angle, const TGLine3D & ray)
virtual void SetToRotate (const TGLine3D & vector0, const TGLine3D & vector1)

Interface Category:

API.

Purpose:

Sets this TGrafMatrix3D to one that rotates around the specified axis.
Sets this TGrafMatrix3D to one that rotates around the specified ray(vector).
Sets this TGrafMatrix3D to one that rotates vector vector0 into vector vector1.

Calling Context:

You can call this function directly.
You can call this function directly.
You can call this function directly.

Parameters:

GDegrees angle -The rotation angle in degree.
EAxis axis -The axis of rotation.
GDegrees angle -The rotation angle in degree.
const TGLine3D & ray -The ray where the axis of rotation is taken place.
const TGLine3D & vector0 -The vector defines where the rotation will start off.
const TGLine3D & vector1 -The vector defines where the rotation will end up.

Return Value:

None.

Exceptions:

Throws an eUndefined TTransformException exception if the axis is unknown.

Concurrency:

Not multithread safe.

Other Considerations:

None.

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