#include <MMaterial.h>

Class Description

This method is obsolete.

Deprecated:: Use MHWRender::MShaderInstance or MHWRender::MFragmentManager instead.

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:: apiMeshShape/apiMeshShapeUI.cpp, gpuCache/gpuCacheShapeNode.cpp, pnTriangles/pnTrianglesNode.cpp, and quadricShape/quadricShape.cpp.

Public Types
enum	MtextureChannel { kColor = 0, kTransparency, kAmbientColor, kIncandescence, kBumpMap, kDiffuse, kTransluscence, kRoughness, kHighlightSize, kWhiteness, kCosinePower, kEccentricity, kSpecularRollOff, kSpecularColor, kReflectivity, kReflectedColor }
	Channels which can be queried. More...

Public Member Functions
	MMaterial ()
	Constructor.

	MMaterial (const MMaterial &in)
	Copy constructor. More...

	MMaterial (const MObject &, MStatus *ReturnStatus=NULL)
	Constructor from shader set MObject. More...

	~MMaterial ()
	Destructor.

MStatus	evaluateMaterial (M3dView &, const MDagPath &)
	Evaluate a material. More...

MStatus	evaluateShininess ()
	Perform necessary evaluation to be able to get shininess back. More...

MStatus	evaluateDiffuse ()
	Perform necessary evaluation to be able to get diffuse back. More...

MStatus	evaluateEmission ()
	Perform necessary evaluation to be able to get emission back. More...

MStatus	evaluateSpecular ()
	Perform necessary evaluation to be able to get specular back. More...

MStatus	evaluateTexture (MDrawData &data)
	Evaluate texturing related information. More...

bool	materialIsTextured () const
	Do we have a texture (evaluated or not). More...

MStatus	setMaterial (const MDagPath &, bool hasTransparency)
	Set the current GL material. More...

MStatus	getShininess (float &)
	Get the GL shininess. More...

MStatus	getDiffuse (MColor &)
	Get the GL diffuse color. More...

MStatus	getEmission (MColor &)
	Get the GL emission color. More...

MStatus	getSpecular (MColor &)
	Get the GL specular color. More...

MStatus	getHasTransparency (bool &)
	Determine if material or texture has transparency. More...

MStatus	getTextureTransformation (const MDrawData &data, MMatrix &texXform)
	Get the current textures transformation. More...

MStatus	getTextureTransformation (const MDrawData &data, float &rotateUV, float &scaleU, float &scaleV, float &translateU, float &translateV, float &rotateFrame)
	Get the current textures transformation. More...

void	applyTexture (M3dView &, const MDrawData &)
	For materials that have texture, this method must be used before the OpenGL drawing to apply the texture to the current view. More...

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

MPxHwShaderNode *	getHwShaderNode (MStatus *ReturnStatus=NULL)
	Get the hardware shader node. More...

MObject	shadingEngine ()
	Get the shading engined associated with this material. More...

MStatus	evaluateTextureTransformation ()
	This method is obsolete. More...

MStatus	getTextureTransformation (float &scaleU, float &scaleV, float &translateU, float &translateV, float &rotate)
	This method is obsolete. More...

Static Public Member Functions
static MMaterial	defaultMaterial ()
	Get the default material. More...

static const char *	className ()
	Returns the name of this class. More...

Member Enumeration Documentation

enum 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 ( const MMaterial & other )

Copy constructor.

Parameters

[in] other

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.

Status Codes:

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.

Member Function Documentation

MStatus 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: Status code

Status Codes:

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

Examples:: apiMeshShape/apiMeshShapeUI.cpp, gpuCache/gpuCacheShapeNode.cpp, pnTriangles/pnTrianglesNode.cpp, and quadricShape/quadricShape.cpp.

MStatus evaluateShininess ( )

Perform necessary evaluation to be able to get shininess back.

Returns: Status code

Status Codes:

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

MStatus evaluateDiffuse ( )

Perform necessary evaluation to be able to get diffuse back.

Returns: Status code

Status Codes:

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

MStatus evaluateEmission ( )

Perform necessary evaluation to be able to get emission back.

Returns: Status code

Status Codes:

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

MStatus evaluateSpecular ( )

Perform necessary evaluation to be able to get specular back.

Returns: Status code

Status Codes:

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

MStatus evaluateTexture ( MDrawData & data )

Evaluate texturing related information.

Must be called before getting any texture properties such as getHasTransparency(), getTextureTransformation() and applyTexture().

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: Status code

