ISimpleMaterial provides any material or texture plugin the ability to display itself in the new Viewport Display system in 3ds Max 2012. More...

#include <ISimpleMaterial.h>

Inheritance diagram for ISimpleMaterial:

Public Types
enum	FillMode { FillPoint , FillWireframe , FillSolid }
	This is the fill mode used in both SetFillMode and GetFillMode. More...

enum	MapUsage { UsageDiffuse = 0 , UsageOpacity , MaxUsage }
	This enum type tells the viewport rendering system the usage of each texture. More...

Public Types inherited from BaseInterface
enum	LifetimeType { noRelease , immediateRelease , wantsRelease , serverControlled }

Public Member Functions
virtual ISimpleMaterial *	Clone ()=0
	Clones the instance of ISimpleMaterial. More...

virtual void	SetFillMode (ISimpleMaterial::FillMode mode)=0
	Specifies the fill mode of the material. More...

virtual ISimpleMaterial::FillMode	GetFillMode () const =0
	Returns the fill mode that the material is using. More...

virtual void	SetAmbientColor (const AColor &color)=0
	Specifies the ambient color as an RGBA value. More...

virtual const AColor &	GetAmbientColor () const =0
	Returns ambient color that the material is using. More...

virtual void	SetDiffuseColor (const AColor &color)=0
	Specifies diffuse color as an RGBA value. More...

virtual const AColor &	GetDiffuseColor () const =0
	Returns diffuse color that the material is using. More...

virtual void	SetSpecularColor (const AColor &color)=0
	Specifies the specular color as an RGBA value. More...

virtual const AColor &	GetSpecularColor () const =0
	Returns specular color that the material is using. More...

virtual void	SetEmissiveColor (const AColor &color)=0
	Specifies the Emissive color as an RGBA value. More...

virtual const AColor &	GetEmissiveColor () const =0
	Returns Emissive color that the material is using. More...

virtual void	SetSpecularPower (float power)=0
	Specifies the specular exponent of the material to be set. More...

virtual float	GetSpecularPower ()=0
	Returns specular power that the material is using. More...

virtual void	SetSpecularLevel (float level)=0
	Specifies the specular level. More...

virtual float	GetSpecularLevel () const =0
	Returns specular level that the material is using. More...

virtual void	SetSelfIllumColorOn (bool bOn)=0
	Specifies the self illumination mode. More...

virtual bool	GetSelfIllumColorOn () const =0
	Returns self illumination mode that the material is using. More...

virtual bool	SetTextureTransform (MapUsage usage, const Matrix3 &transform)=0
	Set texture transform matrix. More...

virtual Matrix3 &	GetTextureTransform (MapUsage usage)=0
	Get texture transform matrix. More...

virtual bool	SetTexture (TexHandle *pTexture, MapUsage usage)=0
	Set texture with texture handle. More...

virtual TexHandle *	GetTexture (MapUsage usage)=0
	Get texture handle. More...

virtual void	ClearTextures ()=0
	Clears all texture used by this material. More...

virtual bool	SetBorderColor (MapUsage usage, const AColor &color)=0
	Sets the border color as an RGBA value for the texture with the specified texture usage. More...

virtual const AColor &	GetBorderColor (MapUsage usage) const =0
	Returns the border color of the texture with the specified texture usage. More...

Public Member Functions inherited from BaseInterface
virtual UtilExport	~BaseInterface ()
	Destructor. More...

UtilExport BaseInterface *	GetInterface (Interface_ID id)

virtual UtilExport Interface_ID	GetID ()

virtual LifetimeType	LifetimeControl ()

virtual bool	RegisterNotifyCallback (InterfaceNotifyCallback *incb)

virtual void	UnRegisterNotifyCallback (InterfaceNotifyCallback *incb)

virtual BaseInterface *	AcquireInterface ()

virtual void	ReleaseInterface ()

virtual void	DeleteInterface ()

virtual BaseInterface *	CloneInterface (void *remapDir=NULL)

Public Member Functions inherited from InterfaceServer
virtual UtilExport	~InterfaceServer ()
	Destructor. More...

template<class InterfaceType >
InterfaceType *	GetTypedInterface ()

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

Detailed Description

ISimpleMaterial provides any material or texture plugin the ability to display itself in the new Viewport Display system in 3ds Max 2012.

ISimpleMaterial supports fast efficient handling of a basic phong style shader. It supports all the usual surface elements like Diffuse, Specular with the added ability to support two input textures for diffuse and opacity. If a developer needs finer control over the visual appearance of the material then they should look to use the Advanced mode graphics API

