Taxonomy Categories:
Member Functions:
Interface Category:
API.
Inherits From:
MCollectible
Inherited By:
TGrafBundle3D
TLinkedBundle3DState
TLocalAttribute3DState
TRootAttribute3DState
Purpose:
A graphic state consists of all the graphical state variables needed to draw a geometry. For a 3-D graphic, this includes attributes specific to the object, such as colors, shaders, and frame pen, as well as global information like the camera, lights, and 3-D coordinate system. The global information is supplied by a TSceneState object (which handles camera and lighting information) and by a TMatrix3DState (which handles the coordinate system). The attributes specific to the object are stored in a TAttribute3DState object.
TAttribute3DState is directly analogous to the 2-D class TAttributeState. An abstract base class, TAttribute3DState provides access to the set of graphic attributes by means of Get member functions (such as GetOutsideColor). The standard attributes (colors, shaders, and frame pen) are implemented as separate classes (TColor, TShader, and TPen). The TAttribute3DState also stores a few other pieces of information: the drawing operation, shading resolution, shading interpolation, and backface culling. You can create other attributes by deriving from TGrafAttribute; these custom attributes can be retrieved by name, with TAttribute3DState::GetGrafAttribute.
Derived classes typically implement storage, concatenation behavior, and caching of appropriate values. The main derived class is TGrafBundle3D, which adds functions to adopt and orphan all the standard attributes, as well as to iterate over the set of nonstandard attributes.
TAttribute3DState provides pure virtual functions to get and set a time stamp. Time stamps are a quick and efficient way to determine whether two TAttribute3DState 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. A TAttribute3DState derived class must maintain the value of its time stamp. If any part of the object's visible value changes, then it should update its time stamp by calling UpdateTimeStamp. A special case: if the object is in the default state, its time stamp is zero.
Instantiation:
Abstract class; do not allocate.
Deriving Classes:
Provided classes: TGrafBundle3D, and TLinkedBundle3DState. Derived classes must maintain the time stamp.
Concurrency:
Not multithread safe.
Resource Use:
No special requirements.
virtual ~ TAttribute3DState ()
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: TAttribute3DState::GetOutsideShader
virtual const TShader * GetOutsideShader () const
Interface Category:
API.
Purpose:
Returns a constant pointer to the TShader used for shading the outside surface. This is a pure virtual function which must be overridden by derived classes.
Calling Context:
Do not call this function directly. It is designed to be overridden by the derived classes.
Parameters:
Return Value:
Returns a constant pointer to a TShader object that specifies how the outside surface of the graphic will be shaded.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
virtual const TShader * GetInsideShader () const
Interface Category:
API.
Purpose:
Returns a constant pointer to the TShader used for shading the inside surface. This is a pure virtual function which must be overridden by derived classes.
Calling Context:
Do not call this function directly. It is designed to be overridden by the derived classes.
Parameters:
Return Value:
Returns a constant pointer to a TShader object that specifies how the inside surface of the graphic will be shaded.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
virtual const TColor * GetOutsideColor () const
Interface Category:
API.
Purpose:
Returns a constant pointer to the TColor used as the base color for the outside surface and the frame. This is a pure virtual function which must be overridden by derived classes.
Calling Context:
Do not call this function directly. It is designed to be overridden by the derived classes.
Parameters:
Return Value:
A constant pointer to the TColor used as the base color for the outside surface and the frame.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
virtual const TColor * GetInsideColor () const
Interface Category:
API.
Purpose:
Returns a constant pointer to the TColor used as the base color for the inside surface. This is a pure virtual function which must be overridden by derived classes.
Calling Context:
Do not call this function directly. It is designed to be overridden by the derived classes.
Parameters:
Return Value:
A constant pointer to the TColor used as the base color for the inside surface.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TAttribute3DState::GetTextureMappingMatrix
virtual const TGrafMatrix * GetTextureMappingMatrix () const
Interface Category:
API.
Purpose:
Returns a constant pointer to the TGrafMatrix used to map a 2-D texture to the 2-D parameter space of the 3-D surface. This is a pure virtual function which must be overridden by derived classes.
Calling Context:
Do not call this function directly. It is designed to be overridden by the derived classes.
Parameters:
Return Value:
A constant pointer to the TGrafMatrix used to map a 2-D texture to the surface.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
virtual const TPen * GetFramePen () const
Interface Category:
API.
Purpose:
Returns a constant pointer to the TPen that determines the frame's pen style (such as hairline or dashed). This is a pure virtual function which must be overridden by derived classes.
Calling Context:
Do not call this function directly. It is designed to be overridden by the derived classes.
Parameters:
Return Value:
A constant pointer to the TPen that is used to draw the frame.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TAttribute3DState::GetGrafAttribute
virtual const TGrafAttribute * GetGrafAttribute (const TToken & attributeKey) const
Interface Category:
API.
Purpose:
Returns the TGrafAttribute object that is associated with the key. TGrafAttribute objects are custom attributes that you install into the bundle. This is a pure virtual function which must be overridden by derived classes.
Calling Context:
Do not call this function directly. It is designed to be overridden by the derived classes.
Parameters:
- const TToken & key -The name of the attribute class to be retrieved.
Return Value:
A constant pointer to the TGrafAttribute object associated with the name that is passed in as a key.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
Iterating over extensible (custom) attributes is not supported yet.
virtual TPseudoTimeStamp GetTimeStamp () const
Interface Category:
API.
Purpose:
Returns the time stamp stored by this object. This is a virtual function that is designed to be overridden by a derived class. It is the responsibility of derived classes to maintain the time stamp value. The time stamp value provides an efficient way to see whether two TAttributeState objects are equal.
Calling Context:
Call this function directly, but it is designed to be overridden.
Parameters:
Return Value:
Returns a TPseudoTimeStamp object that is unique with respect to all other TAttribute3DState objects.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
- TAttribute3DState ()
- TAttribute3DState (const TAttribute3DState &)
Interface Category:
API.
Purpose:
- Default constructor. This is a protected constructor which must be overridden by derived classes.
- Copy constructor. This is a protected constructor which must be overridden by derived classes.
Calling Context:
- Called by the stream-in operators. Do not call this function directly.
- Called to copy an object. Do not call this function directly except from a derived class' copy constructor.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
TAttribute3DState & operator =(const TAttribute3DState &)
Interface Category:
API.
Purpose:
Assignment operator. This is a protected member function which is designed to be overridden by derived classes.
Calling Context:
Do not call this function directly except from within a derived class' operator =function.
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.
virtual TStream & operator >>=(TStream &) const
Interface Category:
API.
Purpose:
Stream-out operator.
Calling Context:
Called to stream out data. This is a protected member function designed to be called from a derived class' operator >>=function. Do not call this function directly.
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.
virtual TStream & operator <<= (TStream &)
Interface Category:
API.
Purpose:
Stream-in operator.
Calling Context:
Called to stream in data. This is a protected member function designed to be called from a derived class' operator <<= function. Do not call this function directly.
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.
void SetTimeStamp (TPseudoTimeStamp)
Interface Category:
API.
Purpose:
Sets the internal time stamp stored in this object to the time stamp passed in as a TPseudoTimeStamp. This is a protected member function that is designed for internal use only.
Calling Context:
Only called from functions within a derived class.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
void UpdateTimeStamp ()
Interface Category:
API.
Purpose:
Updates the internal time stamp value of this object to reflect the current time. This is a protected member function that is designed for internal use only.
Calling Context:
Only called from functions within a derived class.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
void ResetTimeStamp ()
Interface Category:
API.
Purpose:
Sets the time stamp to zero. This is a protected member function that is designed for internal use only.
Calling Context:
Only called from functions within a derived class.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
bool IsSameClass (const MCollectible &) const
Interface Category:
API.
Purpose:
Compares the class of this object with that of the specified object and returns true if and only if they are the same class.
Calling Context:
Called from a derived class to determine if this object is the same class as the specified object.
Parameters:
- const MCollectible & -The object whose class to compare against.
Return Value:
Returns true if and only if the specified object is of the same class as this object.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TAttribute3DState::GetDrawingOperation
virtual TAttributeState :: EDrawOperation GetDrawingOperation () const
Interface Category:
API.
Purpose:
Returns a value that specifies the drawing operation. This is a pure virtual function that must be overridden by derived classes.
Calling Context:
Do not call this function directly. It is designed to be overridden by the derived classes.
Parameters:
Return Value:
Returns a value that specifies the drawing operation.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TAttribute3DState::GetShadingQuality
virtual EShadingQuality GetShadingQuality () const
Interface Category:
API.
Purpose:
Returns a value that specifies the shading quality to use in rendering.
Calling Context:
Do not call this function directly. It is designed to be overridden by the derived classes.
Parameters:
Return Value:
Returns a value that specifies the shading quality to be used in the rendering process. The possible return values are kFast, kMedium, kBest, and kShadingQualityUnset.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TAttribute3DState::GetBackfaceCulling
virtual EBackfaceCulling GetBackfaceCulling () const
Interface Category:
API.
Purpose:
Returns a value that specifies whether the shading and rendering operations should ignore any surface that faces away from the camera. This is a pure virtual function which must be overridden by derived classes.
Calling Context:
Do not call this function directly. It is designed to be overridden by the derived classes.
Parameters:
Return Value:
Returns a value that specifies whether the shaders and renderers should ignore any surface which is not visible to the camera.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TAttribute3DState::GetPrimaryDitherHint
virtual const TDitherHint * GetPrimaryDitherHint () const
Interface Category:
API.
Purpose:
Returns a pointer to the dither hint object to be used when dithering is performed.
Calling Context:
Do not call this function directly. It is designed to be overridden by the derived classes.
Parameters:
Return Value:
Returns a pointer to the dither hint object to be used when dithering is performed.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TAttribute3DState::GetShadingInterpolation
virtual EShadingInterpolationMode GetShadingInterpolation () const
Interface Category:
API.
Purpose:
Returns the shading interpolation mode used by the shader. Shading interpolation occurs for the pixels that do not have their color explicitly computed by the shader, as defined by the shading resolution. This is a pure virtual function which must be overridden by derived classes.
Calling Context:
Do not call this function directly. It is designed to be overridden by the derived classes.
Parameters:
Return Value:
Returns a value that specifies the shading interpolation mode.
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.