This reference page is linked to from the following overview topics: Material and Texture Map Plug-ins, Thread Safety, Plug-in Base Classes, Parameter Types, Retrieving the Material from a Node, Mental Ray Classes, Translation of Texture Map and Materials, Supported Types.

Detailed Description

See also:: Class MtlBase, Class Texmap, Class ShadeContext, Class ShadeOutput, Class Interval, Class Color.

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:: See Method Groups for Class Mtl.

#include <imtl.h>

Inheritance diagram for Mtl:

[legend]

List of all members.

Public Member Functions
CoreExport	Mtl ()
SClass_ID	SuperClassID ()
	Retrieves a constant representing the type of the plugin.
virtual void	GetClassName (MSTR &s)
	Retrieves the name of the plugin class.
CoreExport MtlBase *	GetActiveTexmap ()
CoreExport void	SetActiveTexmap (MtlBase *txm)
CoreExport void	RefDeleted ()
	Called after a references to this is deleted.
CoreExport void	RefAdded (RefMakerHandle rm)
	Called after a reference is made to a target.
virtual Color	GetAmbient (int mtlNum=0, BOOL backFace=FALSE)=0
virtual Color	GetDiffuse (int mtlNum=0, BOOL backFace=FALSE)=0
virtual Color	GetSpecular (int mtlNum=0, BOOL backFace=FALSE)=0
virtual float	GetShininess (int mtlNum=0, BOOL backFace=FALSE)=0
virtual float	GetShinStr (int mtlNum=0, BOOL backFace=FALSE)=0
virtual float	GetXParency (int mtlNum=0, BOOL backFace=FALSE)=0
virtual BOOL	GetSelfIllumColorOn (int mtlNum=0, BOOL backFace=FALSE)
virtual float	GetSelfIllum (int mtlNum=0, BOOL backFace=FALSE)
virtual Color	GetSelfIllumColor (int mtlNum=0, BOOL backFace=FALSE)
virtual Sampler *	GetPixelSampler (int mtlNum=0, BOOL backFace=FALSE)
virtual float	WireSize (int mtlNum=0, BOOL backFace=FALSE)
virtual void	SetAmbient (Color c, TimeValue t)=0
virtual void	SetDiffuse (Color c, TimeValue t)=0
virtual void	SetSpecular (Color c, TimeValue t)=0
virtual void	SetShininess (float v, TimeValue t)=0
virtual BOOL	SupportsShaders ()
virtual BOOL	SupportsRenderElements ()
virtual void	Shade (ShadeContext &sc)=0
virtual int	NumSubMtls ()
virtual Mtl *	GetSubMtl (int i)
virtual void	SetSubMtl (int i, Mtl *m)
virtual int	VPDisplaySubMtl ()
virtual CoreExport MSTR	GetSubMtlSlotName (int i)
CoreExport MSTR	GetSubMtlTVName (int i)
CoreExport void	CopySubMtl (HWND hwnd, int ifrom, int ito)
virtual CoreExport float	GetDynamicsProperty (TimeValue t, int mtlNum, int propID)
virtual CoreExport void	SetDynamicsProperty (TimeValue t, int mtlNum, int propID, float value)
virtual float	EvalDisplacement (ShadeContext &sc)
virtual Interval	DisplacementValidity (TimeValue t)
CoreExport bool	SvCanInitiateLink (IGraphObjectManager gom, IGraphNode gNode)
virtual BOOL	DontKeepOldMtl ()
virtual void	SetRenderData (RenderData *rdata)
virtual RenderData *	GetRenderData ()
virtual bool	IsOutputConst (ShadeContext &sc, int stdID)
virtual bool	EvalColorStdChannel (ShadeContext &sc, int stdID, Color &outClr)
virtual CoreExport bool	EvalMonoStdChannel (ShadeContext &sc, int stdID, float &outVal)

Constructor & Destructor Documentation

CoreExport Mtl ( )

Remarks:: Constructor. The active texture map is set to NULL.

Member Function Documentation

SClass_ID SuperClassID ( ) [inline, virtual]

Search for all occurrences

Retrieves a constant representing the type of the plugin.

Returns:: A super class id that uniquely identifies the type (category) of the plugin. Note that several plugin classes can be of the same type, thus return the same super class id. Plugins are uniquely identified by their class ids. List of Super Class IDs.

See also:: SClass_ID

Reimplemented from ReferenceTarget.

{ return MATERIAL_CLASS_ID; }

virtual void GetClassName ( MSTR & s ) [inline, virtual]

Search for all occurrences

Retrieves the name of the plugin class.

This name is usually used internally for debugging purposes. For Material plug-ins this method is used to put up the material "type" name in the Material Editor.

Parameters:

s	Reference to a string filled in with the name of the plugin class

Reimplemented from ReferenceTarget.

Reimplemented in MSPluginMtl, and MSMtlXtnd.

{ s= MSTR(_M("Mtl")); }

CoreExport MtlBase* GetActiveTexmap ( )

Search for all occurrences

Remarks:: Implemented by the System.

Returns a pointer to the active texture map used in the interactive renderer.

Reimplemented in MSPluginMtl, and MSMtlXtnd.

CoreExport void SetActiveTexmap ( MtlBase * txm )

Search for all occurrences

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().

Reimplemented in MSPluginMtl, and MSMtlXtnd.

CoreExport void RefDeleted ( ) [virtual]

Search for all occurrences

Called after a references to this is deleted.

This is called after deleting a reference to a reference target, in the case that the target was not deleted. When the last strong reference to a ReferenceTarget is removed, the ReferenceTarget is deleted, the destructor is called, and the memory cleared.

Reimplemented from ReferenceTarget.

Reimplemented in MSPluginMtl.

CoreExport void RefAdded ( RefMakerHandle rm ) [virtual]

Search for all occurrences

Called after a reference is made to a target.

This is called after a reference is made to this. If the target (this) needs to know that a reference to made to it, the target (this) can override this function.

Parameters:

rm	- The ReferenceMaker creating the reference.

Reimplemented from ReferenceTarget.

Reimplemented in MSPluginMtl.

virtual Color GetAmbient	(	int	mtlNum = `0`,
		BOOL	backFace = `FALSE`
	)		`[pure virtual]`

Search for all occurrences

Remarks:: Returns the ambient color of the specified material for use in the interactive renderer.

Parameters:

mtlNum	This is the material index for mult-materials.
backFace	If the surface normal of the face is pointing away from the viewer this will be TRUE; otherwise FALSE.

Implemented in MSPluginMtl, and MSMtlXtnd.

virtual Color GetDiffuse	(	int	mtlNum = `0`,
		BOOL	backFace = `FALSE`
	)		`[pure virtual]`

Search for all occurrences

Remarks:: Returns the diffuse color of the specified material for use in the interactive renderer.

Parameters:

mtlNum	This is the material index for mult-materials.
backFace	If the surface normal of the face is pointing away from the viewer this will be TRUE; otherwise FALSE.

Implemented in MSPluginMtl, and MSMtlXtnd.

virtual Color GetSpecular	(	int	mtlNum = `0`,
		BOOL	backFace = `FALSE`
	)		`[pure virtual]`

Search for all occurrences

Remarks:: Returns the specular color of the specified material for use in the interactive renderer.

Parameters:

mtlNum	This is the material index for mult-materials.
backFace	If the surface normal of the face is pointing away from the viewer this will be TRUE; otherwise FALSE.

Implemented in MSPluginMtl, and MSMtlXtnd.

virtual float GetShininess	(	int	mtlNum = `0`,
		BOOL	backFace = `FALSE`
	)		`[pure virtual]`

Search for all occurrences

Remarks:: Returns the shininess value of the specified material for use in the interactive renderer.

Parameters:

mtlNum	This is the material index for mult-materials.
backFace	If the surface normal of the face is pointing away from the viewer this will be TRUE; otherwise FALSE.

Implemented in MSPluginMtl, and MSMtlXtnd.

virtual float GetShinStr	(	int	mtlNum = `0`,
		BOOL	backFace = `FALSE`
	)		`[pure virtual]`

Search for all occurrences

Remarks:: Returns the shininess strength value of the specified material for use in the interactive renderer.

Parameters:

mtlNum	This is the material index for mult-materials.
backFace	If the surface normal of the face is pointing away from the viewer this will be TRUE; otherwise FALSE.

Implemented in MSPluginMtl, and MSMtlXtnd.

virtual float GetXParency	(	int	mtlNum = `0`,
		BOOL	backFace = `FALSE`
	)		`[pure virtual]`

Search for all occurrences

Remarks:: Returns the transparency value of the specified material for use in the interactive renderer.

Parameters:

mtlNum	This is the material index for mult-materials.
backFace	If the surface normal of the face is pointing away from the viewer this will be TRUE; otherwise FALSE.

Implemented in MSPluginMtl, and MSMtlXtnd.

virtual BOOL GetSelfIllumColorOn	(	int	mtlNum = `0`,
		BOOL	backFace = `FALSE`
	)		`[inline, virtual]`

Search for all occurrences

Remarks:: Returns TRUE if the Self Illumination Color is on (checked) for the specified material; otherwise FALSE.

Parameters:

mtlNum	This is the material index for mult-materials.
backFace	If the surface normal of the face is pointing away from the viewer this will be TRUE; otherwise FALSE.

Default Implementation:: { return TRUE; }

Reimplemented in StdMat2, MSPluginMtl, and MSMtlXtnd.

{ return TRUE; }

virtual float GetSelfIllum	(	int	mtlNum = `0`,
		BOOL	backFace = `FALSE`
	)		`[inline, virtual]`

Search for all occurrences

Remarks:: Returns the self illumination value of the specified material for use in the interactive renderer.

Parameters:

mtlNum	This is the material index for mult-materials.
backFace	If the surface normal of the face is pointing away from the viewer this will be TRUE; otherwise FALSE.

Default Implementation:: { return 0.0f; }

Reimplemented in MSPluginMtl, and MSMtlXtnd.

{ return 0.0f; }

virtual Color GetSelfIllumColor	(	int	mtlNum = `0`,
		BOOL	backFace = `FALSE`
	)		`[inline, virtual]`

Search for all occurrences

Remarks:: Returns the Self Illumination Color of the specified material for use in the interactive renderer.

Parameters:

mtlNum	This is the material index for mult-materials.
backFace	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; }

Reimplemented in StdMat2, MSPluginMtl, and MSMtlXtnd.

{ Color c( .0f,.0f,.0f); return c; }

virtual Sampler* GetPixelSampler	(	int	mtlNum = `0`,
		BOOL	backFace = `FALSE`
	)		`[inline, virtual]`

Search for all occurrences

Remarks:: Returns a pointer to the Sampler used for the specified sub-material.

Parameters:

mtlNum	This is the material index for mult-materials.
backFace	If the surface normal of the face is pointing away from the viewer this will be TRUE; otherwise FALSE.

Default Implementation:: { return NULL; }

Reimplemented in StdMat2, and MSMtlXtnd.

{ return NULL; }

virtual float WireSize	(	int	mtlNum = `0`,
		BOOL	backFace = `FALSE`
	)		`[inline, virtual]`

Search for all occurrences

Remarks:: Returns the wire size of the material.

Parameters:

mtlNum	This is the material index for mult-materials.
backFace	If the surface normal of the face is pointing away from the viewer this will be TRUE; otherwise FALSE.

Default Implementation:: { return 1.0f; }

Reimplemented in MSPluginMtl, and MSMtlXtnd.

{ return 1.0f; }

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

Search for all occurrences

Remarks:: This method saves the specified color at the specified time.

Parameters:

c	The color to store.
t	The time to set this color.

Implemented in StdMat, MSPluginMtl, and MSMtlXtnd.

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

Search for all occurrences

Remarks:: This method saves the specified color at the specified time.

Parameters:

c	The color to store.
t	The time to set this color.

Implemented in StdMat, MSPluginMtl, and MSMtlXtnd.

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

Search for all occurrences

Remarks:: This method saves the specified color at the specified time.

Parameters:

c	The color to store.
t	The time to set this color.

Implemented in StdMat, MSPluginMtl, and MSMtlXtnd.

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

Search for all occurrences

Remarks:: This method saves the specified shininess at the specified time.

Parameters:

v	The shininess value to store.
t	The time to set this color.

Implemented in StdMat, MSPluginMtl, and MSMtlXtnd.

virtual BOOL SupportsShaders ( ) [inline, virtual]

Search for all occurrences

Remarks:: This method returns TRUE if the material supports shaders, otherwise FALSE.

Default Implementation:: { return FALSE; }

Reimplemented in StdMat2, and MSMtlXtnd.

{ return FALSE; } // moved from class StdMat

virtual BOOL SupportsRenderElements ( ) [inline, virtual]

Search for all occurrences

Reimplemented in MSMtlXtnd.

{ return FALSE; }

virtual void Shade ( ShadeContext & sc ) [pure virtual]

Search for all occurrences

Remarks:: 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:

sc	Describes properties of the pixel to be shaded. The result of this method is returned in the ShadeOutput data member of sc.

Implemented in MSPluginMtl, and MSMtlXtnd.

virtual int NumSubMtls ( ) [inline, virtual]

Search for all occurrences

Remarks:: Returns the number of sub-materials managed by this material.

Default Implementation:: { return 0; }

Reimplemented in MSPluginMtl, and MSMtlXtnd.

{ return 0; }

virtual Mtl* GetSubMtl ( int i ) [inline, virtual]

Search for all occurrences

Remarks:: Returns a pointer to the 'i-th' sub-material of this material.

Parameters:

i	The index of the material to return.

Default Implementation:: { return NULL; }

Reimplemented in MSPluginMtl, and MSMtlXtnd.

{ return NULL; }

virtual void SetSubMtl	(	int	i,
		Mtl *	m
	)		`[inline, virtual]`

Search for all occurrences

Remarks:: Stores the 'i-th' sub-material of this material.

Parameters:

i	The index of the material to store.
m	The material pointer to store.

Default Implementation:: {}

Reimplemented in MSPluginMtl, and MSMtlXtnd.

{ }

virtual int VPDisplaySubMtl ( ) [inline, virtual]

Search for all occurrences

Remarks:: 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; }

{ return -1; }  // which sub-mtl to display in the viewport: -1 indicates not implemented.

virtual CoreExport MSTR GetSubMtlSlotName ( int i ) [virtual]

Search for all occurrences

Remarks:: 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:

i	The index of the sub-materials whose slot name should be returned.

Reimplemented in MSPluginMtl, and MSMtlXtnd.

CoreExport MSTR GetSubMtlTVName ( int i )

Search for all occurrences

Remarks:: Returns the name of the 'i-th' sub-material that should appear in track view.

Parameters:

i	The index of the sub-materials whose track view name should be returned.

Reimplemented in MSPluginMtl, and MSMtlXtnd.

CoreExport void CopySubMtl	(	HWND	hwnd,
		int	ifrom,
		int	ito
	)

Search for all occurrences

virtual CoreExport float GetDynamicsProperty	(	TimeValue	t,
		int	mtlNum,
		int	propID
	)		`[virtual]`

Search for all occurrences

Remarks:: This method returns the specified dynamics property of the material at the specified time.

Parameters:

t	The time to return the dynamics property.
mtlNum	The index of the sub-material or zero if this is a base material.
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.

Reimplemented in MSPluginMtl, and MSMtlXtnd.

virtual CoreExport void SetDynamicsProperty	(	TimeValue	t,
		int	mtlNum,
		int	propID,
		float	value
	)		`[virtual]`

Search for all occurrences

Remarks:: This method sets the specified dynamics property of the material at the specified time.

Parameters:

t	The time at which to set the value.
mtlNum	The sub-material number for a multi-material.
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.
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.

Reimplemented in MSPluginMtl, and MSMtlXtnd.

virtual float EvalDisplacement ( ShadeContext & sc ) [inline, virtual]

Search for all occurrences

Remarks:: Returns the amount of displacement along the normal of the surface at the point as specified by the ShadeContext.

Parameters:

sc	This contains the details of the point being displaced.

Default Implementation:: { return 0.0f; }

Reimplemented in MSPluginMtl, and MSMtlXtnd.

{ return 0.0f; }

virtual Interval DisplacementValidity ( TimeValue t ) [inline, virtual]

Search for all occurrences

Remarks:: Returns the validity interval of the displacement mapping around the specified time.

Parameters:

t	The Interval returned reflects the validity around this time.

Default Implementation:: { return FOREVER; }

Reimplemented in MSPluginMtl, and MSMtlXtnd.

{ return FOREVER; }

CoreExport bool SvCanInitiateLink	(	IGraphObjectManager *	gom,
		IGraphNode *	gNode
	)		`[virtual]`

Search for all occurrences

Remarks:: Returns true if this animatable can be the initiator of a link operation in the schematic view.

Parameters:

gom	Points to the schematic view window manager.
gNode	Points to this node in the schematic view.

Reimplemented from Animatable.

virtual BOOL DontKeepOldMtl ( ) [inline, virtual]

Search for all occurrences

Remarks:: 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; }

Reimplemented in MSMtlXtnd.

{ return FALSE; }

virtual void SetRenderData ( RenderData * rdata ) [inline, virtual]

Search for all occurrences

Remarks:: This method allows the renderer to attach auxiliary data to each material.

Parameters:

rdata The auxiliary data you wish to attach.

Default Implementation:: { renderData = rdata; }

{ renderData = rdata; }

virtual RenderData* GetRenderData ( ) [inline, virtual]

Search for all occurrences

Remarks:: This method returns the auxiliary data attached to the material by the renderer.

Default Implementation:: { return renderData; }

{ return renderData; }

virtual bool IsOutputConst	(	ShadeContext &	sc,
		int	stdID
	)		`[inline, virtual]`

Search for all occurrences

Remarks:: 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:

sc	This describes the context of the question.
stdID	The ID of the channel in question. See Texture Map Indices.

Default Implementation:: { return FALSE; }

Reimplemented in MSPluginMtl, and MSMtlXtnd.

{ return false; }

virtual bool EvalColorStdChannel	(	ShadeContext &	sc,
		int	stdID,
		Color &	outClr
	)		`[inline, virtual]`

Search for all occurrences

Remarks:: 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:

sc	This describes the context in which the material should be evaluated.
stdID	The ID of the channel to perform evaluation on. See Texture Map Indices.
outClr	The result of the evaluation.

Default Implementation:: { return FALSE; }

Reimplemented in MSPluginMtl, and MSMtlXtnd.

{ return false; }

virtual CoreExport bool EvalMonoStdChannel	(	ShadeContext &	sc,
		int	stdID,
		float &	outVal
	)		`[virtual]`

Search for all occurrences

Reimplemented in MSPluginMtl, and MSMtlXtnd.

Mtl Class Reference

Detailed Description

Public Member Functions

Constructor & Destructor Documentation

Member Function Documentation