- Main Page
- Related Pages
- Modules
- Namespaces
- Classes
- Examples

- Class List
- Class Hierarchy
- Class Members

Public Types | Public Member Functions | Static Public Member Functions

# MMaterial Class Reference
OpenMayaUI - API module for user interface

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

enum MtextureChannel

Search for all occurrences

Channels which can be queried.

Only Lambert, Phong, PhongE, Blinn, and Anisotropic are supported

Enumerator:

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

## 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
| ) |  |

Search for all occurrences

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:
  apiMeshShapeUI.cpp, apiSimpleShapeUI.cpp, pnTrianglesNode.cpp, and quadricShape.cpp.

MStatus evaluateShininess | ( |  | ) |

Search for all occurrences

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 | ( |  | ) |

Search for all occurrences

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 | ( |  | ) |

Search for all occurrences

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 | ( |  | ) |

Search for all occurrences

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 evaluateTexture | ( | MDrawData & | data | ) |

Search for all occurrences

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:
  apiMeshShapeUI.cpp, apiSimpleShapeUI.cpp, and quadricShape.cpp.

bool materialIsTextured | ( |  | ) | const

Search for all occurrences

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
| ) |  |

Search for all occurrences

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

MStatus getShininess | ( | float & | value | ) |

Search for all occurrences

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 | ) |

Search for all occurrences

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:
  pnTrianglesNode.cpp.

MStatus getEmission | ( | MColor & | color | ) |

Search for all occurrences

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:
  pnTrianglesNode.cpp.

MStatus getSpecular | ( | MColor & | color | ) |

Search for all occurrences

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:
  pnTrianglesNode.cpp.

MStatus getHasTransparency | ( | bool & | value | ) |

Search for all occurrences

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:
  apiMeshShapeUI.cpp, apiSimpleShapeUI.cpp, pnTrianglesNode.cpp, and quadricShape.cpp.

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

Search for all occurrences

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:
  pnTrianglesNode.cpp.

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

Search for all occurrences

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] | 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
| ) |  |

Search for all occurrences

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 textureImage | ( | MImage & | image,
|  | MColor & | color,
|  | MtextureChannel | chan,
|  | bool & | mapped,
|  | MDagPath & | dagPath,
|  | int | xRes = `-1`,
|  | int | yRes = `-1`
| ) |  |

Search for all occurrences

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` | ) |

Search for all occurrences

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]`

Search for all occurrences

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 | ( |  | ) |

Search for all occurrences

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]`

Search for all occurrences

Returns the name of this class.

Returns:
  Name of this class.

MStatus evaluateTextureTransformation | ( |  | ) |

Search for all occurrences

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
| ) |  |

Search for all occurrences

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.

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