Shader Class Reference

This reference page is linked to from the following overview topics: Rendering Plug-ins, Plug-in Base Classes.

---

Search for all occurrences

---

Detailed Description

Used by developers to create Shader plug-ins.

The methods of this class must be implemented to provide data to the 3ds Max interactive renderer. This will let that renderer to properly reflect the look of the shader in the viewports. The methods associated with the actual Shader illumination code are from the base class BaseShader. There are various Get and Set methods defined in this class. Plug-in developers provide implementations for the 'Get' methods which are used by the interactive renderer. The implementations of the 'Set' methods are used when switching between shaders types in the Materials Editor. This is used to transfer the corresponding colors between the old Shader and the new one. Note that some shaders may not have the exact parameters as called for in the methods. In those case an approximate value may be returned from the 'Get' methods. For example, the Strauss Shader doesn't have an Ambient channel. In that case the Diffuse color is taken and divided by 2 and returned as the Ambient color. This gives the interactive renderer something to work with that might not be exact but is somewhat representative.

See also:

BaseShader, MacroRecorder

#include <shaders.h>

Inheritance diagram for Shader:

List of all members.

Public Member Functions
virtual void	CopyStdParams (Shader *pFrom)=0
	Copies the standard shader parameters from pFrom to this object.
virtual void	SetLockDS (BOOL lock)=0
	Sets the state of the Diffuse/Specular lock to on or off.
virtual BOOL	GetLockDS ()=0
	Returns the Diffuse/Specular lock'.
virtual void	SetLockAD (BOOL lock)=0
	Sets the state of the Ambient/Diffuse lock to on or off.
virtual BOOL	GetLockAD ()=0
	Returns the Ambient/Diffuse lock.
virtual void	SetLockADTex (BOOL lock)=0
	Sets the state of the Ambient/Diffuse Texture lock to on or off.
virtual BOOL	GetLockADTex ()=0
	Returns the Ambient/Diffuse Texture lock.
virtual void	SetSelfIllum (float v, TimeValue t)=0
	Sets the Self Illumination parameter to the specified value at the time passed as TimeValue.
virtual void	SetSelfIllumClrOn (BOOL on)=0
	Sets the Self Illumination Color On/Off state.
virtual void	SetSelfIllumClr (Color c, TimeValue t)=0
	Sets the Self Illumination Color at the specified time.
virtual void	SetAmbientClr (Color c, TimeValue t)=0
	Sets the Ambient Color at the specified time.
virtual void	SetDiffuseClr (Color c, TimeValue t)=0
	Sets the Diffuse Color at the specified time.
virtual void	SetSpecularClr (Color c, TimeValue t)=0
	Sets the Specular Color at the specified time.
virtual void	SetGlossiness (float v, TimeValue t)=0
	Sets the Glossiness parameter to the specified value at the time passed.
virtual void	SetSpecularLevel (float v, TimeValue t)=0
	Sets the Specular Level parameter to the specified value at the time passed.
virtual void	SetSoftenLevel (float v, TimeValue t)=0
	Sets the Soften Specular Highlights Level to the specified value at the time passed.
virtual BOOL	IsSelfIllumClrOn (int mtlNum, BOOL backFace)=0
	Returns the The Self Illumination Color setting.
virtual Color	GetAmbientClr (int mtlNum, BOOL backFace)=0
	Returns the Ambient Color.
virtual Color	GetDiffuseClr (int mtlNum, BOOL backFace)=0
	Returns the Diffuse Color.
virtual Color	GetSpecularClr (int mtlNum, BOOL backFace)=0
	Returns the Specular Color.
virtual Color	GetSelfIllumClr (int mtlNum, BOOL backFace)=0
	Returns the Self Illumination Color.
virtual float	GetSelfIllum (int mtlNum, BOOL backFace)=0
	Returns the Self Illumination Amount.
virtual float	GetGlossiness (int mtlNum, BOOL backFace)=0
	Returns the Glossiness Level.
virtual float	GetSpecularLevel (int mtlNum, BOOL backFace)=0
	Returns the Specular Level.
virtual float	GetSoftenLevel (int mtlNum, BOOL backFace)=0
	Returns the Soften Level as a float.
virtual BOOL	IsSelfIllumClrOn ()=0
	Returns the Self Illumination Color setting.
virtual Color	GetAmbientClr (TimeValue t)=0
	Returns the Ambient Color at the specified time.
virtual Color	GetDiffuseClr (TimeValue t)=0
	Returns the Diffuse Color at the specified time.
