C++ API Reference

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

#include <MMaterial.h>

Public Types

enum  MtextureChannel {
  kColor, 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...
 
MPxHwShaderNodegetHwShaderNode (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...
 

Detailed Description

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.

This method is obsolete. [from before Maya 2016]

Deprecated:
Use MHWRender::MShaderInstance or MHWRender::MFragmentManager instead.
Examples:
gpuCache/gpuCacheShapeNode.cpp.

Member Enumeration Documentation

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]shaderSetAn MObject representing a shader set (e.g. from MFnMesh::getConnectedShaders()) from which to get the material
[out]ReturnStatusThe 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]viewthe view
[in]pathpath to the object
Returns
Status code
Status Codes:
  • MS::kSuccess the evaluate was successfull
  • MS::kFailure the evaluate failed
Examples:
gpuCache/gpuCacheShapeNode.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]datadraw request data to carry the texture information
Returns
Status code
Status Codes:
  • MS::kSuccess the evaluate was successfull
  • MS::kFailure the evaluate failed
bool materialIsTextured ( ) const

Do we have a texture (evaluated or not).

Returns
True if the material is textured, false otherwise.
MStatus setMaterial ( const MDagPath path,
bool  hasTransparency 
)

Set the current GL material.

Parameters
[in]pathpath to the object
[in]hasTransparencywhether the material has transparency
Returns
Status code
Status Codes:
  • MS::kSuccess the method was successfull
  • MS::kFailure the method failed
Examples:
gpuCache/gpuCacheShapeNode.cpp.
MStatus getShininess ( float &  value)

Get the GL shininess.

Parameters
[out]valuestorage 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]colorstorage 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.
MStatus getEmission ( MColor color)

Get the GL emission color.

Parameters
[out]colorstorage for the emission color
Returns
Status code
Status Codes:
  • MS::kSuccess got valid emission color
  • MS::kFailure failed to get valid emission color
MStatus getSpecular ( MColor color)

Get the GL specular color.

Parameters
[out]colorstorage for the specular color
Returns
Status code
Status Codes:
  • MS::kSuccess got valid specular color
  • MS::kFailure failed to get valid specular color
MStatus getHasTransparency ( bool &  value)

Determine if material or texture has transparency.

Parameters
[out]valueTrue 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
MStatus getTextureTransformation ( const MDrawData data,
MMatrix texXform 
)

Get the current textures transformation.

Parameters
[in]datathe draw data from the draw request
[out]texXformstorage for the texture transformation
Returns
Status code
Status Codes:
  • MS::kSuccess got valid transformation values.
  • MS::kFailure failed to get valid transformation values.
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:

  1. A clockwise rotation of rotateUV degrees around the pivot point [0.5,0.5].
  2. A scaling around the origin [0,0].
  3. A translation
  4. Another clockwise rotation of rotateFrame degrees around the pivot point [0.5,0.5].
Parameters
[in]datathe draw data from the draw request
[out]rotateUVstorage for rotatation value of the UV coordinates
[out]scaleUstorage for u scale value
[out]scaleVstorage for v scale value
[out]translateUstorage for u translation value
[out]translateVstorage for v translation value
[out]rotateFramestorage 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]viewthe view in which the textured drawing is to take place
[in]datathe draw data from the draw request
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]imageThe image retrieved. If no image could be retrieve, the value will not change.
[out]colorEither 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]chanTexture channel to check.
[out]mappedWhether the channel is mapped or not (true or false)
[in]dagPathOptional dag path to object. An object path is required to produce texture maps from non-2D procedural textures.
[in]xResOptional 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]yResOptional 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]ReturnStatusStatus 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:
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.

[as of Maya 2019]

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.

[as of Maya 2019]

Deprecated:
Use the non-deprecated overloads of the getTextureTransformation() member function instead.
Parameters
[out]scaleUstorage for u scale value
[out]scaleVstorage for v scale value
[out]translateUstorage for u translation value
[out]translateVstorage for v translation value
[out]rotatestorage 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: