Below are brief descriptions and usage instructions for the C++ plug-ins provided.
See section Work with ASHLI shaders to learn how to use this plug-in.
This plug-in creates a node called "affects". Add two dynamic attributes called "A" and "B". When you change the value on A, note that B will recompute.
The following sequence of commands will demonstrate how to use this plug-in:
// Create an "affects" node by typing the MEL command:
createNode affects;
// Add two integer dynamic attributes to the newly created affects node by typing the MEL command:
addAttr -ln A -at long affects1;
addAttr -ln B -at long affects1;
// Change the value of "A" to 10 by typing the MEL command:
setAttr affects1.A 10;
// At this point, the affectsNode::setDependentsDirty() method gets called which causes "B" to be marked dirty.
// Compute the value on "B" by doing a getAttr:
getAttr affects1.B;
// The affectsNode::compute() method is entered which copies the value from "A" (i.e. 10) to "B".
Produces dependency graph node arcLen
This node is a simple example of how to take geometry as an input to a dependency node. This node takes a NURBS curve as an input and outputs its arc length, using the MFnNurbsCurve function to perform the calculation.
The input for this node is a NURBS curve attribute called “inputCurve”. NURBS curve shapes nodes have two compatible output attributes that you can use as inputs for the arcLen node - “local” and “worldSpace”.
The output attribute of the arcLen node is just called “output”. It is a double value that represents the total length of the curve with an epsilon value of 0.001.
The following MEL code shows how to hook up the node to a curve.
createNode -n arcLen1 arcLen;
connectAttr curveShape1.local arcLen1.inputCurve;
From here, you can connect the “output” attribute to whatever you wish to drive, or just read it using the following command:
getAttr arcLen1.output;
This node is provided as an example of how to take geometry as an input. It should be noted that there is already a node in Maya that performs the same service called “curveInfo”.
Produces dependency graph node animCube
This plug-in demonstrates how to take time as an input, and create polygonal geometry for output. The compute method of the node constructs a polygonal cube whose size depends on the current frame number. The resulting mesh is passed to an internal Maya node which displays it and allows it to be positioned.
To use this node, execute the MEL command “animCubeNode.mel” that contains the following commands:
createNode transform -n animCube1;
createNode mesh -n animCubeShape1 -p animCube1;
createNode animCube -n animCubeNode1;
connectAttr time1.outTime animCubeNode1.time;
connectAttr animCubeNode1.outputMesh animCubeShape1.inMesh;
This creates a mesh node under a transform node which is hooked into the world for display. It then creates an animCube node, and connects its input to the time node, and its output to the mesh node.
A cube will now appear on the screen. If the play button on the time slider is pressed, the displayed cube will grow and shrink as the frame number changes.
Produces shape node apiMesh, dependency graph node apiMeshCreator, and data type apiMeshData
This plug-in demonstrates how to create a polygonal mesh shape which has vertices that can be selected, moved, animated, and deformed. This shape also supports OpenGL display of materials.
This plug-in also registers a new kind of geometry data, apiMeshData, and demonstrates how to pass this data between nodes.
The apiMeshCreator node can create two types of apiMeshData, a cube and a sphere. The “shapeType” attribute is used to specify the type of shape to create. This node also takes normal mesh data as an input and converts it to apiMeshData. If there is no input mesh then the output is based on the shapeType attribute.
To create an apiMesh shape, you must first create the apiMesh node, then create an apiMeshCreator node and connect the two nodes as follows:
createNode apiMesh -n m1;
createNode apiMeshCreator -n c1;
connectAttr c1.outputSurface m1.inputSurface;
Produces shape node apiSimpleShape.
This plug-in demonstrates how to create a surface shape with components using the MPxComponentShape class. Use the following MEL to create the node once the plug-in is loaded.
string $node = `createNode apiSimpleShape`;
// Add some CVs
string $attr = $node + ".controlPoints[0]";
int $idx = 0;
for ( $i=0; $i<100; $i++)
{for ( $j=0; $j<100; $j++)
{string $attr = $node + ".controlPoints[ " + $idx + "]";
setAttr $attr $i $j 3;
$idx++;
}
}
Produces MEL command blindComplexData and user defined data type blindComplexData
This plug-in demonstrates how to create blind data (dynamic attributes) based on user defined data types. The plug-in uses an array of structures in which each element contains both a double and an int as the user data type.
The use of the MPlug class to set and retrieve the value of the attribute is demonstrated, as are read and write routines that implement the storage and retrieval of the data in both Maya ASCII and Maya Binary file formats.
To use this plug-in, select a dependency node, and then issue the command blindComplexData. A dynamic attribute containing a five element array will be attached to each selected dependency node. If the scene is saved in Maya ASCII format, you will be able to see the MEL commands that save the value of the dynamic attribute. If the scene is reloaded, the dynamic attribute will be reattached to the applicable nodes.
Produces two dependency graph nodes: blindDataShader and blindDataMesh
This plug-in demonstrates the use of blind data to provide color information to a hardware shading node. It contains two parts, blindDataMesh and blindDataShader.
The blindDataMesh node builds a mesh and populates its blind data with color information. The blindDataShader node is a hardware shader which picks up the color information for drawing. The shader part of the plug-in picks uses the vertex IDs of the MPxHwShaderNode::geometry() method to acquire the blind data color information.
To use this plug-in: Open the blindDataShader.mel file and execute its contents. The results can be viewed by using the shading menu to smooth shade and then turn on hardware texturing.
Produces MEL command blindDoubleData and user defined data type blindDoubleData
This plug-in demonstrates how to create blind data (dynamic attributes) based on user defined data types. The plug-in uses a simple double value as the user data type. The use of the MPlug class to set and retrieve the value of the attribute is demonstrated, as are read and write routines that implement the storage and retrieval of the data in both Maya ASCII and Maya Binary file formats.
To use this plug-in, select a dependency node, and then issue the command blindDoubleData. A dynamic attribute containing the double value, 3.2, will be attached to each selected dependency node. If the scene is saved in Maya ASCII format, you will be able to see the MEL commands that save the value of the dynamic attribute. If the scene is reloaded, the dynamic attribute will be reattached to the applicable nodes.
Produces MEL command blindShortData
This example adds a dynamic attribute to the dependency nodes of each of the currently selected items. The attribute is a short and its default value is set to 99. To use this plug-in, select an object, bring up the Attribute Editor (select Window > Attribute Editor), and then click on the “Extras” tab. The attribute editor should display no extra attributes. Then execute blindShortData in the command window. An attribute will appear in the editor set to the value of 99. The value can be modified in the editor, or with the MEL commands setAttr and getAttr. When the scene is saved the new attribute and value for each selected item are also saved. This example demonstrates how simple blind data can be attached to an object.
Produces dependency graph node buildRotation
This example demonstrates performing a linear algebra calculation based on inputs and outputting the result.
The node takes an up vector and a forward vector as inputs and outputs the rotation that takes the y-axis and the z-axis and rotates them to be the up and forward vectors respectively.
A sample use of this node is to align an object to another surface based on a normal and a tangent vector. This example uses the pointOnSurfaceNode which is a standard node provided with Maya.
sphere -radius 4;
cone -ax 0 1 0;
createNode pointOnSurfaceInfo;
connectAttr nurbsSphereShape1.worldSpace pointOnSurfaceInfo1.inputSurface;
connectAttr pointOnSurfaceInfo1.position nurbsCone1.translate;
setAttr pointOnSurfaceInfo1.u 0.01;
setAttr pointOnSurfaceInfo1.v 0.01;
At this point, the cone will be constrained to a point on the surface of the sphere. As the u and v attributes of the pointOnSurfaceNode are changed, the cone will move around the surface. The next step is to align the cone so that the tip points in the direction of the normal. The buildRotation node will be used to do this.
createNode buildRotation;
connectAttr pointOnSurfaceInfo1.normal buildRotation1.up;
connectAttr pointOnSurfaceInfo1.tangentU buildRotation1.forward;
connectAttr buildRotation1.rotate nurbsCone1.rotate;
Now the cone will be constrained to the surface of the sphere and will also be aligned with the normal of the sphere at the point of constraint.
The plug-in is named cgfxShader.mll. It defines one node, named cgfxShader, and one command, also named cgfxShader. The command is used to manipulate the node. This is very similar to the expression command and node.
The cgfxShader node is a hardware shader (derived from MPxHwShaderNode).
By itself, the shader or s attribute is the only thing visible on a cgfxShader node. You set this attribute to the name of a .fx file and many interesting effects can occur. A .fx file holds CgFX effect definitions. This effect completely controls how the drawing is done. Therefore, if you load a different .fx file, you get a completely different effect on the screen. In theory, the cgfxShader node could do anything that any other hardware shader node could do.
Along with the effect, the CgFX file provides a set of parameters that can be modified to change the effect in controlled ways. For example, a glow effect may allow you to set the color, intensity, and size of the glow. A bumpy, shiny effect may allow you to change the bump texture map. All of these parameters are exposed as dynamic attributes on the shader node. If the effect has a glowColor parameter, the cgfxShader node would have a dynamic color attribute named glowColor. Changes to the attribute affect the parameter.
You specify the .fx file via the Attribute Editor or via the cgfxShader command. All the dynamic attributes that no longer apply are removed and all the attributes that are needed by the new effect are added. You can see all the changes in the Attribute Editor.
cgfxShader [-e] [-fx fileName] [-n name] [nodeName]
The easiest way to use the shaders is via the Hypershade window. Load the plug-in before opening the HyperShade window and then simply invoke Create > Material > Cgfx Shader. You can then simply drag the material onto a shape to assign it.
Produces dependency graph node circle
This plug-in is an example of a user-defined dependency graph node. It takes a number as input (such as time) and generates two output numbers one which describes a sine curve as the input varies and one that generates a cosine curve. If these two are hooked up to the x and z translation attributes of an object the object will describe move through a circle in the xz plane as time is changed.
Executing the command “source circleNode” will create a new “Circle” menu with a single item. Selecting this will build a simple model (a sphere which follows a circular path) which can be played back, by clicking on the “play” icon on the time slider.
The node has two additional attributes which can be changed to affect the animation, “scale” which defines the size of the circular path, and “frames” which defines the number of frames required for a complete circuit of the path. Either of these can be hooked up to other nodes, or can be simply set via the MEL command “setAttr” operating on the circle node “circleNode1” created by the MEL script. For example, “setAttr circleNode1.scale #” will change the size of the circle and “setAttr circleNode1.frames #” will cause objects to complete a circle in indicated number of frames.
Produces MEL command closestPointCmd
This examples demonstrates how to use the MMeshIntersector class to find the closest point between a point light and a mesh. To use this plug-in, first load it and then execute:
file -f -new;
defaultPointLight(1, 1,1,1, 0, 0, 0,0,0, 1);
move -r 0 5 0 ;
polyPlane -w 1 -h 1 -sx 10 -sy 10 -ax 0 1 0 -cuv 2 -ch 1;
scale -r 10 10 10 ;
closestPointCmd pointLight1 pPlane1;
Computes closestPointOnCurve (NURBS curve) from the input position
This plug-in defines both a MEL command and a DG node which takes in as input, a NURBS curve and a worldspace position, then computes the closest point on the input curve from the input position.
In addition to the worldspace “position” at the closest point on the curve, also returned are the “normal”, “tangent”, “U-parameter” and “closest distance from the input position”, at the closest point on the curve.
Produces Mel command clusterWeightFunction
This example demonstrates how to use the MFnWeightGeometryFilter::setWeight method to set the weights of the CVs of a cluster according to a mathematical function.
To use this plug-in, select the cluster and a geometry affected by the cluster.
select cluster1 nurbsSphereShape1;
Then execute the MEL command clusterWeightFunction with the flag to specify which mathematical function to use:
clusterWeightFunction -sine;
The componentScaleManip is a manipulator plug-in that demonstrates how components can be manipulated using a scale manipulator using the manipulator API. This example produces the MEL command componentScaleContext to create the tool context for the component scale manipulator.
To create the tool button for the plug-in, create a new shelf named “Shelf1” and execute the following MEL commands to create the tool button in this shelf:
componentScaleContext;
setParent Shelf1;
toolButton -cl toolCluster -t componentScaleContext1 -i1 "moveManip.xpm";
To use the manipulator, create a nurbs surface and select some CVs. Then click on the tool button created above to activate the plug-in context. The tool should work much like the built-in scale tool, except that the plug-in will only operate on NURBS CVs.
Registers conditions callbacks
The conditionTest plug-in is a simple plug-in that displays which “conditions” are being changed inside Maya. A condition in Maya is something of interest to the Maya internals or plug-ins that has a true or false value. For example, “SomethingSelected” and “playingBack” are two available conditions. These conditions can be tracked at the MEL level with the -conditionTrue, -conditionFalse, or -conditionChanged flags to the scriptJob command.
The plug-in adds a “conditionTest” command that lets you see which conditions are available, track specific conditions, and to see which conditions are being tracked. The basic command syntax is:
conditionTest [-m on|off] [conditionName ...]
The conditionName arguments should be the names of conditions. If no names are specified, the command will operate on all available conditions.
If you use the -m flag, you can specify whether the plug-in should track messages for the specified conditions or not. If you specify the -m flag without any condition names, it will turn on or off tracking for all conditions.
mel: conditionTest -m 1 SomethingSelected
Condition Name State Msgs On
-------------------- ----- -------
SomethingSelected false yes
After this example, the plug-in will display the line:
condition SomethingSelected changed to true
condition SomethingSelected changed to false
every time the selection list becomes empty or not empty. You can disable all condition tracking with the command: conditionTest -m off;
Produces MEL command convertBump
This plug-in command can be used to convert a bump file texture from a grey-scale height field format (used by Maya) to a normal map format that is typically used for real-time, hardware-based rendering.
This code also demonstrates how to use the MImage class to load, manipulate and save image files on disk.
To test this plug-in, first compile and load it using the plug-in manager, then type the following in the script editor:
convertBump "C:/bump.tga" "C:/bump_norm.tga" "tga" 1.0
This would convert the input texture (c:/bump.tga) into an output normal map (c:/bump_norm.tga) using the default bumpScale ratio. The bumpScale parameter can be used to increase or decrease the bumpiness of the resulting normal map.
See the documentation of MImage::saveToFile() for a complete list of the available file formats supported.
convertEdgesToContainedFacesCmd
Produces MEL command convertEdgesToContainedFaces
This plug-in creates a MEL command that converts a selection of edges into a selection of faces that interconnect the original edges (that is, only faces whose composite edges are contained in the original edge selection).
The command's return value is a string array that contains the names of all of the new contained faces. This MEL command has no flags, returns a string array, and operates on selected edges.
select -r pCube1.e[1:2] pCube1.e[6:7];
string $convertedFaces[] = `convertEdgesToContainedFaces`;
// Result: pCube1.f[1] //
convertVerticesToContainedEdgesCmd
Produces MEL command convertVerticesToContainedEdges
This plug-in creates a MEL command that converts a selection of vertices into a selection of edges that interconnect the original vertices (that is, only edges whose composite vertices are contained in the original vertex selection). The command’s return value is a string array that contains the names of all of the new contained edges.
This MEL command has no flags, returns a string array, and operates on selected vertices.
select -r pCube1.vtx[2:5];
string $convertedEdges[] = `convertVerticesToContainedEdges`;
// Result: pCube1.e[1:2] pCube1.e[6:7] //
convertVerticesToContainedFacesCmd
Produces MEL command convertVerticesToContainedFaces
This plug-in creates a MEL command that converts a selection of vertices into a selection of faces that interconnect the original vertices (that is, only faces whose composite vertices are contained in the original vertex selection). The command’s return value is a string array that contains the names of all of the new contained faces.
This MEL command has no flags, returns a string array, and operates on selected vertices.
select -r pCube1.vtx[0:5];
string $convertedFaces[] = `convertVerticesToContainedFaces`;
// Result: pCube1.f[0:1] //
Produces MEL command createClip
This example demonstrates the steps used to create a nonlinear animation clip using the API. The clip will be created either on the selected items, or on a character set node that is supplied using the -c/-char flag. The plug-in creates the animation curves that make up the clip, places them in a source clip, then instances the source clip twice.
To use this plug-in, create a sphere and select it. Then execute the command:
createClip
Open the Maya® Trax™ Editor to see the clips in place on the timeline.
This plug-in demonstrates how to create user-defined manipulators from a user-defined context.
This is the script for running this plug-in:
source "customAttrManip.mel";
sphere;
move 5 0 0;
cone;
move -5 0 0;
select -cl;
Produces dependency graph node cvColor
This example provides an example of how to color the CVs of a NURBS surface by drawing OpenGL points on top of them. This node implements a locator that is intended to be made a sibling of a NURBS surface shape, and sit under the same transform. If the “local” space output attribute of the shape is connected to the “inputSurface” attributed of the locator node, then the later will draw colored points at each CV location. The current algorithm in the node will color the CVs in one of four different colors based on their XY location:
x < 0 && y < 0: Red x < 0 && y >= 0: Cyan x >= 0 && y < 0: Blue x >= 0 && y >= 0: Yellow
To use this plug-in, first load it then execute the command “source cvColorNode” to define the MEL command attachColorNode. This command iterates across selected objects, and attaches a cvColor node, as described above, to each NURBS surface it encounters. Moving the objects, or its CVs, after the node is attached will cause the colors of the CVs to change. The pointSize attribute of the node controls the size of the point that is drawn. The drawingEnabled attribute, if set to false, will disable the display of the colored points.
Produces dependency graph node cvColorShader
This plug-in creates a node that allows vertex color(CPV) to be software rendered. Once the plug-in is loaded, the node will appear as a Color Utility in the Hypershade window. Connect this node to a shader's Color or Incandescence attribute.
This example demonstrates how to handle selection lists and return the contents in a string form that the scripting language will understand. The cvExpand command goes through the current selection list and splits ranges of CVs that are selected into individual strings for each CV, so if the selection list looked like this:
ls -selection;
// Result: curveShape1.cv[1:3] //
Then the cvExpand command will return this instead:
cvExpand;
// Result: curveShape1.cv[1] curveShape1.cv[2] curveShape1.cv[3] //
This example demonstrates how to obtain the world or local space position of a NURBS CV or a polygonal vertex.
The command accepts the flags -l/-local or -w/-world, where world is the default, to indicate whether a local or world space location of the CV is required. The command can handle at most 1 CV per invocation since it returns the coordinate as 3 element a MEL float array. If no arguments are provided to the command, it checks the active selection list. If exactly one CV or vertex is present in that list, it returns its location. If more than one is selected, an error is produced. Alternatively, a single component can be specified on the command line using MEL syntax. For example:
cvPos nurbsSphereShape1.cv[0][0];
Produces MEL command dagPoseInfo
This example demonstrates how to extract DAG pose info for a skeleton’s bind pose, or for other poses created using the “dagPose” command. It demonstrates using an MItSelectionList iterator to determine the selected joints, and using the MPlug class to traverse plug connections and get matrix data from the graph.
To use this plug-in, build a skeleton and bind geometry using either the “Smooth” or “Rigid” Bind feature. Then select the joints for which you want to find the bindPose, and execute the command:
dagPoseInfo -f filename;
Please refer to the example code that describes the output format.
This plug-in demonstrates each of the node deletion callbacks available in Maya API. This plug-in can be used to distinguish when each type of callback should be used. Callbacks are added to nodes by invoking the command:
deletedMessage <node 1> [<node 2> ...]
This command will register 3 callbacks on the nodes.
1) MNodeMessage::addNodeAboutToDeleteCallback is used to register an about to delete callback on the nodes.
2) MNodeMessage::addNodePreRemovalCallback is used to register a pre-removal callback on the nodes.
3) MDGMessage::addNodeRemovedCallback is used to register a callback that called when the node is removed.
For example, to register the callbacks for a nurbs sphere:
sphere;
deletedMessage nurbsSphere1;
delete nurbsSphere1;
// Removal callback node: makeNurbSphere1
// Removal callback node: nurbsSphereShape1
// About to delete callback for node: nurbsSphere1
// Pre-removal callback for node: nurbsSphere1
// Removal callback node: nurbsSphere1
This plug-in implements a dynExprField node for a uniform field. This allows the per particle attributes to drive the field's attributes.
To run the plug-in, do the following:
source dynExprFieldTest.mel
dynExprFieldTest;
Produces MEL command eventTest
The eventTest plug-in is a simple plug-in that displays which “events” are occurring inside Maya. An event in Maya is something of interest to the Maya internals or plug-ins that occurs at a specific point in time. For example, “SelectionChanged” and “timeChanged” are two available events. These events can be tracked at the MEL level with the -event flag to the scriptJob command.
The plug-in adds an “eventTest” command that lets you see which events are available, track specific events, and to see which events are being tracked. The basic command syntax is:
eventTest [-m on|off] [eventName ...]
The eventName arguments should be the names of events. If no names are specified, the command will operate on all available events.
If you use the -m flag, you can specify whether the plug-in should track messages for the specified events or not. If you specify the -m flag without any event names, it will turn on or off tracking for all events.
mel: eventTest -m 1 timeChanged
Event Name Msgs On
-------------------- -------
timeChanged yes
After this example, the plug-in will display the line:
event timeChanged occurred
every time the current time changes. You can disable all event tracking with the command: eventTest -m off;
Produces a dependency graph node exampleRampAttrNode.
This plug-in demonstrates how to create curve and color ramps on a custom node. In addition, required coding for the AE template is included in the example.
loadPlugin exampleRampAttribute;
createNode exampleRampAttrNode;
Produces MEL command exportJointClusterData
This example demonstrates how to find all joint cluster nodes and uses the MFnWeightGeometryFilter function set and MItGeometry iterator to export weights per CV for each geometry deformed by each joint cluster.
To use this plug-in, build a skeleton and bind geometry using the “Rigid Bind” feature. Then type the command:
exportJointClusterData -f filename;
exportJointClusterData -f "C:/temp/skinData"
jointName <skinCount>
skin_1 <weightCount>
<skin_1_component_index1> <skin_1_wt1>
<skin_1_component_index2> <skin_1_wt2>
<skin_1_component_index3> <skin_1_wt3>
...
skin_2 <weightCount>
<skin_2_component_index1> <skin_2_wt1>
<skin_2_component_index2> <skin_2_wt2>
<skin_2_component_index3> <skin_2_wt3>
...
Produces MEL command exportSkinClusterData
This example demonstrates how to find all skin cluster nodes and uses the MFnSkinCluster function set and MItGeometry iterator to export weights per CV for all geometry that are bound as a skin to a skeleton.
To use this plug-in, build a skeleton and bind geometry using the “Smooth Bind” feature and execute the command:
exportSkinClusterData -f filename;
Please refer to the example code that describes the output format.
Produces MEL command findFileTextures
This example demonstrates how to navigate the dependency graph both manually and using the DG iterator. The command searches the dependency graph looking for file texture nodes that are attached to the shading engine. This example also illustrates the use of filters when navigating the DG. As file texture nodes are found, information about their attributes is extracted and printed on standard error. More extensive documentation is in the source code.
To use this plug-in, load a scene that contains some texture information, and find a node (or nodes) that are being shaded by a file texture. Then execute “findFileTextures nodeName1 nodeName2 ...” to find the file textures.
Produces MEL command findTexturesPerPolygon
This example is a variation of the findFileTexturesCmd example. When a file texture node is connected to the color attribute of a shader, the file name will be extracted and printed along with the polygonal index. More extensive documentation is in the source code.
To use this plug-in, apply a shader that has a file texture node applied to the color attribute on a selected object and execute the command “findTexturesPerPolygon”.
This is a simple plug-in for demonstration the use of the new MPxPolyTweakUVCommand class to manipulate UVs.
flipUV [-es on|off] [-fg on|off] [-h on|off]
Depending on the type of texture used, results may not show up in the modelling windows. To see the result, use the UV Editor.
Produces dependency graph node footPrintLocator and footPrintLocatorManip
This example demonstrates how to use the Show Manip Tool with a user-defined manipulator. The user-defined manipulator corresponds to the foot print locator.
To use this plug-in, just type “createNode footPrintLocator” to create a foot print locator, select the foot print, and then click on the Show Manip Tool.
Produces dependency graph node footPrint
This example demonstrates how to create a user-defined locator. A locator is a dag object that is drawn in the 3D views but that does not render. This example plug-in defines a new locator node that draws a foot print. The foot print can be selected and moved using the regular manipulators.
To use this plug-in, just type “createNode footPrint” to create a foot print locator.
Produces dependency graph node fullLoft
This plug-in demonstrates how to take an array of NURBS curves as input and produce a NURBS surface as output. The input curves must have the same number of knots, and both form and degree are ignored.
To use this command, draw two or more curves. Select the curves and execute the MEL command “source fullLoftNode.mel”. This creates the fullLoft node and an output surface, as well as several rebuildCurve nodes to provide a uniform number of CVs for the fullLoft node.
Produces MEL command getAttrAffects
This command takes the name of a node as an argument. It then iterates over each attribute of the node and prints a list of the attributes that it affects and the ones that affect it. To use it issue the command “getAttrAffects nodeName”, where nodeName is the name of the node whose attributes you want to display. If invoked with no arguments, getAttrAffects will display the attribute info regarding all selected nodes.
Produces MEL command convertGeometryCache
This example converts geometry cache files into an ASCII format through the IFF file API.
This plug-in only covers one aspect of parsing geometry cache data. Please see the cacheFileExample.py for a more comprehensive example. This Python script shows how to parse and interpret Maya caches (.mc). This example avoids the use of specialized IFF code so that any standalone application can learn to parse Maya cache files.
Produces MPxConstraint node geometrySurfaceConstraint and MEL command geometrySurfaceConstraint.
This example demonstrates how to use the MPxConstraint and MPxConstraintCommand classes to create a geometry constraint. This type of constraint will keep the constrained object attached to the target as the target is moved. The constrained object can be constrained to one of multiple targets. You can choose to constrain to the target of the highest or lowest weight. To use this plug-in, first load it and then execute:
file -f -new;
polyPlane -w 1 -h 1 -sx 10 -sy 10 -ax 0 1 0 -cuv 2 -ch 1;
scale -r 15 15 15;
polyCylinder -r 1 -h 2 -sx 20 -sy 1 -sz 1 -ax 0 1 0 -rcp 0 -cuv 3 -ch 1;
select -cl;
select -r pPlane1 pCylinder1;
geometrySurfaceConstraint -weight 1;
This plug-in implements a custom collision solver for Maya's dynamic hair system. It allows users to override the following aspects of Maya's dynamic hair systems:
It should be noted that Maya's dynamic hair system involves four areas of collision detection, and this plug-in is specific only to the Hair-to-Object aspect.
This is the helixCmd example from the documentation. It is a demonstration of building a simple command which does not have undo. The command accepts two arguments, “-r” to set the radius of the helix, and “-p” to set the pitch of the helix. So, to create a helix, execute the command “helix [ -r #] [ -p #]” in the command window.
A MEL script is also provided with this example which can be run by executing the command “source helixCmd”.
This script creates a new “Plug-ins” menu under which the “helix” command can be found. Selecting this menu item will bring up a window that allows you to set the radius and pitch for the new helix. This is a good example of hooking up a command to the UI.
This example takes a selected curve and turns it into a helix. That in and of itself isn’t very interesting, but the plug-in implements undo and redo functions so that the change can be undone and then redone. This plug-in is then a simple example of implementing a command which supports do, undo, and redo. To use it, create a curve, then execute “helix2” in the command window. The curve will change into a helix. Select “Undo” from the “Edit” menu, and the change will be undone. Select “Redo” and it will be redone.
Produces MEL command helixMotif
This plug-in is only available on Linux.
This example demonstrates how to create a separate Motif window that uses the same application shell as Maya.
The new window contains a single Motif button widget labelled Create Helix that when pressed creates a helix exactly as is done in the getProjectedFacesCmd example. Maya still controls the X event loop, but arbitrary X widgets and callbacks can be registered, and they will be dispatched by Maya when their event occurs.
Produces MEL commands helixToolCmd and helixToolContext
This example takes the helix example one large step forward by wrapping the command in a context. This allows you to drag out the region in which you want the helix drawn. To use it, you should first execute the command “source helixTool”. This will create a new entry in the “Shelf1” tab of the tool shelf called “Helix Tool”. Click on the new icon, then move the cursor into the perspective window and drag out a cylinder which defines the volume in which the helix will be generated. This plug-in is an excellent example of building a context around a command.
This is the “hello” example from the documentation. You simply type a “hello” in the command window and “Hello” will be output to the window from which you started Maya.
Produces MEL command helloWorld
This is the first example from the documentation. When “helloWorld” is typed into the command window “Hello World” is output to the window from which you started Maya.
The idleTest plug-in shows an example of using both the idle messages and UI deleted messages in a simple plug-in. These messages correspond to the -idleEvent and -uiDeleted flags for the scriptJob command.
When you load the plug-in, it adds the command “idleTest”. To run it, type “idleTest n” where n is some positive number. Idle test will then create a window and start filling it with a list of prime numbers. The test will compute one new prime number for each idle message that it receives. You will notice that idle messages stop during playback or while dragging an object.
If you type a large enough number for n, you will also notice that the idle messages will use up *all* available CPU cycles. For this reason, plug-ins should generally cancel their requests for idle messages once they are no longer needed.
When you delete the window that idleTest has created, the plug-in will receive a “UI deleted” message and cancel any outstanding idle message callbacks.
This command takes as an argument the name of an IFF file. The file is opened and read and general information about the file is returned as a result. For example: “iffInfo sphere.iff”
This command takes as arguments the name of an IFF file and the x and y co-ordinates of a pixel in the image. It returns the r/g/b/a values at that pixel. For example: “iffPixel sphere.iff 100 210"
This command takes as arguments the names of an existing IFF file and the name of a PPM (portable pixmap) file that it should create. The IFF image is read and written out in PPM format to the second file.
This plug-in demonstrates the functionality of the MDagMessage class which allows the listening of instance related messages. The messages support listening to:
1) Instance Added for a specified node (and its instances)
2) Instance Removed for a specified node (and its instances)
3) Instance Added for any node
4) Instance Removed for any node
This plug-in works in the following manner:
ii. Gets its dagPath using an iterator
iii. Adds callback for instance added and removed for this circle.
The callback functions just displays a message indicating the invocation of the registered callback function.
To execute this plug-in, do the following:
instCallbackCmd;
Produces a proxy command intersectCmd.
This plug-in finds the intersection point between a mesh and a spotlight using the accelerations intersection methods of MFnMesh.
First load the plug-in and then create a spotLight and polyPlane. Execute the following:
global proc intersectExample()
{// Make sure light and poly plane names are the same
intersectCmd spotLight1 pPlane1;
select -r spotLight1;
}
scriptJob -ac "spotLight1.tx" intersectExample;
scriptJob -ac "spotLight1.ty" intersectExample;
scriptJob -ac "spotLight1.tz" intersectExample;
scriptJob -ac "spotLight1.rx" intersectExample;
scriptJob -ac "spotLight1.ry" intersectExample;
scriptJob -ac "spotLight1.rz" intersectExample;
Produces dependency graph node jitter
This plug-in is an example of a user-defined procedural dependency graph node. It is primarily oriented toward animation, but can be used to add noise in any connection between two float attributes. It takes a float value as input, adds a pseudo-random value to the input and outputs the noisy float value. For example, if the output of a parameter curve node is connected to the input of the jitter node and the output of the jitter node is connected to the translateX attribute of a surface, the motion of the surface will “jitter” parallel to the X axis.
The node has one other input, “time”. The output of the time slider node, “time1.outTime”, should be connected to the time attribute on the jitter node if the “jittered” animation is to be repeatable. The attribute “scale” can be used to increase or decrease the magnitude of the random offset applied to the input of the jitter node.
Once the plug-in is loaded, the MEL command:
jitter "jitter1" "someNode1.outFloat" "someNode2.inFloat";
will create the jitter node, jitter1, attach the attribute someNode1.outFloat to jitter1.input and attach jitter1.output to someNode2.inFloat. It also attaches the time slider output, time1.outTime to jitter1.time and jitter2.time.
Additionally, it creates two windows with sliders for adjusting the scale.
The jitter node can be easily demonstrated in conjunction with the circleNode plug-in. Load the circleNode and jitterNode plug-ins. Then execute the following commands:
source circleNode
source jitterNode
createSphereAndAttachCircleNode;
jitter "jitter1" "circleNode1.sineOutput" "sphere1.translateX";
jitter "jitter2" "circleNode1.cosineOutput" "sphere1.translateZ";
Clicking the “play” icon on the time slider will cause the sphere to move along a “jittered” circle. The amount of jitter can be varied by adjusting the scale sliders in the windows “jitter1 Scale Editor” and “jitter2 Scale Editor”.
Registers new midi input device jlcVcrDevice
This plug-in is only available on Linux.
Loading this plug-in will register the JL-Cooper midi VCR input device with Maya as type jlcVcrDevice.
To use the device, execute the MEL script “jlcVcrDevice.mel”. This will attach the buttons on the midi device to the animation playback commands in Maya as follows:
To get a list of all input devices currently registered in Maya, use the command listInputDevices.
Produces dependency graph node latticeNoise and MEL command latticeNoise
This plug-in is an example of the following:
The latticeNoise command creates a new lattice deformer around the currently selected geometry, or around the objects specified on the command line. The command also inserts a latticeNoise node in between the lattice shape in the DAG and the node that performs the deformation.
The end effect of the latticeNoise command is that the objects inside the lattice deform with respect to the lattice, but they also wobble about randomly as noise is applied to the lattice points. The latticeNoise node has attributes for amplitude and frequency that control the amount of noise applied.
An example of using the command is:
latticeNoise nurbsSphereShape1 nurbsConeShape1;
Adds the new file format Lep to the file manipulation dialogs
As soon as this plug-in is loaded, the new file format will be available in the “Open”, “Import, and “Export” dialogs.
The icon that is displayed in the file selection boxes is the one that is contained in the file lepTranslator.rgb that is also located in the example plug-in directory. Maya will find this icon as long as the path to the directory that contains it is included in FILE_ICON_PATH environment variable.
An “Lep” file is an ASCII file with a first line of “<LEP>”. The remainder of the file contains MEL commands that create one of the primitives: nurbsSphere, nurbsCone and nurbsCylinder, as well as move commands to position them.
When writing the file, only primitives of these three types will be created along with their positions in 3D space. The reader routine will actually handle more MEL commands than these, but only this limited set of types will be written.
As well, this example demonstrates how to utilize file options. When saving a file, if you click on the option box beside the File > Export menu item, a dialog will pop up that contains two radio boxes asking whether to “Write Positions”. The default is true, and if false is selected, then the move commands for primitives will not be written to the output file. This dialog is implemented by the MEL script, lepTranslatorOpts.mel which is also located in the plug-in directory.
An sample input file is supplied in the example plug-in directory as lepTranslator.lep.
Produces MEL command listLightLinks.
This example demonstrates how to use the MLightLinks class to query Maya's light linking information. The command takes no arguments.If the currently selected object is a light, then the command will select all objects illuminated by that light. If the currently selected object is a piece of geometry, then the command will select all the lights that illuminate that geometry.
Produces MEL command listPolyHoles.
This example demonstrates how to use the MFnMesh::getPolyHoles() function to describe all the holes in a polygon mesh. The command takes no arguments. When invoked, the command outputs a description of any holes in the currently selected mesh to the Output Window (on Windows), or to the console (on the Linux platform).
Produces MEL command lockEvent
This plug-in demonstrates the API callbacks for node and plug locking. These callbacks allow you to receive notification when the locked status of a plug or node is queried internally. The API programmer has the option, upon receipt of the callback, to override/(-o) the lock state of node or plug. This override is controlled via a decision variable passed into the callback function. The variable can hold two values
1. decision = true --> You want to accept the lock state and do whatever the internal default behavior is.
2. decision = false --> You want to deny the lock state and do the opposite of what Maya would usually do.
The flow of execution would be as follows:
1. Received a callback from Maya.
2. What kind of event is this?
3. Do I want to allow this event?
4. Yes, I do not want to OVERRIDE this event. decision = true.
4. No, I want to OVERRIDE this event. decision = false.
sphere ;
// Watch the translateX plug on the sphere we just created
lockEvent -a 3 nurbsSphere1.translateX;
// Do not allow any changes to the plug.
lockEvent -o true;
// Now you can try changes nurbsSphere1.translateX 's value
// but you will not be allowed to do so.
//
setAttr "nurbsSphere1.translateX" 22;
Produces file translator Maya ASCII (via plug-in)
This plug-in is an example of a file translator. Although this is not the actual code used by Maya when it creates files in MayaAscii format, it nonetheless produces a very close approximation of the same format. Close enough that Maya can load the resulting files as if they were MayaAscii.
Currently, the plug-in does not support the following:
To use this plug-in, load it and then invoke it through the Export All menu item.
Produces MEL command marqueeToolContext
This is another context example, except that this example does not have an associated command. To use it, you must execute the command “source marqueeTool” in the command window. This will create a new entry in the “Shelf1” tab of the tool shelf called “Marquee Tool”. When this tool is active, you can select objects in the 3D windows in the same way that you would with the selection tool, that is it can be used for either click selection, drag selection. Both will also work with the shift key held down in the same manner as the selection tool.
Produces command meshOp. Produces dependency node meshOpNode.
Demonstrates the use of the new high level polygon API methods that have been added to MFnMesh.
Note: this plug-in re-uses the following files from the splitUVCmd
Produces MEL command motionPath
This plug-in assigns a curve as a motion path to an object. To use it, create an object and draw a curve. Clear all selected items, then pick the object followed by the curve (order is important). Once both are selected, execute “motionPath” in the command window, then click the play button. The object will move along the curve. This is a simple example of how to use the motion path function set.
Produces MEL command motionTrace
In order to use this plug-in you must first create an object and animate it by setting keyframes. An easy way to do this is to just create a primitive, then set a bunch of keyframes for it with the spiralAnimCurveCmd plug-in.
Once this is done, select the animated object and invoke “motionTrace”. The object will move along its animated path under control of the plug-in and when the animation is complete, the plug-in will draw a curve into the scene that represents the motion path of the object.
The plug-in accepts -s, -e, and -b parameters to control the startFrame, endFrame and byFrame values that it uses in running the animation.
Produces MEL command moveCurveCVs
This is a simple little plug-in which takes the selected CVs of a NURBS curves and moves them to the origin. Of itself it’s not a very practical plug-in, but it demonstrates retrieving CVs from a selection list and the use of the Curve CV iterator.
To use it, you must draw a curve, switch Maya from Object selection mode to Component selection mode, the pick some or all of the CVs of the curve. Then, type the command “moveCurveCVs” in the command window to move the CVs.
Produces MEL command moveManipContext to create the example context.
To use this plug-in, execute the command "source moveManip". This creates a new entry in the "Shelf1" tab of the tool shelf, called "moveManip". Create a sphere and click on the moveManip icon on the shelf. A free point triad manipulator will appear when the object is selected.
Produces MEL commands moveNumericToolCmd and moveNumericToolContext
This is an example of a selection-action tool that allows the user to type in precise translation values to while in the move tool. Once an object is selected, the tool turns into a translation tool. In this mode, the user can type in numeric values in the numeric input field to translate the object.
This tool only supports the translation of transforms, and will only perform translation in orthographic views. Undo, redo, and journaling are supported by this tool.
To use this plug-in, execute the command “source moveNumericTool”. This creates a new entry in the “Shelf1” tab of the tool shelf, called “moveNumericTool”. Click on the new icon, then select an object and drag it around in an orthographic view. With the object still selected, type in the numeric input field to enter a specific translation. You can specify whether you want absolute or relative translation values by clicking on the button to the left of the numeric input field.
Produces MEL commands moveToolCmd and moveToolContext
This is an example of a selection-action tool. When nothing is selected, this tool behaves in exactly the same way as Maya’s selection tool. Once an object is selected, the tool turns into a translation tool.
Note that at this time, the plug-in can translate:
This plug-in will only perform translation in orthographic views. Undo, redo, and journaling are supported by this tool.
To use this plug-in, execute the command “source moveTool”. This creates a new entry in the “Shelf1” tab of the tool shelf, called “moveTool”. Click on the new icon, then select an object and drag it around in an orthographic view. The left mouse button allows movement in two directions, while the middle mouse button constrains the movement to a single direction.
Produces MEL command moveManipContext to create the example context.
To use this plug-in, execute the command "source moveManip". This creates a new entry in the "Shelf1" tab of the tool shelf, called "moveManip". Create a sphere and click on the moveManip icon on the shelf. A free point triad manipulator will appear when the object is selected.
Produces dependency graph node multiCurve
This plug-in demonstrates how to use the MArrayDataBuilder class to create an array attribute in a compute function, the number of elements of which change on each compute cycle.
The node accepts a nurbsCurve as input, and outputs an array of nurbsCurves as outputs. The number of curves is controlled by the attribute numCurves and the spacing between each of the output curves is controlled by the attribute curveOffset. Both numCurves and curveOffset are keyable.
To use this plug-in, load it then execute the MEL command “source multiCurveNode.mel”. This will create a curve, hook it up to an instance of a multiCurve node, keyframe the numCurves and curveOffset attributes, and then hook the output of the multiCurve node to a curveVarGroup node which will display all the output curves. Once this script has been run, push play and as the animation progresses, new curves will be created and the spacing between them will increase.
This plug-in demonstrates how to query a dependency node for its type and for the plugs connected to it. It iterates over the selected items and for each item it prints the following:
To use it, select some objects, then execute “nodeInfo” in the command window. The node information will be printed in the window from which you started Maya.
Produces MEL command nodeMessage
This plug-in that demonstrates how to register/de-register a callback with the MNodeMessage class. This plug-in will register a new command in Maya called “nodeMessage” which adds a callback for the all nodes on the active selection list. A message is printed to stdout whenever a connection is made or broken for those nodes.
Produces dependency graph node offsetNode
This plug-in demonstrates how to create a user-defined weighted deformer with an associated shape. A deformer is a node which takes any number of input geometries, deforms them, and places the output into the output geometry attribute. This example plug-in defines a new deformer node that offsets vertices according to their CV’s weights.
Produces dependency graph node ownerEmitter
This node is an example of a particle emitter that emits in a direction from multiple points defined by a particle shape.
There is an example MEL script “ownerEmitter.mel” that shows how to create the node and appropriate connections to correctly establish a user defined particle emitter.
This example plug-in produces the MEL command “particlePaths” that demonstrates how particle ID information can be used to trace out curves from particle positions over time.
The following sequence of commands will create a set of curves for a particle explosion:
emitter -type omni -r 15 -sro 0 -nuv 0 -cye none -cyi 1 -spd 1 -srn 0 -nsp 1 -tsp 0 -mxd 0 -mnd 0 -dx 1 -dy 0 -dz 0 -sp 0;
particle ;
connectDynamic -em emitter1 particle1;
select -r particleShape1;
gravity -pos 0 0 0 -m 0.5 -att 0 -dx 0 -dy -1 -dz 0 -mxd -1 -vsh none -vex 0 -vof 0 0 0 -vsw 360 -tsr 0.5;
connectDynamic -f gravityField1 particle1;
particlePaths -s 0 -f 4 -i 0.5 particleShape1;
The command uses the function set MFnParticleSystem to sample particle positions and identifiers at discrete points in time.
The command supports the options –s (start time), -f (finish time), and –i (increment period). The particle positions will be sampled starting from the start time through to the finish time in increments of the increment time. The accumulated particle positions will be passed to the MFnNurbsCurve function set to create curves from the accumulated data.
Produces command particleSystemInfo
Demonstrates the use of the new MFnParticleSystem class for retrieving particle information. The number of particle positions followed by the positions are printed to the script editor.
particleSystemInfo $particleNodeName;
particleSystemInfo particleShape2;
This plug-in demonstrates how to extract paint effects render line information from a Maya scene. Load the plug-in and a Maya scene that contains paint effects information, then execute the following:
// Get all data
pfxInfo strokeShape2;
// Or
pfxInfo strokeShape2 "all";
// Only line and width
pfxInfo pfxHairShape2 "lineAndWidth";
// Just line
pfxInfo strokeShape1 "line";
The render line information will be written to the MEL editor.
This simple plug-in demonstrates the pick-by-name functionality. Simply execute “pick <object_name>” in the command window. Also some pattern matching is possible, i.e. “pick surface*” which will pick all objects whose name begins with “surface”.
This plug-in is ATI Radeon specific. It is a hardware shader plug-in to perform:
This is an excerpt from the PN triangle extension specification:
“When PN Triangle generation is enabled, each triangle-based geometric primitive is replaced with a new curved surface using the primitive vertices as control points. The intent of PN Triangles are to take a set of triangle-based geometry and algorithmically tessellate it into a more organic shape with a smoother silhouette. The new surface can either linearly or quadratically interpolate the normals across the patch. The vertices can be either linearly or cubically interpolated across the patch. Linear interpolation of the points would be useful for getting more sample points for lighting on the same geometric shape. All other vertex information (colors, texture coordinates, fog coordinates, and vertex weights) are interpolated linearly across the patch.”
This plug-in defines both a MEL command and a DG node which computes the worldspace position and normal on a poly mesh given a face index, a U-parameter and a V-parameter as input.
The concept of this plug-in is based on the pointOnSurface MEL command and pointOnSurfaceInfo node. The pointOnSubdNode.cpp plug-in example from the Maya API Devkit was also used for reference.
The MEL script AEpointOnSurfaceInfoTemplate.mel was referred to for the AE template MEL script that accompanies the pointOnMeshInfo node.
Produces dependency graph command pointOnSubd
This node is a simple example of how to query a subdivision surface as an input to a dependency node. This node takes a subdivision surface and a parameter point on subdivision surface and outputs the position and the normal of the surface at that point. The MEL script “connectObjectToPointOnSubd.mel” that accompanies this plug-in contains detailed documentation on how to use the node and itself provides a demonstration of that use.
This plug-in demonstrates how to register/de-register a callback with the MPolyMessage class.
This plug-in will register a new command in Maya called "polyMessage" which adds a callback for the all nodes on the active selection list. A message is printed to stdout whenever component ids for those nodes are changed.
To run this plug-in, do the following:
// create a poly plane
// open the outliner and select the poly shape
// Run the plug-in
polyMessage
// select some vertices of the poly shape
// hit the delete key to see the remapped ids of the edges, vertices and faces written out
Produces MEL command polyPrimitive
This plug-in creates several types of polygon primitives and demonstrates the creation of polygonal data. Once it is loaded, executing “polyPrimitive #”, where “#” is an integer between 1 and 7, in the command window will cause a polygon to be created at the origin.
If you execute the command “source polyPrimitiveCmd”, the script polyPrimitiveCmd.mel will be run. After this, if the command “polyPrimitiveMenu” is executed, it will bring up a window which allows you to create these objects simply by clicking a button.
This plug-in demonstrates how to add user defined triangulation for meshes using the new poly API class, MPxPolyTrg.
The node registers a user defined face triangulation function. After the function is registered it can be used by any mesh in the scene to do the triangulation (replace the mesh native triangulation). In order for the mesh to use this function, an attribute on the mesh ‘userTrg’ has to be set to the name of the function.
Different meshes may use different functions. Each of them needs to be registered. The same node can provide more than one function.
createNode polyTrgNode -n ptrg;
polyPlane -w 1 -h 1 -sx 10 -sy 10 -ax 0 1 0 -tx 0 -ch 1 -n pp1;
select -r pp1Shape;
setAttr pp1Shape.userTrg -type "string" "triangulate";
This plug-in demonstrates how to use the MProgressWindow class. The command "progressWindowPlugin" displays a simple progress window which updates every second. The progress window can be terminated by hitting escape.
To run this plug-in, do the following:
progressWindowCmd;
A progress window will be displayed. It should be noted that Maya can only display one progress window at a time. MEL also supports creating a progress window. Program errors may occur if the progress windows of MEL and the API are being called at the same time.
Produces shape node quadricShape
This plug-in registers a new type of shape with Maya called “quadricShape”. This shape will display spheres, cylinders, disks, and partial disks using the OpenGL gluQuadric functions.
For example, to create a sphere:
createNode quadricShape -n qSphere;
It should be noted that there are no output attributes for this shape.
The following input attributes define the type of shape to draw.
Produces MEL command referenceQuery
This example provides useful information about referenced files in the main scene. For each referenced file, the output format is as follows:
Referenced File: filename1
Connections Made
sourceAttribute -> destinationAttribute
...
Connections Broken
sourceAttribute -> destinationAttribute
...
Attributes Changed Since File Referenced
attribute1
attribute2
...
To use the plug-in, open a scene file that contains file references. Execute the MEL command “referenceQuery”. The reference information is written to standard output
Produces dependency graph node renderAccessNode
This example demonstrates how to work with render callbacks. The plug-in will register a render callback, a shadow cast callback, and a post-process callback. When a render starts, render callback will be invoked, providing info related to the render's size. Then if shadow maps exist in the render, shadow cast callback will be invoked after shadow maps have been calculated, providing data to the shadow maps. Finally after geometry's have been rendered, post-render callback will be invoked, providing pointers to the rendered pixels.
The plug-in will modify the rendered image in post-process callback to demonstrate how to manipulate the pixels. The attribute pointWorld will be converted to screen space and back to test MRenderData::worldToScreen() and MRenderData::screenToWorld().
renderViewInteractiveRenderCmd
A new example that demonstrates the immediate feedback setting that has been added to the startRender() methods of the MRenderView class. After loading this plug-in, execute the following to see what options it supports:
help renderViewInteractiveRender;
Produces MEL command renderViewRender
This example demonstrates how to render a full image to the Render View window using the MRenderView class. The command takes no arguments. It renders a 640x480 image tiled with a red and white circular pattern to the Render View.
Produces MEL command renderViewRenderRegion
This example demonstrates how to use the MRenderView class to update the currently selected Render Region in Maya's Render View. The command takes no arguments, and always updates the Render Region with a blue and white circular pattern. The command assumes that the Render View is currently displaying a 640x480 image (such as the one generated by the 'renderViewRender' example command).
The rotateManip is a manipulator plug-in that demonstrates the rotate base manipulator function set. This example produces the MEL command rotateContext to create the tool context for this manipulator.
To create the tool button for the plug-in, create a new shelf named “Shelf1” and execute the following MEL commands to create the tool button in this shelf:
rotateContext;
setParent Shelf1;
toolButton -cl toolCluster -t rotateContext1 -i1 "moveManip.xpm";
To use the manipulator, select an object and click on the new tool button. A rotate manipulator should appear on the object along with a state manipulator nearby. The plug-in rotate manipulator is configured to behave similarly to the built-in rotate manipulator. The state manipulator can be used to choose the mode for the rotate manipulator, which can be one of object space mode, world space mode, gimbal mode, and object space mode with snapping enabled.
Produces MEL command sampleCmd
This example demonstrates how to sample shading group/node using MRenderUtil::sampleShadingNetwork().
The command takes lists of shading info such as pointCamera and UVs, and samples a given shading group/node and returns the result colors and transparencies. Lighting will be calculated if a shading group is sampled. Shadows can be calculated as well if the -shadow flag is specified. For example:
sampleCmd file1.outColor 4 -uvs 0 0 1 0 1 1 0 1;
sampleCmd creater1.outColor 4 -refPoints 0 0 0 1 0 0 1 0 1 0 0 1;
sampleCmd -h provides more details on how to use the command.
Produces MEL command sampleParticles
This example demonstrates how to sample shading groups or nodes using MRenderUtil::sampleShadingNetwork() to assign colors to a particle object.
The command takes lists of shading info such as pointCamera and UVs, and samples a given shading group or node, then assigns the sampled colors and transparencies to a grid of particles using the emit command. Lighting will be calculated if a shading group is sampled. Shadows can be calculated if the -shadow flag is specified.
This plug-in demonstrates walking the DAG using the DAG iterator class. To use it, create a number of objects anywhere in the scene, then execute the command scanDag. This will traverse the DAG printing information about each node it finds to the window from which you started Maya. The plug-in contains specific knowledge of cameras, lights, and NURBS surfaces, and will print object type specific information for each of these.
As well, the command accepts several flags:
Produces MEL command scanDagSyntax
This command plug-in provides the same functionality as scanDagCmd except that the syntax parsing is performed via syntax objects. The command accepts several flags:
This class stores useful information about a shader's attribute, including what's connected upstream of it. It also automatically passes through shader switches.
The ShapeMonitor is a singleton class that watches shape or texture nodes, and keep track of which one changed since the last export. It is used to keep the IFX scenegraph up-to-date in respect to textures.
Additionally, once the ShapeMonitor is no longer necessary (for example, the scene is being closed), it can be destroyed using the destroy() function. Finally, all callbacks and data structures can be cleared by calling the initialize() function.
Produces dependency graph node shell
This plug-in demonstrates how to generate a complex mesh object procedurally. It also demonstrates how to customize the attribute editor for a node.
To use the plug-in, enter the MEL command “shell” to create a new shell node. A mesh object will also be created to display the output. Open the attribute editor for the new shell node to see custom controls for picking various sea shell presets. The attribute editor layout is created by the file AEShellTemplate.mel and provides a complex example of how to create an attribute editor template.
Produces dependency graph node shiftNode
This plug-in demonstrates modifying uvCoord and refPointCamera from within a texture plug-in. The uvCoord and refPointCamera are marked as “renderSource” attributes. The uvCoord and refPointCamera for the current sample position are requested and then subsequently shifted four times. Each time these attributes are modified, the inColor attribute is requested, and because the attributes are render sources, the request for inColor forces a shading evaluation. Thus the 2D or 3D texture connected to inColor will be evaluated four additional times for every point shaded. The inColor values are averaged which produces a blurred result.
Produces dependency graph node simpleEmitter
This node is an example of a particle emitter that emits in a direction from a single position.
There is an example MEL script “simpleEmitter.mel” that shows how to create the node and appropriate connections to correctly establish a user defined particle emitter.
Produces dependency graph node simpleFluidEmitter.
This example demonstrates how to use the new MPxFluidEmitterNode class to implement most of the functionality of Maya’s standard fluid emitters.
createNode simpleFluidEmitter -name simpleFluidEmitter;
// create particle object and connect to the plugin emitter node.
particle -name particles ;
connectDynamic -em simpleFluidEmitter particles;
setAttr "simpleFluidEmitter.rate" 200;
setAttr "simpleFluidEmitter.speed" 25;
playbackOptions -e -min 0.00 -max 60.0;
currentTime -e 0;
play -wait -forward true;
// make some keyframes on emitter
currentTime 0 ;
select -r simpleFluidEmitter ;
setKeyframe "simpleFluidEmitter.tx";
setKeyframe "simpleFluidEmitter.ty";
setKeyframe "simpleFluidEmitter.tz";
setKeyframe "simpleFluidEmitter.rx";
setKeyframe "simpleFluidEmitter.ry";
setKeyframe "simpleFluidEmitter.rz";
currentTime 30 ;
move -r -2.011944 6.283524 -2.668834 ;
move -r -ls -wd 0 0 12.97635 ;
rotate -r -os 0 -75.139762 0 ;
setKeyframe "simpleFluidEmitter.tx";
setKeyframe "simpleFluidEmitter.ty";
setKeyframe "simpleFluidEmitter.tz";
setKeyframe "simpleFluidEmitter.rx";
setKeyframe "simpleFluidEmitter.ry";
setKeyframe "simpleFluidEmitter.rz";
currentTime 60 ;
move -r 0 0 -14.526107 ;
move -r 0 -8.130523 0 ;
rotate -r -os 0 0 78.039751 ;
rotate -r -os 0 0 53.86918 ;
setKeyframe "simpleFluidEmitter.tx";
setKeyframe "simpleFluidEmitter.ty";
setKeyframe "simpleFluidEmitter.tz";
setKeyframe "simpleFluidEmitter.rx";
setKeyframe "simpleFluidEmitter.ry";
setKeyframe "simpleFluidEmitter.rz";
Produces dependency graph node userLoft
This plug-in demonstrates how to accept geometry as an input, and create geometry for output. A NURBS curve is input to the node, and from it a NURBS surface is created. The resulting geometry is passed to an internal Maya node which displays it and allows it to be positioned.
To use this node, first draw a curve in the X-Y plane. Then execute the MEL command “simpleLoftNode.mel” that contains the following commands:
createNode transform -n simpleLoft1;
createNode nurbsSurface -n simpleLoftShape1 -p simpleLoft1;
createNode simpleLoft -n simpleLoftNode1;
connectAttr curveShape1.local simpleLoftNode1.inputCurve;
connectAttr simpleLoftNode1.outputSurface simpleLoftShape1.create;
This creates a nurbsSurface node and hooks the result into the world for display. It then creates a simpleLoft node, and connects its input to curveShape1 (the geometry from the first curve drawn), and connects its output to the NURBS surface node.
A surface will now appear on the screen. If the CVs of the original curve are selected and moved, the surface will be reconstructed to match.
Registers IK solver simpleSolverNode
Loading this plug-in will register a new IK solver with Maya as type simpleSolverNode. To use the solver, create a single IK bone with 2 joints using the Joint tool, then enter the following command in the command window to create an IK handle which uses the new solver:
ikHandle -sol simpleSolverNode -sj joint1 -ee joint2
Moving the handle in the x-y plane will rotate the joint.
ikHandle -q -sol handleName
Produces dependency graph node simpleSpring
This node is an example of a spring node that calculates the spring behavior that Maya will use in a simulation.
There is an example MEL script “simpleSpring.mel” that shows how to create the node and appropriate connections to correctly establish a user defined spring law.
Produces dependency graph node sine
This plug-in is a simpler version of circleNode. It takes a single input value and outputs the sine of this multiplied by 10. It’s a simple example of creating a procedural animation. Below are a simple set of commands to attach this node to a sphere:
sphere -n sphere;
createNode sine -n sine1;
connectAttr sine1.output sphere.tx;
connectAttr time1.outTime sine1.input;
Once this is done, as the time changes the sphere will roughly move along the X axis in a periodic manner.
(Roughly because the input is normally 1 through 48 and the compute method of the sine node just takes the sine of the input, which should be radians.)
Produces MEL command spiralAnimCurve
This plug-in attaches anim curves to the X, Y, and Z translation attributes of the selected objects, and then animates the object along a spiral path. This is a good example of attaching a anim curve to the attributes of an object.
To use it, select an object (or objects) in the Maya perspective window, the execute the command “spiralAnimCurve”. Next click on the “play” button on the time slider at the bottom right of the screen. The selected objects will move in a spiral as the animation plays.
The splitUV command unshares or “splits” the selected UVs of a polygonal mesh. It is also a good example of how to write poly operation nodes that properly deal with history, tweaks, etc. For a thorough explanation of creating this command, refer to the splitUVCmd example in the “Working with the polyAPI” chapter of the <PalItal>Maya Developer’s Tool Kit.
The surfaceBumpManip is a manipulator plug-in that demonstrates how the pointOnSurface base manipulator can be used. This example produces the MEL command surfaceBumpContext to create the tool context for this manipulator.
To create the tool button for the plug-in, create a new shelf named “Shelf1” and execute the following MEL commands to create the tool button in this shelf:
surfaceBumpContext;
setParent Shelf1;
toolButton -cl toolCluster -t surfaceBumpContext1 -i1 "moveManip.xpm";
To use the manipulator, create a NURBS sphere and select the tool button. A manipulator should appear on the surface of the sphere. Moving the manipulator over the surface of the sphere will cause the surface to be modified near the manipulator by moving a CV out along the sphere normal.
Produces MEL command surfaceCreate
This plug-in creates a NURBS surface by supplying its own CVs and knots. To use it, just enter the command “surfaceCreate”.
Produces MEL command surfaceTwist
To use this command, you must first create and select a number of NURBS surfaces or polygons (a fun surface to twist is the one created by the surfaceCreateCmd command). Then enter the command “surfaceTwist” and all selected surfaces will be twisted around the y-axis.
This command demonstrates how to access and modify the CVs of a NURBS surface or the vertices of a polygon.
Produces dependency graph node sweptEmitter
This node is an example of a particle emitter that emits in a direction from a curve or surface.
There is an example MEL script “sweptEmitter.mel” that shows how to create the node and appropriate connections to correctly establish a user defined particle emitter.
Produces dependency graph nodes swissArmyLocator and swissArmyLocatorManip
This is a contrived example plug-in that attaches one of every kind of user-defined manipulator to a node. It is a good example of the source code required to create each user-defined manipulator. To use it, issue the command:
createNode swissArmyLocator
then click the showManip icon on the toolbar. The locator on the screen will be overlaid with one of every kind of user-defined manipulator.
Produces MEL command threadTestCmd.
This example demonstrates how to use the MThreadPool class to calculate primes using a threaded algorithm. For comparison purposes, a serial calculation of primes is also provided. To use this plug-in, first load it and then execute the following:
threadTestCmd 1 10000
Where argument 1 and argument 2 specify the start and end ranges of the prime search.
Produces MEL command threadTestWithLocksCmd.
Very similar to the threadTestCmd but incorporates thread spin locking with the MSpinLock class. To use this plug-in, first load it and then execute the following:
threadTestWithLocksCmd 100000
Produces dependency graph node torusField
This node is an example of a dynamics field that creates a attract-repel field between itself and a distance.
There is an example MEL script “torusField.mel” that shows how to create the node and appropriate connections to correctly establish a user defined field.
Produces dependency graph node transCircle
This plug-in demonstrates how to use an attribute that contains multiple values (a compound attribute). The translate attribute of the transform node is used which is composed of the elements: translateX, translateY, and translateZ, all of which are communicated over a single dependency graph connection.
To use this node, execute the MEL command “transCircleNode.mel” that contains the following commands:
createNode transCircle -n circleNode1;
sphere -n sphere1 -r 1;
sphere -n sphere2 -r 2;
connectAttr sphere2.translate circleNode1.inputTranslate;
connectAttr circleNode1.outputTranslate sphere1.translate;
connectAttr time1.outTime circleNode1.input;
This creates two spheres and a transCircle node. The translate attribute of sphere1 is connected to the input of the transCircle node, and its output is connected to the translate attribute of sphere2.
If the play button is pressed, the second sphere will circle around the first. If the first sphere is moved, the second will also move such that the first sphere always remains at the center of the circle.
This plug-in also comes with a sample of an attribute editor template. This example suppresses the display of all attributes except scale and frames, and also provides an extra quick set control for the scale attribute that uses radio buttons to update the attribute value.
Produces MEL command translate
This plug-in translates the CVs of selected curves, surfaces, or polygonal objects by a user specified amount. It is a good example of manipulating CVs on these three data types. To use it, select an object then execute “translate 1.0 2.0 3.0” in the command window.
It should be noted that this command will not work on NURBS primitives that have construction history. The history forces the CVs to return to their original position immediately after the translate command has moved them. To allow the translate command to work on such surfaces, you must either delete the construction history on the object ( Edit > Delete by Type > Construction History), or open the Tool Settings window before creating the surface and turn off History.
This plug-in example demonstrates how to listen to undo and redo message events using the MEventMessage class.
undoRedoMsg add;
undoRedoMsg remove;
The add argument causes listening to undo/redo to be turned on. The remove argument causes undo/redo listening to be removed.
This example plug-in produces the MEL command “userMessage” that demonstrates how a plug-in can use user-defined messages.
Here is an example of how the command can be used:
// Register a user-defined event named “test”. The plug-in will internally register
// callbacks for the event.
userMessage -r test;
// Post to the user-defined event. The plug-in prints info messages from the callbacks.
userMessage -p test;
// Entered userMessage::userCallback2
// Received data: Sample Client Data (an MString object)
// Entered userMessage::userCallback1
// Received data: Sample Client Data (an MString object)
// Deregister the user-defined event
userMessage -d test;
// Trying to post a message after the event has been removed will fail.
userMessage -p test;
Produces a command viewCallbackTest.
This plug-in installs the pre and post rendering callbacks of MUiMessage. As a simple demonstration, a modelling view can be inverted or shaded based on depth. In the depth shaded mode, the closer objects are lighter in color. Below is some sample MEL for using this plug-in once it is loaded.
// Invert mode
viewCallbackTest -bo "invert" `getPanel -withFocus`;
// Depth mode
viewCallbackTest -bo "showDepth" `getPanel -withFocus`;
Limitations: screen does not refresh right after plug-in executes.
Produces MEL command viewCapture
This plug-in uses OpenGL to capture the current 3D view and write it into a PPM file. To use it, give it a filename as an argument into which the PPM image of the current view should be written.
Demonstrates the use of the MFnVolumeLight class. This example creates a volume light then queries and sets a number of its attributes.
volumeLight;
volumeLight -a $arc -c $coneEndRadius -e $emitAmbient;
This example demonstrates how to work with multi of multi attributes as found in deformer nodes. A weightList node is created by the plug-in. The ::compute() method of the plug-in demonstrates how to manipulate multi of multi attributes while ::initialize() shows how to create the attribute. The plug-in can be demonstrated with the following once the plug-in is loaded:
createNode weightList;
setAttr weightList1.bias 1;
getAttr -type weightList1.weightsList;
// check result in shell window
This simple command prints a message to standard out describing the API types of Maya objects. If no Maya objects are passed to the command then it lists the types of all of the currently selected objects.
For each object, the following information will be printed:
This list is essentially the class derivation list containing all parent classes of this object.
whatis nurbsSphereShape1
results in the following output:
Name: nurbsSphereShape1
Type: kNurbsSurface
Function Sets: kBase, kNamedObject, kDependencyNode, kDagNode, kShape, kGeometric, kSurface, kNurbsSurface, kNurbsSurfaceGeom
This is a good example of taking Maya objects as arguments to a command.
Produces dependency graph node yTwist
This plug-in demonstrates how to create a user-defined deformer. A deformer is a node which takes any number of input geometries, deforms them, and places the output into the output geometry attribute. This example plug-in defines a new deformer node that twists the deformed vertices of the input around the y-axis.
Produces MEL command zoomCamera
This is a simple plug-in which divides the horizontal field of view for the current active camera by 2.0. It is a good example of getting the current active view, and of modifying the camera. To use this plug-in, first create a camera by selecting the menu item Create > Cameras > Camera, then position the camera to “look at” an object in the scene. Then, either,
You will now be looking through the camera. Execute “zoomCamera” in the command window, and your view through the camera will zoom-in by a factor of 2.
Produces MEL command listParticleInstances.
This plug-in demonstrates how to use the MFnInstancer class and the MItInstancer class to enumerate particle instances in a scene. If one or more instancer nodes are selected when the command is invoked, MFnInstancer will be used to enumerate each instancer's instances, exercising both the instancesForParticle() and allInstances() methods. If no instancers are selected, then MItInstancer is used to iterate through all the particle instances in the scene.
Produces dependency node genericAttributeNode.
This plug-in demonstrates how to create a MPxNode that contains generic attributes. Several generic attributes are added to the node and the compute method() sets its result based on a controlling type attribute.
Produces dependency node curvedArrows.
A simple locator node that demonstrates the transparency flag on locator nodes. Transparent objects must be drawn in a special draw pass by Maya because the rendered output is dependent on the draw order of objects. The isTransparent() method tells the API that this locator should be placed in this special transparency queue for rendering.
API programmers can see the effect of this draw operation by toggling the 'transparencySort' attribute on this node. When the attribute is set to true, the locator will be drawn in sorted order with all transparent objects in the scene. When it is set to false it will be drawn with all opaque objects in the scene.
This also demonstrates the related drawLast() flag. This flag allows a locator to be specified as the last object to be drawn in a given refresh pass. This flag serves a very specialized purpose, but it can also be important when using the isTransparent flag in crucial situations.
Produces dependency node customImagePlane.
Demonstrates how to create your own custom image plane based on Maya's internal image plane classes. This allows API users to override the default Maya image plane behavior. This class is similar to typical API nodes in that it can have a compute method and can contain static attributes added by the API user. This example class overrides the default image plane behavior and allows users to add transparency to an image plane using the transparency attribute on the node. Note, this code also illustrates how to use MImage to control the floating point depth buffer. When useDepthMap is set to true, depth is added to the image such that half of the image is at the near clip plane and the remaining half is at the far clip plane.
Once the image plane node has been created, you must attach it to the camera shape that is displaying the node. Image planes are attached to cameras via the imagePlane message attribute on the camera shape. To attach this example image plane you should connect the image plane's message attribute to the cameraShapes imagePlane attribute. The imagePlane attribute is a multi attribute and can hold references to multiple image planes.
string $imageP = `createNode customImagePlane`;
connectAttr -f ($imageP + ".message") "perspShape.imagePlane[0]"
Produces dependency node stringFormat.
This plug-in is an example of a user-defined dependency graph node. It takes several numbers as input, as well as a format string. It generates a formatted string as an output.
All occurrences of ^[0-9][dft] are replaced with the corresponding input parameter using the specified format.
For example, the string "format ^1f ^2d ^0t end format", using the array {2.3, 3.4, 4.5} as an input will generate the result "format 3.4 4 00:00:02 end format"
Produces dependency node particleAttr.
The particleAttrNode is an example node that extends the MPxParticleAttributeMapperNode type. These nodes allow us to define custom nodes to map per-particle attribute data to a particle shape.
In this particular example, we have defined two operations:
The compute2DTexture() replicates the internal behavior of Maya's internal 'arrayMapper' node at the API level. Given an input texture node and a U/V coordinate per particle input, this node will evaluate the texture at the given coordinates and map the result back to the outColorPP or outValuePP attributes. See the method description for compute2DTexture() for details on how to setup a proper attribute mapping graph.
The computeMesh() is a user-defined operation. It is called when the 'computeNode' attribute is connected to a polygonal mesh. Given a particle count, it then maps the object space vertex positions of the mesh to a user-defined 'outPositions' vector attribute. This 'outPositions' attribute can then be connected to drive one of the shape’s vector typed, per-particle attribute. In the given example, the particle shape's 'rampPosition' attribute is being driven. For further details, see the computeMesh() method description for information on how to setup this example.
Produces dependency node hwManagedTextureShader
Demonstrates how to use texture caching in a hardware shader efficiently. The supportsBatching() method is used in this example.
D3DViewportRenderer (Windows only)
This plug-in demonstrates how to use Direct3D as the renderer of a viewport. It is a simple example that renders a bounding box for each polygonal surface in the Maya scene.
Produces MEL command customSourceFile
This plug-in is an example of a user-defined MPxMayaAsciiFilter. It allows users to segment scenes into files containing various types of nodes. Users can specify which node types are exported by using the "includeType" and "excludeType" options in the file command. For example, the following would save only renderLayer nodes:
mel: file -rename "myLayerData";
mel: file -type "filteredAsciiFile";
mel: file -save -options ";includeType kRenderLayer;";
In addition, the type of connectAttrs written in the ASCII file are determined by the node types that are exported. If the source node in the connectAttr is to be output, then the connectAttr is written. In addition to allowing scenes to be segmented, this plug-in also allows ASCII files to write a line which will source other ASCII files. Use this plug-in to allow a single master file source in all of the different files containing scene segments. This is also controlled via the file command's options. The following commands illustrate how to source in the render layer segment saved in the above example:
mel: file -rename "myMasterFile";
mel: file -save -options ";excludeType kRenderLayer; sourceFile myLayerData.faf"
In the case above, the excludeType argument is used to ensure that no render layer information is output in myMasterFile. The sourceFile option outputs the following line in myMasterFile.faf:
customSourceFile -fileName "myLayerData.faf";
When this line is parsed as myMasterFile.faf is loaded, the customSourceFile command, which this plug-in also contains, is executed. It simply sources myLayerData.faf, first prepending the myMasterFile.faf's path.
Simple Image File plug-in. This plug-in registers a new image file format against file extension .moo. Loading any .moo image file will produce a procedurally generated color spectrum, including values outside of 0 to 1.