Class: TSurfaceShader

Declaration: SampleShaders.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

TShader

Inherited By:

None.

Purpose:

TSurfaceShader is a concrete class, derived from TShader. TSurfaceShader conveniently combines some of the functionality of the other TShader derived classes by applying not just one map but four--an image map, a bump map, and two procedure maps. One procedure map changes the color (as does the image map) and the other procedure map changes the shading normal (as does the bump map). However, this usage is not enforced; you can specify any procedure map for either one. By default, all maps are NIL; member functions are provided to set, get, and delete each map. TSurfaceShader::ComputeShade applies the maps in the following order: image map, procedure map for color, bump map, procedure map for shading normal. After applying the four maps, ComputeShade invokes the child shader's ComputeShade member function. As with the other TShader derived classes, this child shader is by default a TReflectanceShader, but by invoking TSurfaceShader::SetChildShader you can replace it with any other type of shader.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

None.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TSurfaceShader::TSurfaceShader

TSurfaceShader ()
TSurfaceShader (const TSurfaceShader & source)
TSurfaceShader (const TShader & childShader)

Interface Category:

API.

Purpose:

Default constructor. Sets all the maps to NIL and the child shader to a TReflectanceShader object.
Copy constructor.
Constructor used to set the child shader.

Calling Context:

Called by the stream-in operators. You can also call this function directly.
Called to copy an object. You can call this function directly.
Call this function directly.

Parameters:

Takes no parameters.
const TSurfaceShader & source -The object to be copied.
const TShader & childShader -The child shader to use.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TSurfaceShader::~TSurfaceShader

virtual ~ TSurfaceShader ()

Interface Category:

API.

Purpose:

Destructor.

Calling Context:

Called to destroy an object.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TSurfaceShader::SetImageMap

virtual void SetImageMap (const TImageMap & imageMap)

Interface Category:

API.

Purpose:

Sets the image map to the given value. The image map is used first in TSurfaceShader::ComputeShade to modify the color of the surface point according to the specified image map.

Calling Context:

Call this function directly.

Parameters:

const TImageMap & imageMap -The new image map to use.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TSurfaceShader::SetProcedureMap

virtual void SetProcedureMap (const TProcedureMap & procedureMap, bool forNormal =false)

Interface Category:

API.

Purpose:

Sets the procedure map to the given value. The Boolean flag argument specifies whether this procedure map will be used for color modification (the default value) or for normal vector modification. The color procedure map is used second in TSurfaceShader::ComputeShade to modify the color of the surface point according to the specified procedure map. The normal procedure map is used fourth in TSurfaceShader::ComputeShade to modify the normal of the surface point according to the specified procedure map.

Calling Context:

Call this function directly.

Parameters:

const TProcedureMap & procedureMap -The new procedure map to use.
bool forNormal =false -A Boolean flag, which, when set to false (the default), sets this procedure map to be used for color modification, making it used immediately after the image map in TSurfaceShader::ComputeShade.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TSurfaceShader::SetBumpMap

virtual void SetBumpMap (const TBumpMap & bumpMap)

Interface Category:

API.

Purpose:

Sets the bump map to the given value. The bump map is used third in TSurfaceShader::ComputeShade to modify the normal vector of the surface point.

Calling Context:

Call this function directly.

Parameters:

const TBumpMap & bumpMap -The new bump map to use.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TSurfaceShader::GetImageMap

virtual const TImageMap * GetImageMap () const

Interface Category:

API.

Purpose:

Returns a constant pointer to the image map held by this object.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns a constant pointer to the image map held by this object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TSurfaceShader::GetProcedureMap

virtual const TProcedureMap * GetProcedureMap (bool forNormal =false) const

Interface Category:

API.

Purpose:

Returns a constant pointer to one of the two procedure maps held by this object. If the Boolean argument is set to false (the default), the procedure map intended for color modification is returned. Otherwise, the procedure map intended for normal modification is returned.

Calling Context:

Call this function directly.

Parameters:

bool forNormal =false -A Boolean flag, which, when set to false (the default) causes the procedure map intended for color modification to be returned.

Return Value:

Returns a constant pointer to one of the two procedure maps held by this object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TSurfaceShader::GetBumpMap

virtual const TBumpMap * GetBumpMap () const

Interface Category:

API.

Purpose:

Returns a constant pointer to the bump map held by this object.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns a constant pointer to the bump map held by this object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TSurfaceShader::RemoveImageMap

virtual void RemoveImageMap ()

Interface Category:

API.

Purpose:

Deletes the image map held by this object and sets the pointer to NIL.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TSurfaceShader::RemoveProcedureMap

virtual void RemoveProcedureMap (bool forNormal =false)

Interface Category:

API.

Purpose:

Deletes one of the two procedure maps held by this object and sets the pointer to NIL. If the Boolean argument is set to false (the default), the color procedure map is deleted. Otherwise, it deletes the normal procedure map.

Calling Context:

Call this function directly.

Parameters:

bool forNormal =false -A Boolean flag, which, when false (the default), causes the procedure map intended for color modification to be deleted.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TSurfaceShader::RemoveBumpMap

virtual void RemoveBumpMap ()

Interface Category:

API.

Purpose:

Deletes the bump map held by this object and sets the pointer to NIL.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TSurfaceShader::ComputeShade

virtual void ComputeShade (TShadingSample & shadingInfo, const TSceneState & sceneState)

Interface Category:

API.

Purpose:

Computes the resultant color and other shading variables, given the current surface point and scene state. The modification maps held by this object are applied in the following order: the image map, the color procedure map, the bump map, and finally, the normal procedure map. After these maps have been applied, the child shader is applied.

Calling Context:

Call this function directly.

Parameters:

TShadingSample & shadingInfo -The shading information about the point to be shaded.
const TSceneState & sceneState -The state of the scene.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TSurfaceShader::SetChildShader

virtual void SetChildShader (const TShader & aShader)

Interface Category:

API.

Purpose:

Sets the child shader to the given value. The child shader is used to shade the point after the various maps have been applied.

Calling Context:

Call this function directly.

Parameters:

const TShader & aShader -The new child shader to use.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TSurfaceShader::GetChildShader

virtual TShader * GetChildShader () const

Interface Category:

API.

Purpose:

Returns a pointer to the child shader held by this object.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns a pointer to the child shader held by this object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TSurfaceShader::GetShadingUsageVariables

virtual void GetShadingUsageVariables (TShadingUsageVariables & variables) const

Interface Category:

API.

Purpose:

Returns a TShadingUsageVariables object specifying what information the shader needs in order to shade the surface. This is dependent upon the needs of the child shader as well as the needs of the various other maps held by this object.

Calling Context:

Call this function directly.

Parameters:

TShadingUsageVariables & variables -The variables needed for shading are returned in this object.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TSurfaceShader::operator=

TSurfaceShader & operator =(const TSurfaceShader & source)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Call this function by using the operator in an assignment statement.

Parameters:

const TSurfaceShader & source -The object to be copied.

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: TSurfaceShader::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: TSurfaceShader::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.

Click the icon to mail questions or corrections about this material to Taligent personnel.