Taxonomy Categories:
Member Functions:
Interface Category:
API.
Inherits From:
MCollectible, TLinkableClippingSceneState
Inherited By:
None.
Purpose:
TSceneBundle provides global attributes that affect all the geometries in a 3-D scene. (The local attributes for each geometry are provided by TGrafBundle3D.) TSceneBundle is a concrete class, derived from TLinkableClippingSceneState.
The standard scene attributes include the ambient light, a list of lights, the atmosphere shader, and the camera. Ambient light is a unique light source that distributes light intensity uniformly in all directions from no specified location. It is specified by a TColor object; the color has a certain hue and intensity, but no location. By contrast, the nonambient lights illuminate the scene from specific locations. These are instances of various TLight derived classes--TPointLight, TParallelLight, or TSpotLight. Each light is represented in the list by a TLightSurrogate object. The atmosphere shader, as represented by a TAtmosphereShader derived class, simulates atmosphere attenuation to create effects like fog, clouds, or haze. The camera is an instance of a TCamera derived class, which specifies the camera position, projection point, clipping planes, and so forth. The TSceneBundle default constructor initializes the ambient color to white, the camera to TPerspectiveCamera, and all other attributes to NIL.
In addition to the standard attributes, you can add other attributes to the scene bundle. These are TGrafAttribute objects that you can define. There is one extended attribute provided: THiddenSurfaceRemovalControl. Like TGrafBundle3D, TSceneBundle provides a member function that creates an iterator for traversing the list of extended attributes. TSceneBundle also provides another iterator for the list of lights.
TSceneBundle can set rendering attributes that are applied to all geometries. For example, a Z buffer rendering can turn the visibility check either on or off, based on an attribute object (the default being a THiddenSurfaceRemovalControl).
Instantiation:
Allocate on the heap or the stack.
Deriving Classes:
None.
Concurrency:
Not multithread safe.
Resource Use:
No special requirements.
- TSceneBundle ()
- TSceneBundle (const TSceneBundle & aSceneBundle)
Interface Category:
API.
Purpose:
- Default constructor. Sets all lights, shaders, and cameras to NIL. Sets the ambient light color to white.
- Copy constructor.
Calling Context:
- Called by the stream-in operators. You can also call this function directly.
- Called to copy an object.
Parameters:
- Takes no parameters.
- const TSceneBundle & aSceneBundle -The object to be copied.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
virtual ~ TSceneBundle ()
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: TSceneBundle::SetAmbientLight
virtual void SetAmbientLight (const TColor & lightColor)
Interface Category:
API.
Purpose:
Sets the ambient light to the given value. The ambient light uses the hue and intensity values of the light object but has no specific location.
Calling Context:
Call this function directly.
Parameters:
- const TColor & lightColor -The color to use for the ambient light.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TSceneBundle::GetAmbientLight
virtual void GetAmbientLight (TColor & lightColor) const
Interface Category:
API.
Purpose:
Returns the color used for the ambient light in the TColor object.
Calling Context:
Call this function directly.
Parameters:
- TColor & lightColor -The ambient light color is returned here.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TSceneBundle::AdoptAtmosphereShader
virtual void AdoptAtmosphereShader (TAtmosphereShader * AtmosphereShader)
Interface Category:
API.
Purpose:
Assumes ownership of the specified TAtmosphereShader, which is used for shading the scene.
Calling Context:
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: TSceneBundle::OrphanAtmosphereShader
virtual TAtmosphereShader * OrphanAtmosphereShader ()
Interface Category:
API.
Purpose:
Relinquishes ownership of the TAtmosphereShader object, setting the new atmosphere shader to NIL.
Calling Context:
Call this function directly.
Parameters:
Return Value:
Returns a pointer to the TAtmosphereShader that is no longer owned by this bundle.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TSceneBundle::GetAtmosphereShader
virtual const TAtmosphereShader * GetAtmosphereShader () const
Interface Category:
API.
Purpose:
Returns a constant pointer to the atmosphere shader owned by this bundle.
Calling Context:
Call this function directly.
Parameters:
Return Value:
Returns a constant pointer to the atmosphere shader owned by this bundle.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TSceneBundle::AdoptCamera
virtual void AdoptCamera (TCamera * camera)
Interface Category:
API.
Purpose:
Assumes ownership of the specified TCamera, which is used as the point of view for the scene.
Calling Context:
Call this function directly.
Parameters:
- TCamera * camera -The camera to be adopted by this bundle.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TSceneBundle::OrphanCamera
virtual TCamera * OrphanCamera ()
Interface Category:
API.
Purpose:
Relinquishes ownership of the TCamera object, setting the new camera to NIL.
Calling Context:
Call this function directly.
Parameters:
Return Value:
Returns a pointer to the TCamera object that is no longer owned by this bundle.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TSceneBundle::GetCamera
virtual const TCamera * GetCamera () const
Interface Category:
API.
Purpose:
Returns a constant pointer to the camera that is owned by this bundle.
Calling Context:
Call this function directly.
Parameters:
Return Value:
Returns a constant pointer to the camera that is owned by this bundle.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TSceneBundle::AdoptSceneAttribute
virtual void AdoptSceneAttribute (TGrafAttribute * adoptedAttribute)
Interface Category:
API.
Purpose:
Assumes ownership of the specified TGrafAttribute, adding it to the list of extended attributes.
Calling Context:
Call this function directly.
Parameters:
- TGrafAttribute * adoptedAttribute -The extended attribute to add to this bundle.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TSceneBundle::OrphanSceneAttribute
virtual TGrafAttribute * OrphanSceneAttribute ( const TToken & attributeName)
Interface Category:
API.
Purpose:
Relinquishes ownership of the named attribute, removing it from the list of extended attributes.
Calling Context:
Call this function directly.
Parameters:
- const TToken & attributeName -The name of the extended attribute to orphan.
Return Value:
Returns a pointer to the named TGrafAttribute.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TSceneBundle::GetSceneAttribute
virtual const TGrafAttribute * GetSceneAttribute ( const TToken & attributeName) const
Interface Category:
API.
Purpose:
Returns a constant pointer to the named extended attribute.
Calling Context:
Call this function directly.
Parameters:
- const TToken & attributeName -The name of the extended attribute to get.
Return Value:
Returns a constant pointer to the named TGrafAttribute.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TSceneBundle::CreateSceneAttributeIterator
virtual TSceneAttributeIterator * CreateSceneAttributeIterator () const
Interface Category:
API.
Purpose:
Creates an iterator that accesses the bundle's extended attributes (but not the standard attributes).
Calling Context:
Call this function directly.
Parameters:
Return Value:
Returns a pointer to a TSceneAttributeIterator that can access all of this bundle's extended attributes.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TSceneBundle::AdoptLight
virtual TLightSurrogate AdoptLight (TLight * aLight)
Interface Category:
API.
Purpose:
Assumes ownership of the specified TLight, adding its surrogate to the list of lights. A pointer to the surrogate light is returned.
Calling Context:
Call this function directly.
Parameters:
- TLight * aLight -The light to adopt.
Return Value:
Returns a pointer to the TLightSurrogate created during the adoption process.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TSceneBundle::OrphanLight
virtual TLight * OrphanLight (const TLightSurrogate & aLightSurrogate)
Interface Category:
API.
Purpose:
Relinquishes ownership of the given surrogate light, removing it from the list of lights. A pointer to the original light object is returned.
Calling Context:
Call this function directly.
Parameters:
Return Value:
Returns a pointer to the TLight object that is no longer owned by this bundle.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TSceneBundle::ReplaceLight
virtual TLight * ReplaceLight (const TLightSurrogate & aLightSurrogate, TLight * aNewLight)
Interface Category:
API.
Purpose:
Replaces the light matching the specified TLightSurrogate with the specified TLight. The existing TLightSurrogate is now matched with the new TLight in the list of lights.
Calling Context:
Call this function directly.
Parameters:
- const TLightSurrogate & aLightSurrogate -The surrogate light to replace.
- TLight * aNewLight -The new TLight object for the surrogate light to represent.
Return Value:
Returns a pointer to the TLight object in the list that the surrogate light now represents.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TSceneBundle::DeleteAllLights
virtual void DeleteAllLights ()
Interface Category:
API.
Purpose:
Removes all lights from the list in the bundle.
Calling Context:
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: TSceneBundle::CreateLightIterator
virtual TIteratorOver < TKeyValuePair < TLightSurrogate , TLight >>* CreateLightIterator () const
Interface Category:
API.
Purpose:
Returns an iterator that will iterate over all of the lights owned by the bundle.
Calling Context:
Call this function directly.
Parameters:
Return Value:
Returns a pointer to a TIteratorOver that will iterate over all the lights owned by the bundle.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
---
Member Function: TSceneBundle::operator>>=
virtual TStream & operator >>=(TStream &) const
Interface Category:
API.
Purpose:
Stream-out operator.
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: TSceneBundle::operator<<=
virtual TStream & operator <<= (TStream &)
Interface Category:
API.
Purpose:
Stream-in operator.
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: TSceneBundle::operator=
TSceneBundle & operator =(const TSceneBundle & src)
Interface Category:
API.
Purpose:
Assignment operator.
Calling Context:
Call this function by using the operator in an assignment statement.
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: TSceneBundle::GetTimeStamp
virtual TPseudoTimeStamp GetTimeStamp () const
Interface Category:
API.
Purpose:
Returns the time of last modification of this object in a TPseudoTimeStamp object. This is useful for determining if two TSceneBundles are equal.
Calling Context:
Call this function directly.
Parameters:
Return Value:
Returns a TPseudoTimeStamp object that represents the time of the last modification of this bundle.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
Changes to the time stamp of the local or parent object are not checked.
Click the icon to mail questions or corrections about this material to Taligent personnel.
Copyright©1995 Taligent,Inc. All rights reserved.