This reference page is linked to from the following overview topics: Porting Simple Material and Texture Map Plug-ins to Nitrous, Porting Advanced Material and Texture Map Plug-ins to Nitrous, Parameter Flags, Principal Classes for Materials and Textures, Accessing Material Properties, Editing Material and Texture Parameters.

Detailed Description

See also:: Class ReferenceTarget, Class ISubMap, Class Mtl, Class Texmap, Class ShadeContext, Class RenderMapsContext, Class RenderGlobalContext, Class UVGen, Class XYZGen, Class PStamp, Class Quat.

Description:: This is the base class from which materials and textures are subclassed. Methods are provided to access the name, flags, and sub-materials/maps. There is also a method that is called when the material or texture is to be displayed in the material editor parameters area.

Note the following about dialog proc processing of sub-map buttons:

When you post the message:

PostMessage(hwmedit, WM_TEXMAP_BUTTON, i,(LPARAM)theMtl);

You are telling the system that the user clicked on the button for the 'i-th' sub-map of theMtl. The message doesn't propagate up -- it goes directly to the materials editor. It then uses calls on theMtl->SetSubTexmap() and theMtl->GetSubTexmap() to assign the new map. So even if your material has some complicated internal hierarchical structure of references, to the system it is still a simple "logical" hierarchy of a material with some sub-texmaps.

Data Members:: Quat meditRotate;

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

This describes the rotation of the sample geometry in the materials editor.

ULONG gbufID;

This is the G-Buffer ID of the material or texmap. This is a "effects number" assigned in the materials editor to a map or material, and it will be written into the effects channel of the G-Buffer when a pixel with that material on it is rendered. To implement this, each map or material, in the beginning of its Shade(), EvalColor(), or EvalMono() methods should have the code:

if (gbufID) sc.SetGBufferID(gbufID);

Method Groups:: See Method Groups for Class MtlBase.

#include <imtl.h>

Inheritance diagram for MtlBase:

[legend]

List of all members.

Public Member Functions
CoreExport	MtlBase ()
CoreExport	~MtlBase ()
CoreExport Class_ID	ClassID ()
	Retrieves a constant that uniquely identifies the plugin class.
MSTR &	GetName ()
CoreExport void	SetName (MSTR s)
CoreExport void	SetMtlFlag (int mask, BOOL val=TRUE)
CoreExport void	ClearMtlFlag (int mask)
CoreExport int	TestMtlFlag (int mask)
int	GetMeditObjType ()
void	SetMeditObjType (int t)
int	GetMeditTiling ()
void	SetMeditTiling (int t)
CoreExport BOOL	AnyMulti ()
BOOL	TextureDisplayEnabled ()
virtual CoreExport MSTR	GetFullName ()
CoreExport MtlBase &	operator= (const MtlBase &m)
virtual int	BuildMaps (TimeValue t, RenderMapsContext &rmc)
virtual CoreExport ULONG	Requirements (int subMtlNum)
virtual ULONG	LocalRequirements (int subMtlNum)
virtual CoreExport void	MappingsRequired (int subMtlNum, BitArray &mapreq, BitArray &bumpreq)
virtual void	LocalMappingsRequired (int subMtlNum, BitArray &mapreq, BitArray &bumpreq)
virtual BOOL	IsMultiMtl ()
virtual int	MapSlotType (int i)
CoreExport void	DeactivateMapsInTree ()
virtual void	Update (TimeValue t, Interval &valid)=0
virtual void	Reset ()=0
virtual Interval	Validity (TimeValue t)=0
virtual ParamDlg *	CreateParamDlg (HWND hwMtlEdit, IMtlParams *imp)=0
CoreExport IOResult	Save (ISave *isave)
CoreExport IOResult	Load (ILoad *iload)
ULONG	GetGBufID ()
void	SetGBufID (ULONG id)
CoreExport void	EnumAuxFiles (AssetEnumCallback &nameEnum, DWORD flags)
virtual CoreExport PStamp *	GetPStamp (int sz)
virtual CoreExport PStamp *	CreatePStamp (int sz, BOOL Render=FALSE)
virtual CoreExport void	DiscardPStamp (int sz)
CoreExport SvGraphNodeReference	SvTraverseAnimGraph (IGraphObjectManager gom, Animatable owner, int id, DWORD flags)
CoreExport bool	SvHandleDoubleClick (IGraphObjectManager gom, IGraphNode gNode)
CoreExport MSTR	SvGetName (IGraphObjectManager gom, IGraphNode gNode, bool isBeingEdited)
CoreExport bool	SvCanSetName (IGraphObjectManager gom, IGraphNode gNode)
CoreExport bool	SvSetName (IGraphObjectManager gom, IGraphNode gNode, MSTR &name)
CoreExport COLORREF	SvHighlightColor (IGraphObjectManager gom, IGraphNode gNode)
CoreExport bool	SvIsSelected (IGraphObjectManager gom, IGraphNode gNode)
	Returns true if the object is selected in its schematic view.
CoreExport MultiSelectCallback *	SvGetMultiSelectCallback (IGraphObjectManager gom, IGraphNode gNode)
CoreExport bool	SvCanSelect (IGraphObjectManager gom, IGraphNode gNode)
virtual BOOL	SupportTexDisplay ()
virtual DWORD_PTR	GetActiveTexHandle (TimeValue t, TexHandleMaker &thmaker)
CoreExport void	IncrActive ()
CoreExport void	DecrActive ()
int	Active ()
virtual void	ActivateTexDisplay (BOOL onoff)
CoreExport MtlBase *	GetActiveMB ()
	Get the active MtlBase.
CoreExport void	SetActiveMB (MtlBase *activeMB)
	Set the active MtlBase.
virtual BOOL	SupportsMultiMapsInViewport ()
virtual void	SetupGfxMultiMaps (TimeValue t, Material *mtl, MtlMakerCallback &cb)
virtual void *	GetInterface (ULONG id)
	Inherited from Animatable.
virtual BaseInterface *	GetInterface (Interface_ID id)
	Inherited from Animatable.
virtual ReferenceTarget *	GetRefTarget ()
virtual CoreExport int	SetProperty (ULONG id, void *data)
virtual CoreExport void *	GetProperty (ULONG id)
virtual CoreExport void	BaseClone (ReferenceTarget from, ReferenceTarget to, RemapDir &remap)
	This method copies base class data from an object to its clone.
virtual BOOL	GetTransparencyHint (TimeValue t, Interval &valid)
	Transparency hint indicates whether the material is potentially transparent for both rendering and viewport display, so that the renderers or viewport can decide whether to optimize it or not.
Public Attributes
Quat	meditRotate
ULONG	gbufID
Friends
class	Texmap

Constructor & Destructor Documentation

CoreExport MtlBase ( )

Remarks:: Constructor. The flags and G-buffer id are initialized.

CoreExport ~MtlBase ( )

Member Function Documentation

CoreExport Class_ID ClassID ( ) [virtual]

Search for all occurrences

Retrieves a constant that uniquely identifies the plugin class.

This method must return the unique ID for the plugin class. If two ClassIDs conflict, the system will only load the first conflicting one it finds. A program (gencid.exe) is provided to generate unique class id values.

Returns:: A class id that uniquely identifies a plugin class

See also:: Class ClassID, List of Class IDs.

Reimplemented from Animatable.

Reimplemented in MSPluginTexmap, MSTexmapXtnd, MSPluginMtl, and MSMtlXtnd.

MSTR& GetName ( ) [inline]

Search for all occurrences

Remarks:: Implemented by the System.

Returns the name of the material or texture.

{ return name; }

CoreExport void SetName ( MSTR s )

Search for all occurrences

Remarks:: Implemented by the System.

Stores the name of the material or texture.

CoreExport void SetMtlFlag	(	int	mask,
		BOOL	val = `TRUE`
	)

Search for all occurrences

Remarks:: Implemented by the System.

Alters the flags, either setting or clearing them, using the mask and method passed.

Parameters:

mask	The flags to alter. See Material Flags.
val	If TRUE the mask is ORed into the flags (mtlFlags \|= mask); otherwise (mtlFlags &= ~mask).

CoreExport void ClearMtlFlag ( int mask )

Search for all occurrences

Remarks:: Implemented by the System.

Clears the specified flags.

Parameters:

mask	The flags to clear. See Material Flags.

CoreExport int TestMtlFlag ( int mask )

Search for all occurrences

Remarks:: Implemented by the System.

Tests the specified flags. Returns nonzero if the flags are set; otherwise zero. See Material Flags.

Parameters:

mask	The flags to test.

int GetMeditObjType ( ) [inline]

Search for all occurrences

Remarks:: This method is used internally.

{ return (mtlFlags&MTL_MEDIT_OBJTYPE_MASK)>>MTL_OBJTYPE_SHIFT; }

void SetMeditObjType ( int t ) [inline]

Search for all occurrences

Remarks:: This method is used internally.

{ mtlFlags &= ~MTL_MEDIT_OBJTYPE_MASK; mtlFlags |= t<<MTL_OBJTYPE_SHIFT; }

int GetMeditTiling ( ) [inline]

Search for all occurrences

Remarks:: This method is used internally.

{ return (mtlFlags&MTL_MEDIT_TILING_MASK)>>MTL_TILING_SHIFT; }

void SetMeditTiling ( int t ) [inline]

Search for all occurrences

Remarks:: This method is used internally.

{ mtlFlags &= ~MTL_MEDIT_TILING_MASK; mtlFlags |= t<<MTL_TILING_SHIFT; }

CoreExport BOOL AnyMulti ( )

Search for all occurrences

Remarks:: Implemented by the System.

This method may be called to recursively determine if there are any multi-materials or texmaps in the tree.

Returns:: TRUE if the material or texture map has any mult-materials; otherwise FALSE.

BOOL TextureDisplayEnabled ( ) [inline]

Search for all occurrences

Remarks:: This method is used internally.

{ return TestMtlFlag(MTL_TEX_DISPLAY_ENABLED); }

virtual CoreExport MSTR GetFullName ( ) [virtual]

Search for all occurrences

Remarks:: Implemented by the System.

This method returns the name that appears in the track view. It returns the "Instance Name(class Name)". For example "Green Glass (Standard)". The default implementation should be used.

Reimplemented in MSPluginTexmap, and MSPluginMtl.

CoreExport MtlBase& operator= ( const MtlBase & m )

Remarks:: Implemented by the System.

Materials and Texmaps must use this operator to copy the common portion of themselves when cloning.

virtual int BuildMaps	(	TimeValue	t,
		RenderMapsContext &	rmc
	)		`[inline, virtual]`

Search for all occurrences

Remarks:: This method is called for a plug-in to do any work it needs to do prior to rendering. For example this is used by the 3ds Max Mirror and Auto Reflect materials to render their bitmaps.

Parameters:

t	The current time.
rmc	Provides information about the view being rendered and can provide access to the global rendering environment information via *RenderGlobalContext gc = rmc.GetGlobalContext()**. See Class RenderMapsContext and Class RenderGlobalContext.

Returns:: Nonzero on success; zero on failure. In the case of failure the renderer is halted (rendering is cancelled).

Reimplemented in MSPluginTexmap, MSTexmapXtnd, MSPluginMtl, and MSMtlXtnd.

{ return 1; }

virtual CoreExport ULONG Requirements ( int subMtlNum ) [virtual]

Search for all occurrences

Remarks:: This method returns the cumulative requirements of the material and its sub-materials and maps. The default implementation just ORs together the local requirements of the material with the requirements of all its children. Most materials will only need to implement LocalRequirements().

Parameters:

subMtlNum Specifies the number of the sub-material whose requirements should be returned. -1 may be used to return a value generated by looping over all the sub-materials and ORing together the requirements.

Returns:: See Material Requirements Flags.

Default Implementation:: The default implementation automatically traverses the sub-material/map tree. On any MtlBase that returns TRUE for IsMultiMtl() it will only recursively call the sub material (or map) for the subMtlNum called. The exception to this is when subMtlNum<0: in this case all sub-mtls and submaps are enumerated. Therefore the LocalRequirements() method below only needs to consider the material or map itself, not the sub-mtls and sub-maps.

Reimplemented in MSPluginTexmap, MSTexmapXtnd, MSPluginMtl, and MSMtlXtnd.

virtual ULONG LocalRequirements ( int subMtlNum ) [inline, virtual]

Search for all occurrences

Remarks:: Specifies various requirements for this material. The value returned from this method should not include requirements of its sub-materials and sub-maps.

Parameters:

subMtlNum Specifies the number of the sub-material whose requirements should be returned.

Returns:: See Material Requirements Flags.

Default Implementation:: { return 0; }

Reimplemented in MSPluginTexmap, MSTexmapXtnd, MSPluginMtl, and MSMtlXtnd.

{ return 0; }

virtual CoreExport void MappingsRequired	(	int	subMtlNum,
		BitArray &	mapreq,
		BitArray &	bumpreq
	)		`[virtual]`

Search for all occurrences

Remarks:: This method gives the UVW channel requirements of the material and its tree. The default implementation just OR's together the local mapping requirements of the material with the requirements of all its children. For most materials, all they need to implement is the LocalMappingsRequired() method.

Parameters:

subMtlNum	Specifies the number of the sub-material whose mapping information is retrieved.
mapreq	This array of bits is initialized to an empty set with MAX_MESHMAPS elements. Each bit corresponds to a mapping channel. Set a bit to one to indicate the material requires the corresponding UVW channel.
bumpreq	This array of bits is initialized to an empty set with MAX_MESHMAPS elements. Each bit corresponds to a mapping channel. Set a bit to one to indicate the material requires the corresponding bump mapping channel.

Reimplemented in MSPluginTexmap, MSTexmapXtnd, MSPluginMtl, and MSMtlXtnd.

virtual void LocalMappingsRequired	(	int	subMtlNum,
		BitArray &	mapreq,
		BitArray &	bumpreq
	)		`[inline, virtual]`

Search for all occurrences

Remarks:: This method specifies UVW channel requirements for the material: This method should not include UVW channel requirements of any sub-materials and sub-maps.

Parameters:

subMtlNum	Specifies the number of the sub-material whose mapping information is retrieved.
mapreq	This array of bits is initialized to an empty set with MAX_MESHMAPS elements. Each bit corresponds to a mapping channel. Set a bit to one to indicate the material requires the corresponding UVW channel.
bumpreq	This array of bits is initialized to an empty set with MAX_MESHMAPS elements. Each bit corresponds to a mapping channel. Set a bit to one to indicate the material requires the corresponding bump mapping channel.

Default Implementation:: {}

Sample Code:

All 2D textures that use UVGen or otherwise select mapping channels need to implement this method Here's an example:

            void LocalMappingsRequired(int subMtlNum, BitArray & mapreq, BitArray &bumpreq)
            {
                uvGen->MappingsRequired(subMtlNum,mapreq,bumpreq);
            }

All 3D textures that use the XYZGen to put up a coordinates rollup must implement this method. Here's an example:

            void LocalMappingsRequired(int subMtlNum, BitArray & mapreq,BitArray &bumpreq)
            {
                xyzGen->MappingsRequired(subMtlNum,mapreq,bumpreq);
            }

Reimplemented in MSPluginTexmap, MSTexmapXtnd, MSPluginMtl, and MSMtlXtnd.

{  }

virtual BOOL IsMultiMtl ( ) [inline, virtual]

Search for all occurrences

Remarks:: This method returns TRUE for materials or textures that select sub-materials based on submaterial number (for example a mesh faceMtlIndex).

The only materials for which this method should return TRUE are those that choose to use one of their sub-maps or sub-mtls based on the submaterial number. For the majority of materials and maps, they should return FALSE, and in that case all of the submaterials and maps are enumerated by MtlBase::Requirements().

Default Implementation:: { return FALSE; }

Reimplemented in MSPluginTexmap, MSTexmapXtnd, MSPluginMtl, and MSMtlXtnd.

{ return FALSE; }

virtual int MapSlotType ( int i ) [inline, virtual]

Search for all occurrences

Remarks:: In the Coordinates rollup in the user interface for a texture map are two options. These options are Texture or Environment. The slot type is one of these two options, texture coordinates or environment coordinates. There are a variety of texture coordinate types. There are the type assigned to the object and the environment type (Spherical, Cylindrical, Shrink-wrap, Screen). This method is used to determine the type required by the particular sub-texture. This is either texture coordinates (MAPSLOT_TEXTURE) or environment coordinates (MAPSLOT_ENVIRON).

Parameters:: int i

The index of the sub-texture whose slot type to return.

Returns:: See Map Slot Types.

Default Implementation:: { return MAPSLOT_TEXTURE; }

Implements ISubMap.

Reimplemented in Texmap.

