ShadeContext Class Reference

#include <ShadeContext.h>

Class Description

See also

Materials, Textures and Maps, Class LightDesc, Class RenderGlobalContext, Class Color, Class ShadeOutput, Class AColor, Class UVGen, Class Box3, Class IPoint2, Class Point2, Class IRenderElement, Class Point3, Class Class_ID.

Description:

This class is passed to materials and texture maps. It contains all the information necessary for shading the surface at a pixel.

Normally, the ShadeContext is provided by the 3ds Max renderer. However developers that need to create their own ShadeContext for use in passing to the texture and material evaluation functions can do so by deriving a class from ShadeContext and providing implementations of the virtual methods. Some sample code is available demonstrating how this is done in /MAXSDK/SAMPLES/OBJECTS/LIGHT.CPP (see the code for class SCLight : public ShadeContext). The default implementations of these methods are shown for developers that need to create their own ShadeContext.

Note that raytracing (and all shading calculations in the default renderer) takes place in camera space.

For additional information on the methods DP(), Curve(), DUVW() and DPdUVW() see Additional Notes.

All methods are implemented by the system unless noted otherwise.

Data Members:

BOOL doMaps

Indicates if texture maps should be applied.

BOOL filterMaps;

Indicates if textures should be filtered.

BOOL shadow

Indicates if shadows should be applied.

BOOL backFace;

Indicates if we are on the back side of a 2-sided face.

int mtlNum

The material number of the face being shaded. This is the sub-material number for multi-materials.

Color ambientLight

This is the color of the ambient light.

int nLights;

This is the number of lights being used in a render, which is the number of active lights in the scene, or if there are none, 2 for the default lights. For example, this is used in the Standard material in a loop like this:

LightDesc *l;
for (int i=0; i\<sc.nLights; i++) {
    l = sc.Light(i);
    ..etc
}

int rayLevel;

This data member is available in release 2.0 and later only.

This is used to limit the number of reflections for raytracing. For instance, if you're rendering a hall of mirrors, and the ray is reflecting back and forth, you don't want the raytracing to go forever. Every time Texmap::EvalColor() gets called again on a ray you create a new ShadeContext and bump up the rayLevel one. This allows you to test this value and see if it has reached the limit of how deep to go (if it reaches a maximum level, you can return black for example).

Note that it is conceivable that more than one raytrace material can be in effect at a time (from different developers). In such a case, where one surface might have one raytracer and another surface a different one, and a ray was bouncing back and forth between them, each needs to be aware of the other. This is why this value is here – the two texmaps each modify and check it.

int xshadeID;

This data member is available in release 2.0 and later only.

This is currently not used.

RenderGlobalContext *globContext;

This data member is available in release 2.0 and later only.

Points to an instance of RenderGlobalContext. This class describes the properties of the global rendering environment. This provides information such as the renderer in use, the project type for rendering, the output device width and height, several matrices for transforming between camera and world coordinates, the environment map, the atmospheric effects, the current time, field rendering information, and motion blur information.

LightDesc *atmosSkipLight;

The light description of lights to prevent self shadowing by volumetric lights.

RenderGlobalContext *globContext;

A pointer to the rendering global context.

ShadeOutput out;

This is where the material should leave its results.

The following is a discussion of blending the ShadeContext.out.c and ShadeContext.out.t together to get the final color:

The (c,t) returned by shaders is interpreted as follows: t.r is the (premultiplied) alpha for the r-channel, etc.

So if you want to composite (c,t) over a background b,

color = b*t + c ( where the multiplication of b and t multiplies the individual components ).

When you want to convert a (c,t) to a simple R,G,B,Alpha, just average together the components of t to get Alpha. (and use the r,g,b components of c directly).

Inheritance diagram for ShadeContext:

