MEL How-To #103

How do I create a shading network that connects a Shading Group, a material and a texture?

Consider the following shading network:

This network comprises a Lambert material (and its Shading Group), to which a file texture node is connected to its '.color' attribute. A place2dTexture node is connected to allow for editing the texture placement.

The first thing to create is the Material node. This can be a "lambert", or "blinn", or whatever. Each has its own attributes that you may wish to connect. Some, like '.color', are common to all materials.

The command to create a shading node, such as a material, is slightly different than for other nodes. While you can use the "createNode" command for these as well, it is more convenient to use the "shadingNode" command, as this takes care of registering the nodes for Maya's rendering editors, such as the Hypershade.

The "shadingNode" command offers several modes for creating nodes:

Synopsis: shadingNode [flags] String
Flags:
  -al -asLight
 -app -asPostProcess
  -as -asShader
  -at -asTexture
  -au -asUtility

A "lambert" node is classified as a shader. You can query the classification string for a shader node using the "getClassification" MEL command. This query is not necessary for constructing the shading network; it is offered here only to clarify the example.

// Query the classification string for Maya's "lambert" node.
//
getClassification lambert;
// Result: shader/surface //

Therefore, in this case the '-asShader' flag is specified when creating the material.

// Create a Lambert Material
//
string $material = `shadingNode -asShader lambert -name "mayaLogo"`;

The Shading Group manages membership to the material. It is created as a renderable set using the "sets" command.

// Create a Shading Group
//
string $SG = `sets -renderable true -noSurfaceShader true -empty -name "mayaLogoSG"`;

// Connect the material to the Shading Group.
//
connectAttr -f ( $material + ".outColor" ) ( $SG + ".surfaceShader" );

The file node provides a texture image for any color attribute. In this case, it is connected to the Lambert's '.color' input. Again, the "shadingNode" command is used to create renderable texture nodes. A "file" node is classified as a texture, so the '-asTexture' flag is specified in this case.

// Query the classification string for Maya's "file" node.
//
getClassification file;
// Result: texture/2d //

// Create a file texture node
//
string $fileNode = `shadingNode -asTexture file -name "mayaLogo_bmp"`;

// Connect it to the material color
//
connectAttr -f ( $fileNode + ".outColor" ) ( $material + ".color" );

The image loaded by a file texture node is referenced by its filepath, which is assigned to the '.fileTextureName' string attribute.

// Assign filepath to '.fileTextureName' attribute.
//
string $filepath = "C:/AW/ewertb/projects/default/sourceimages/mayaLogo.bmp";
setAttr -type "string" ( $fileNode + ".fileTextureName" ) $filepath;

The place2dTexture node is optional. It is not required for the shading network to function properly. As above, the "shadingNode" command is used to create a placement node, this time specifying the '-asUtility' flag.

// Query the classification string for Maya's "place2dTexture" node.
//
getClassification place2dTexture;
// Result: utility/general/placement/2d //

// A convenience procedure for connecting common attributes between two nodes.
//
proc connect( string $attr, string $place, string $file )
{
  connectAttr -f ( $place + "." + $attr ) ( $file + "." + $attr );
}

string $place2d = ( "place_" + $fileNode );
$place2d = `shadingNode -asUtility place2dTexture -name $place2d`;

// Use convenience command to connect attributes which share 
// their names for both the placement and file nodes.
//
connect "coverage"       $place2d $fileNode;
connect "translateFrame" $place2d $fileNode;
connect "rotateFrame"    $place2d $fileNode;
connect "mirror"         $place2d $fileNode;
connect "stagger"        $place2d $fileNode;
connect "wrapU"          $place2d $fileNode;
connect "wrapV"          $place2d $fileNode;
connect "repeatUV"       $place2d $fileNode;
connect "offset"         $place2d $fileNode;
connect "rotateUV"       $place2d $fileNode;

// These two are named differently.
//
connectAttr -f ( $place2d + ".outUV" ) ( $fileNode + ".uv" );
connectAttr -f ( $place2d + ".outUvFilterSize" ) ( $fileNode + ".uvFilterSize" );

Placement nodes add unnecessary clutter to the Hypershade if they're not actually used, so apply them sparingly. If you're creating a network from a script or your own UI, provide an option for the user as to whether to create the placement node. Alternately, you can query Maya's own preference for this, which is stored in the optionVar "createTexturesWithPlacement":

// Determine if user prefers a placement node connected to a new texture node.
//
int $createPlacement = `optionVar -q createTexturesWithPlacement`;

Related How-To's

04 Sep 2004