Status Codes:

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

Examples:: apiMeshShape/apiMeshShapeUI.cpp, and quadricShape/quadricShape.cpp.

bool materialIsTextured ( ) const

Do we have a texture (evaluated or not).

Returns: True if the material is textured, false otherwise.

Examples:: apiMeshShape/apiMeshShapeUI.cpp, pnTriangles/pnTrianglesNode.cpp, and quadricShape/quadricShape.cpp.

MStatus 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: Status code

Status Codes:

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

Examples:: apiMeshShape/apiMeshShapeUI.cpp, gpuCache/gpuCacheShapeNode.cpp, pnTriangles/pnTrianglesNode.cpp, and quadricShape/quadricShape.cpp.

MStatus getShininess ( float & value )

Get the GL shininess.

Parameters

[out] value storage for shininess

Returns: Status code

Status Codes:

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

MStatus getDiffuse ( MColor & color )

Get the GL diffuse color.

Parameters

[out] color storage for the diffuse color

Returns: Status code

Status Codes:

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

Examples:: gpuCache/gpuCacheShapeNode.cpp, and pnTriangles/pnTrianglesNode.cpp.

MStatus getEmission ( MColor & color )

Get the GL emission color.

Parameters

[out] color storage for the emission color

Returns: Status code

Status Codes:

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

Examples:: pnTriangles/pnTrianglesNode.cpp.

MStatus getSpecular ( MColor & color )

Get the GL specular color.

Parameters

[out] color storage for the specular color

Returns: Status code

Status Codes:

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

Examples:: pnTriangles/pnTrianglesNode.cpp.

MStatus getHasTransparency ( bool & value )

Determine if material or texture has transparency.

Parameters

[out] value True if material or texture has transparency, false otherwise.

Returns: Status code

Status Codes:

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

Examples:: apiMeshShape/apiMeshShapeUI.cpp, pnTriangles/pnTrianglesNode.cpp, and quadricShape/quadricShape.cpp.

MStatus getTextureTransformation	(	const MDrawData &	data,
		MMatrix &	texXform
	)

Get the current textures transformation.

Parameters

[in]	data	the draw data from the draw request
[out]	texXform	storage for the texture transformation

Returns: Status code

Status Codes:

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

Examples:: pnTriangles/pnTrianglesNode.cpp.

MStatus getTextureTransformation	(	const MDrawData &	data,
		float &	rotateUV,
		float &	scaleU,
		float &	scaleV,
		float &	translateU,
		float &	translateV,
		float &	rotateFrame
	)

Get the current textures transformation.

The transformations should applied in the following order:

A clockwise rotation of rotateUV degrees around the pivot point [0.5,0.5].
A scaling around the origin [0,0].
A translation
Another clockwise rotation of rotateFrame degrees around the pivot point [0.5,0.5].

Parameters

[in]	data	the draw data from the draw request
[out]	rotateUV	storage for rotatation value of the UV coordinates
[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]	rotateFrame	storage for rotatation value of the frame coordinates

Returns: Status code

Status Codes:

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

void applyTexture	(	M3dView &	view,
		const 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:: apiMeshShape/apiMeshShapeUI.cpp, pnTriangles/pnTrianglesNode.cpp, and quadricShape/quadricShape.cpp.

MStatus 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.
[out]	color	Either the mapped or unmapped color. If the channel is mapped then an RGBA value of (1,1,1,1) will be returned, otherwise the unmapped channel's current color value will be returned.
[in]	chan	Texture channel to check.
[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: Status code

Status Codes:

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

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

Parameters

[out] ReturnStatus Status code

Returns: Pointer to hardware shader node.

Status Codes:

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

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:: apiMeshShape/apiMeshShapeUI.cpp, and gpuCache/gpuCacheShapeNode.cpp.

MObject shadingEngine ( )

Get the shading engined associated with this material.

Returns: The MObject that maps to the appropriate shading engine node. It is possible for this value to be NULL.

const char * className ( )

static

Returns the name of this class.

Returns: Name of this class.

MStatus evaluateTextureTransformation ( )

This method is obsolete.

Deprecated:: Use evaluateTexture() instead.

Returns: Status code

Status Codes:

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

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

This method is obsolete.

Deprecated:: Use the non-deprecated overloads of the getTextureTransformation() member function instead.

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: Status code

Status Codes:

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

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

MMaterial.h
MMaterial.cpp

MMaterial Class Reference

Class Description

Public Types

Public Member Functions

Static Public Member Functions

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation