Class: TLinkableMatrixState

Declaration: MatrixState.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

TMatrixState

Inherited By:

TSimpleMatrixState

Purpose:

TLinkableMatrixState is an abstract class derived from TMatrixState. The base class provides protocol for accessing the encapsulated transformation matrix, as well as functionality for maintaining a time stamp. To these functions, TLinkableMatrixState adds pure virtual member functions for creating a hierarchy of matrix states. A hierarchy of matrix states lets you concatenate the transformation matrices corresponding to a hierarchy of graphics. (Most programmers will find ports more convenient for this purpose, however.) Typically, the parent matrix state corresponds to a graphic that contains another graphic, and the child matrix state corresponds to the contained graphic. You give an object a parent as an argument to TLinkableMatrixState::LinkTo.

Instantiation:

Abstract class; do not allocate.

Deriving Classes:

Derived classes should override all the pure virtual member functions. It is up to the derived class to decide just what a parent-child relationship means and to implement the LinkTo operation accordingly. For example, TSimpleMatrixState implements linking by concatenating the parent's matrix with the child's.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TLinkableMatrixState::~TLinkableMatrixState

virtual ~ TLinkableMatrixState ()

Interface Category:

API.

Purpose:

Destructor.

Calling Context:

Called to destroy an object.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLinkableMatrixState::GetMatrix

virtual const TGrafMatrix * GetMatrix () const

Interface Category:

API.

Purpose:

Returns a constant pointer to the transformation matrix. This is a pure virtual function that must be overridden by the derived classes.

Calling Context:

Do not call this function directly.

Parameters:

Return Value:

Returns a constant pointer to a TGrafMatrix object that represents the transformation matrix held by this object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLinkableMatrixState::LinkTo

virtual void LinkTo (const TMatrixState * parent)

Interface Category:

API.

Purpose:

Makes the specified TMatrixState the parent of this object. This is a pure virtual function that must be overridden by derived classes. Usually, the parent TMatrix3DState generally comes from the graphic object's parent.

Calling Context:

Do not call this function directly.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLinkableMatrixState::Unlink

virtual void Unlink ()

Interface Category:

API.

Purpose:

Severs the association between this object and its current parent. This is a pure virtual function that must be overridden by derived classes.

Calling Context:

Do not call this function directly.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLinkableMatrixState::TLinkableMatrixState

  1. TLinkableMatrixState ()
  2. TLinkableMatrixState (const TLinkableMatrixState &)

Interface Category:

API.

Purpose:

  1. Default constructor. This is a protected constructor that must be overridden by derived classes.
  2. Copy constructor. This is a protected member function designed to be overridden by derived classes.

Calling Context:

  1. Only for internal use by Resurrect. Developers should treat as protected.
  2. Called to copy an object. Only for internal use by Copy. Developers should treat as protected.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLinkableMatrixState::operator=

TLinkableMatrixState & operator =(const TLinkableMatrixState &)

Interface Category:

API.

Purpose:

Assignment operator. This is a protected member function that is designed to be overridden by derived classes.

Calling Context:

Do not call this function directly, except from within the operator =function of a derived class.

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

TStream & operator >>=(TStream &) const

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Called to stream out data.

Parameters:

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

TStream & operator <<= (TStream &)

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Called to stream in data.

Parameters:

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: TLinkableMatrixState::GetSharedTimeStampState

virtual TTimeStampState * GetSharedTimeStampState () const

Interface Category:

API.

Purpose:

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. This is a pure virtual member function that must be overridden by every derived class. There is no meaningful default that can be provided by the base class. Here are some simple rules for determining what to do: (1) The root of a hierarchy must own a TTimeStampState object and share it with its children by means of GetSharedTimeStampState. (2) An object that has a parent may either share its parent's time stamp state or create its own. If its local value changes infrequently, it should share its parent's time stamp state. (In this case, GetSharedTimeStampState returns the parent's time stamp state.) On the other hand, if the object's local value changes frequently, it should instead own an instance of a TTimeStampState derived class that is dependent on its parent's shared time stamp.

Calling Context:

Do not call this function directly.

Parameters:

Return Value:

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

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.
Copyright©1995 Taligent,Inc. All rights reserved.