Taxonomy Categories:
Member Functions:
Interface Category:
API.
Inherits From:
None.
Inherited By:
TLinkableClippingSceneState
TLinkableSceneState
TRootSceneState
Purpose:
TSceneState is an abstract class whose protocol provides access to the set of scene attributes--camera, lights, and atmospheric shading. TSceneState is one of several substate classes packaged together in TGrafState. TGrafState represents the entire graphic state--all the state variables needed to draw a geometry. For a 3-D graphic, this includes attributes specific to each individual object, such as colors, shaders, and frame pen, as well as global information like the camera, lights, and 3-D coordinate system. The attributes specific to the object are stored in a TAttribute3DState object, while the coordinate system is handled by a TMatrix3DState. The TSceneState object supplies the global scene attributes, those that potentially affect every object in a scene.
TSceneState provides access to the set of scene attributes by means of Get member functions (such as GetAmbientLight). The standard attributes (camera, ambient light, nonambient lights, and atmospheric attenuation) are implemented as separate classes (TCamera, TColor, TLight, and TAtmosphereShader). The TSceneState also can store other pieces of information, called extended attributes. You can create other attributes by deriving from TGrafAttribute; these custom attributes can be retrieved by name, with TSceneState member::GetGrafAttribute.
TSceneState implements member functions to get and set a time stamp. Time stamps are a quick and efficient way to determine whether two TSceneState 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.
Most application programmers will use port objects, such as TLinkedScenePort, rather than manipulate TSceneState objects directly.
Instantiation:
Abstract class; do not allocate.
Deriving Classes:
TLinkableSceneState and TLinkableClippingSceneState. Derived classes typically implement storage, concatenation behavior, and caching of appropriate values. The main descendant is TSceneBundle, which adds functions to adopt and orphan all the attributes. TSceneBundle's relation to TSceneState is similar to TGrafBundle3D's relation to its ancestor, TAttribute3DState.
A TSceneState derived class must maintain the value of its time stamp. If any part of the object's visible value changes, 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.
Concurrency:
Not multithread safe.
Resource Use:
No special requirements.
virtual ~ TSceneState ()
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: TSceneState::GetAmbientLight
virtual void GetAmbientLight (TColor &) const
Interface Category:
API.
Purpose:
Returns, in the specified parameter, a TColor indicating the intensity and hue of the ambient light shining on the scene. This is a pure virtual function that must be overridden by derived classes.
Calling Context:
Do not call this function directly.
Parameters:
- TColor & -The color (intensity and hue) of the ambient light is returned here.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TSceneState::GetAtmosphereShader
virtual const TAtmosphereShader * GetAtmosphereShader () const
Interface Category:
API.
Purpose:
Returns a constant pointer to the TAtmosphereShader, which simulates atmospheric attenuation due to haze, clouds, or fog between the objects in the scene and the viewer. 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 the TAtmosphereShader, which simulates atmospheric attenuation due to haze, clouds, or fog between the objects in the scene and the viewer.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TSceneState::GetCamera
virtual const TCamera * GetCamera () const
Interface Category:
API.
Purpose:
Returns a constant pointer to the TCamera, which simulates a camera or eye that views the scene. 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 the TCamera, which simulates a camera or eye that views the scene.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TSceneState::GetSceneAttribute
virtual const TGrafAttribute * GetSceneAttribute (const TToken & attributeName) const
Interface Category:
API.
Purpose:
Returns a constant pointer to the named extended TGrafAttribute. This is a pure virtual function that must be overridden by derived classes.
Calling Context:
Do not call this function directly.
Parameters:
- const TToken & attributeName -The name of the attribute being requested.
Return Value:
Returns a constant pointer to the named TGrafAttribute. Returns NIL if the named attribute is not found.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TSceneState::CreateSceneAttributeIterator
virtual TSceneAttributeIterator * CreateSceneAttributeIterator () const
Interface Category:
API.
Purpose:
Creates an iterator that accesses the scene's extended attributes (but not the standard attributes). 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 pointer to a TSceneAttributeIterator that can be used to access the extended attributes held by this object.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TSceneState::GetTimeStamp
virtual TPseudoTimeStamp GetTimeStamp () const
Interface Category:
API.
Purpose:
Returns the local time stamp of this object. The local time stamp changes whenever the data in this TSceneState object changes. This is a virtual function that is designed to be overridden by derived classes.
Calling Context:
Do not call this function directly.
Parameters:
Return Value:
Returns a TPseudoTimeStamp object that represents the time of the last modification of this object.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
- TSceneState ()
- TSceneState (const TSceneState &)
Interface Category:
API.
Purpose:
- Default constructor. This is a protected member function that must be overridden by derived classes.
- Copy constructor. This is a protected member function that is designed to be overridden by derived classes.
Calling Context:
- Do not call this function directly.
- Do not call this function directly, except from within the copy constructor of a derived class.
Parameters:
- Takes no parameters.
- const TSceneState & -The object to be copied.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TSceneState::operator=
TSceneState & operator =(const TSceneState &)
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 =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: TSceneState::operator>>=
TStream & operator >>=(TStream &) const
Interface Category:
API.
Purpose:
Stream-out operator. This is a protected member function that is designed to be overridden by derived classes.
Calling Context:
Called to stream out data.
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.
Member Function: TSceneState::operator<<=
TStream & operator <<= (TStream &)
Interface Category:
API.
Purpose:
Stream-in operator. This is a protected member function that is designed to be overridden by derived classes.
Calling Context:
Called to stream in data.
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.
Member Function: TSceneState::SetTimeStamp
void SetTimeStamp (TPseudoTimeStamp)
Interface Category:
API.
Purpose:
Sets the time of the local time stamp. This is a protected member function designed to be overridden by derived classes. It is used primarily by internal functions that need to set the time stamp equal to the time stamp of a copied object.
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: TSceneState::UpdateTimeStamp
void UpdateTimeStamp ()
Interface Category:
API.
Purpose:
Updates the time stamp of the object. This function is called whenever the data in the object changes. This is a protected member function that is designed to be called internally by concrete derived classes and by the stream-in operator.
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: TSceneState::ResetTimeStamp
void ResetTimeStamp ()
Interface Category:
API.
Purpose:
Resets the local time stamp to zero. This is a protected member function designed for internal use only.
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: TSceneState::CreateLightIterator
virtual TIteratorOver < TKeyValuePair < TLightSurrogate , TLight >>* CreateLightIterator () const
Interface Category:
API.
Purpose:
Creates an iterator that can be used to access the list of lights that shine upon the scene from specific locations. 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 pointer to a TIterator object that can be used to access the list of lights that shine upon the scene.
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.