MMaterial Class Reference
[OpenMayaUI - API module for user interface]

#include <MMaterial.h>

List of all members.

---

Detailed Description

Hardware shading material class used in MPxSurfaceShapeUI.

This class is used in the draw functions of user defined shapes (see MPxSurfaceShapeUI) for setting up and querying materials used in shaded mode drawing.

Examples:

apiMeshShapeUI.cpp, apiSimpleShapeUI.cpp, pnTrianglesNode.cpp, and quadricShape.cpp.

Public Types
enum	MtextureChannel {    kColor = 0, kTransparency, kAmbientColor, kIncandescence,    kBumpMap, kDiffuse, kTransluscence, kRoughness,    kHighlightSize, kWhiteness, kCosinePower, kEccentricity,    kSpecularRollOff, kSpecularColor, kReflectivity, kReflectedColor }
Public Member Functions
	MMaterial ()
	MMaterial (const MMaterial &in)
	MMaterial (const MObject &, MStatus *ReturnStatus=NULL)
	~MMaterial ()
MStatus	evaluateMaterial (M3dView &, const MDagPath &)
MStatus	evaluateShininess ()
MStatus	evaluateDiffuse ()
MStatus	evaluateEmission ()
MStatus	evaluateSpecular ()
MStatus	evaluateTexture (MDrawData &data)
MStatus	evaluateTextureTransformation ()
bool	materialIsTextured () const
MStatus	setMaterial (const MDagPath &, bool hasTransparency)
MStatus	getShininess (float &)
MStatus	getDiffuse (MColor &)
MStatus	getEmission (MColor &)
MStatus	getSpecular (MColor &)
MStatus	getHasTransparency (bool &)
MStatus	getTextureTransformation (float &scaleU, float &scaleV, float &translateU, float &translateV, float &rotate)
void	applyTexture (M3dView &, MDrawData &)
MStatus	textureImage (MImage &image, MColor &color, MtextureChannel chan, bool &mapped, MDagPath &dagPath, int xRes=-1, int yRes=-1)
MPxHwShaderNode *	getHwShaderNode (MStatus *ReturnStatus=NULL)
Static Public Member Functions
static MMaterial	defaultMaterial ()

---

Member Enumeration Documentation

enum MMaterial::MtextureChannel

Channels which can be queried. Only Lambert, Phong, PhongE, Blinn, and Anisotropic are supported

Enumerator:

kColor	nop
kTransparency
kAmbientColor
kIncandescence
kBumpMap
kDiffuse
kTransluscence
kRoughness	PhongE only.
kHighlightSize	PhongE only.
kWhiteness	PhongE only.
kCosinePower	Phong only.
kEccentricity	Blinn only.
kSpecularRollOff	Blinn only.
kSpecularColor	Blinn and Phong(E) only.
kReflectivity	Blinn and Phong(E) only.
kReflectedColor	Blinn and Phong(E) only.

---

Constructor & Destructor Documentation

MMaterial::MMaterial

(

)

Constructor.

MMaterial::MMaterial

(

const MMaterial &

other

)

Copy constructor.

Parameters:

[in]

other

MMaterial::MMaterial	(	const MObject &	shaderSet,
		MStatus *	ReturnStatus = NULL
	)

Constructor from shader set MObject.

Parameters:

[in]	shaderSet	An MObject representing a shader set (e.g. from MFnMesh::getConnectedShaders()) from which to get the material
[out]	ReturnStatus	The return status.

• MS::kSuccess The method was successful.
• MS::kNullPointerArgument The MObject does not represent valid Maya object.
• MS::kInvalidObjectType The MObject does not represent a shader set.
• MS::kFailure An error occurred.

MMaterial::~MMaterial

(

)

Destructor.

---

Member Function Documentation

MStatus MMaterial::evaluateMaterial	(	M3dView &	view,
		const MDagPath &	path
	)

Evaluate a material. Must be called before evaluating or getting any material properties.

Parameters:

[in]	view	the view
[in]	path	path to the object

Returns:

• MS::kSuccess the evaluate was successfull
• MS::kFailure the evaluate failed

Examples:

apiMeshShapeUI.cpp, apiSimpleShapeUI.cpp, pnTrianglesNode.cpp, and quadricShape.cpp.

MStatus MMaterial::evaluateShininess

(

)

Perform necessary evaluation to be able to get shininess back.

Returns:

• MS::kSuccess the evaluate was successfull
• MS::kFailure the evaluate failed

MStatus MMaterial::evaluateDiffuse

(

)

Perform necessary evaluation to be able to get diffuse back.

Returns:

• MS::kSuccess the evaluate was successfull
• MS::kFailure the evaluate failed

MStatus MMaterial::evaluateEmission

(

)

Perform necessary evaluation to be able to get emission back.

Returns:

• MS::kSuccess the evaluate was successfull
• MS::kFailure the evaluate failed

MStatus MMaterial::evaluateSpecular

(

)

Perform necessary evaluation to be able to get emission back.

Returns:

• MS::kSuccess the evaluate was successfull
• MS::kFailure the evaluate failed

MStatus MMaterial::evaluateTexture

(

MDrawData &

data

)

Do texture evaluation and set a flag to tell if the texture is transparent.

This method should be called from MPxSurfaceShapeUI::getDrawRequests. The draw data argument is the MDrawData for the request that will carry the texture information to the MPxSurfaceShapeUI::draw method.

Parameters:

[in]

data

draw request data to carry the texture information

Returns:

• MS::kSuccess the evaluate was successfull
• MS::kFailure the evaluate failed

Examples:

apiMeshShapeUI.cpp, apiSimpleShapeUI.cpp, and quadricShape.cpp.

MStatus MMaterial::evaluateTextureTransformation

(

)

Perform necessary evaluation to be able to get the texture transformation information back.

Returns:

• MS::kSuccess the evaluate was successfull
• MS::kFailure the evaluate failed

bool MMaterial::materialIsTextured

(

)

const

Do we have a texture (evaluated or not).

Returns:

• MS::true the material is textured
• MS::false the material is not textured

Examples:

apiMeshShapeUI.cpp, apiSimpleShapeUI.cpp, pnTrianglesNode.cpp, and quadricShape.cpp.

MStatus MMaterial::setMaterial	(	const MDagPath &	path,
		bool	hasTransparency
	)

Set the current GL material.

Parameters:

[in]	path	path to the object
[in]	hasTransparency	whether the material has transparency

Returns:

• MS::kSuccess the method was successfull
• MS::kFailure the method failed

Examples:

apiMeshShapeUI.cpp, pnTrianglesNode.cpp, and quadricShape.cpp.

MStatus MMaterial::getShininess

(

float &

value

)

Get the GL shininess.

Parameters:

[out]

value

storage for shininess

Returns:

• MS::kSuccess got valid shininess value
• MS::kFailure failed to get valid shininess value

MStatus MMaterial::getDiffuse

(

MColor &

color

)

Get the GL diffuse color.

Parameters:

[out]

color

storage for the diffuse color

Returns:

• MS::kSuccess got valid diffuse color
• MS::kFailure failed to get valid diffuse color

Examples:

pnTrianglesNode.cpp.

MStatus MMaterial::getEmission

(

MColor &

color

)

Get the GL emission color.

Parameters:

[out]

color

storage for the emission color

Returns:

• MS::kSuccess got valid emission color
• MS::kFailure failed to get valid emission color

Examples:

pnTrianglesNode.cpp.

MStatus MMaterial::getSpecular

(

MColor &

color

)

Get the GL specular color.

Parameters:

[out]

color

storage for the specular color

Returns:

• MS::kSuccess got valid specular color
• MS::kFailure failed to get valid specular color

Examples:

pnTrianglesNode.cpp.

MStatus MMaterial::getHasTransparency

(

bool &

value

)

Get flag to determine if material or texture has transparency.

Parameters:

[out]

value

flag to return

Returns:

• MS::kSuccess got valid transparency flag
• MS::kFailure failed to get valid transparency flag

Examples:

apiMeshShapeUI.cpp, apiSimpleShapeUI.cpp, pnTrianglesNode.cpp, and quadricShape.cpp.

MStatus MMaterial::getTextureTransformation	(	float &	scaleU,
		float &	scaleV,
		float &	translateU,
		float &	translateV,
		float &	rotate
	)

Get the current textures transformation.

Parameters:

[out]	scaleU	storage for u scale value
[out]	scaleV	storage for v scale value
[out]	translateU	storage for u translation value
[out]	translateV	storage for v translation value
[out]	rotate	storage for rotate value

Returns:

• MS::kSuccess got valid transformation values.
• MS::kFailure failed to get valid transformation values.

Examples:

pnTrianglesNode.cpp.

void MMaterial::applyTexture	(	M3dView &	view,
		MDrawData &	data
	)

For materials that have texture, this method must be used before the OpenGL drawing to apply the texture to the current view. This method should be called from within your MPxSurfaceShapeUI::draw method.

Parameters:

[in]	view	the view in which the textured drawing is to take place
[in]	data	the draw data from the draw request

Examples:

apiMeshShapeUI.cpp, pnTrianglesNode.cpp, and quadricShape.cpp.

MStatus MMaterial::textureImage	(	MImage &	image,
		MColor &	color,
		MtextureChannel	chan,
		bool &	mapped,
		MDagPath &	dagPath,
		int	xRes = -1,
		int	yRes = -1
	)

For materials that have texture, this method will attempt to retrieve the pixel map for a given mapped channel of that material. If the channel is not mapped than a status of failure will be returned.

The material types that can be queried include:

• Lambert
• Phong
• PhongE
• Anisotropic
• Blinn

Currently only channels mapped to single file textures is supported.

Parameters:

[out]	image	The image retrieved. If no image could be retrieve, the value will not change.
[in]	color	Either the mapped or unmapped color. If the channel is mapped than an RGBA value of (1,1,1,1) will be returned, otherwise the unmapped channel's current color value will be returned.
[out]	mapped	Whether the channel is mapped or not (true or false)
[in]	dagPath	Optional dag path to object. An object path is required to produce texture maps from non-2D procedural textures.
[in]	xRes	Optional width of image to create. The minimal allowed value is 2. This parameter only applies to procedural textures. The dimension in X will be 128 by default, if a value less than 2 is specified.
[in]	yRes	Optional height of image to create. The minimal allowed value is 2. This parameter only applies to procedural textures. The dimension in Y will be 128 by default, if a value less than 2 is specified.

Returns:

• Mstatus::sSuccess If the channel exists on the material.
• Mstatus::sFailure If the channel does not exist on the material

MPxHwShaderNode * MMaterial::getHwShaderNode

(

MStatus *

ReturnStatus = NULL

)

Get the hardware shader node. If this material has a hardware shader, a pointer to it will be returned in hwShader. If there is no hardware shader, hwShader will be set to NULL.

Returns:

• MS::kSuccess successfully returned a pointer or NULL
• MS::kFailure failed for some reason

MMaterial MMaterial::defaultMaterial

(

)

[static]

Get the default material. There will always be a default material in the scene and therefore the result of this function should always succeed. The default material will correspond to the initialShadingGroup node that is in the scene.

Returns:

The default material returned as a MMaterial object.

Examples:

apiMeshShapeUI.cpp.