Class: TMatrix3DState

Declaration: Matrix3DState.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

None.

Inherited By:

TLinkableMatrix3DState TRootMatrix3DState TCamera

Purpose:

TMatrix3DState is the 3-D counterpart to TMatrixState. An abstract class, it encapsulates two 3-D transformation matrices: the affine matrix and the projection matrix. The affine matrix is the normal matrix returned by GetMatrix; it defines a 3-D transformation of the model. The projection matrix combines the affine matrix with any perspective terms from a camera. TMatrix3DState provides a time stamp to keep track of when the object changes. Time stamps are a quick and efficient way to determine whether two TMatrix3DState objects are equal. If the time stamps of the two objects are equal, then the objects are equal. However, if the time stamps are not equal, the objects might or might not be equal. The time stamp gets updated whenever the object changes. As a special case, a time stamp of zero indicates that the object is in the default state, having an identity affine matrix and the default projection provided by a camera. Normal time stamps are stored separately for each object in a hierarchy of matrix states. To determine whether anything in the hierarchy has changed, each object in the hierarchy must be queried. Shared time stamps provide a more efficient alternative. A TSharedTimeStampState object contains a time stamp that changes whenever any part of the hierarchy changes. TMatrix3DState::GetSharedTimeStampState returns a pointer to this object, allowing you to more quickly determine whether anything has changed. In addition to the transformation matrix encapsulated by TMatrix3DState, there are other 3-D graphic state variables, encapsulated by TAttribute3DState and TSceneState. All of these classes (along with similar 2-D classes) are themselves encapsulated by TGrafState. Most programmers will use all these state classes indirectly, dealing instead with port objects, such as TLinkedModelMatrix3DPort.

Instantiation:

Abstract class; do not allocate.

Deriving Classes:

Derived classes should override all the pure virtual member functions. A derived class must maintain the value of its own time stamp, as well as the shared time stamp. Whenever any part of the object's visible value changes, the object should update its own time stamp by calling UpdateTimeStamp, and it should likewise update the shared time stamp by invoking TSharedTimeStampState::UpdateTimeStamp. The shared time stamp should be updated whenever any value in this state object changes, as well as whenever a new state object is linked into the hierarchy.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TMatrix3DState::~TMatrix3DState

virtual ~ TMatrix3DState ()

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: TMatrix3DState::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: TMatrix3DState::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: TMatrix3DState::TMatrix3DState

  1. TMatrix3DState ()
  2. TMatrix3DState (const TMatrix3DState &)

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 constructor that must be overridden by derived classes.

Calling Context:

  1. Called by the stream-in operators. Do not 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: TMatrix3DState::operator=

TMatrix3DState & operator =(const TMatrix3DState &)

Interface Category:

API.

Purpose:

Assignment operator. This is a protected function that is designed to be overridden by derived classes. This function will copy the value of the time stamp to the new object.

Calling Context:

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

Parameters:

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: TMatrix3DState::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: TMatrix3DState::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: TMatrix3DState::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) A 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.