Class: TLinkableMatrix3DState

Declaration: Matrix3DState.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

TMatrix3DState

Inherited By:

TSimpleMatrix3DState

Purpose:

TLinkableMatrix3DState is an abstract class derived from TMatrix3DState, just as its 2-D counterpart, TLinkableMatrixState, is derived from TMatrixState. The base class provides protocol for accessing the encapsulated transformation matrices, as well as functionality for maintaining a time stamp. To these functions, TLinkableMatrix3DState 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 TLinkableMatrix3DState::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 LinkTo accordingly. For example, TSimpleMatrix3DState implements linking by concatenating the parent's matrix with the child's.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TLinkableMatrix3DState::~TLinkableMatrix3DState

virtual ~ TLinkableMatrix3DState ()

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: TLinkableMatrix3DState::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). This is a pure virtual function that must be overridden by derived classes.

Calling Context:

Do not call this function directly.

Parameters:

Return Value:

Returns a constant pointer to a TGrafMatrix3D object that represents the normal (affine) matrix combined with any projection terms specified by the camera involved.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLinkableMatrix3DState::GetMatrix

virtual const TGrafMatrix3D * GetMatrix () const

Interface Category:

API.

Purpose:

Returns a constant pointer to the affine transformation matrix of the underlying graphic model.

Calling Context:

Do not call this function directly.

Parameters:

Return Value:

Returns a constant pointer a TGrafMatrix3D that represents the affine transformation matrix of the underlying graphic model.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLinkableMatrix3DState::LinkTo

virtual void LinkTo (const TMatrix3DState * 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 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: TLinkableMatrix3DState::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: TLinkableMatrix3DState::TLinkableMatrix3DState

  1. TLinkableMatrix3DState ()
  2. TLinkableMatrix3DState (const TLinkableMatrix3DState &)

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 function designed to be overridden by derived classes.

Calling Context:

  1. Called by the stream-in operators. You cannot call this function directly.
  2. Called to copy an object. Do not call this function directly, except from within the copy constructor of a derived class.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLinkableMatrix3DState::operator=

TLinkableMatrix3DState & operator =(const TLinkableMatrix3DState &)

Interface Category:

API.

Purpose:

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

Calling Context:

Do not call this function directly, except from within the operator equals 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: TLinkableMatrix3DState::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: TLinkableMatrix3DState::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: TLinkableMatrix3DState::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 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 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 can 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.