Class Mtl
See Also: Class MtlBase, Class Texmap, Class ShadeContext, ShadeOutput, Class Interval, Class Color.
class Mtl : public MtlBase
Description:
This is the base class for the creation of material plug-ins. This class provides methods to do things such as compute the properties of the material for a given location, return the number of sub-materials and access the properties of the material for the interactive renderer.
Plug-In Information:
Class Defined In IMTL.H
Super Class ID MATERIAL_CLASS_ID
Standard File Name Extension DLT
Extra Include File Needed IMTL.H
Method Groups:
The following hyperlinks take you to the start of groups of related methods within the class:
Methods:
Prototype:
Mtl();
Remarks:
Constructor. The active texture map is set to NULL.
Prototype:
virtual TSTR GetSubMtlSlotName(int i);
Remarks:
Implemented by the Plug-In.
This method returns the slot name of the 'i-th' sub-material. This name appears in the materials editor dialog. For instance, if you are in a material and then you go down into a sub-material, this is the name that appears just below the 'Get Material' icon. For example, in the Multi/Sub-Object material when you choose one of the sub-materials, the map name appears to let you know which slot you are working on. For the Multi/Sub-Object material, this is the number of the slot, i.e."#1:", "#2:", "#3:", etc.
Parameters:
int i
The index of the sub-materials whose slot name should be returned.
Prototype:
TSTR GetSubMtlTVName(int i);
Remarks:
Implemented by the Plug-In.
Returns the name of the 'i-th' sub-material that should appear in track view.
Parameters:
int i
The index of the sub-materials whose track view name should be returned.
Prototype:
virtual void Shade(ShadeContext& sc)=0;
Remarks:
Implemented by the Plug-In.
This is the main method of the material. This is called by the renderer to compute the color and transparency output returned in sc.out.
Parameters:
ShadeContext& sc
Describes properties of the pixel to be shaded. The result of this method is returned in the ShadeOutput data member of sc.
Prototype:
MtlBase* GetActiveTexmap();
Remarks:
Implemented by the System.
Returns a pointer to the active texture map used in the interactive renderer.
Prototype:
void SetActiveTexmap(MtlBase *txm);
Remarks:
Implemented by the System.
Stores the pointer to the active texture map used in the interactive renderer. Note that this method does not do everything required to update the viewports with the new texmap. To accomplish that call Interface::ActivateTexture().
The following methods are used for displaying materials in the 3ds max viewports.
Prototype:
virtual Color GetAmbient(int mtlNum=0, BOOL backFace=FALSE)=0;
Remarks:
Implemented by the Plug-In.
Returns the ambient color of the specified material for use in the interactive renderer.
Parameters:
int mtlNum=0
This is the material index for mult-materials.
BOOL backFace=FALSE
If the surface normal of the face is pointing away from the viewer this will be TRUE; otherwise FALSE.
Prototype:
virtual Color GetDiffuse(int mtlNum=0, BOOL backFace=FALSE)=0;
Remarks:
Implemented by the Plug-In.
Returns the diffuse color of the specified material for use in the interactive renderer.
Parameters:
int mtlNum=0
This is the material index for mult-materials.
BOOL backFace=FALSE
If the surface normal of the face is pointing away from the viewer this will be TRUE; otherwise FALSE.
Prototype:
virtual Color GetSpecular(int mtlNum=0, BOOL backFace=FALSE)=0;
Remarks:
Implemented by the Plug-In.
Returns the specular color of the specified material for use in the interactive renderer.
Parameters:
int mtlNum=0
This is the material index for mult-materials.
BOOL backFace=FALSE
If the surface normal of the face is pointing away from the viewer this will be TRUE; otherwise FALSE.
Prototype:
virtual float GetShininess(int mtlNum=0, BOOL backFace=FALSE)=0;
Remarks:
Implemented by the Plug-In.
Returns the shininess value of the specified material for use in the interactive renderer.
Parameters:
int mtlNum=0
This is the material index for mult-materials.
BOOL backFace=FALSE
If the surface normal of the face is pointing away from the viewer this will be TRUE; otherwise FALSE.
Prototype:
virtual float GetShinStr(int mtlNum=0, BOOL backFace=FALSE)=0;
Remarks:
Implemented by the Plug-In.
Returns the shininess strength value of the specified material for use in the interactive renderer.
Parameters:
int mtlNum=0
This is the material index for mult-materials.
BOOL backFace=FALSE
If the surface normal of the face is pointing away from the viewer this will be TRUE; otherwise FALSE.
Prototype:
virtual float GetXParency(int mtlNum=0, BOOL backFace=FALSE)=0;
Remarks:
Implemented by the Plug-In.
Returns the transparency value of the specified material for use in the interactive renderer.
Parameters:
int mtlNum=0
This is the material index for mult-materials.
BOOL backFace=FALSE
If the surface normal of the face is pointing away from the viewer this will be TRUE; otherwise FALSE.
Prototype:
virtual float GetSelfIllum(int mtlNum=0, BOOL backFace=FALSE);
Remarks:
This method is available in release 2.0 and later only.
Implemented by the Plug-In.
Returns the self illumination value of the specified material for use in the interactive renderer.
Parameters:
int mtlNum=0
This is the material index for mult-materials.
BOOL backFace=FALSE
If the surface normal of the face is pointing away from the viewer this will be TRUE; otherwise FALSE.
Default Implementation:
{ return 0.0f; }
Prototype:
virtual BOOL GetSelfIllumColorOn(int mtlNum=0, BOOL backFace=FALSE);
Remarks:
This method is available in release 3.0 and later only.
Returns TRUE if the Self Illumination Color is on (checked) for the specified material; otherwise FALSE.
Parameters:
int mtlNum=0
This is the material index for mult-materials.
BOOL backFace=FALSE
If the surface normal of the face is pointing away from the viewer this will be TRUE; otherwise FALSE.
Default Implementation:
{ return TRUE; }
Prototype:
virtual Color GetSelfIllumColor(int mtlNum=0, BOOL backFace=FALSE);
Remarks:
This method is available in release 3.0 and later only.
Returns the Self Illumination Color of the specified material for use in the interactive renderer.
Parameters:
int mtlNum=0
This is the material index for mult-materials.
BOOL backFace=FALSE
If the surface normal of the face is pointing away from the viewer this will be TRUE; otherwise FALSE.
Default Implementation:
{ Color c( .0f,.0f,.0f); return c; }
Prototype:
virtual float WireSize(int mtlNum=0, BOOL backFace=FALSE)
Remarks:
Implemented by the Plug-In.
Returns the wire size of the material.
Parameters:
int mtlNum=0
This is the material index for mult-materials.
BOOL backFace=FALSE
If the surface normal of the face is pointing away from the viewer this will be TRUE; otherwise FALSE.
Default Implementation:
{ return 1.0f; }
Prototype:
virtual Sampler *GetPixelSampler(int mtlNum=0, BOOL backFace=FALSE);
Remarks:
This method is available in release 3.0 and later only.
Returns a pointer to the Sampler used for the specified sub-material.
Parameters:
int mtlNum=0
This is the material index for mult-materials.
BOOL backFace=FALSE
If the surface normal of the face is pointing away from the viewer this will be TRUE; otherwise FALSE.
Default Implementation:
{ return NULL; }
Prototype:
virtual RenderData *GetRenderData();
Remarks:
This method is available in release 4.0 and later only.
This method returns the auxiliary data attached to the material by the renderer.
Default Implementation:
{ return renderData; }
Prototype:
virtual BOOL IsOutputConst(ShadeContext& sc, int stdID);
Remarks:
This method is available in release 4.0 and later only.
This method returns TRUE if the evaluated color/value (output) is constant over all possible inputs described by the shade context. If it cannot determine the correct answer, it returns FALSE.
Parameters:
ShadeContext& sc
This describes the context of the question.
int stdID
The ID of the channel in question. See List of Texture Map Indices
Default Implementation:
{ return FALSE; }
Prototype:
virtual BOOL EvalColorStdChannel(ShadeContext& sc, int stdID, Color&
outClr);
Remarks:
This method is available in release 4.0 and later only.
This method evaluates the material on a single standard texmap channel over an area described in the ShadeContext. A return value of FALSE indicates that the color could not be evaluated.
If there's no texmap defined for a channel or the output of the texmap is not "meaningful", the raw color stored by the material or shader is returned. (The output of a texmap is meaningful in a given ShadeContext if it is the same as when the scene is rendered. If the map cannot determine whether the output value is the same as when rendered, it should not be meaningful.)
Note that the output color is not clamped. If the method is called with a monochrome channel ID, the result value is copied in the R, G and B components of the Color structure.
As a default implementation, this method sets the output color to black and returns FALSE.
Parameters:
ShadeContext& sc
This describes the context in which the material should be evaluated.
int stdID
The ID of the channel to perform evaluation on. See List of Texture Map Indices
Color& outClr
The result of the evaluation.
Default Implementation:
{ return FALSE; }
Prototype:
virtual void SetAmbient(Color c, TimeValue t)=0;
Remarks:
Implemented by the Plug-In.
This method saves the specified color at the specified time.
Parameters:
Color c
The color to store.
TimeValue t
The time to set this color.
Prototype:
virtual void SetDiffuse(Color c, TimeValue t)=0;
Remarks:
Implemented by the Plug-In.
This method saves the specified color at the specified time.
Parameters:
Color c
The color to store.
TimeValue t
The time to set this color.
Prototype:
virtual void SetSpecular(Color c, TimeValue t)=0;
Remarks:
Implemented by the Plug-In.
This method saves the specified color at the specified time.
Parameters:
Color c
The color to store.
TimeValue t
The time to set this color.
Prototype:
virtual void SetShininess(float v, TimeValue t)=0;
Remarks:
Implemented by the Plug-In.
This method saves the specified shininess at the specified time.
Parameters:
float v
The shininess value to store.
TimeValue t
The time to set this color.
Prototype:
virtual void SetRenderData(RenderData *rdata);
Remarks:
This method is available in release 4.0 and later only.
This method allows the renderer to attach auxiliary data to each material.
Parameters:
RenderData *rdata
The auxiliary data you wish to attach.
Default Implementation:
{ renderData = rdata; }
Prototype:
virtual int NumSubMtls()
Remarks:
Implemented by the Plug-In.
Returns the number of sub-materials managed by this material.
Default Implementation:
{ return 0; }
Prototype:
virtual Mtl* GetSubMtl(int i)
Remarks:
Implemented by the Plug-In.
Returns a pointer to the 'i-th' sub-material of this material.
Parameters:
int i
The index of the material to return.
Default Implementation:
{ return NULL; }
Prototype:
virtual void SetSubMtl(int i, Mtl *m)
Remarks:
Implemented by the Plug-In.
Stores the 'i-th' sub-material of this material.
Parameters:
int i
The index of the material to store.
Mtl *m
The material pointer to store.
Default Implementation:
{}
Prototype:
virtual int SubMtlOn(int i);
Remarks:
This method is not currently used.
Prototype:
virtual int VPDisplaySubMtl();
Remarks:
This method is available in release 4.0 and later only.
This method returns which sub-mtl is to display in the viewport, a return value of:-1 indicates not implemented.
Note that when a material, such as Blend, has a method of selecting which sub-map is to be shown in the viewport, and implements this method, the materials editor lets you turn on Show Map In Viewport (SMIV) in all the sub maps at once. When the material, such as top-bottom, doesn't have a selector, and doesn't implement this method, then the materials editor will only let you turn on SMIV for one map/mtl in the entire sub-tree of the material.
Default Implementation:
{ return -1; }
Prototype:
float GetDynamicsProperty(TimeValue t, int mtlNum, int propID);
Remarks:
This method is available in release 2.0 and later only.
This method returns the specified dynamics property of the material at the specified time.
Parameters:
TimeValue t
The time to return the dynamics property.
int mtlNum
The index of the sub-material or zero if this is a base material.
int propID
Specifies the type of property. One of the following values:
DYN_BOUNCE
The bounce coefficient. Values in the range 0.0 to 1.0.
DYN_STATIC_FRICTION
The static friction property. Values in the range 0.0 to 1.0.
DYN_SLIDING_FRICTION
The sliding friction property. Values in the range 0.0 to 1.0.
Default Implementation:
The default implementation for Mtl will handle all multi-materials. All root level materials (for instance Standard) need to implement this method.
Prototype:
void SetDynamicsProperty(TimeValue t, int mtlNum, int propID, float value);
Remarks:
This method is available in release 2.0 and later only.
This method sets the specified dynamics property of the material at the specified time.
Parameters:
TimeValue t
The time at which to set the value.
int mtlNum
The sub-material number for a multi-material.
int propID
Specifies the type of property. One of the following values:
DYN_BOUNCE
The bounce coefficient. Values in the range 0.0 to 1.0.
DYN_STATIC_FRICTION
The static friction property. Values in the range 0.0 to 1.0.
DYN_SLIDING_FRICTION
The sliding friction property. Values in the range 0.0 to 1.0.
float value
The value to set.
Default Implementation:
The default implementation for Mtl will handle all multi-materials. All root level materials (for instance Standard) need to implement this method.
Prototype:
virtual float EvalDisplacement(ShadeContext& sc);
Remarks:
This method is available in release 2.0 and later only.
Returns the amound of displacement along the normal of the surface at the point as specified by the ShadeContext.
Parameters:
ShadeContext& sc
This contains the details of the point being displaced.
Default Implementation:
{ return 0.0f; }
Prototype:
virtual Interval DisplacementValidity(TimeValue t);
Remarks:
This method is available in release 2.0 and later only.
Returns the validity interval of the displacement mapping around the specified time.
Parameters:
TimeValue t
The Interval returned reflects the validity around this time.
Default Implementation:
{ return FOREVER; }
Prototype:
virtual BOOL DontKeepOldMtl();
Remarks:
This method is available in release 3.0 and later only.
Return TRUE to prevent the Replace Material (Discard old material? / Keep old material as sub-material?) dialog from being presented to the user; FALSE to allow it to be presented. This allows a plug-in to control the display of this dialog when being created in a Material Editor slot.
Default Implementation:
{ return FALSE; }
Prototype:
virtual BOOL SupportsShaders();
Remarks:
This method is available in release 4.0 and later only.
This method returns TRUE if the material supports shaders, otherwise FALSE.
Default Implementation:
{ return FALSE; }