Class: TProcedureMapShader

Declaration: SampleShaders.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

TShader

Inherited By:

None.

Purpose:

TProcedureMapShader is a concrete class, derived from TShader, that applies a procedure map to a 3-D object in order to simulate a more complex surface. The procedure map is stored in an instance of a TProcedureMap derived class (which is NIL by default and which you should set by a constructor argument or by invoking TProcedureMapShader::SetProcedureMap). TProcedureMapShader::ComputeShade overrides that of the TShader base class. TProcedureMapShader::ComputeShade applies the procedure represented by the TProcedureMap. The TProcedureMap can use or modify any public member variable of the TShadingSample object that represents the current point on the surface. Thus, a procedure map is more general than an image texture map, which directly alters only the point's color, or a bump map, which directly alters only the point's shading normal. The TProcedureMapShader has a subsidiary shader that it uses to perform additional shading after manipulating the TShadingSample. By default, this shader is a TReflectanceShader, but by invoking TProcedureMapShader::SetChildShader (or with a constructor argument) you can replace the default shader with an instance of any other class that descends from TShader. The TProcedureMapShader automatically invokes this subsidiary shader's ComputeShade member function to perform the additional shading, which uses the new shading normal. A transformation matrix can be temporarily applied to each point of the surface before the procedure map operates on the point. The matrix to use is specified with SetMatrix. Every invocation of ComputeShade transforms the current point using this matrix, applies the procedure map to the transformed point, and afterwards, undoes the transformation so that the point's geometry remains unchanged. This strategy lets you create several different appearances for a given geometry, without the overhead of instantiating separate objects for each occurrence.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

None.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TProcedureMapShader::TProcedureMapShader

TProcedureMapShader ()
TProcedureMapShader (const TProcedureMap & map)
TProcedureMapShader (const TProcedureMap & map, const TShader & childShader)
TProcedureMapShader (const TProcedureMapShader & source)

Interface Category:

API.

Purpose:

Default constructor. Sets the procedure map function to NIL, the matrix to NIL, and the child shader to a TReflectanceShader object.
Constructor used to set the procedure map.
Constructor used to set the procedure map and the child shader.
Copy constructor.

Calling Context:

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

Parameters:

Takes no parameters.
const TProcedureMap & map -The procedure map to use.
const TProcedureMap & map -The procedure map to use.
const TShader & childShader -The child shader to use.
const TProcedureMapShader & source -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: TProcedureMapShader::~TProcedureMapShader

virtual ~ TProcedureMapShader ()

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: TProcedureMapShader::SetProcedureMap

virtual void SetProcedureMap (const TProcedureMap & procedureMap)

Interface Category:

API.

Purpose:

Sets the procedure map to the given value.

Calling Context:

Call this function directly.

Parameters:

const TProcedureMap & procedureMap -The new procedure map to use.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TProcedureMapShader::GetProcedureMap

virtual const TProcedureMap * GetProcedureMap () const

Interface Category:

API.

Purpose:

Returns the procedure map used by this object.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns a constant pointer to the TProcedureMap that is used by this object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TProcedureMapShader::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.

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: TProcedureMapShader::SetChildShader

virtual void SetChildShader (const TShader & aShader)

Interface Category:

API.

Purpose:

Sets the child shader, which is used to shade the base color after it is computed by the procedure map, to the given shader.

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: TProcedureMapShader::GetChildShader

virtual TShader * GetChildShader () const

Interface Category:

API.

Purpose:

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

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

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

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TProcedureMapShader::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 procedure map.

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: TProcedureMapShader::SetMatrix

virtual void SetMatrix (const TGrafMatrix3D & matrix)

Interface Category:

API.

Purpose:

Sets the matrix to the given value. The matrix is used prior to the application of the procedure map to transform the surface point to a new location.

Calling Context:

Call this function directly.

Parameters:

const TGrafMatrix3D & matrix -The transformation matrix to use.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TProcedureMapShader::GetMatrix

virtual const TGrafMatrix3D * GetMatrix () const

Interface Category:

API.

Purpose:

Returns a constant pointer to the transformation matrix that is applied to the surface point just prior to computing the procedure map function.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns a constant pointer to the transformation matrix that is applied to the surface point just prior to computing the procedure map function.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TProcedureMapShader::operator=

TProcedureMapShader & operator =(const TProcedureMapShader & source)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Called when an object is assigned to another compatible object.

Parameters:

const TProcedureMapShader & 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: TProcedureMapShader::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: TProcedureMapShader::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.