Class: TMatrixState

Declaration: MatrixState.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

None.

Inherited By:

TLinkableMatrixState TRootMatrixState

Purpose:

A graphic state consists of all the graphical state variables needed to draw a geometry. The 2-D state variables include a transformation matrix, a clipping area, and attributes such as paint, transfer mode, and pen geometry. The transformation matrix is packaged in a TMatrixState object, the clipping area is packaged in a TClipState, and the attributes are packaged in a TAttributeState. (All three of these are abstract classes, so the state variables are actually stored in instances of classes derived from these three.) The transformation matrix itself is an object of the TGrafMatrix class. The matrix is used to translate, scale, or rotate a graphic. The TMatrixState class, an abstract base class, encapsulates this TGrafMatrix, providing protocol for accessing the matrix. Graphic states are frequently used in hierarchies (because graphics themselves are frequently hierarchies). TMatrixState itself does not provide any protocol for a hierarchy of graphic states; that ability is provided by its derived class TLinkableMatrixState. However, most application programmers will use port objects, such as TLinkedModelMatrixPort, rather than use TMatrixState objects directly. TMatrixState implements member functions for maintaining a time stamp. Time stamps are a quick and efficient way to determine whether two TMatrixState 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 is updated whenever the object changes. This is particularly useful in constructing hierarchies that require matrix concatenation, because the concatenation need only be recomputed when a matrix has changed. As a special case, a time stamp of zero indicates that the object has an identity matrix. 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. TMatrixState::GetSharedTimeStampState returns a pointer to this object, allowing you to determine more quickly if anything has changed. TMatrixState and its descendants are used for 2-D graphics; the corresponding 3-D classes are TMatrix3DState and its descendants.

Instantiation:

Abstract class; do not allocate.

Deriving Classes:

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 is 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: TMatrixState::~TMatrixState

virtual ~ TMatrixState ()

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

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

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TMatrixState::TMatrixState

  1. TMatrixState ()
  2. TMatrixState (const TMatrixState &)

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. 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: TMatrixState::operator=

TMatrixState & operator =(const TMatrixState &)

Interface Category:

API.

Purpose:

Assignment operator. This is a protected member 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 =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: TMatrixState::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: TMatrixState::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: TMatrixState::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 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.