Class: TSimpleMatrixState

Declaration: MatrixState.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

TLinkableMatrixState

Inherited By:

None.

Purpose:

TSimpleMatrixState is a concrete class, derived from TLinkableMatrixState, that implements a local transformation matrix. TSimpleMatrixState overrides the TLinkableMatrixState protocol for creating a hierarchy of matrix states, and it inherits the TMatrixState functionality for maintaining a time stamp. Whenever the TSimpleMatrixState's transformation matrix is changed, TSimpleMatrixState updates its own time stamp. TSimpleMatrixState's single local transformation matrix can be made part of a hierarchy by linking the TSimpleMatrixState to another matrix state object. TSimpleMatrixState implements linking by preconcatenating its local matrix with the matrix of the parent matrix state. When this happens, TSimpleMatrixState caches the result, 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 TSimpleMatrixState to recalculate the concatenation. You can set the local transformation matrix to any TGrafMatrix. 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 concatenation 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: TSimpleMatrixState::TSimpleMatrixState

TSimpleMatrixState ()
TSimpleMatrixState (const TSimpleMatrixState &)
TSimpleMatrixState (const TGrafMatrix & 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. You can also call this function directly.
Called to copy an object. You can call this function directly.
Call this function directly.

Parameters:

Takes no parameters.
const TSimpleMatrixState & -The object to be copied.
const TGrafMatrix & 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: TSimpleMatrixState::~TSimpleMatrixState

virtual ~ TSimpleMatrixState ()

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: TSimpleMatrixState::GetMatrix

virtual const TGrafMatrix * 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 a TGrafMatrix object that represents the concatenation transformation matrix for this object and its parent.

Exceptions:

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

Concurrency:

Not multithread safe.

Other Considerations:

This function should only be called when linked to a parent.

Member Function: TSimpleMatrixState::LinkTo

virtual void LinkTo (const TMatrixState * 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 TMatrixState * parent -The TMatrixState 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: TSimpleMatrixState::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: TSimpleMatrixState::operator=

TSimpleMatrixState & operator =(const TSimpleMatrixState &)

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

bool operator ==(const TSimpleMatrixState &) const

Interface Category:

API.

Purpose:

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

Calling Context:

Call this function directly.

Parameters:

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

bool operator != (const TSimpleMatrixState &) const

Interface Category:

API.

Purpose:

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

Calling Context:

Call this function directly.

Parameters:

const TSimpleMatrixState & -The object to compare with this TSimpleMatrixState 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: TSimpleMatrixState::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: TSimpleMatrixState::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: TSimpleMatrixState::SetLocalMatrix

void SetLocalMatrix (const TGrafMatrix &)

Interface Category:

API.

Purpose:

Sets the local transformation matrix to the specified TGrafMatrix. If the parent object is not NIL, the shared time stamp is 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: TSimpleMatrixState::GetLocalMatrix

const TGrafMatrix * 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 TGrafMatrix object that is the local transformation matrix.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TSimpleMatrixState::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 has 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:

Throws a Parameter Assert exception if the parent object is NIL.

Concurrency:

Not multithread safe.

Other Considerations:

None.

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