{ return defaultSlotType; }

CoreExport void DeactivateMapsInTree ( )

Search for all occurrences

Remarks:: Implemented by the System.

This method must be called on a sub-material or sub-map when it is removed, in case it or any of its sub-maps are active in the viewport.

virtual void Update	(	TimeValue	t,
		Interval &	valid
	)		`[pure virtual]`

Search for all occurrences

Remarks:: A material has a Shade() method, and a texture map has a EvalColor() method. These are called by the renderer for every pixel. This method is called before rendering begins to allow the plug-in to evaluate anything prior to the render so it can store this information. In this way this information does not need to be calculated over and over for every pixel when Shade() or EvalColor() is called. This allows texture and material evaluation to be more efficient. It is generally called once at the start of each frame, or during interactive playback when the time changes. It is not guaranteed to get called on every frame, because if you returned a validity interval that covers several frames, your parent material won't bother to call you if the current frame is still in that interval.

Parameters:

t	The current time.
valid	The validity interval to update to reflect the validity interval of the material or texture at the time passed.

Implemented in MSPluginTexmap, MSTexmapXtnd, MSPluginMtl, and MSMtlXtnd.

virtual void Reset ( ) [pure virtual]

Search for all occurrences

Remarks:

This method is called to reset the material or texmap back to its default values. This should be done by calling the Reset method of the material or texture map plugin's class descriptor (ClassDesc2::Reset). In addition, the plugin can execute any other initialization code it has. Example from maxsdk\samples\materials\dblsided.cpp

            void DoubleSided::Reset() {
                dblsidedCD.Reset(this, TRUE); // Resets all pb2's
                Init();
            }

Note:: When migrating plugins from ClassDesc to ClassDesc2 and IParamBlock2, do not forget to update this method to call the class descriptor's Reset method. If the plugin's Reset tries to replace parameter block objects based on IParamBlock2 that use the P_AUTO_UI flag, the UI code will continue to hold a pointer to the replaced parameter block, and this will lead to problems.

Implemented in MSPluginTexmap, MSTexmapXtnd, MSPluginMtl, and MSMtlXtnd.

virtual Interval Validity ( TimeValue t ) [pure virtual]

Search for all occurrences

Remarks:: This method is called to determine the validity interval of the material or texture.

Parameters:

t	Specifies the time about which to compute the validity interval.

Returns:: The validity interval of the item at the specified time.

Implemented in MSPluginTexmap, MSTexmapXtnd, MSPluginMtl, and MSMtlXtnd.

virtual ParamDlg* CreateParamDlg	(	HWND	hwMtlEdit,
		IMtlParams *	imp
	)		`[pure virtual]`

Search for all occurrences

Remarks:: This method gets called when the material or texture is to be displayed in the material editor parameters area. The plug-in should allocate a new instance of a class derived from ParamDlg to manage the user interface.

Note: The following is a discussion of this CreateParamDlg() method, and the SetDlgThing() method, and the way they relate to the ParamMap2 system. A good example for this discussion is a texture map which typically has several rollouts, say its texmap parameters, a UVW coordinates rollout, and an Output rollout.

The normal way for a texmap to implement these other (common) rollouts is for the it to create a UVGen instance and a TextureOutput instance as 'sub-objects' in the map and then ask them to put up their rollouts when it is asked to do so by the Materials Editor (in CreateParamDlg()). The Materials Editor requires a ParamDlg pointer back from the CreateParamDlg() on which it calls methods to control the UI, such as time change updates or loading up a new texmap of the same class into the UI when the user switches them, so that the whole UI doesn't need to be rebuilt.

Prior to the ParamMap2 system, a texmap would implement its own ParamDlg subclass and would keep track of the UVGen and TextureOutput ParamDialogs and pass on any time change or SetThing() calls to them. ParamMap2 introduced its own ParamDlg subclass (Class IAutoMParamDlg) that you can ask it to build for you and have manage all interaction with the Materials Editor automatically. As before, this still needs to know about the other (sub-object) ParamDlgs, and so it has the ability to keep a list of 'secondary' ParamDlgs to which it passes on the SetTime()s and SetThing()s.

When the Materials Editor asks the texmap to CreateParamDlg(), the texmap asks its ClassDesc2 to build one of these (ClassDesc2::CreateParamDlgs()). If the texmap itself has multiple ParamBlock2s, CreateParamDlgs() builds one ParamDlg per pblock/rollout, makes the first of them a 'master' and adds the rest as secondary ParamDlgs. The texmap then asks the UVGen and TextureOutput objects to CreateParamDlg() for their rollouts and adds them to the master IAutoMParamDlg also.

Now consider the need for the SetDlgThing() method below. It is related to the SetThing() method that the Materials Editor calls on the 'master' ParamDlg to switch into the UI a texmap of the same class as that currently in the UI. Normally, the master IAutoParamDlg would propagate the SetThing() to its registered secondary ParamDlgs. In the case of multiple paramblock2s in the texmap, this would be correct, since the 'thing' in this case is the incoming texmap. But this doesn't work for the secondary UVGen and TextureOutput ParamDlgs; their 'things' are the UVGen and TextureOutput subobjects of the incoming map. So, IAutoParamDlg first calls SetDlgThing() on the incoming texmap so that it gets a chance to call the correct SetThing()s on the sub-object ParamDlgs with the appropriate incoming sub-objects. A clear example of this is in Gradient::SetDlgThing() in /MAXSDK/SAMPLES/MATERIALS/GRADIENT.CPP. It is called once for each secondary ParamDlg. For those ParamDlgs that have special SetThing() requirements, it does the appropriate sub-object SetThing() and returns TRUE. If it does no special handling for a particular ParamDlg, it returns FALSE, signaling to the IAutoMParamDlg that it should do the standard SetThing() propagation for that dialog.

