#include <ihardwarematerial.h>

Class Description

See also: Class IDXDataBridge

Description:: This class is only available in release 5 or later.

A pointer to this class is provided by IDXDataBridge::SetDXData(). The GFX layer will implement all these methods. Most of the methods are direct replicas of the DirectX API for SetRenderState and SetTextureStageState.

The reason for this is that only one thread can access the graphics hardware at any one time. Using this interface means that the GFX driver can have its database initialized with the DirectX states required for this object, when it comes to access the graphics device.

To use this class good knowledge of DirectX is needed, a copy of the DirectX documentation is also recommended.

For an example usage of this class see MAXSDK/SAMPLES/HardwareShaders/LightMap/Lightmap.cpp

Inheritance diagram for IHardwareMaterial:

Public Member Functions
virtual Interface_ID	GetID ()

virtual LifetimeType	LifetimeControl ()

virtual void	SetCustomFlag (bool bVal)=0

virtual void	SetFillMode (DWORD mode)=0

virtual void	SetShadeMode (DWORD mode)=0

virtual void	SetMaterial (LPD3DXMATERIAL pMtl)=0

virtual void	SetDiffuseColor (LPD3DXCOLOR pClr)=0

virtual void	SetDiffuseColor (Color c, float alpha=1.0f)=0

virtual void	SetDiffuseColor (Point3 c, float alpha=1.0f)=0

virtual void	SetAmbientColor (LPD3DXCOLOR pClr)=0

virtual void	SetAmbientColor (Color c, float alpha=1.0f)=0

virtual void	SetAmbientColor (Point3 c, float alpha=1.0f)=0

virtual void	SetSpecularColor (LPD3DXCOLOR pClr)=0

virtual void	SetSpecularColor (Color c, float alpha=1.0f)=0

virtual void	SetSpecularColor (Point3 c, float alpha=1.0f)=0

virtual void	SetEmissiveColor (LPD3DXCOLOR pClr)=0

virtual void	SetEmissiveColor (Color c, float alpha=1.0f)=0

virtual void	SetEmissiveColor (Point3 c, float alpha=1.0f)=0

virtual void	SetSpecularPower (float power)=0

virtual bool	SetNumTexStages (DWORD numStages)=0

virtual bool	SetTexture (DWORD stage, DWORD_PTR pTexture)=0

virtual bool	SetTexture (DWORD stage, LPCSTR filename)=0

virtual bool	SetTexture (DWORD stage, DWORD_PTR pTexture, MapUsageType usage)=0

virtual bool	SetTexture (DWORD stage, LPCSTR filename, MapUsageType usage)=0
	This method allows a texture to be loaded to the graphics device. More...

virtual bool	SetTextureUVWSource (DWORD stage, DWORD type)=0

virtual bool	SetTextureMapChannel (DWORD stage, DWORD numChan)=0

virtual bool	SetTextureCoordIndex (DWORD stage, DWORD index)=0

virtual bool	SetTextureTransformFlag (DWORD stage, DWORD flag)=0

virtual bool	SetTextureTransform (DWORD stage, LPD3DXMATRIX pTransform)=0

virtual bool	SetTextureColorOp (DWORD stage, DWORD colorOp)=0

virtual bool	SetTextureColorArg (DWORD stage, DWORD argNum, DWORD colorArg)=0

virtual bool	SetTextureAlphaOp (DWORD stage, DWORD alphaArg)=0

virtual bool	SetTextureAlphaArg (DWORD stage, DWORD argNum, DWORD alphaArg)=0

virtual bool	SetTextureAddressMode (DWORD stage, DWORD coordNum, DWORD mode)=0

virtual bool	SetVertexShader (DWORD_PTR pVertexShader)=0

virtual bool	SetPixelShader (DWORD_PTR pPixelShader)=0

virtual bool	SetEffect (DWORD_PTR pEffect)=0

virtual bool	SetPlugin (BaseInterface *pPlugin)=0

virtual bool	SetINode (INode *pINode)=0

virtual void	SetTextureFactor (DWORD factor)=0

virtual void	SetSpecularLevel (float level)=0
	This method sets the specular level. More...

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

UtilExport BaseInterface *	GetInterface (Interface_ID id)

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

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

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

Member Function Documentation

virtual Interface_ID GetID ( )

inlinevirtual

Remarks: The returns the unique ID for this interface. By default it will return IHARDWARE_MATERIAL_INTERFACE_ID

Reimplemented from BaseInterface.

84 { return IHARDWARE_MATERIAL_INTERFACE_ID; }

IHARDWARE_MATERIAL_INTERFACE_ID

#define IHARDWARE_MATERIAL_INTERFACE_ID

Definition: ihardwarematerial.h:27

virtual LifetimeType LifetimeControl ( )

inlinevirtual

Remarks: This method allows inquiries into the actual lifetime policy of a client and provide a server-controlled delete notify callback.

Returns: One of the following LifetimeTypes:

noRelease

Do not call release, use interface as long as you like.

immediateRelease

The interface is only good for one calls. The release is implied so a call to release is not required.

wantsRelease

The clients are controlling the lifetime, so the interface needs a Release() when the client has finished. This is the default.

serverControlled

The server controls the lifetime and will use the InterfaceNotifyCallback to inform the code when it is gone.

Default Implementation:: { return noRelease; }

Reimplemented from BaseInterface.

87 { return noRelease; }

BaseInterface::noRelease

Definition: baseinterface.h:94

virtual void SetCustomFlag ( bool bVal )

pure virtual

virtual void SetFillMode ( DWORD mode )

pure virtual

Remarks: This is equivalent to the DirectX method SetRenderState(FILLMODE,mode)

Parameters:: DWORD mode

A member of D3DFILLMODE

virtual void SetShadeMode ( DWORD mode )

pure virtual

Remarks: This is equivalent to DirectX method SetRenderState(SHADEMODE,mode)

Parameters:: DWORD mode

A member of D3DSHADEMODE

virtual void SetMaterial ( LPD3DXMATERIAL pMtl )

pure virtual

Remarks: Please see the DirectX documentation for more information on this method

virtual void SetDiffuseColor ( LPD3DXCOLOR pClr )

pure virtual

Remarks: Specifies Diffuse color to be set by using the DirectX data structure LPD3DXCOLOR.

virtual void SetDiffuseColor	(	Color	c,
		float	alpha = `1.0f`
	)

pure virtual

Remarks: Allows the Diffuse color to be set

Parameters:: Color c

The diffuse color

float alpha

The colors alpha

virtual void SetDiffuseColor	(	Point3	c,
		float	alpha = `1.0f`
	)

pure virtual

Remarks: Allows the Diffuse color to be set

Parameters:: Point3 c

The diffuse color

float alpha

The colors alpha

virtual void SetAmbientColor ( LPD3DXCOLOR pClr )

pure virtual

Remarks: Specifies the Ambient color to set by using a DirectX data structure.

virtual void SetAmbientColor	(	Color	c,
		float	alpha = `1.0f`
	)

pure virtual

Remarks: Allows the Ambient color to be set

Parameters:: Color c

The ambient color

float alpha

The colors alpha

virtual void SetAmbientColor	(	Point3	c,
		float	alpha = `1.0f`
	)

pure virtual

Remarks: Allows the Ambient color to set

Parameters:: Point3 c

The ambient color

float alpha

The colors alpha

virtual void SetSpecularColor ( LPD3DXCOLOR pClr )

pure virtual

Remarks: Specifies the Specular color to set by using a DirectX data structure.

virtual void SetSpecularColor	(	Color	c,
		float	alpha = `1.0f`
	)

pure virtual

Remarks: Allows the Specular color to be set

Parameters:: Color c

The specular color

float alpha

The colors alpha

virtual void SetSpecularColor	(	Point3	c,
		float	alpha = `1.0f`
	)

pure virtual

Remarks: Allows the Specular color to set

Parameters:: Point3 c

The specular color

float alpha

The colors alpha

virtual void SetEmissiveColor ( LPD3DXCOLOR pClr )

pure virtual

Remarks: Allows the Emissive color to set by using a DirectX data structure.

virtual void SetEmissiveColor	(	Color	c,
		float	alpha = `1.0f`
	)

pure virtual

Remarks: Allows the Emissive color to be set

Parameters:: Color c

The emissive color

float alpha

The colors alpha

virtual void SetEmissiveColor	(	Point3	c,
		float	alpha = `1.0f`
	)

pure virtual

Remarks: Allows the Emissive color to be set

Parameters:: Point3 c

The emissive color

float alpha

The colors alpha

virtual void SetSpecularPower ( float power )

pure virtual

Remarks: Allows the specular exponent of the material to be set

Parameters:: float power

The specular amount

virtual bool SetNumTexStages ( DWORD numStages )

pure virtual

Remarks: This sets the internal size for the table that will hold the Texture information for the material. If you are not using any Texture stages then this should be set to zero, otherwise it should match exactly the number of textures being used.

Parameters:: DWORD numStages

The number of Texture stages

virtual bool SetTexture	(	DWORD	stage,
		DWORD_PTR	pTexture
	)

pure virtual

Remarks: This allows a texture to be loaded to the graphics device. In this case the texture is loaded/created by the GFX via calls to IHardwareRenderer::BuildTexture() which will return a DWORD_PTR, which is an internal representation of the texture. The texture was allocated it will return true.

Parameters:: DWORD stage

The stage to hold the texture

DWORD_PTR pTexture

A texture pointer returned by IHardwareRenderer::BuildTexture()

virtual bool SetTexture	(	DWORD	stage,
		LPCSTR	filename
	)

pure virtual

Remarks: This allows a texture to be loaded to the graphics device. The file is assumed to exist. If successful it will return true.

Parameters:: DWORD stage

The stage to hold the texture

LPCSTR filename

A string containing the filename of the texture to load

virtual bool SetTexture	(	DWORD	stage,
		DWORD_PTR	pTexture,
		MapUsageType	usage
	)

pure virtual

Remarks: This allows a texture to be loaded to the graphics device. In this case the texture is loaded/created by the GFX via calls to IHardwareRenderer::BuildTexture() which will return a DWORD_PTR, which is an internal representation of the texture. The texture was allocated it will return true.

NOTE:If you want to take advantage of the new viewport display mechanism ,you should pass a valid MapUsageType other than MAPUSAGE_UNDEFINED for stage 0. Otherwise, it will use the old display mechanism.

Parameters

[in]	stage	- The stage to hold the texture
[in]	pTexture	- A texture pointer returned by IHardwareRenderer::BuildTexture()
[in]	usage	- A enum type that tell the rendering system the usage of the texture

Returns: TRUE if successful, FALSE otherwise.

virtual bool SetTexture	(	DWORD	stage,
		LPCSTR	filename,
		MapUsageType	usage
	)

pure virtual

This method allows a texture to be loaded to the graphics device.

The file is assumed to exist. If successful it will return true. NOTE:If you want to take advantage of the new viewport display mechanism ,you should pass a valid MapUsageType other than MAPUSAGE_UNDEFINED for stage 0. Otherwise, it will use the old display mechanism.

Parameters

[in]	stage	- The stage to hold the texture
[in]	filename	- A string containing the filename of the texture to load
[in]	usage	- A enum type that tell the rendering system the usage of this texture

Returns: TRUE if successful, FALSE otherwise.

virtual bool SetTextureUVWSource	(	DWORD	stage,
		DWORD	type
	)

pure virtual

Remarks: This specifies where the Texture Coordinates will be retrieved. Most of the time the mesh will supply them so the type would be UVSOURCE_HWGEN. However a Viewport Shader could create them dynamically so would supply. If successful it will return true.

Parameters:: DWORD stage

The stage to set

DWORD type

The UVW Source. It can be any of the following :-

UVSOURCE_MESH

UVSOURCE_XYZ

UVSOURCE_MESH2

UVSOURCE_WORLDXYZ

UVSOURCE_FACEMAP

UVSOURCE_HWGEN

virtual bool SetTextureMapChannel	(	DWORD	stage,
		DWORD	numChan
	)

pure virtual

Remarks: This specifies what mapping channel from the mesh the Texture Coordinates will be retrieved. This is used in the stripping code so that the VertexBuffer is populated with the correct TVs. If successful it will return true.

Parameters:: DWORD stage

The stage to set

DWORD type

The mapping channel to use

virtual bool SetTextureCoordIndex	(	DWORD	stage,
		DWORD	index
	)

pure virtual

Remarks: This specifies what texture coordinate the stage will use. This value is used in the DirectX call SetTextureStageState(stage, D3DTSS_TEXCOORDINDEX, index). If successful it will return true.

Parameters:: DWORD stage

The stage to set

DWORD index

The texture coordinate index to use

virtual bool SetTextureTransformFlag	(	DWORD	stage,
		DWORD	flag
	)

pure virtual

Remarks: This specifies what texture flag the stage will use. This value is used in the DirectX call SetTextureStageState(stage, D3DTSS_TEXTURETRANSFORMFLAGS, flag). If successful it will return true.

Parameters:: DWORD stage

The stage to set

DWORD flag

The DirectX flag to set

virtual bool SetTextureTransform	(	DWORD	stage,
		LPD3DXMATRIX	pTransform
	)

pure virtual

Remarks: This specifies what texture flag the stage will use. This value is used in the DirectX call SetTransform((D3DTRANSFORMSTATETYPE)(D3DTS_TEXTURE0+stage), pTransform). If successful it will return true.

Parameters:: DWORD stage

The stage to set

LPD3DXMATRIX pTransform

The DirectX matrix to set

virtual bool SetTextureColorOp	(	DWORD	stage,
		DWORD	colorOp
	)

pure virtual

Remarks: This method is a direct replica if the DirectX color operators used with D3DTSS_COLOROP. Please refer to the DirectX documentation for further information

Parameters:: DWORD stage

The stage to set

DWORD colorOp

A member of the DirectX enumerated type D3DTEXTUREOP

virtual bool SetTextureColorArg	(	DWORD	stage,
		DWORD	argNum,
		DWORD	colorArg
	)

pure virtual

Remarks: This method is a direct replica if the DirectX Texture Argument flag used with D3DTSS_COLOROPARG. The argNum defines which argument to set. Please refer to the DirectX documentation for further information

Parameters:: DWORD stage

The stage to set

DWORD argNum

The argument index to set. If this is set to 1 then D3DTSS_COLORPARG1 will be addressed

DWORD colorArg

The Argument to set.

virtual bool SetTextureAlphaOp	(	DWORD	stage,
		DWORD	alphaArg
	)

pure virtual

Remarks: This method is a direct replica if the DirectX alpha blending operators used with D3DTSS_ALPHAOP. Please refer to the DirectX documentation for further information

Parameters:: DWORD stage

The stage to set

DWORD alphaArg

A member of the DirectX enumerated type D3DTEXTUREOP

virtual bool SetTextureAlphaArg	(	DWORD	stage,
		DWORD	argNum,
		DWORD	alphaArg
	)

pure virtual

Remarks: This method is a direct replica if the DirectX Texture Alpha Argument flag used with D3DTSS_APLHAPARG. The argNum defines which argument to set. Please refer to the DirectX documentation for further information

Parameters:: DWORD stage

The stage to set

DWORD argNum

The alpha argument index to set. If this is set to 1 then D3DTSS_ALPHAARG1 will be addressed

DWORD colorArg

The Alpha Argument to set.

virtual bool SetTextureAddressMode	(	DWORD	stage,
		DWORD	coordNum,
		DWORD	mode
	)

pure virtual

virtual bool SetVertexShader ( DWORD_PTR pVertexShader )

pure virtual

Remarks: This method allows a DirectX vertex shader to be loaded. It is used in conjunction with IHardwareRenderer::LoadVertexShader which will return a DWORD_PTR of internal storage for the shader. There are methods in Class IHardwareRenderer that provide a means to supply the constants used in the shader.

Parameters:: DWORD_PTR pVertexShader

The vertex shader to load.

virtual bool SetPixelShader ( DWORD_PTR pPixelShader )

pure virtual

Remarks: This method allows a DirectX pixel shader to be loaded. It is used in conjunction with IHardwareRenderer::LoadPixelShader which will return a DWORD_PTR of internal storage for the shader. There are methods Class IHardwareRenderer that provide a means to supply the constants used in the shader.

Parameters:: DWORD_PTR pPixelShader

The vertex shader to load

virtual bool SetEffect ( DWORD_PTR pEffect )

pure virtual

Remarks: This method allows a DirectX effect. It is used in conjunction with IHardwareRenderer::LoadEffectFile which will return a DWORD_PTR of internal storage for the file. There are methods in Class IHardwareRenderer that provide a means to connect the application to the effects file.

Parameters:: DWORD_PTR pEffect

The effect file to load

virtual bool SetPlugin ( BaseInterface * pPlugin )

pure virtual

virtual bool SetINode ( INode * pINode )

pure virtual

virtual void SetTextureFactor ( DWORD factor )

pure virtual

Remarks: This method sets color used for multiple-texture blending with the D3DTA_TFACTOR

texture-blending argument or the D3DTOP_BLENDFACTORALPHA texture-blending operation.

Parameters:: DWORD factor

"factor" is a D3DCOLOR variable. The default value is opaque white(0xFFFFFFFF).

virtual void SetSpecularLevel ( float level )

pure virtual

This method sets the specular level.

This method sets the specular level value. The specular level information is used
to adjust the specular color when viewport is in best quality mode.
NOTE:If specular level map exists, this value will be ignored.

Parameters

[in] level - The specular level value.

IHardwareMaterial Class Reference

Class Description

Public Member Functions

Additional Inherited Members

Member Function Documentation