#include <material.h>

Class Description

Describes a material of a geometry including its surface colors, transparency and texture information.

The material class is responsible for the appearance of a surface when its rendered. Each mesh in Mudbox has an associated material, and multiple meshes can use the same material instance.

When Mudbox renders the mesh, it first uses the associated material to prepare the opengl pipeline for the mesh by calling the Material::Activate() function. The material class is also used to determine the list of paintable textures over the surface. The functions Material::TextureCount() and Material::Texture() are used for this purpose. For more details, see the TexturePool class.

You can derive from the Material class to create your own custom materials with texture channels that control any parameters you wish. See the SDK examples.

How to access a specific texture value at a point on the surface:

Calculate the texture coordinate associated for the surface point. This can be done by calculating a linear conbination of the texture coordinates at the corners of the face based on the information you have about where the point is inside the face.
Decide which texture are you interested in, by examining the list of textures in the corrseponding material instance by calling the TextureCount() and Texture() functions. You can get the name of a texture by calling the Texture::Name() function. This list is dynamic is because it can changed depending on the material implementation. The default Mudbox material has a fixed list, but materials created from custom cgfx files can have very different texture lists.
Since Mudbox supports layers for each texture, you next need to choose the layer you are interested in. To do this, cast the pointer obtained in step 2 to LayerContainer. Once you have a pointer to a layercontainer instance, you can check the list of layers and their names. Finally you have to cast the layer to a TexturePool again.
Based on your interpolated texture coordinate, you have to select the proper tile in the TexturePool by calling TexturePool::Tile() function. (If the UV space of an object goes beyond the range 0-1, Mudbox uses multiple tiles to represent each layer of a texture.) Pass in a bounding box representing the tile you are interested in. For example, if the desired texture coordinate is 1.3, 3.4, then you would pass in a bounding box between ( 1, 3, 0 ) and ( 2, 4, 0 ). (In texture space, the third coordinate is always 0.) Once you get the tile, you would sample the texel at 0.3, 0.4 within that tile. (See next step)
Once you got the texture, copy it to an Image object by calling the Texture::CopyTo() function. You can easily access the color of the needed pixel by calling the Image::ColorAt() function. Note that copying a texture to an image is a slow process, so if you want to sample multiple surface points, it is smart to copy the textures only once, and cache it.

Examples:: FixedFunctionMaterial/FixedFunctionMaterial.h, and ToonMaterial/ToonMaterial.h.

Definition at line 73 of file material.h.

Inheritance diagram for Material:

Public Member Functions
	~Material ()

virtual bool	Activate (const Mesh *pMesh, const AxisAlignedBoundingBox &cUVArea, const Color &cColor=Color::white)
	Prepares the GPU to draw with this material. More...

virtual void	Deactivate (void)
	Sets the GPU back to its default state. More...

virtual float	Transparency (void) const
	Returns the overall transparency of the surface. More...

virtual void	SetTransparency (float fTransparency)
	Sets the transparency of the surface. More...

virtual bool	TexturesVisible (void) const
	Returns true if textures should be visible on the rendered surface. More...

virtual void	SetTexturesVisible (bool bVisible)
	Sets if the textures should be visible on the surface. More...

virtual bool	IsTCNeeded (void) const
	Returns true if the material implementation needs texture coordinates from the mesh. More...

virtual bool	IsTNBNeeded (void) const
	Returns true if the material implementation needs tangent and binormal data from the mesh. More...

virtual unsigned int	TextureCount (void) const
	Returns the number of textures associated with the material. More...

virtual class TexturePool *	Texture (unsigned int iTextureIndex) const
	Returns a pointer to the specified texture. Do not delete this pointer. More...

virtual bool	SetTextureTileLive (const AxisAlignedBoundingBox &cUVArea, bool bLive, float fTCGrad=-1.0f, bool bSync=false, bool bLazyUpdate=false)
	Loads or unloads the specified uv tile for all textures in this material. More...

virtual bool	IsTextureTileLive (const AxisAlignedBoundingBox &cUVArea)
	Returns if the specified uv tile is loaded into memory. More...

virtual unsigned int	TextureTileCount () const
	Returns the number of texture tiles associated with this material. More...

virtual void	SetTextureTileLODBias (const AxisAlignedBoundingBox &cArea, float fTCGrad)
	Set the texture coordinate gradient for the specified texture tile area. More...

virtual qint64	TileVideoMemoryUsage (const AxisAlignedBoundingBox &cArea, float fTCGrad=-1.0f) const
	Returns the amount video memory that Mudbox estimates the specified tile would use for the specified texture coordinate gradient. More...

virtual AxisAlignedBoundingBox	TextureTileArea (unsigned int iTileIndex) const
	Returns the uv area covered by the given tile. More...

virtual void	ActivateUVArea (const AxisAlignedBoundingBox &cArea)
	Prepares the GPU to draw a specific uv area. More...

virtual VertexDataUsage	MapVertexData (VertexDataUsage eUsage) const
	This function is called to determine the mapping of vertex shader inputs for the material. More...

virtual Layer *	ImportPaintLayer (const QString &sFileName, const QString &sChallenName, Mesh *pMesh=0 )
	Import a new paint layer from a file to the material. More...

Public Member Functions inherited from TreeNode
	TreeNode (void)

	~TreeNode (void)

virtual void	Serialize (Stream &s)
	Serializes the node. More...

virtual void	AddChild (TreeNode *pChild, bool bFirst=false) const
	Adds a node/subtree to the list of children. The added node will be removed from the current parent if it has one. More...

virtual void	RemoveChild (TreeNode *pChild) const
	Removes a node/subtree from the list of children. More...

virtual TreeNode *	FirstChild (void) const
	Returns the first node from the child list. More...

virtual TreeNode *	Parent (void) const
	Returns the parent node. More...

virtual TreeNode *	NextSibling (void) const
	Returns the next linked node with the same parent. More...

virtual TreeNode *	PrevSibling (void) const
	Returns the previous linked node with the same parent. More...

virtual void	MoveChild (TreeNode pChild, TreeNode pAfter)
	Moves the child after the given node in order. More...

virtual TreeNode *	ChildByClass (const ClassDesc *pClass, bool bAutoCreate=true) const
	Returns the first child with the specified type. When the bAutoCreate parameter is true and such a child does not exists, it creates it with the preferred descedant type. More...

template<typename type >
type *	ChildByClass (bool bAutoCreate=true) const
	Same as above, a most confortable version. More...

virtual TreeNode *	ChildByClass (const ClassDesc *pClass, unsigned int iIndex=0) const
	Returns the first child with the specified type, or returns zero if no child found. More...

template<typename type >
type *	ChildByClass (unsigned int iIndex=0) const
	Same as above, a most confortable version. More...

virtual void	DeleteChildByClass (const ClassDesc *pClass)
	Deletes all child which is derived from a specific class. More...

virtual QString	Info (void) const
	Returns descriptive information about the node. More...

virtual bool	Visible (void) const
	Returns if the node is visible. Should be overridden in derived classes. More...

virtual void	SetVisible (bool b)
	Sets the node visibility Should be overridden in derived classes. More...

virtual bool	Locked (void) const
	Returns if the node is locked. Should be overridden in derived classes. More...

virtual void	SetLocked (bool b)
	Sets the locking of the node. Should be overridden in derived classes. More...

virtual bool	HiddenFromUI (void) const
	Returns true if the node cannot be seen from UI. More...

virtual void	SetHiddenFromUI (bool b)
	Sets visibility in UI. More...

virtual void	OnLinked (const TreeNode *pOldParent)
	This function is called then the node is linked to a new parent. More...

virtual void	CheckValidity (Node::DiagnosticLevel iLevel=dgnLevel2) const
	See the documentation for Node::CheckValidity. More...

QString	UniqueChildName (const TreeNode *pChild, const QString &sPrefix="") const
	Finds a node name that is unique among the children of this node. More...

virtual void	SetStringID (const QString &sName)
	This method does the same thing as Node::SetStringID, except it ensures the name is unique among this node's siblings. More...

virtual void	CopyTo (Node *pNode) const

Public Member Functions inherited from Node
	Node (const QString &sStringID="", const QString &sDisplayName="")
	Standard constructor. More...

virtual	~Node (void)

virtual void	Initialize (void)

void	LoadTemplate (const QString &sFileName="", bool bStartEvent=false)
	Use an external XML file to initialize the attributes. More...

void	SaveTemplate (const QString &sFileName="", bool bSaveOnlyVisible=false)
	Save current attributes as an XML template. More...

unsigned int	Version (void) const
	Returns the current version of the node. This number increases when the content of the node changed (when ContentChanged() called). More...

void	SetVersion (unsigned int iVersion)
	Sets the current version number for the node. More...

unsigned int	ReferenceCount (void) const
	Returns the number of pointers referencing this node. More...

Attribute *	ReferencePointer (unsigned int iIndex) const
	Returns the address of an attribute which refers to this node. The type of the attribute is always aptr. More...

Node *	ReferenceNode (unsigned int iIndex) const
	Returns the address of a node referencing this node. More...

virtual QString	Name (const ClassDesc *pClass=0) const
	Deprecated. More...

virtual void	SetName (const QString &sName)
	Deprecated. More...

virtual QString	StringID (const ClassDesc *pClass=0) const
	Returns the string id of the node. More...

virtual QString	DisplayName (void) const
	Returns the display name of the node. More...

virtual void	SetDisplayName (const QString &sDisplayName)
	Sets the display name of the node. More...

virtual QString	HelpID (void) const
	Returns the help entry id of the node. Can be overwritten in derived classes. More...

virtual void	SetHelpID (const QString &sHelpID)
	Sets the help entry id of the node. More...

void	Annex (Node *pSource, const QString &sCategory="")
	Relink all the attributes of the source node to this one. More...

bool	IsKindOf (const ClassDesc *pClass) const
	Returns true if this node is derived from the pClass class. More...

void	ContentChanged (void) const
	This function must be called if the content of the node is changed. More...

virtual Node *	Duplicate (void) const

virtual void	OnNodeEvent (const Attribute &cAttribute, NodeEventType cType)
	This function is called if an event occurs with any of the attributes of the node. More...

virtual void	OnEvent (const EventGate &cEvent)
	This function is called when a generic event occurs. See EventGate class. More...

void	RequestDeferredEvent (Attribute &cAttribute)
	Request for a deferred event, which will occur only in the main loop. More...

unsigned int	AttributeCount (void) const
	Returns the number of attributes owned by the node. More...

Attribute *	AttributeByIndex (int iIndex) const
	Returns a specified attribute (or 0 if iIndex is greater than the number of attributes). More...

Attribute *	AttributeByName (const QString &sName) const
	Returns a specified attribute by its name. Returns 0 if the attribute not found. More...

Attribute *	AttributeByID (const QString &sID) const
	Returns a specified attribute by its ID. Returns 0 if the attribute not found. More...

void	SetAttributeValue (const QString &sAttributeID, const QString &sNewValue)
	Set the value of an attribute from a string. More...

QString	AttributeValue (const QString &sAttributeID) const
	Returns the current value of an attribute as a string. More...

void	LogAttributes (void) const
	Write all attributes into the log file. More...

virtual QWidget *	CreatePropertiesWindow (QWidget *pParent)
	Create a window which displays the attributes of the node. Can be overriden to provide a custom interface. More...

Attribute *	AddAttribute (Attribute::AttributeType type, const QString &id)
	Allows SDK users to add attributes at runtime. More...

Node *	Next (void) const
	Returns the next node in the chain. Used to enumerate the current nodes. See also First(). More...

int	ID (void) const
	Returns an ID for the node. The ID is unique in the whole application life. More...

bool	SetID (int iID)
	Set ID for the node. More...

Protected Member Functions
	Material (void)
	Constructor. More...

Additional Inherited Members
Public Types inherited from Node
enum	DiagnosticLevel { dgnLevel1, dgnLevel2, dgnLevel3 }
	Indicates the level of validity checking that is performed in CheckValidity() More...

Static Public Member Functions inherited from Node
static void	StartHashing ()
	This is called once in main once static ctors are done. More...

static Node *	First (void)
	This function will return the first node in the memory. Used to enumerate all the current nodes. See also Next(). More...

static Node *	ByID (int iID)
	Returns the node with the specified ID, or zero if such a node does not exists. More...

static Node *	ByName (const QString &sClass, const QString &sName)
	Search for a node with the name sName. More...

Public Attributes inherited from TreeNode
	DECLARE_CLASS

Public Attributes inherited from Node
AttributeThisPointer	m_pThis

	DECLARE_CLASS

Constructor & Destructor Documentation

Material ( void )

protected

Constructor.

Do not use it directly; Use CreateInstance() instead.

Material *myMaterial = CreateInstance<Material>();

~Material ( )

Member Function Documentation

virtual bool Activate	(	const Mesh *	pMesh,
		const AxisAlignedBoundingBox &	cUVArea,
		const Color &	cColor = `Color::white`
	)

virtual

Prepares the GPU to draw with this material.

This method is called by Mudbox when the material is about to used for a mesh. It should return true if additional rendering steps are needed. The cColor parameter is only as suggestion, its up to the material class how it uses (or ignores) it.

Parameters

[in]	pMesh	The mesh to be rendered
[in]	cUVArea	The UV tile of the mesh to be rendered (each tile is drawn separately)
[in]	cColor	The suggested color for the tile

virtual void Deactivate ( void )

virtual

Sets the GPU back to its default state.

virtual float Transparency ( void ) const

virtual

Returns the overall transparency of the surface.

Range 0..1. Not currently used.

It is up to the material implementation how it handles this overall transparency value. It can ignore it, but then the user wont be able to control the transparency of their objects in the scene. 0 means totally transparent while 1 means opaque. This is currently not used in mudbox (transparency is always 1) but it might be used in future versions.

virtual void SetTransparency ( float fTransparency )

virtual

Sets the transparency of the surface.

Range 0..1. Called by Mudbox when the user changes the transparency for an object. Not currently used.

Parameters

[in] fTransparency Ranges from 0 (transparent) to 1 (opaque)

virtual bool TexturesVisible ( void ) const

virtual

Returns true if textures should be visible on the rendered surface.

It is up to the material implementation how it handles this parameter. It is provided in case a user wants to turn off texturing in the scene. In that case SetTexturesVisible() is called with false as the parameter.

If textures are set to invisible, then the material implementation should use a fixed value for the different channels that were using textures.

virtual void SetTexturesVisible ( bool bVisible )

virtual

Sets if the textures should be visible on the surface.

Parameters

[in] bVisible To make textures visible, set this to true.

virtual bool IsTCNeeded ( void ) const

virtual

Returns true if the material implementation needs texture coordinates from the mesh.

If you are deriving a new material class, you need to have this method return true if your material needs texture coordinate information to draw itself properly.

virtual bool IsTNBNeeded ( void ) const

virtual

Returns true if the material implementation needs tangent and binormal data from the mesh.

If you are deriving a new material class, you need to have this method return true if your material needs tangent and binormal data to draw itself properly.

virtual unsigned int TextureCount ( void ) const

virtual

Returns the number of textures associated with the material.

virtual class TexturePool* Texture ( unsigned int iTextureIndex ) const

virtual

Returns a pointer to the specified texture. Do not delete this pointer.

Parameters

[in] iTextureIndex Index of the texture to be returned