virtual Color	GetSpecularClr (TimeValue t)=0
	Returns the Specular Color at the specified time.
virtual float	GetGlossiness (TimeValue t)=0
	Returns the Glossiness value at the specified time.
virtual float	GetSpecularLevel (TimeValue t)=0
	Returns the Specular Level at the specified time.
virtual float	GetSoftenLevel (TimeValue t)=0
	Returns the Soften Specular Highlights setting at the specified time.
virtual float	GetSelfIllum (TimeValue t)=0
	Returns the Self Illumination Amount at the specified time.
virtual Color	GetSelfIllumClr (TimeValue t)=0
	Returns the Self Illumination Color at the specified time.
virtual float	EvalHiliteCurve (float x)
	Evaluates the hightlight curve that appears in the Shader user interface.
virtual float	EvalHiliteCurve2 (float x, float y, int level=0)
	This is the highlight curve function for the two highlight curves which intersect and appear in the UI, for instance in the Anistropic shader.
CoreExport void	ShadeReflection (ShadeContext &sc, IllumParams &ip, Color &mapClr)
	Implements the Max std way of handling reflection to provide the default implementation.
CoreExport void	ShadeTransmission (ShadeContext &sc, IllumParams &ip, Color &mapClr, float amount)
	Implements the Max std way of handling transmission to provide the default implementation.
void	PreShade (ShadeContext &sc, IReshadeFragment *pFrag)
void	PostShade (ShadeContext &sc, IReshadeFragment *pFrag, int &nextTexIndex, IllumParams *ip)
BaseInterface *	GetInterface (Interface_ID id)
	Inherited from Animatable.
void *	GetInterface (ULONG id)
	Inherited from Animatable.

---

Member Function Documentation

virtual void CopyStdParams

(

Shader *

pFrom

)

[pure virtual]

Search for all occurrences

Copies the standard shader parameters from pFrom to this object.

Note that plug-ins typically disable the macro recorder during this operation as the Get and Set methods are called. See the sample code for examples.

Parameters:

pFrom

The pointer to the source parameters.

virtual void SetLockDS

(

BOOL

lock

)

[pure virtual]

Search for all occurrences

Sets the state of the Diffuse/Specular lock to on or off.

Parameters:

lock	true for on, false for off.

virtual BOOL GetLockDS

(

)

[pure virtual]

Search for all occurrences

Returns the Diffuse/Specular lock'.

Returns:

true if the Diffuse/Specular lock is on, false otherwise.

virtual void SetLockAD

(

BOOL

lock

)

[pure virtual]

Search for all occurrences

Sets the state of the Ambient/Diffuse lock to on or off.

Parameters:

lock	true for on, false for off.

virtual BOOL GetLockAD

(

)

[pure virtual]

Search for all occurrences

Returns the Ambient/Diffuse lock.

Returns:

true if the Ambient/Diffuse lock is on, false otherwise.

virtual void SetLockADTex

(

BOOL

lock

)

[pure virtual]

Search for all occurrences

Sets the state of the Ambient/Diffuse Texture lock to on or off.

Parameters:

lock	true for on; false for off.

virtual BOOL GetLockADTex

(

)

[pure virtual]

Search for all occurrences

Returns the Ambient/Diffuse Texture lock.

Returns:

true if the Ambient/Diffuse Texture lock is on, false otherwise.

virtual void SetSelfIllum	(	float	v,
		TimeValue	t
	)		[pure virtual]

Search for all occurrences

Sets the Self Illumination parameter to the specified value at the time passed as TimeValue.

Parameters:

v	The value to set.
t	The time to set the value.

virtual void SetSelfIllumClrOn

(

BOOL

on

)

[pure virtual]

Search for all occurrences

Sets the Self Illumination Color On/Off state.

Parameters:

on	true for on, false for off.

virtual void SetSelfIllumClr	(	Color	c,
		TimeValue	t
	)		[pure virtual]

Search for all occurrences

Sets the Self Illumination Color at the specified time.

Parameters:

c	The color for the self illumination to set to.
t	The time to set the color.

virtual void SetAmbientClr	(	Color	c,
		TimeValue	t
	)		[pure virtual]

Search for all occurrences

Sets the Ambient Color at the specified time.

Parameters:

c	The color for the ambient to set to.
t	The time to set the color.

virtual void SetDiffuseClr	(	Color	c,
		TimeValue	t
	)		[pure virtual]

Search for all occurrences

Sets the Diffuse Color at the specified time.

Parameters:

c	The color for the diffuse color to set to.
t	The time to set the color.