A developer typically would not need to worry about many of the Set methods in the class as the viewport display system will translate the host material calling MtlBase::GetDiffuse() and then using ISimpleMaterial::SetDiffuse to update the display definition.
Every material and texture map will have an ISimpleMaterial available as it is added as a property of the MtlBase. To access the property use the following code

ISimpleMaterial *pISimpleMtl = (ISimpleMaterial *)GetProperty(PROPID_SIMPLE_MATERIAL);

PROPID_SIMPLE_MATERIAL

#define PROPID_SIMPLE_MATERIAL

Definition: AnimPropertyID.h:22

The only aspect of the material setup that is not fully automatic is the allocation of textures. In general materials have a more complicated requirement for texture display. An example would be diffuse and opacity display with different mapping channels. Texture plugins on the other hand tend to be more simplistic. However, there are examples of a more complex setup as can be seen with the mix or composite maps. To support these more complex setups the developer must implement ITextureDisplay and implement SetupTextures. SetupTextures is called when ever a change in the material or texture is detected by the system. It is in this method the developer should assign the texture using SetTexture. This method also provides a chance to override the automatic translation of the material parameters, however, it is not a requirement. If ITextureDisplay is not implemented the translation code will use GetActiveTexHandle() to access the texture resource, this is how texture maps such as Checker work.

ISimpleMaterial also allows the material to define a draw style such as whether it is a solid or wireframe. During translation the materials requirements will be checked. For example the standard material can be forced into wireframe mode. The translating code would look like this

// assuming geomNode is a pointer to INode, the node currently being translated
Mtl * mtl = geomNode->GetMtl();
ULONG mtlReq = mtl->Requirements(0);
if (mtlReq & MTLREQ_WIRE) {
        pISimpleMtl->SetFillMode(FillWireframe);
}

ISimpleMaterial is used to provide quick and approximate representations of materials in the viewport. More realistic material representations can be created by writing custom real-time shader using the advanced mode graphics API

Note: All of the methods of this interface are implemented by the graphics driver layer, it is not designed to be derived by plug-ins.

Member Enumeration Documentation

◆ FillMode

enum FillMode

This is the fill mode used in both SetFillMode and GetFillMode.

Enumerator
FillPoint	Point rendering style used for vertex ticks.
FillWireframe	Wireframe rendering style.
FillSolid	Solid rendering style.

             {
                 FillPoint,          
                 FillWireframe,      
                 FillSolid,          
             };

◆ MapUsage

enum MapUsage

This enum type tells the viewport rendering system the usage of each texture.

Enumerator
UsageDiffuse	Diffuse channel.
UsageOpacity	Opacity channel.
MaxUsage

             {
                 UsageDiffuse = 0,   
                 UsageOpacity,       
                 // to add more
                 MaxUsage,
             };

Member Function Documentation

◆ Clone()

virtual ISimpleMaterial* Clone ( )

pure virtual

Clones the instance of ISimpleMaterial.

Returns: a pointer of new cloned ISimpleMaterial.

◆ SetFillMode()

virtual void SetFillMode ( ISimpleMaterial::FillMode mode )

pure virtual

Specifies the fill mode of the material.

Parameters

[in] mode A member of ISimpleMaterial::FillMode.

◆ GetFillMode()

virtual ISimpleMaterial::FillMode GetFillMode ( ) const

pure virtual

Returns the fill mode that the material is using.

Returns: the fill mode.

◆ SetAmbientColor()

virtual void SetAmbientColor ( const AColor & color )

pure virtual

Specifies the ambient color as an RGBA value.

Parameters

[in] color The ambient color.

◆ GetAmbientColor()

virtual const AColor& GetAmbientColor ( ) const

pure virtual

Returns ambient color that the material is using.

Returns: the ambient color.

◆ SetDiffuseColor()

virtual void SetDiffuseColor ( const AColor & color )

pure virtual

Specifies diffuse color as an RGBA value.

If diffuse texture map exists, this value will be ignored.

Parameters

[in] color The diffuse color.

◆ GetDiffuseColor()

virtual const AColor& GetDiffuseColor ( ) const

pure virtual

Returns diffuse color that the material is using.

Returns: the diffuse color.

◆ SetSpecularColor()

virtual void SetSpecularColor ( const AColor & color )

pure virtual

Specifies the specular color as an RGBA value.

Parameters

[in] color The specular color.

◆ GetSpecularColor()

virtual const AColor& GetSpecularColor ( ) const

pure virtual

Returns specular color that the material is using.

Returns: the specular color.

◆ SetEmissiveColor()

virtual void SetEmissiveColor ( const AColor & color )

pure virtual

Specifies the Emissive color as an RGBA value.

Parameters

[in] color The Emissive color.

◆ GetEmissiveColor()

virtual const AColor& GetEmissiveColor ( ) const

pure virtual

Returns Emissive color that the material is using.

Returns: the Emissive color.

◆ SetSpecularPower()

virtual void SetSpecularPower ( float power )

pure virtual

Specifies the specular exponent of the material to be set.

Parameters

[in] power The specular amount.

◆ GetSpecularPower()

virtual float GetSpecularPower ( )

pure virtual

Returns specular power that the material is using.

THe power value can be in the range of 0.0f and 1.0f

Returns: the specular power.

◆ SetSpecularLevel()

virtual void SetSpecularLevel ( float level )

pure virtual

Specifies the specular level.

The specular level information is used to adjust the specular color. THe level value can be in the range of 0.0f and 10.0f

Parameters

[in] level The specular level value.

◆ GetSpecularLevel()

virtual float GetSpecularLevel ( ) const

pure virtual

Returns specular level that the material is using.

Returns: the specular level.

◆ SetSelfIllumColorOn()

virtual void SetSelfIllumColorOn ( bool bOn )

pure virtual

Specifies the self illumination mode.

Parameters

[in] bOn Sets whether Self Illumination Color is on or off.

◆ GetSelfIllumColorOn()

virtual bool GetSelfIllumColorOn ( ) const

pure virtual

Returns self illumination mode that the material is using.

Returns: the self illumination mode. If TRUE, the SelfIllumColor is on.

◆ SetTextureTransform()

virtual bool SetTextureTransform	(	MapUsage	usage,
		const Matrix3 &	transform
	)

pure virtual

Set texture transform matrix.

Parameters

[in]	usage	The texture usage
[in]	transform	The transform matrix

Returns: true if successful

◆ GetTextureTransform()

virtual Matrix3& GetTextureTransform ( MapUsage usage )

pure virtual

Get texture transform matrix.

Parameters

[in] usage The texture usage

Returns: the texture transform matrix

◆ SetTexture()

virtual bool SetTexture	(	TexHandle *	pTexture,
		MapUsage	usage
	)

pure virtual

Set texture with texture handle.

See also: ITextureDisplay::SetupTextures()

Parameters

[in]	pTexture	A texture handle. If pTexture is NULL it will clear the texture. This can give finer control than using ClearTextures()
[in]	usage	The texture usage

Returns: True if successful

◆ GetTexture()

virtual TexHandle* GetTexture ( MapUsage usage )

pure virtual

Get texture handle.

Parameters

[in] usage The texture usage

Returns: A pointer to texture handle

◆ ClearTextures()

virtual void ClearTextures ( )

pure virtual

Clears all texture used by this material.

◆ SetBorderColor()

virtual bool SetBorderColor	(	MapUsage	usage,
		const AColor &	color
	)

pure virtual

Sets the border color as an RGBA value for the texture with the specified texture usage.

Parameters

[in]	usage	The texture usage
[in]	color	The border color

Returns: True if successful

◆ GetBorderColor()

virtual const AColor& GetBorderColor ( MapUsage usage ) const

pure virtual

Returns the border color of the texture with the specified texture usage.

Parameters

[in] usage The texture usage

Returns: the border color

Public Types

Public Member Functions

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

◆ FillMode

◆ MapUsage

Member Function Documentation

◆ Clone()

◆ SetFillMode()

◆ GetFillMode()

◆ SetAmbientColor()

◆ GetAmbientColor()

◆ SetDiffuseColor()

◆ GetDiffuseColor()

◆ SetSpecularColor()

◆ GetSpecularColor()

◆ SetEmissiveColor()

◆ GetEmissiveColor()

◆ SetSpecularPower()

◆ GetSpecularPower()

◆ SetSpecularLevel()

◆ GetSpecularLevel()

◆ SetSelfIllumColorOn()

◆ GetSelfIllumColorOn()

◆ SetTextureTransform()

◆ GetTextureTransform()

◆ SetTexture()

◆ GetTexture()

◆ ClearTextures()

◆ SetBorderColor()

◆ GetBorderColor()