Public Member Functions
void	ResetOutput (int n=-1)
virtual Class_ID	ClassID ()
virtual BOOL	InMtlEditor ()=0
virtual int	Antialias ()
virtual int	ProjType ()
virtual LightDesc *	Light (int n)=0
virtual TimeValue	CurTime ()=0
virtual int	NodeID ()
virtual INode *	Node ()
virtual Object *	GetEvalObject ()
virtual Point3	BarycentricCoords ()
virtual int	FaceNumber ()=0
virtual Point3	Normal ()=0
virtual void	SetNormal (Point3 p)
virtual Point3	OrigNormal ()
virtual Point3	GNormal ()=0
virtual float	Curve ()
virtual Point3	V ()=0
virtual void	SetView (Point3 p)=0
virtual Point3	OrigView ()
virtual Point3	ReflectVector ()=0
virtual Point3	RefractVector (float ior)=0
virtual void	SetIOR (float ior)
virtual float	GetIOR ()
virtual Point3	CamPos ()=0
virtual Point3	P ()=0
virtual Point3	DP ()=0
virtual void	DP (Point3 &dpdx, Point3 &dpdy)
virtual Point3	PObj ()=0
virtual Point3	DPObj ()=0
virtual Box3	ObjectBox ()=0
virtual Point3	PObjRelBox ()=0
virtual Point3	DPObjRelBox ()=0
virtual void	ScreenUV (Point2 &uv, Point2 &duv)=0
virtual IPoint2	ScreenCoord ()=0
virtual Point2	SurfacePtScreen ()
virtual Point3	UVW (int channel=0)=0
virtual Point3	DUVW (int channel=0)=0
virtual void	DPdUVW (Point3 dP[3], int channel=0)=0
virtual int	BumpBasisVectors (Point3 dP[2], int axis, int channel=0)
virtual BOOL	IsSuperSampleOn ()
virtual BOOL	IsTextureSuperSampleOn ()
virtual int	GetNSuperSample ()
virtual float	GetSampleSizeScale ()
virtual Point3	UVWNormal (int channel=0)
virtual float	RayDiam ()
virtual float	RayConeAngle ()
virtual CoreExport AColor	EvalEnvironMap (Texmap *map, Point3 view)
virtual void	GetBGColor (Color &bgcol, Color &transp, BOOL fogBG=TRUE)=0
virtual float	CamNearRange ()
virtual float	CamFarRange ()
virtual Point3	PointTo (const Point3 &p, RefFrame ito)=0
virtual Point3	PointFrom (const Point3 &p, RefFrame ifrom)=0
virtual Point3	VectorTo (const Point3 &p, RefFrame ito)=0
virtual Point3	VectorFrom (const Point3 &p, RefFrame ifrom)=0
virtual CoreExport Point3	VectorToNoScale (const Point3 &p, RefFrame ito)
virtual CoreExport Point3	VectorFromNoScale (const Point3 &p, RefFrame ifrom)
virtual void	SetGBufferID (int gbid)
virtual FILE *	DebugFile ()
virtual AColor	EvalGlobalEnvironMap (Point3 dir)
virtual BOOL	GetCache (Texmap *map, AColor &c)
virtual BOOL	GetCache (Texmap *map, float &f)
virtual BOOL	GetCache (Texmap *map, Point3 &p)
virtual void	PutCache (Texmap *map, const AColor &c)
virtual void	PutCache (Texmap *map, const float f)
virtual void	PutCache (Texmap *map, const Point3 &p)
virtual void	TossCache (Texmap *map)
virtual INT_PTR	Execute (int cmd, ULONG_PTR arg1=0, ULONG_PTR arg2=0, ULONG_PTR arg3=0)
LightDesc *	GetAtmosSkipLight ()
void	SetAtmosSkipLight (LightDesc *lt)
virtual int	NRenderElements ()
virtual IRenderElement *	GetRenderElement (int n)
virtual CoreExport Color	DiffuseIllum ()
MAX_DEPRECATED bool	IsPhysicalSpace () const
template<class T >
MAX_DEPRECATED void	ScaledToRGB (T &energy) const
MAX_DEPRECATED float	ScaledToRGB (float energy) const
MAX_DEPRECATED void	ScaledToRGB ()
template<class T >
MAX_DEPRECATED void	ScalePhysical (T &energy) const
MAX_DEPRECATED float	ScalePhysical (float energy) const
template<class T >
MAX_DEPRECATED void	ScaleRGB (T &energy) const
MAX_DEPRECATED float	ScaleRGB (float energy) const
	ShadeContext ()
Public Member Functions inherited from InterfaceServer
virtual UtilExport	~InterfaceServer ()
	Destructor. More...
virtual UtilExport BaseInterface *	GetInterface (Interface_ID id)

Public Attributes
SCMode	mode
	The rendering mode in which the shade context is currently operating. More...
BOOL	doMaps
BOOL	filterMaps
BOOL	shadow
BOOL	backFace
int	mtlNum
Color	ambientLight
int	nLights
int	rayLevel
int	xshadeID
LightDesc *	atmosSkipLight
RenderGlobalContext *	globContext
ShadeOutput	out

Additional Inherited Members
Static Public Member Functions inherited from MaxHeapOperators
static UtilExport void *	operator new (size_t size)
	Standard new operator used to allocate objects If there is insufficient memory, an exception will be thrown. More...
static UtilExport void *	operator new (size_t size, const std::nothrow_t &e)
	Standard new operator used to allocate objects if there is insufficient memory, NULL will be returned. More...
static UtilExport void *	operator new (size_t size, const char *filename, int line)
	New operator used to allocate objects that takes the filename and line number where the new was called If there is insufficient memory, an exception will be thrown. More...
static UtilExport void *	operator new (size_t size, int block_type, const char *filename, int line)
	New operator used to allocate objects that takes the type of memory, filename and line number where the new was called If there is insufficient memory, an exception will be thrown. More...
static UtilExport void *	operator new (size_t size, const std::nothrow_t &e, const char *filename, int line)
	New operator used to allocate objects that takes the filename and line number where the new was called If there is insufficient memory, NULL will be returned. More...
static UtilExport void *	operator new (size_t size, unsigned long flags)
	New operator used to allocate objects that takes extra flags to specify special operations If there is insufficient memory, an exception will be thrown. More...
static UtilExport void *	operator new (size_t size, const std::nothrow_t &e, unsigned long flags)
	New operator used to allocate objects that takes extra flags to specify special operations If there is insufficient memory, NULL will be returned. More...
static UtilExport void *	operator new[] (size_t size)
	New operator used to allocate arrays of objects If there is insufficient memory, an exception will be thrown. More...
static UtilExport void *	operator new[] (size_t size, const std::nothrow_t &e)
	New operator used to allocate arrays of objects If there is insufficient memory, NULL will be returned. More...
static UtilExport void *	operator new[] (size_t size, const char *filename, int line)
	New operator used to allocate arrays of objects If there is insufficient memory, an exception will be thrown. More...
static UtilExport void *	operator new[] (size_t size, int block_type, const char *filename, int line)
	New operator used to allocate arrays of objects. More...
static UtilExport void *	operator new[] (size_t size, const std::nothrow_t &e, const char *filename, int line)
	New operator used to allocate arrays of objects If there is insufficient memory, NULL will be returned. More...
static UtilExport void *	operator new[] (size_t size, unsigned long flags)
	New operator used to allocate arrays of objects If there is insufficient memory, an exception will be thrown. More...
static UtilExport void *	operator new[] (size_t size, const std::nothrow_t &e, unsigned long flags)
	New operator used to allocate arrays of objects If there is insufficient memory, NULL will be returned. More...
static UtilExport void	operator delete (void *ptr)
	Standard delete operator used to deallocate an object If the pointer is invalid, an exception will be thrown. More...
static UtilExport void	operator delete (void *ptr, const std::nothrow_t &e)
	Standard delete operator used to deallocate an object If the pointer is invalid, nothing will happen. More...
static UtilExport void	operator delete (void *ptr, const char *filename, int line)
	Delete operator used to deallocate an object that takes the filename and line number where the delete was called If the pointer is invalid, an exception will be thrown. More...
static UtilExport void	operator delete (void *ptr, int block_type, const char *filename, int line)
	Delete operator used to deallocate an object that takes the type of memory, filename and line number where the delete was called If the pointer is invalid, an exception will be thrown. More...
static UtilExport void	operator delete (void *ptr, const std::nothrow_t &e, const char *filename, int line)
	Delete operator used to deallocate an object that takes the filename and line number where the delete was called If the pointer is invalid, nothing will happen. More...
static UtilExport void	operator delete (void *ptr, unsigned long flags)
	Delete operator used to deallocate an object that takes extra flags to specify special operations If the pointer is invalid, an exception will be thrown. More...
static UtilExport void	operator delete (void *ptr, const std::nothrow_t &e, unsigned long flags)
	Delete operator used to deallocate an object that takes extra flags to specify special operations If the pointer is invalid, nothing will happen. More...
static UtilExport void	operator delete[] (void *ptr)
	Standard delete operator used to deallocate an array of objects If the pointer is invalid, an exception will be thrown. More...
static UtilExport void	operator delete[] (void *ptr, const std::nothrow_t &e)
	Standard delete operator used to deallocate an array of objects If the pointer is invalid, nothing will happen. More...
static UtilExport void	operator delete[] (void *ptr, const char *filename, int line)
	Delete operator used to deallocate an array of objects that takes the filename and line number where the delete was called If the pointer is invalid, an exception will be thrown. More...
static UtilExport void	operator delete[] (void *ptr, int block_type, const char *filename, int line)
	Delete operator used to deallocate an array of objects that takes the type of memory, filename and line number where the delete was called If the pointer is invalid, an exception will be thrown. More...
static UtilExport void	operator delete[] (void *ptr, const std::nothrow_t &e, const char *filename, int line)
	Delete operator used to deallocate an array of objects that takes the filename and line number where the delete was called If the pointer is invalid, nothing will happen. More...
static UtilExport void	operator delete[] (void *ptr, unsigned long flags)
	Delete operator used to deallocate an array of objects that takes extra flags to specify special operations If the pointer is invalid, an exception will be thrown. More...
static UtilExport void	operator delete[] (void *ptr, const std::nothrow_t &e, unsigned long flags)
	Delete operator used to deallocate an array of objects that takes extra flags to specify special operations If the pointer is invalid, an exception will be thrown. More...
static UtilExport void *	operator new (size_t size, void *placement_ptr)
	Placement new operator. More...
static UtilExport void	operator delete (void *ptr, void *placement_ptr)
	Placement delete operator. More...
static UtilExport void *	aligned_malloc (size_t size, size_t alignment)
	Allocates memory on a specified alignment boundary. More...
static UtilExport void *	aligned_realloc (void *ptr, size_t size, size_t alignment)
	Reallocates memory on a specified alignment boundary. More...
static UtilExport void	aligned_free (void *ptr)
	Frees a block of memory that was allocated with aligned_malloc/aligned_realloc. More...

Constructor & Destructor Documentation

ShadeContext ( )

inline

Remarks

Constructor. The data members are initialized as follows:

mode = SCMODE_NORMAL; nLights = 0; shadow = TRUE; rayLevel = 0; globContext = NULL; atmosSkipLight = NULL;

                   {
        mode = SCMODE_NORMAL; nLights = 0; shadow = TRUE;  rayLevel = 0; 
        globContext = NULL; atmosSkipLight = NULL; 
    }

Member Function Documentation

void ResetOutput ( int  n = -1 )

inline

Remarks

Sets the surface color output and surface transparency output to Black.

Parameters:

int n = -1

By supplying a negative value this method will clear elements but leave the number of elements unchanged.

{ out.Reset(n); }   

virtual Class_ID ClassID ( )

inlinevirtual

Remarks

Returns the Class_ID of this ShadeContext. This is used to distinguish different ShadeContexts.

Default Implementation:

{ return Class_ID(0,0); }

{ return Class_ID(0,0); }  // to distinguish different ShadeContexts.

virtual BOOL InMtlEditor ( )

pure virtual

Remarks

Returns TRUE if this rendering is for the material editor sample sphere (geometry); otherwise FALSE.

virtual int Antialias ( )

inlinevirtual

Remarks

Returns the state of the antialiasing switch in the renderer dialog - TRUE if on; FALSE if off.

Default Implementation:

{return 0;}

{return 0;}

virtual int ProjType ( )

inlinevirtual

Remarks

This method returns the projection type.

Returns

A value of 0 indicates perspective projection; a value of 1 indicates parallel projection.

Default Implementation:

{return 0;}

{ return 0;} // returns: 0: perspective, 1: parallel

virtual LightDesc* Light ( int  n )

pure virtual

Remarks

This method returns the 'i-th' light. Use data member nLights to get the total number of lights.

Parameters:

int n

Specifies the light to return.

virtual TimeValue CurTime ( )

pure virtual

Remarks

Returns the current time value (the position of the frame slider).

Returns

The current time.

virtual int NodeID ( )

inlinevirtual

Remarks

Returns the node ID for the item being rendered or -1 if not set. This ID is assigned when the scene is being rendered - each node is simply given an ID - 0, 1, 2, 3, etc.

Default Implementation:

{return -1;}

{ return -1; }

virtual INode* Node ( )

inlinevirtual

Remarks

Returns the INode pointer of the node being rendered. This pointer allows a developer to access the properties of the node. See Class INode.

Default Implementation:

{ return NULL; }

{ return NULL; }

virtual Object* GetEvalObject ( )

inlinevirtual

Remarks

Returns the evaluated object for this node. When rendering, usually one calls GetRenderMesh() to get the mesh to render. However, at certain times you might want to get the object itself from the node. For example, you could then call ClassID() on the object and determine its type. Then the object could be operated on procedurally (for instance you could recognize it as a true sphere, cylinder or torus). Note that this method will return NULL if object is motion blurred.

For example, here is how you can check if the object is a particle system:

// . . .
Object *ob = sc.GetEvalObject();
if (ob \&\& ob-\>IsParticleSystem()) { // . . . }

Default Implementation:

{ return NULL; }

{ return NULL; } // Returns the evaluated object for this node. 

virtual Point3 BarycentricCoords ( )

inlinevirtual

Remarks

The coordinates relative to triangular face. The barycentric coordinates of a point p relative to a triangle describe that point as a weighted sum of the vertices of the triangle. If the barycentric coordinates are b0, b1, and b2, then:

p = b0*p0 + b1*p1 + b2*p2;

where p0, p1, and p2 are the vertices of the triangle. The Point3 returned by this method has the barycentric coordinates stored in the its three coordinates. These coordinates are relative to the current triangular face being rendered. These barycentric coordinates can be used to interpolate any quantity whose value is known at the vertices of the triangle. For example, if a radiosity shader had available the illumination values at each of the three vertices, it could determine the illumination at the current point using the barycentric coordinates.

Default Implementation:

{ return Point3(0,0,0);}

{ return Point3(0,0,0);}  // coords relative to triangular face 

virtual int FaceNumber ( )

pure virtual

Remarks

Returns the index of the face being rendered. For the scan-line renderer, which renders only triangle meshes, this is the index of the face in the Mesh data structure. This is meant for use in plug-in utilities such as a radiosity renderer, which stores a table of data, indexed on face number, in the Nodes's AppData, for use in a companion material.

virtual Point3 Normal ( )

pure virtual

Remarks

Returns the interpolated normal (in camera space). This is the value of the face normal facing towards the camera. This is affected by SetNormal() below.

virtual void SetNormal ( Point3  p )

inlinevirtual

Remarks

This method will set the value of the face normal facing towards the camera. This may be used to temporarily perturb the normal. The Standard material uses this for example because it implements bump mapping. It changes the normal and then calls other lighting functions, etc. These other method then see this changed normal value. When it is done it puts back the previous value.

Parameters:

Point3 p

The normal to set.

{} // used for perturbing normal

virtual Point3 OrigNormal ( )

inlinevirtual

Remarks

Returns the original surface normal (not affected by SetNormal() above.)

Default Implementation:

{ return Normal(); }

{ return Normal(); } // original surface normal: not affected by SetNormal();

virtual Point3 GNormal ( )

pure virtual

Remarks

This returns the geometric normal. For triangular mesh objects this means the face normal. Normals are unit vectors.

virtual float Curve ( )

inlinevirtual

Remarks

This is an estimate of how fast the normal is varying. For example if you are doing environment mapping this value may be used to determine how big an area of the environment to sample. If the normal is changing very fast a large area must be sampled otherwise you'll get aliasing. This is an estimate of dN/dsx, dN/dsy put into a single value.

{ return 0.0f; }          // estimate of dN/dsx, dN/dsy

virtual Point3 V ( )

pure virtual

Remarks

This method returns the unit view vector, from the camera towards P, in camera space.

virtual void SetView ( Point3  p )

pure virtual

Remarks

Sets the view vector as returned by V().

Parameters:

Point3 p

The view vector set.

virtual Point3 OrigView ( )

inlinevirtual

Remarks

This is the original view vector that was not affected by ShadeContext::SetView().

Default Implementation:

{ return V(); }

{ return V(); } // Original view vector: not affected by SetView();

virtual Point3 ReflectVector ( )

pure virtual

Remarks

This takes the current view vector and the current normal vector and calculates a vector that would result from reflecting the view vector in the surface. This returns the reflection vector.

virtual Point3 RefractVector ( float  ior )

pure virtual

Remarks

This is similar to the method above however it calculates the view vector being refracted in the surface. This returns the refraction vector.

Parameters:

float ior

The relative index of refraction between the air and the material.

virtual void SetIOR ( float  ior )

inlinevirtual

Remarks

Set index of refraction.

Parameters:

float ior

The index of refraction to set. This value can be any positive (non-zero) value.

Default Implementation:

{}

{} // Set index of refraction

virtual float GetIOR ( )

inlinevirtual

Remarks

Returns the index of refraction.

Default Implementation:

{ return 1.0f; }

{ return 1.0f; } // Get index of refraction

virtual Point3 CamPos ( )

pure virtual

Remarks

Returns the camera position in camera space. For the 3ds Max renderer this will always be 0,0,0.

virtual Point3 P ( )

pure virtual

Remarks

Returns the point to be shaded in camera space.

virtual Point3 DP ( )

pure virtual

Remarks

This returns the derivative of P, relative to the pixel. This gives the renderer or shader information about how fast the position is changing relative to the screen.

virtual void DP ( Point3 &  dpdx, Point3 &  dpdy  )

inlinevirtual

Remarks

This returns the derivative of P, relative to the pixel - same as above. This method just breaks it down into x and y.

{};  // deriv of P, relative to pixel

virtual Point3 PObj ( )

pure virtual

Remarks

Returns the point to be shaded in object coordinates.

virtual Point3 DPObj ( )

pure virtual

Remarks

Returns the derivative of PObj(), relative to the pixel.

virtual Box3 ObjectBox ( )

pure virtual

Remarks

Returns the object extents bounding box in object coordinates.

virtual Point3 PObjRelBox ( )

pure virtual

Remarks

Returns the point to be shaded relative to the object box where each component is in the range of -1 to +1.

virtual Point3 DPObjRelBox ( )

pure virtual

Remarks

Returns the derivative of PObjRelBox(). This is the derivative of the point relative to the object box where each component is in the range of -1 to +1.

virtual void ScreenUV ( Point2 &  uv, Point2 &  duv  )

pure virtual

Remarks

Retrieves the point relative to the screen where the lower left corner is 0,0 and the upper right corner is 1,1.

Parameters:

Point2& uv

The point.

Point2 &duv

The derivative of the point.

virtual IPoint2 ScreenCoord ( )

pure virtual

Remarks

Returns the integer screen coordinate (from the upper left).

virtual Point2 SurfacePtScreen ( )

inlinevirtual

Remarks

Return the surface point at the center of the fragment in floating point screen coordinates. See the documentation for Sampler::DoSample() for an explanation of the use of this method. See Class Sampler.

Default Implementation:

{ return Point2(0.0,0.0); }

{ return Point2(0.0,0.0); } // return the surface point in screen coords

virtual Point3 UVW ( int  channel = 0 )

pure virtual

Remarks

Returns the UVW coordinates for the point.

Parameters:

int channel=0;

Specifies the channel for the values. One of the following:

0: Vertex Color Channel.

1 through 99: Mapping Channels.

virtual Point3 DUVW ( int  channel = 0 )

pure virtual

Remarks

This method returns the UVW derivatives for the point. This is used for filtering texture maps and antialiasing procedurals that are using UVW. Note that in standard 3ds Max textures, the UVGen class is used, and it calls this method itself. See the methods UVGen::GetBumpDP() for more details for using UVGen. If you are not using UVGen then you can use this method and UVW(). UVW() gets the UVW coordinates of the point and DUVW() gets the change in the UVWs for the point. This tells you a maximum change for each of UVW. This tells you how much of the area of the map to sample. So when you call the Bitmap method GetFiltered(float u, float v, float du, float dv, BMM_Color_64 *ptr) this tells you how big the sample should be. This lets you filter or average over this area to keep the map from aliasing.

Parameters:

int channel=0;

Specifies the channel for the values. One of the following:

0: Vertex Color Channel.

1 through 99: Mapping Channels.

virtual void DPdUVW ( Point3  dP[3], int  channel = 0  )

pure virtual

Remarks

This returns the bump basis vectors for UVW in camera space. Note that if you want to retrieve these bump basis vectors that are altered by the UVGen instance use the method UVGen::GetBumpDP(). Also see the Advanced Topics section Materials, Textures and Maps for more details on bump mapping.

Parameters:

Point3 dP[3]

The bump basic vectors. dP[0] is a vector corresponding to the U direction. dp[1] corresponds to V, and dP[2] corresponds to W.

int channel=0;

Specifies the channel for the values. One of the following:

0: Vertex Color Channel.

1 through 99: Mapping Channels.

virtual int BumpBasisVectors ( Point3  dP[2], int  axis, int  channel = 0  )

inlinevirtual

Remarks

This method should replace DpDUVW over time but is left in place as not to break 3rd party plugins. If this method returns 1, that is assumed to mean it is implemented, and it will be used instead of DpDUVW.

Parameters:

Point3 dP[2]

The bump basic vectors. dP[0] is a vector corresponding to the U direction. dp[1] corresponds to V, and dP[2] corresponds to W.

int axis

Specified the 2D cases for: AXIS_UV, AXIS_VW, or AXIS_WU.

int channel=0;

Specifies the channel for the values. One of the following:

0: Vertex Color Channel.

1 through 99: Mapping Channels.

Default Implementation:

{ return 0; }

{ return 0; } 

virtual BOOL IsSuperSampleOn ( )

inlinevirtual

{ return FALSE; }

virtual BOOL IsTextureSuperSampleOn ( )

inlinevirtual

{ return FALSE; }

virtual int GetNSuperSample ( )

inlinevirtual

{ return 0; }

virtual float GetSampleSizeScale ( )

inlinevirtual

{ return 1.0f; }

virtual Point3 UVWNormal ( int  channel = 0 )

inlinevirtual

Remarks

This method returns a vector in UVW space normal to the face in UVW space. This can be CrossProd(U[1]-U[0],U[2]-U[1]), where U[i] is the texture coordinate at the i-th vertex of the current face. This may be used for hiding textures on back side of objects.

Parameters:

int channel=0;

Specifies the channel for the values. One of the following:

0: Vertex Color Channel.

1 through 99: Mapping Channels.

Default Implementation:

{ return Point3(0,0,1); }

{ return Point3(0,0,1); }  

virtual float RayDiam ( )

inlinevirtual

Remarks

Returns the diameter of the ray cone at the pixel point (the point it intersects the surface being shaded). This is a dimension in world units. As a ray is propagated it is updated for each new surface that is encountered.

Default Implementation:

{ return Length(DP()); }

{ return Length(DP()); } 

virtual float RayConeAngle ( )

inlinevirtual

Remarks

Returns the angle of a ray cone hitting this point. It gets increased/decreased by curvature on reflection.

Visualize a small pyramid, with the top at the eye point, and its sides running through each corner of the pixel to be rendered, then onto the scene. Then visualize a small cone fitting inside this pyramid. This method returns the angle of that cone. When rendering, if the ray cone goes out and hits a flat surface, the angle of reflection will always be constant for each pixel. However, if the ray cone hits a curved surface, the angle will change between pixels. This change in value give some indication of how fast the sample size is getting bigger.

Default Implementation:

{ return 0.0f; }

{ return 0.0f; } 

virtual CoreExport AColor EvalEnvironMap ( Texmap *  map, Point3  view  )

virtual

Remarks

This is used by the Standard material to do the reflection maps and the refraction maps. Given the map, and a direction from which you want to view it, this method changes the view vector to be the specified vector and evaluates the function.

Parameters:

Texmap *map

The map to evaluate.

Point3 view

The view direction.

Returns

The color of the map, in r, g, b, alpha.

virtual void GetBGColor ( Color &  bgcol, Color &  transp, BOOL  fogBG = TRUE  )

pure virtual

Remarks

Retrieves the background color and the background transparency.

Parameters:

class Color &bgCol

The returned background color.

class Color &transp

The returned transparency.

int fogBG

Specifies you want the current atmospheric shaders to be applied to the background color. If TRUE the shaders are applied; if FALSE they are not.

virtual float CamNearRange ( )

inlinevirtual

Remarks

Returns the camera near range set by the user in the camera's user interface.

{return 0.0f;}

virtual float CamFarRange ( )

inlinevirtual

Remarks

Returns the camera far range set by the user in the camera's user interface.

{return 0.0f;}

virtual Point3 PointTo ( const Point3 &  p, RefFrame  ito  )

pure virtual

Remarks

Transforms the specified point from internal camera space to the specified space.

Parameters:

const Point3& p

The point to transform.

RefFrame ito

The space to transform the point to. One of the following values:

REF_CAMERA

REF_WORLD

REF_OBJECT

Returns

The transformed point, in the specified space.

virtual Point3 PointFrom ( const Point3 &  p, RefFrame  ifrom  )

pure virtual

Remarks

Transforms the specified point from the specified coordinate system to internal camera space.

Parameters:

const Point3& p

The point to transform.

RefFrame ifrom

The space to transform the point from. One of the following values:

REF_CAMERA

REF_WORLD

REF_OBJECT

Returns

The transformed point in camera space.

virtual Point3 VectorTo ( const Point3 &  p, RefFrame  ito  )

pure virtual

Remarks

Transform the vector from internal camera space to the specified space.

Parameters:

const Point3& p

The vector to transform.

RefFrame ito

The space to transform the vector to. One of the following values:

REF_CAMERA

REF_WORLD

REF_OBJECT

virtual Point3 VectorFrom ( const Point3 &  p, RefFrame  ifrom  )

pure virtual

Remarks

Transform the vector from the specified space to internal camera space.

Parameters:

const Point3& p

The vector to transform.

RefFrame ifrom

The space to transform the vector from. One of the following values:

REF_CAMERA

REF_WORLD

REF_OBJECT

virtual CoreExport Point3 VectorToNoScale ( const Point3 &  p, RefFrame  ito  )

virtual

Remarks

Transform the vector from internal camera space to the specified space without scaling.

Parameters:

const Point3& p

The vector to transform.

RefFrame ito

The space to transform the vector to. One of the following values:

REF_CAMERA

REF_WORLD

REF_OBJECT

virtual CoreExport Point3 VectorFromNoScale ( const Point3 &  p, RefFrame  ifrom  )

virtual

Remarks

Transform the vector from the specified space to internal camera space without scaling.

Note: This method was added to correct a problem that was occurring in 3D Textures when the bump perturbation vectors were transformed from object space to camera space, so they are oriented correctly as the object rotates. If the object has been scaled, this transformation causes the perturbation vectors to be scale also, which amplifies the bump effect. This method is used to rotate the perturbation vectors so they are correctly oriented in space, without scaling them.

Parameters:

const Point3& p

The vector to transform.

RefFrame ifrom

RefFrame ifrom

The space to transform the vector from. One of the following values:

REF_CAMERA

REF_WORLD

REF_OBJECT

virtual void SetGBufferID ( int  gbid )

inlinevirtual

Remarks

When a map or material is evaluated (in Shade(), EvalColor() or EvalMono()), if it has a non-zero gbufID, it should call this routine to store the gbid into the shade context.

Note: Normally a texmap calls this method so the index would be set for all of the area covered by the texture. There is no reason that this has to be done for every pixel however. A texture could just set the ID for particular pixels. This could allow post processing routines (for example a glow) to only process part of a texture and not the entire thing. For example, at the beginning of texmap's EvalColor() one typically has code that does:

if (gbufid) sc.SetGBufferID(gbufid);

This takes the gbufid (which is in MtlBase) and (if it is non-zero) stores it into the shade context. The renderer, after evaluating the Shade() function for the material at a pixel, looks at the gbufferID left in the shade context, and stores it into the gbuffer at that pixel. So if the texmap adds another condition like

if (inHotPortion)
if (gbufid) sc.SetGBufferID(gbufid);

It will do it for just the chosen pixels.

Parameters:

int gbid

The ID to store.

{ out.gbufId = gbid; }

virtual FILE* DebugFile ( )

inlinevirtual

Remarks

This method is used internally.

{ return NULL; }

virtual AColor EvalGlobalEnvironMap ( Point3  dir )

inlinevirtual

Remarks

Returns the color of the global environment map from the given view direction.

Parameters:

Point3 dir

Specifies the direction of view.

Default Implementation:

{ return AColor(0,0,0,0); }

{ return AColor(0,0,0,0); }

virtual BOOL GetCache ( Texmap *  map, AColor &  c  )

inlinevirtual

Remarks

This method is used with texture maps only. If a map is multiply instanced within the same material, say on the diffuse channel and on the shininess channel, it will return the same value each time its evaluated. Its a waste of processor time to re-evaluate the map twice. This method allows you to cache the value so it won't need to be computed more than once.

Note that the cache is automatically cleared after each ShadeContext call. This is used within one evaluation of a material hierarchy.

Parameters:

Texmap *map

Points to the texmap storing the cache (usually the plug-ins this pointer).

AColor &c

The color to store.

Returns

TRUE if the color was returned; otherwise FALSE.

Default Implementation:

{ return FALSE; }

Sample Code:

This code from /MAXSDK/SAMPLES/MATERIALS/NOISE.CPP and shows how the cache is retrieved and stored:

RGBA Noise::EvalColor(ShadeContext& sc) {
Point3 p,dp;
if (!sc.doMaps) return black;
AColor c;
// If the cache exists, return the color
if (sc.GetCache(this,c))
return c;
// Otherwise compute the color
. . .
// At the end of the eval the cache is stored
sc.PutCache(this,c);
}

{ return FALSE; }

virtual BOOL GetCache ( Texmap *  map, float &  f  )

inlinevirtual

Remarks

Retrieves a floating point value from the cache. See the AColor version above for details.

Parameters:

Texmap *map

Points to the texmap storing the cache (usually the plug-ins this pointer).

float &f

The value to store.

Returns

TRUE if the value was returned; otherwise FALSE.

Default Implementation:

{ return FALSE; }

{ return FALSE; }

virtual BOOL GetCache ( Texmap *  map, Point3 &  p  )

inlinevirtual

Remarks

Retrieves a Point3 value from the cache. See the AColor version above for details.

Parameters:

Texmap *map

Points to the texmap storing the cache (usually the plug-ins this pointer).

Point3 &p

The point to store.

Returns

TRUE if the value was returned; otherwise FALSE.

Default Implementation:

{ return FALSE; }

{ return FALSE; }

virtual void PutCache ( Texmap *  map, const AColor &  c  )

inlinevirtual

Remarks

Puts a color to the cache. See the method GetCache(Texmap *map, const AColor &c) above for details.

Parameters:

Texmap *map

Points to the texmap storing the cache (usually the plug-ins this pointer).

const AColor &c

The color to store.

Default Implementation:

{}

{}

virtual void PutCache ( Texmap *  map, const float  f  )

inlinevirtual

Remarks

Puts a floating point value to the cache. See the method GetCache(Texmap map, const AColor &c) above for details.

Parameters:

Texmap *map

Points to the texmap storing the cache (usually the plug-ins this pointer).

const float f

The floating point value to store.

Default Implementation:

{}

{}

virtual void PutCache ( Texmap *  map, const Point3 &  p  )

inlinevirtual

Remarks

Puts a floating point value to the cache. See the method GetCache(Texmap map, const AColor &c) above for details.

Parameters:

Texmap *map

Points to the texmap storing the cache (usually the plug-ins this pointer).

const Point3 &p

The Point3 value to store.

Default Implementation:

{}

{}

virtual void TossCache ( Texmap *  map )

inlinevirtual

Remarks

Removes the specified cache.

Parameters:

Texmap *map

Points to the texmap storing the cache (usually the plug-ins this pointer).

Default Implementation:

{}

{}

virtual INT_PTR Execute ( int  cmd, ULONG_PTR  arg1 = 0, ULONG_PTR  arg2 = 0, ULONG_PTR  arg3 = 0  )

inlinevirtual

Remarks

This is a general purpose function that allows the API to be extended in the future. The 3ds Max development team can assign new cmd numbers and continue to add functionality to this class without having to 'break' the API.

This is reserved for future use.

Parameters:

int cmd

The command to execute.

ULONG arg1=0

Optional argument 1 (defined uniquely for each cmd).

ULONG arg2=0

Optional argument 2.

ULONG arg3=0

Optional argument 3.

Returns

An integer return value (defined uniquely for each cmd).

Default Implementation:

{ return 0; }

{ return 0; } 

LightDesc* GetAtmosSkipLight ( )

inline

Remarks

This method, along with SetAtmosSkipLight() below, are used by the lights to avoid self-shadowing when applying atmospheric shadows. This method returns a pointer to the LightDesc instance currently calling the Atmosphere::Shade() method when computing atmospheric shadows.

Here's how they are used:

(1) When computing the atmospheric shadows:(somewhere in LightDesc::Illuminate()) do the following:

sc.SetAtmosSkipLight(this);

sc.globContext->atmos->Shade(sc, lightPos, sc.P(), col, trans);

sc.SetAtmosSkipLight(NULL);

(2) In LightDesc::TraverseVolume() do the following:

if (sc.GetAtmosSkipLight()==this)

return;

Default Implementation:

{ return atmosSkipLight; }

\remarks     This method can be used to determine from within the ShadeContext if a

volumetric light should be prevented from generating self-shadows.

Default Implementation:

{ return atmosSkipLight; }

{ return atmosSkipLight; }

void SetAtmosSkipLight ( LightDesc *  lt )

inline

Remarks

This method sets the LightDesc instance currently calling the Atmosphere::Shade() method. See GetAtmosSkipLight() above.

Parameters:

LightDesc *lt

Points to the LightDesc to set.

Default Implementation:

{ atmosSkipLight = lt; }

\remarks     This method allows you to set the volumetric light that should be prevented

from generating self-shadows.

Parameters:

LightDesc *lt

A pointer to the light to set.

Default Implementation:

{ atmosSkipLight = lt; }

{ atmosSkipLight = lt; }

virtual int NRenderElements ( )

inlinevirtual

Remarks

Returns the number of render elements.

Default Implementation:

{ return globContext->NRenderElements(); }

                                  { 
        return globContext ? globContext->NRenderElements():0;
    }

virtual IRenderElement* GetRenderElement ( int  n )

inlinevirtual

Remarks

Returns an interface to the 'i-th' render element.

Parameters:

int n

The zero based index of the render element to return.

Default Implementation:

{ return globContext->GetRenderElement(n); }

                                                    { 
        return globContext ? globContext->GetRenderElement(n) : NULL;
    }

virtual CoreExport Color DiffuseIllum ( )

virtual

Remarks

Computes and returns the incoming diffuse illumination color (for matte/shadow).

MAX_DEPRECATED bool IsPhysicalSpace

(

)

const

Deprecated:

This method merely forwarded the call to globContext->pToneOp. For simplicity of maintenance, it has been removed; globContext->pToneOp should be used directly instead. Make sure to check that both globContext and pToneOp are not null.

MAX_DEPRECATED void ScaledToRGB

(

T &

energy

)

const

Deprecated:

This method merely forwarded the call to globContext->pToneOp. For simplicity of maintenance, it has been removed; globContext->pToneOp should be used directly instead. Make sure to check that both globContext and pToneOp are not null.

MAX_DEPRECATED float ScaledToRGB

(

float

energy

)

const

Deprecated:

This method merely forwarded the call to globContext->pToneOp. For simplicity of maintenance, it has been removed; globContext->pToneOp should be used directly instead. Make sure to check that both globContext and pToneOp are not null.

MAX_DEPRECATED void ScaledToRGB

(

)

Deprecated:

This method merely forwarded the call to globContext->pToneOp. For simplicity of maintenance, it has been removed; globContext->pToneOp should be used directly instead. Make sure to check that both globContext and pToneOp are not null.

MAX_DEPRECATED void ScalePhysical

(

T &

energy

)

const

Deprecated:

This method merely forwarded the call to globContext->pToneOp. For simplicity of maintenance, it has been removed; globContext->pToneOp should be used directly instead. Make sure to check that both globContext and pToneOp are not null.

MAX_DEPRECATED float ScalePhysical

(

float

energy

)

const

Deprecated:

This method merely forwarded the call to globContext->pToneOp. For simplicity of maintenance, it has been removed; globContext->pToneOp should be used directly instead. Make sure to check that both globContext and pToneOp are not null.

MAX_DEPRECATED void ScaleRGB

(

T &

energy

)

const

Deprecated:

This method merely forwarded the call to globContext->pToneOp. For simplicity of maintenance, it has been removed; globContext->pToneOp should be used directly instead. Make sure to check that both globContext and pToneOp are not null.

MAX_DEPRECATED float ScaleRGB

(

float

energy

)

const

Deprecated:

This method merely forwarded the call to globContext->pToneOp. For simplicity of maintenance, it has been removed; globContext->pToneOp should be used directly instead. Make sure to check that both globContext and pToneOp are not null.

Member Data Documentation

SCMode mode

The rendering mode in which the shade context is currently operating.

Maybe be used by materials and texmaps to modify their behaviour.

BOOL doMaps

BOOL filterMaps

BOOL shadow

BOOL backFace

int mtlNum

Color ambientLight

int nLights

int rayLevel

int xshadeID

LightDesc* atmosSkipLight

RenderGlobalContext* globContext

ShadeOutput out