The Render Effects dialog has a similar arrangement to the Materials Editor for controlling Effect UI and so there is an IAutoEParamDlg that works exactly the same way as the IAuotMParamDlg.

Parameters:

hwMtlEdit	The window handle of the materials editor.
imp	The interface pointer for calling methods in 3ds Max.

Returns:: A pointer to the created instance of a class derived from ParamDlg.

Implemented in MSPluginTexmap, MSTexmapXtnd, MSPluginMtl, and MSMtlXtnd.

CoreExport IOResult Save ( ISave * isave ) [virtual]

Search for all occurrences

Remarks:: Implemented by the System.

This method saves the plug-in's data to disk.. The common MtlBase data must be saved as well. The base class method must be called in a chunk at the beginning of every Mtl and Texmap.

Parameters:

isave An interface pointer available for saving data. See Class ISave, I/O Results.

Sample Code:

Note in the code below the base class method is called in a chunk before the rest of the plug-ins data is saved.

            IOResult Gradient::Save(ISave *isave)
            {
                IOResult res;
                // Save common stuff
                isave->BeginChunk(MTL_HDR_CHUNK);
                res = MtlBase::Save(isave);
                if (res!=IO_OK) return res;
                isave->EndChunk();
            
                for (int i=0; i<NSUBTEX; i++) {
                    if (mapOn[i]==0) {
                        isave->BeginChunk(MAPOFF_CHUNK+i);
                        isave->EndChunk();
                    }
                }
                return IO_OK;
            }

Reimplemented from ReferenceMaker.

Reimplemented in MSPluginTexmap, MSTexmapXtnd, MSPluginMtl, and MSMtlXtnd.

CoreExport IOResult Load ( ILoad * iload ) [virtual]

Search for all occurrences

Remarks:: Implemented by the System.

This method is called to load the material or texture from disk. The common MtlBase data must be loaded as well. See the code below.

Parameters:

iload An interface pointer for calling methods to load data. See Class ILoad, I/O Results.

Sample Code:

            IOResult Gradient::Load(ILoad *iload)
            {
                IOResult res;
                int id;
                while (IO_OK==(res=iload->OpenChunk())) {
                    switch(id = iload->CurChunkID()) {
                        case MTL_HDR_CHUNK:
                            res = MtlBase::Load(iload);
                            break;
                        case MAPOFF_CHUNK+0:
                        case MAPOFF_CHUNK+1:
                        case MAPOFF_CHUNK+2:
                            mapOn[id-MAPOFF_CHUNK] = 0;
                            break;
                    }
                    iload->CloseChunk();
                    if (res!=IO_OK)
                        return res;
                }
                iload->RegisterPostLoadCallback(new ParamBlockPLCB(versions,NUM_OLDVERSIONS,&curVersion,this,1));
                return IO_OK;
            }

Reimplemented from ReferenceMaker.

Reimplemented in MSPluginTexmap, MSTexmapXtnd, MSPluginMtl, and MSMtlXtnd.

ULONG GetGBufID ( ) [inline]

Search for all occurrences

Remarks:: Implemented by the System.

Returns the G-buffer ID of this material.

Reimplemented in MSPluginTexmap, MSTexmapXtnd, MSPluginMtl, and MSMtlXtnd.

{ return gbufID; }

void SetGBufID ( ULONG id ) [inline]

Search for all occurrences

Remarks:: Implemented by the System.

Sets the G-buffer ID of this material.

Reimplemented in MSPluginTexmap, MSTexmapXtnd, MSPluginMtl, and MSMtlXtnd.

{ gbufID = id; }

CoreExport void EnumAuxFiles	(	AssetEnumCallback &	nameEnum,
		DWORD	flags
	)		`[virtual]`

Search for all occurrences

Remarks:: This is an implementation of the Animatable method. This default implementation simply recurses, skipping inactive subTexmaps if appropriate.

Reimplemented from ReferenceMaker.

Reimplemented in MSPluginTexmap, MSTexmapXtnd, MSPluginMtl, and MSMtlXtnd.

virtual CoreExport PStamp* GetPStamp ( int sz ) [virtual]

Search for all occurrences

Remarks:: Implemented by the System.

Returns a pointer to the postage stamp image for the file.

Parameters:

sz	One of the following values: PS_SMALL for small (32x32) images. PS_LARGE for large (88x88) images. PS_TINY for tiny (24x24) images.

Reimplemented in MSPluginTexmap, MSTexmapXtnd, MSPluginMtl, and MSMtlXtnd.

virtual CoreExport PStamp* CreatePStamp	(	int	sz,
		BOOL	Render = `FALSE`
	)		`[virtual]`

Search for all occurrences

Remarks:

Implemented by the System.

Creates a postage stamp image and returns a pointer to it. If the postage stamp image already exists then it is simply returned.

Here's an example using this method to display a small material sample.

            void DisplayMB(MtlBase *mb, HDC hdc, int x, int y) {
                mb->CreatePStamp(0,TRUE); // create and render a small pstamp
                PStamp *ps = mb->GetPStamp(0);
                if (ps) {
                    int d = PSDIM(0);
                    int scanw = ByteWidth(d);
                    int nb = scanw*d;
                    UBYTE *workImg = new UBYTE[nb];
                    if (NULL == workImg)
                        return;
                    ps->GetImage(workImg);
                    Rect rect;
                    rect.left = x;
                    rect.top = y;
                    rect.right = x+d;
                    rect.bottom = y+d;
                    GetGPort()->DisplayMap(hdc, rect,0,0, workImg, scanw);
                    delete [] workImg;
                }
            }

