Public Types | Public Member Functions | Static Public Member Functions

MMaterial Class Reference

This reference page is linked to from the following overview topics: 2.3 Shader Instances.


Search for all occurrences

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.

#include <MMaterial.h>

List of all members.

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.
 MMaterial (const MObject &, MStatus *ReturnStatus=NULL)
 Constructor from shader set MObject.
 ~MMaterial ()
 Destructor.
MStatus evaluateMaterial (M3dView &, const MDagPath &)
 Evaluate a material.
MStatus evaluateShininess ()
 Perform necessary evaluation to be able to get shininess back.
MStatus evaluateDiffuse ()
 Perform necessary evaluation to be able to get diffuse back.
MStatus evaluateEmission ()
 Perform necessary evaluation to be able to get emission back.
MStatus evaluateSpecular ()
 Perform necessary evaluation to be able to get emission back.
MStatus evaluateTexture (MDrawData &data)
 Evaluate texturing related information.
bool materialIsTextured () const
 Do we have a texture (evaluated or not).
MStatus setMaterial (const MDagPath &, bool hasTransparency)
 Set the current GL material.
MStatus getShininess (float &)
 Get the GL shininess.
MStatus getDiffuse (MColor &)
 Get the GL diffuse color.
MStatus getEmission (MColor &)
 Get the GL emission color.
MStatus getSpecular (MColor &)
 Get the GL specular color.
MStatus getHasTransparency (bool &)
 Determine if material or texture has transparency.
MStatus getTextureTransformation (const MDrawData &data, MMatrix &texXform)
 Get the current textures transformation.
MStatus getTextureTransformation (const MDrawData &data, float &rotateUV, float &scaleU, float &scaleV, float &translateU, float &translateV, float &rotateFrame)
 Get the current textures transformation.
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.
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.
MPxHwShaderNodegetHwShaderNode (MStatus *ReturnStatus=NULL)
 Get the hardware shader node.
MObject shadingEngine ()
 Get the shading engined associated with this material.
MStatus evaluateTextureTransformation ()
 This method is obsolete.
MStatus getTextureTransformation (float &scaleU, float &scaleV, float &translateU, float &translateV, float &rotate)
 This method is obsolete.

Static Public Member Functions

static MMaterial defaultMaterial ()
 Get the default material.
static const char * className ()
 Returns the name of this class.

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:
Examples:
apiMeshShapeUI.cpp, apiSimpleShapeUI.cpp, pnTrianglesNode.cpp, and quadricShape.cpp.
MStatus evaluateShininess ( )

Perform necessary evaluation to be able to get shininess back.

Returns:
Status code
Status Codes:
MStatus evaluateDiffuse ( )

Perform necessary evaluation to be able to get diffuse back.

Returns:
Status code
Status Codes:
MStatus evaluateEmission ( )

Perform necessary evaluation to be able to get emission back.

Returns:
Status code
Status Codes:
MStatus evaluateSpecular ( )

Perform necessary evaluation to be able to get emission back.

Returns:
Status code
Status Codes:
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:
Examples:
apiMeshShapeUI.cpp, apiSimpleShapeUI.cpp, and quadricShape.cpp.
bool materialIsTextured ( ) const

Do we have a texture (evaluated or not).

Returns:
True if the material is textured, false otherwise.
Examples:
apiMeshShapeUI.cpp, apiSimpleShapeUI.cpp, pnTrianglesNode.cpp, and quadricShape.cpp.
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:
Examples:
apiMeshShapeUI.cpp, pnTrianglesNode.cpp, and quadricShape.cpp.
MStatus getShininess ( float &  value)

Get the GL shininess.

Parameters:
[out]valuestorage for shininess
Returns:
Status code
Status Codes:
MStatus getDiffuse ( MColor color)

Get the GL diffuse color.

Parameters:
[out]colorstorage for the diffuse color
Returns:
Status code
Status Codes:
Examples:
pnTrianglesNode.cpp.
MStatus getEmission ( MColor color)

Get the GL emission color.

Parameters:
[out]colorstorage for the emission color
Returns:
Status code
Status Codes:
Examples:
pnTrianglesNode.cpp.
MStatus getSpecular ( MColor color)

Get the GL specular color.

Parameters:
[out]colorstorage for the specular color
Returns:
Status code
Status Codes:
Examples:
pnTrianglesNode.cpp.
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:
Examples:
apiMeshShapeUI.cpp, apiSimpleShapeUI.cpp, pnTrianglesNode.cpp, and quadricShape.cpp.
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:
Examples:
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:

  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:
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
Examples:
apiMeshShapeUI.cpp, pnTrianglesNode.cpp, and 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]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:
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.
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:
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]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:

MMaterial MMaterial MMaterial MMaterial MMaterial MMaterial MMaterial MMaterial MMaterial MMaterial
MMaterial MMaterial MMaterial MMaterial MMaterial MMaterial MMaterial MMaterial MMaterial MMaterial