Class: TSimpleMatrix3DState

Declaration: Matrix3DState.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

TLinkableMatrix3DState

Inherited By:

None.

Purpose:

TSimpleMatrix3DState, the 3-D counterpart to TSimpleMatrixState, is a concrete class derived from TLinkableMatrix3DState that implements a local transformation matrix. TSimpleMatrix3DState overrides the TLinkableMatrix3DState protocol for creating a hierarchy of matrix states, and it inherits the TMatrix3DState functionality for maintaining a time stamp. Whenever the TSimpleMatrix3DState's transformation matrix is changed, TSimpleMatrix3DState updates its own time stamp. TSimpleMatrix3DState's local transformation matrix can be made part of a hierarchy by linking the TSimpleMatrix3DState to another matrix state object. TSimpleMatrix3DState implements linking by first copying its local matrix into an affine matrix and a projection matrix. The affine matrix is then preconcatenated with the affine matrix of the parent matrix state, and the projection matrix is likewise preconcatenated with the parent's projection matrix. When this happens, TSimpleMatrix3DState caches the results, updates its own time stamp, and records the parent's time stamp. Then, if the same parent is used again, its time stamp is compared to the recorded one. If neither the parent's time stamp nor the local time stamp has changed, the matrices are known to be unchanged, so it is not necessary for the TSimpleMatrix3DState to recalculate the concatenation. You can set the local transformation matrix to any TGrafMatrix3D. It is OK to change the local matrix or the parent's matrix while this object is linked to the parent; doing so causes the concatenated matrices to be recomputed.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

None.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TSimpleMatrix3DState::TSimpleMatrix3DState

TSimpleMatrix3DState ()
TSimpleMatrix3DState (const TSimpleMatrix3DState &)
TSimpleMatrix3DState (const TGrafMatrix3D & localMatrix)

Interface Category:

API.

Purpose:

Default constructor. Sets the local matrix to the identity matrix and sets the parent matrix to NIL.
Copy constructor.
Constructor used to set the local transformation matrix to the given value.

Calling Context:

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

Parameters:

Takes no parameters.
const TSimpleMatrix3DState & -The object to be copied.
const TGrafMatrix3D & localMatrix -The transformation matrix to be held by this TSimpleMatrixState.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TSimpleMatrix3DState::~TSimpleMatrix3DState

virtual ~ TSimpleMatrix3DState ()

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: TSimpleMatrix3DState::GetMatrixWithProjection

virtual const TGrafMatrix3D * GetMatrixWithProjection () const

Interface Category:

API.

Purpose:

Returns a constant pointer to the projection matrix (the affine matrix combined with projection terms that might come from a camera).

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns a constant pointer to the projection matrix.

Exceptions:

Causes a parameter assert exception in ValidateMatrix if the parent is NIL.

Concurrency:

Not multithread safe.

Other Considerations:

The object must be linked to a parent matrix state before calling this function.

Member Function: TSimpleMatrix3DState::GetMatrix

virtual const TGrafMatrix3D * GetMatrix () const

Interface Category:

API.

Purpose:

Returns a constant pointer to the concatenated transformation matrix. This matrix is the concatenation of the local matrix with the matrix of the parent.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns a constant pointer to the concatenated transformation matrix.

Exceptions:

Causes a parameter assert exception in ValidateMatrix if the parent is NIL.

Concurrency:

Not multithread safe.

Other Considerations:

The object must be linked to a parent matrix state before calling this function.

Member Function: TSimpleMatrix3DState::LinkTo

virtual void LinkTo (const TMatrix3DState * parent)

Interface Category:

API.

Purpose:

Makes the specified TSimpleMatrixState the parent of this object. Usually the parent object is the matrix state of the graphic that contains this graphic. The shared time stamp is updated as a result of this operation.

Calling Context:

Call this function directly.

Parameters:

const TMatrix3DState * parent -The TMatrix3DState object to be used as the parent of this object.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TSimpleMatrix3DState::Unlink

virtual void Unlink ()

Interface Category:

API.

Purpose:

Severs the connection between this matrix state and its parent's matrix state (if any).

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: TSimpleMatrix3DState::operator=

TSimpleMatrix3DState & operator =(const TSimpleMatrix3DState &)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

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

Parameters:

const TSimpleMatrixState & -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: TSimpleMatrix3DState::operator==

bool operator ==(const TSimpleMatrix3DState &) const

Interface Category:

API.

Purpose:

Compares two TSimpleMatrix3DState objects and returns true if they are equal (if either their time stamps or all of their transformation matrices are equal).

Calling Context:

Call this function directly.

Parameters:

const TSimpleMatrix3DState & -The object to compare with this TSimpleMatrixState object.

Return Value:

Returns true if both objects are equal.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TSimpleMatrix3DState::operator!=

bool operator != (const TSimpleMatrix3DState &) const

Interface Category:

API.

Purpose:

Compares two TSimpleMatrix3DState objects and returns true if they are not equal.

Calling Context:

Call this function directly.

Parameters:

const TSimpleMatrix3DState & -The object to compare with this TSimpleMatrix3DState object.

Return Value:

Returns true if the objects are not equal.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TSimpleMatrix3DState::operator>>=

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

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Called to stream out data.

Parameters:

TStream & -The stream that the object streams itself 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: TSimpleMatrix3DState::operator<<=

virtual TStream & operator <<= (TStream &)

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Called to stream in data.

Parameters:

TStream & -The stream that the object streams itself 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: TSimpleMatrix3DState::SetLocalMatrix

void SetLocalMatrix (const TGrafMatrix3D &)

Interface Category:

API.

Purpose:

Sets the local transformation matrix to the specified TGrafMatrix. If the parent object is not NIL, the shared time stamp will be updated.

Calling Context:

Call this function directly.

Parameters:

const TGrafMatrix & -The new local transformation matrix.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TSimpleMatrix3DState::GetLocalMatrix

const TGrafMatrix3D * GetLocalMatrix () const

Interface Category:

API.

Purpose:

Returns the local transformation matrix (as opposed to the concatenated matrix, which is returned by the GetMatrix function).

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns a constant pointer to a TGrafMatrix3D object that is the local transformation matrix.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TSimpleMatrix3DState::GetSharedTimeStampState

virtual TTimeStampState * GetSharedTimeStampState () const

Interface Category:

API.

Purpose:

Returns the value of the time stamp that is shared by the objects within this hierarchy. A state object's value is typically dependent on its parent's value. This means that when an object's value is queried, it must check to see if its parent's state has changed, and its parent must do the same, until it reaches the root of the hierarchy. Because state queries are done quite often, such as in a rendering process, shared time stamp states were invented to improve the performance of noticing whether some state in the hierarchy has changed. GetSharedTimeStampState returns a pointer to an object that contains a single time stamp that changes whenever any part of the hierarchy changes. An object can tell if any of the hierarchy above it changed by looking at the shared time stamp, instead of looking at its parent's time stamp, causing the parent to look at its parent's time stamp, and so on.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns a pointer to a TTimeStampState object that represents the last modification time of any object in this hierarchy.

Exceptions:

Causes a parameter assert exception if the parent is NIL.

Concurrency:

Not multithread safe.

Other Considerations:

None.

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