virtual bool SetTextureTileLive	(	const AxisAlignedBoundingBox &	cUVArea,
		bool	bLive,
		float	fTCGrad = `-1.0f`,
		bool	bSync = `false`,
		bool	bLazyUpdate = `false`
	)

virtual

Loads or unloads the specified uv tile for all textures in this material.

To reduce memory footprint, users may opt to unload some tiles of the texture maps they are working with. This method is called by Mudbox to unload (remove from memory) or load (bring in from disk) those specific tiles. When a texture tile is unloaded, the material should use an arbitrary constant value for the channel it represents.

You probably don't need to override this method in your own materials.

If bLazyUpdate is false, the method always returns true. If bLazySet is true this method returns true when it has completed, otherwise it returns false.

Parameters

[in]	cUVArea	The UV bounds of the tile you want
[in]	bLive	Specify true to load the tile, false to unload it.
[in]	fTCGrad	The TC gradient. If none specified, it will not be changed.
[in]	bSync	Texture in video memory is syncronized with system memory
[in]	bLazyUpdate	Set to false to update the tile immediately, true to update incrementally.

virtual bool IsTextureTileLive ( const AxisAlignedBoundingBox & cUVArea )

virtual

Returns if the specified uv tile is loaded into memory.

Parameters

[in] cUVArea The UV bounds of the tile you are interested in

virtual unsigned int TextureTileCount ( ) const

virtual

Returns the number of texture tiles associated with this material.

virtual void SetTextureTileLODBias	(	const AxisAlignedBoundingBox &	cArea,
		float	fTCGrad
	)

virtual

Set the texture coordinate gradient for the specified texture tile area.

Parameters

[in]	cArea	The UV bounds of the tile
[in]	fTCGrad	The tc gradient of the tile

virtual qint64 TileVideoMemoryUsage	(	const AxisAlignedBoundingBox &	cArea,
		float	fTCGrad = `-1.0f`
	)		const

virtual

Returns the amount video memory that Mudbox estimates the specified tile would use for the specified texture coordinate gradient.

See Texture::ProxyLevel for more information about the texture coordinate gradient. The returned value is in bytes.

Parameters

[in]	cArea	The UV bounds of the tile
[in]	fTCGrad	The tc gradient, if none is specified, the current LOD level is used.

virtual AxisAlignedBoundingBox TextureTileArea ( unsigned int iTileIndex ) const

virtual

Returns the uv area covered by the given tile.

Parameters

[in] iTileIndex The index of the tile of interest.

virtual void ActivateUVArea ( const AxisAlignedBoundingBox & cArea )

virtual

Prepares the GPU to draw a specific uv area.

This method is called by Mudbox when the uv region specified by cArea is about to be rendered. For example, for a mesh with 3 tiles Activate will be called for the first tile, and ActivateUVArea will be called for each subsequent area.

virtual VertexDataUsage MapVertexData ( VertexDataUsage eUsage ) const

virtual

This function is called to determine the mapping of vertex shader inputs for the material.

The return value must be a direct value. The value eNotUsed should be returned if the data is not used by the shader.

Parameters

[in] eUsage The usage to be mapped. This is always a generic value. See VertexDataUsage.

virtual Layer* ImportPaintLayer	(	const QString &	sFileName,
		const QString &	sChallenName,
		Mesh *	pMesh = `0`
	)

virtual

Import a new paint layer from a file to the material.

Parameters

[in]	sFileName	The name of the file to be imported. If there are multiple files and tiles, this parameter
	sChallenName	may contain the name of any file. [in] Name of the channel where the paint layer should be created.
[in]	pMesh	Pointer to a mesh which the paint layer will be imported for. For texture maps, this parameter will be ignored, but for ptex files, this parameter is important.

The documentation for this class was generated from the following file:

Mudbox/material.h

Material Class Reference

Class Description

Public Member Functions

Protected Member Functions

Additional Inherited Members

Constructor & Destructor Documentation

Member Function Documentation