Parameters:

sz	One of the following values: PS_SMALL for small (32x32) images. PS_LARGE for large (88x88) images. PS_TINY for tiny (24x24) images.
Render	If set to true, the postage stamp bitmap will have the MtlBase rendered into it automatically. The bitmap can then be retrieved using PStamp::GetImage, for drawing in the UI.

virtual CoreExport void DiscardPStamp ( int sz ) [virtual]

Search for all occurrences

Remarks:: Implemented by the System.

Discards the postage stamp image.

Parameters:

sz	One of the following values: PS_SMALL for small (32x32) images. PS_LARGE for large (88x88) images. PS_TINY for tiny (24x24) images.

Reimplemented in MSPluginTexmap, MSTexmapXtnd, MSPluginMtl, and MSMtlXtnd.

CoreExport SvGraphNodeReference SvTraverseAnimGraph	(	IGraphObjectManager *	gom,
		Animatable *	owner,
		int	id,
		DWORD	flags
	)		`[virtual]`

Search for all occurrences

Remarks:: This method is available in release 3.0 and later only.

This method traverses the graph of objects in the 3ds Max scene, adding desired objects to the schematic view. Developers can specialize this behaviour by overriding this method and adding whatever objects are interesting to the schematic view. Objects are added to the schematic view by calling IGraphObjectManager::AddAnimatable(...). Reference lines are added to the schematic view by calling IGraphObjectManager::AddReference(...). Implementers of this method should call it recursively to process other objects in the scene.

See Class IGraphObjectManager.

Parameters:

gom	Points to the schematic view window manager.
owner	The owning animatable.
id	This is usually the sub-anim number (but can actually be any value the developer chooses).
flags	See List of Schematic %View AddAnimatable Flags.

Returns:: A SvGraphNodeReference object.

Reimplemented from Animatable.

Reimplemented in Texmap, UVGen, XYZGen, and TextureOutput.

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

Search for all occurrences

Remarks:: This method is available in release 3.0 and later only.

This method is called when this node is double-clicked in the schematic view.

Parameters:

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

Returns:: true is handled; false if not interested in the event.

Default Implementation:: { return false; }

Reimplemented from Animatable.

CoreExport MSTR SvGetName	(	IGraphObjectManager *	gom,
		IGraphNode *	gNode,
		bool	isBeingEdited
	)		`[virtual]`

Search for all occurrences

Remarks:: Returns the name of the object as it appears in the schematic view.

Parameters:

gom	Points to the schematic view window manager.
gNode	Points to this node in the schematic view.
isBeingEdited	TRUE if the item is being edited; FALSE if not.

Default Implementation:

        {
            Animatable *owner;
            int subNum;
            MSTR name;
            owner = gNode->GetOwner();
            subNum = gNode->GetID();
            name = owner->SubAnimName(subNum);
            return name;
        }

Reimplemented from Animatable.

Reimplemented in UVGen, XYZGen, and TextureOutput.

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

Search for all occurrences

Remarks:: Return true to permit the object's name to be edited in the schematic view.

Parameters:

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

Default Implementation:: { return false; }

Reimplemented from Animatable.

CoreExport bool SvSetName	(	IGraphObjectManager *	gom,
		IGraphNode *	gNode,
		MSTR &	name
	)		`[virtual]`

Search for all occurrences

Remarks:: Called when the user changes the name of the object in the schematic view.

Parameters:

gom<	Points to the schematic view window manager.
gNode	Points to this node in the schematic view.
name	The new name to set.

Returns:: TRUE if the name was changed; FALSE if not.

Reimplemented from Animatable.

CoreExport COLORREF SvHighlightColor	(	IGraphObjectManager *	gom,
		IGraphNode *	gNode
	)		`[virtual]`

Search for all occurrences

Remarks:: This method is available in release 3.0 and later only.

Returns the highlight color for this node. The highlight color is used to outline nodes in the schematic view when SvIsHighlighted(...) returns true.

Parameters:

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

Returns:: See COLORREF-DWORD format.

Default Implementation:: { return gom->SvGetUIColor(SV_UICLR_PLUGIN_HIGHLIGHT); }

Reimplemented from Animatable.

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

Search for all occurrences

Returns true if the object is selected in its schematic view.

Reimplemented from Animatable.

CoreExport MultiSelectCallback* SvGetMultiSelectCallback	(	IGraphObjectManager *	gom,
		IGraphNode *	gNode
	)		`[virtual]`

Search for all occurrences

Remarks:: This method is called before a multiple select/deselect operation in the schematic view. Returns a callback used to perform the (de)selection. May return NULL if this object cannot be selected in some principle editor outside the schematic view.

Parameters:

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

Returns:: A pointer to the callback object. See Class MultiSelectCallback.

Default Implementation:: { return NULL; }

Reimplemented from Animatable.

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

Search for all occurrences

Remarks:: Returns true if this object can be selected in some editor (viewport, material editor, plug-in specific editor, etc.). Selection is actually accomplished by via the SvGetMultiSelectCallback(...) mechanism described above.

Parameters:

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

Default Implementation:: { return false; }

Reimplemented from Animatable.

virtual BOOL SupportTexDisplay ( ) [inline, virtual]

Search for all occurrences

Remarks:: Returns TRUE if this texture supports being used in the interactive renderer; otherwise FALSE. If the texture does return TRUE it is expected to implement the methods ActivateTexDisplay() and GetActiveTexHandle().

Default Implementation:: { return FALSE; }

Reimplemented in MSPluginTexmap, MSTexmapXtnd, MSPluginMtl, and MSMtlXtnd.

{ return FALSE; }   // supports map display in viewport