virtual void SetSpecularClr	(	Color	c,
		TimeValue	t
	)		[pure virtual]

Search for all occurrences

Sets the Specular Color at the specified time.

Parameters:

c	The color to set to.
t	The time to set the color.

virtual void SetGlossiness	(	float	v,
		TimeValue	t
	)		[pure virtual]

Search for all occurrences

Sets the Glossiness parameter to the specified value at the time passed.

Parameters:

v	The value to set to.
t	The time to set the value.

virtual void SetSpecularLevel	(	float	v,
		TimeValue	t
	)		[pure virtual]

Search for all occurrences

Sets the Specular Level parameter to the specified value at the time passed.

Parameters:

v	The value to set.
t	The time to set the value.

virtual void SetSoftenLevel	(	float	v,
		TimeValue	t
	)		[pure virtual]

Search for all occurrences

Sets the Soften Specular Highlights Level to the specified value at the time passed.

Parameters:

v	The value to set.
t	The time to set the value.

virtual BOOL IsSelfIllumClrOn	(	int	mtlNum,
		BOOL	backFace
	)		[pure virtual]

Search for all occurrences

Returns the The Self Illumination Color setting.

parameters to this method are not applicable and may safely be ignored.

Returns:

true if the Self Illumination Color setting is on (checked), false otherwise.

virtual Color GetAmbientClr	(	int	mtlNum,
		BOOL	backFace
	)		[pure virtual]

Search for all occurrences

Returns the Ambient Color.

The parameters to this method are not applicable and may safely be ignored.

virtual Color GetDiffuseClr	(	int	mtlNum,
		BOOL	backFace
	)		[pure virtual]

Search for all occurrences

Returns the Diffuse Color.

The parameters to this method are not applicable and may safely be ignored.

virtual Color GetSpecularClr	(	int	mtlNum,
		BOOL	backFace
	)		[pure virtual]

Search for all occurrences

Returns the Specular Color.

The parameters to this method are not applicable and may safely be ignored.

virtual Color GetSelfIllumClr	(	int	mtlNum,
		BOOL	backFace
	)		[pure virtual]

Search for all occurrences

Returns the Self Illumination Color.

The parameters to this method are not applicable and may safely be ignored.

virtual float GetSelfIllum	(	int	mtlNum,
		BOOL	backFace
	)		[pure virtual]

Search for all occurrences

Returns the Self Illumination Amount.

The parameters to this method are not applicable and may safely be ignored.

virtual float GetGlossiness	(	int	mtlNum,
		BOOL	backFace
	)		[pure virtual]

Search for all occurrences

Returns the Glossiness Level.

The parameters to this method are not applicable and may safely be ignored.

virtual float GetSpecularLevel	(	int	mtlNum,
		BOOL	backFace
	)		[pure virtual]

Search for all occurrences

Returns the Specular Level.

The parameters to this method are not applicable and may safely be ignored.

virtual float GetSoftenLevel	(	int	mtlNum,
		BOOL	backFace
	)		[pure virtual]

Search for all occurrences

Returns the Soften Level as a float.

The parameters to this method are not applicable and may safely be ignored.

virtual BOOL IsSelfIllumClrOn

(

)

[pure virtual]

Search for all occurrences

Returns the Self Illumination Color setting.

Returns:

true if the Self Illumination Color setting is on (checked), false if it is off

virtual Color GetAmbientClr

(

TimeValue

t

)

[pure virtual]

Search for all occurrences

Returns the Ambient Color at the specified time.

Parameters:

t	The time at which to return the color.

virtual Color GetDiffuseClr

(

TimeValue

t

)

[pure virtual]

Search for all occurrences

Returns the Diffuse Color at the specified time.

Parameters:

t	The time at which to return the color.

virtual Color GetSpecularClr

(

TimeValue

t

)

[pure virtual]

Search for all occurrences

Returns the Specular Color at the specified time.

Parameters:

t	The time at which to return the color.

virtual float GetGlossiness

(

TimeValue

t

)

[pure virtual]

Search for all occurrences

Returns the Glossiness value at the specified time.

Parameters:

t	The time at which to return the value.

virtual float GetSpecularLevel

(

TimeValue

t

)

[pure virtual]

Search for all occurrences

Returns the Specular Level at the specified time.

Parameters:

t	The time at which to return the value.

virtual float GetSoftenLevel

(

TimeValue

t

)

[pure virtual]

Search for all occurrences

Returns the Soften Specular Highlights setting at the specified time.

Parameters:

t	The time at which to return the value.

virtual float GetSelfIllum

(

TimeValue

t

)

[pure virtual]

Search for all occurrences

Returns the Self Illumination Amount at the specified time.

Parameters:

t	The time at which to return the value.

virtual Color GetSelfIllumClr

(

TimeValue

t

)

[pure virtual]

Search for all occurrences

Returns the Self Illumination Color at the specified time.

Parameters:

t	The time at which to return the color.

virtual float EvalHiliteCurve

(

float

x

)

[inline, virtual]

Search for all occurrences

Evaluates the hightlight curve that appears in the Shader user interface.

This gets called from the DrawHilite() function which is available to developers in /MAXSDK/SAMPLES/MATERIALS/SHADER/SHADERUTIL.CPP

Parameters:

x	The input value.

Returns:

The output value on the curve. A value of 1.0 represents the top of the curve as it appears in the UI. Values greater than 1.0 are okay and simply appear off the top of the graph.

{ return 0.0f; }

virtual float EvalHiliteCurve2	(	float	x,
		float	y,
		int	level = 0
	)		[inline, virtual]

Search for all occurrences

This is the highlight curve function for the two highlight curves which intersect and appear in the UI, for instance in the Anistropic shader.

Parameters:

x	The x input value.
y	The y input value.
level	This is used by multi-layer shaders to indicate which layer to draw. The draw highlight curve routines use this when redrawing the graph.

Returns:

The output value of the curve.

{ return 0.0f; }

CoreExport void ShadeReflection	(	ShadeContext &	sc,
		IllumParams &	ip,
		Color &	mapClr
	)		[virtual]

Search for all occurrences

Implements the Max std way of handling reflection to provide the default implementation.

Reimplemented from BaseShader.

CoreExport void ShadeTransmission	(	ShadeContext &	sc,
		IllumParams &	ip,
		Color &	mapClr,
		float	amount
	)		[virtual]

Search for all occurrences

Implements the Max std way of handling transmission to provide the default implementation.

Reimplemented from BaseShader.

void PreShade	(	ShadeContext &	sc,
		IReshadeFragment *	pFrag
	)		[inline, virtual]

Search for all occurrences

Remarks:

This method will pre-shade the object and cache any needed values in the fragment.

This method is called on the materials/shaders/textures as the reshading buffer is being built at the same point in the rendering process where the materials shade function would normally be called. Note that at this time the shade context is completely valid, as in a normal rendering. Any values the material wishes to cache can be attached to the reshading fragment passed in, and retrieved later at postShade time.

Parameters:

ShadeContext& sc

A reference to the shade context.

IReshadeFragment* pFrag

A pointer to the fragment.

Default Implementation:

{ }

Reimplemented from IReshading.

{}

void PostShade	(	ShadeContext &	sc,
		IReshadeFragment *	pFrag,
		int &	nextTexIndex,
		IllumParams *	ip
	)		[inline, virtual]

Search for all occurrences

Remarks:

This method will retrieve cached values and compute shade & transparency for the fragment.

This method is called for the material of each fragment as the reshading buffer is being traversed. Materials retrieve whatever they may have stored to complete the minimal shade context and compute a shade for the fragment. PostShade() calls to shaders contain an additional parameter, the IllumParams, filled with the textured/blended but unshaded values for each texture. The shade context passed into PostShade() is the minimal shade context outlined above.

Parameters:

ShadeContext& sc

A reference to the shade context.

IReshadeFragment* pFrag

A pointer to the fragment.

int& nextTexIndex

A reference to the next texture index.

IllumParams* ip = NULL

A pointer to the IllumParams containing textured/blended but unshaded values for each texture.

Default Implementation:

{ }

Reimplemented from IReshading.

{ Illum( sc, *ip ); }

BaseInterface* GetInterface

(

Interface_ID

id

)

[inline, virtual]

Search for all occurrences

Inherited from Animatable.

Returns a pointer to the Base Interface for the interface ID passed.

Parameters:

id	- The unique ID of the interface to get

Returns:

A Pointer to the Interface

Reimplemented from ReferenceTarget.

{ return BaseShader::GetInterface(id); }

void* GetInterface

(

ULONG

id

)

[inline, virtual]

Search for all occurrences

Inherited from Animatable.

Returns a pointer to the interface.

Parameters:

id	- The id of the interface.

Returns:

A Pointer to the Interface

Reimplemented from ReferenceTarget.

                                {
        if( id == IID_IReshading )
            return (IReshading*)( this );
    //  else if ( id == IID_IValidityToken )
    //      return (IValidityToken*)( this );
        else
            return BaseShader::GetInterface(id);
    }