virtual DWORD_PTR GetActiveTexHandle	(	TimeValue	t,
		TexHandleMaker &	thmaker
	)		`[inline, virtual]`

Search for all occurrences

Remarks:: This method is called to retrieve a texture handle to this texture map.

Parameters:

t	The time to return the texture handle.
thmaker	This class provides methods for creating a texture handle from a 3ds Max bitmap and a Windows DIB. It also has a method to retrieve the required size of the texture map. See Class TexHandleMaker.

Returns:: The texture handle.

Default Implementation:: {return 0;}

Reimplemented in MSPluginTexmap, MSTexmapXtnd, MSPluginMtl, and MSMtlXtnd.

{return 0;}

CoreExport void IncrActive ( )

Search for all occurrences

Remarks:: This method is used internally.

CoreExport void DecrActive ( )

Search for all occurrences

Remarks:: This method is used internally.

int Active ( ) [inline]

Search for all occurrences

Remarks:: This method is used internally.

{ return activeCount; }

virtual void ActivateTexDisplay ( BOOL onoff ) [inline, virtual]

Search for all occurrences

Remarks:: This method is called when the usage of the texture the interactive renderer changes. This method must only be implemented if SupportTexDisplay() returns TRUE. This method does not cause the texture map to be drawn in the viewport but should be called with TRUE as the argument before this can occur. For viewport drawing of textures refer to Interface::ActivateTexture() and Interface::DeActivateTexture() instead.

Parameters:

onoff TRUE if the texture is being used; FALSE if it is no longer being used.

Default Implementation:: {}

Reimplemented in MSPluginTexmap, MSTexmapXtnd, MSPluginMtl, and MSMtlXtnd.

{}

CoreExport MtlBase* GetActiveMB ( )

Search for all occurrences

Get the active MtlBase.

Previous to r9, activeMB was held as a raw pointer. Due to problems where the MtlBase was deleted without clearing this pointer, activeMB is now held indirectly. Methods GetActiveMB and SetActiveMB are used to get/set the activeMB;

Returns:: The active MtlBase

CoreExport void SetActiveMB ( MtlBase * activeMB )

Search for all occurrences

Set the active MtlBase.

Parameters:

[in] activeMB The active MtlBase

virtual BOOL SupportsMultiMapsInViewport ( ) [inline, virtual]

Search for all occurrences

Remarks:: Returns TRUE if this material supports the display of multi-maps in the viewports (interactive renderer); FALSE if it doesn't.

Default Implementation:: { return FALSE; }

Reimplemented in MSPluginTexmap, MSTexmapXtnd, MSPluginMtl, and MSMtlXtnd.

{ return FALSE; }

virtual void SetupGfxMultiMaps	(	TimeValue	t,
		Material *	mtl,
		MtlMakerCallback &	cb
	)		`[inline, virtual]`

Search for all occurrences

Remarks:: This method is called to initialize the interactive renderer Material passed with the properties of this MtlBase.

If a MtlBase (material or texmap) wants to display multiple textures in the viewports, it implements

SupportsMultiMapsInViewport() to return TRUE, and implements SetupGfxMultiMaps to store the necessary information in the Material passed in, including the TextureInfo's for each texture.

The MtlMakerCallback passed in to SetupGfxMultiMaps provides functions to help in setting up the "Material" data structure. The function NumberTexturesSupported() lets you know the capabilities of the current hardware, so you can adapt accordingly. The function GetGfxTexInfoFromTexmap fills in the fields of a TextureInfo except the texHandle and texture ops.

The implementation of SetupGfxMultiMaps must create the "texHandle" for each of the textures described in its TextureInfo array. It typically does this by calling the submap's GetVPDisplayDIB() method, and then creates the texHandle by calling the callBack function MakeHandle(bmi). To avoid doing this calculation when not necessary it is best to save the texHandles along with their validity intervals. Then when SetupGfxMultiMaps is called, if valid texHandles are already in hand they can just be used without recomputing.

Parameters:

t	The time at which to evaluate the material.
mtl	Points to the interactive renderer material to update.
cb	This callback object is provided as a helper to fill in the Material properties above. See Class MtlMakerCallback.

Default Implementation:: {}

Reimplemented in MSPluginTexmap, MSTexmapXtnd, MSPluginMtl, and MSMtlXtnd.

{}

virtual 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.

Reimplemented in MSPluginTexmap, MSTexmapXtnd, MSPluginMtl, and MSMtlXtnd.

{ if(id==I_SUBMAP) return (ISubMap*)this; else return ReferenceTarget::GetInterface(id); }

virtual 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.

Reimplemented in MSMtlXtnd.

{ return ReferenceTarget::GetInterface(id); }

virtual ReferenceTarget* GetRefTarget ( ) [inline, virtual]

Search for all occurrences

Remarks:: Implemented by the System.

The implementation of this method is provided by MtlBase. It returns its this pointer.

Implements ISubMap.

Reimplemented in MSPluginTexmap, MSTexmapXtnd, MSPluginMtl, and MSMtlXtnd.

{return this;}

virtual CoreExport int SetProperty	(	ULONG	id,
		void *	data
	)		`[virtual]`

Search for all occurrences

Remarks:: This is a general method for adding properties, when defining a new Interface would be too cumbersome. This method provides another way to extend the class without actually adding any methods. Sample code that implements this method to add properties to the property list is in /MAXSDK/SAMPLES/CONTROLLERS/PATHCTRL.CPP. See below.

Parameters:

id	The id for the property.
data	A pointer to the data to store.

Returns:: Nonzero if the property was set; otherwise zero.

Default Implementation:: { return 0; }

Sample Code:

This code is from /MAXSDK/SAMPLES/CONTROLLERS/PATHCTRL.CPP. It is used to save the inverse kinematics user interface parameters of the path controller. It saves the property data on the aprops property list. See the Data Members at the beginning of Animatable for details on aprops.

        int PathPosition::SetProperty(ULONG id, void *data)
        {
            if (id==PROPID_JOINTPARAMS) {
                if (!data) {
                    int index = aprops.FindProperty(id);
                    if (index>=0) {
                        aprops.Delete(index,1);
                    }
                }
                else {
                    JointParamsPath *jp = (JointParamsPath*)GetProperty(id);
                    if (jp) {
                        *jp = *((JointParamsPath*)data);
                        delete (JointParamsPath*)data;
                    }
                    else {
                        aprops.Append(1,(AnimProperty**)&data);
                    }
                }
                return 1;
            } else
            if (id==PROPID_INTERPUI) {
                if (!data) {
                    int index = aprops.FindProperty(id);
                    if (index>=0) {
                        aprops.Delete(index,1);
                    }
                }
                else {
                    InterpCtrlUI *ui = (InterpCtrlUI*)GetProperty(id);
                    if (ui) {
                        *ui = *((InterpCtrlUI*)data);
                    }
                    else {
                        aprops.Append(1,(AnimProperty**)&data);
                    }
                }
                return 1;
            }
            else {
                return Animatable::SetProperty(id,data);
            }
        }

Reimplemented from Animatable.

Reimplemented in MSMtlXtnd.

virtual CoreExport void* GetProperty ( ULONG id ) [virtual]

Search for all occurrences

Remarks:: This method is used to retrieve a property specified by the id passed (as stored by SetProperty()).

Note for 3ds Max version 1.1:

Two new property IDs have been added:

PROPID_CLEARCACHES: When passed to a texture map or material, the material should dump any of its caches. For example, the bitmap texture responds to this by freeing the bitmap from memory. For sample code see /MAXSDK/SAMPLES/MATERIALS/BMTEX.CPP.

PROPID_HAS_WSM: When passed to an INode, will return TRUE if the node has World Space Modifiers applied to it or FALSE if it does not. For sample code see /MAXSDK/SAMPLES/IMPEXP/3DSEXP.CPP.

Note for 3ds Max version 1.2:

A new id has been created and assigned the constant:

#define PROPID_EVAL_STEPSIZE_BUG_FIXED 0x1000.

This only effects the evaluation of objects when rendering them using motion blur. Motion blur works by evaluating the object numerous times (at fractions of a frame apart) and combining these images by blending them together.

Originally, 3ds Max would make these evaluations in reverse order within a sub-frame -- from the last one, to the second to the last one, back to the first one. There is a problem with this for certain plug-ins that need to compute their state from time 0 forward. For these objects, the backwards approach may be too computationally intensive.

Both the forward and backward approaches exist in 3ds Max and the developer may choose which method to use. 3ds Max interrogates the object to see how it should handle the evaluation process -- either going backwards or forwards. It calls this method with id set to the constant PROPID_EVAL_STEPSIZE_BUG_FIXED. If a plug-in implements this method to return nonzero, it means the plug-in works correctly using forward stepping, and 3ds Max will use that approach. If a plug-in does not implement this method and handle the id of PROPID_EVAL_STEPSIZE_BUG_FIXED it will return the default value of zero. This means the older method of backwards evaluation will be used.

Therefore, a plug-in object that wants to handle motion blur using forward stepping should implement this method, and if passed an id of PROPID_EVAL_STEPSIZE_BUG_FIXED, should return nonzero.

Parameters:

id	The id of the property to retrieve.

Default Implementation:: { return NULL; }

Sample Code:

This code is from /MAXSDK/SAMPLES/CONTROLLERS/PATHCTRL.CPP. It is used to restore the inverse kinematics user interface parameters of the path controller. It retrieves the property data on the aprops property list. See the Data Members at the beginning of Animatable for details on aprops.

        void* PathPosition::GetProperty(ULONG id)
        {
            if (id==PROPID_INTERPUI || id==PROPID_JOINTPARAMS) {
                int index = aprops.FindProperty(id);
                if (index>=0) {
                    return aprops[index];
                }
                else {
                    return NULL;
                }
            }
            else {
                return Animatable::GetProperty(id);
            }
        }

Reimplemented from Animatable.

Reimplemented in MSMtlXtnd.

virtual CoreExport void BaseClone	(	ReferenceTarget *	from,
		ReferenceTarget *	to,
		RemapDir &	remap
	)		`[virtual]`

Search for all occurrences

This method copies base class data from an object to its clone.

This method is available in release 4.0 and later only. Virtual method.

Note:: All plugins that implement a Clone() method have to call this BaseClone() method from that Clone() method with the old and the new object as parameters. The ordering in regards to when this method is called is unimportant, however this method must, of course, be called after the cloned object is created. This method allows base classes to copy their data into a new object created by the clone operation. As described in the Clone method, the Clone method should just create a new instance and then call the BaseClone method. The BaseClone method should then clones any references and sets any other necessary data. This allows classes that derive from this class to clone cleanly. See the Clone method documentation for a code example. All overrides of BaseClone() must call the base class implementation. The base class implementation copies the CustAttrib objects into the newly created object.

Parameters:

from	- Points to the old object to clone.
to	- Points to the new object created.
remap	- This class is used for remapping references during a Clone.

Reimplemented from ReferenceTarget.

virtual BOOL GetTransparencyHint	(	TimeValue	t,
		Interval &	valid
	)		`[inline, virtual]`

Search for all occurrences

Transparency hint indicates whether the material is potentially transparent for both rendering and viewport display, so that the renderers or viewport can decide whether to optimize it or not.

Parameters: