Introduction to the Maya C++ API Brent Haley The Ohio State University

Programming for Maya The Book (Complete Maya Programming) Maya Help (Developer Resources, Commands, Nodes, API Classes) MEL Scripts –Can be really easy to test –Can see how Maya does its own with echo –Hard to get complex data structures –Slower, due to interpretation C++ API Plug-ins –Very confusing at first, hard to find help / concise examples –Faster, due to machine language

Topics Day 1 –Plug-in Introduction –How to Create a MLL –Command Basics –Node Basics –Warnings Day 2 –VC++ Examples

Simple Scene in Maya 3D View, Hypergraph, and Outliner Using built in functionality Mocap driven animation

Nodes, Plugs, and Attributes Note: I’m zooming in on LilyGeometry to get the 2 nd image

Turning Character into Smoke Create a built in fluid container Have the vertices on Lily’s surface generate density values Requires a way to link Lily’s output geometry to the fluid container’s density values in the hypergraph Note: Lily’s input geometry is driven by her original mesh + skeletal rig and smooth skin binding

Using a Plug-in (1) Add new nodes and commands to Maya Requires one to load the plug-in

Using a Plug-in (2) Select the required components Run the command

Tweak the SmokeNode1 Attributes

Topics Day 1 –Plug-in Introduction –How to Create a MLL –Command Basics –Node Basics –Warnings Day 2 –VC++ Examples

Create a Visual C++ Project The project creation wizard may not be installed (or doesn’t work correctly) Make a Win32Project Under application settings, choose dll and empty project

Open the Project Properties Note: make sure you apply the settings on the next slide to both the debug and release versions (all configs should work).

Set the Project Properties C/C++ -> General -> Additional Include Directories: C:\Program Files\Alias\Maya8.0\include C/C++ -> Preprocessor -> Preprocessor Definitions: WIN32;NDEBUG;_WINDOWS;NT_PLUGIN Linker -> General -> Output File: change the.dll to.mll Linker-> General -> Additional Libarary: C:\Program Files\Alias\Maya8.0\lib Linker -> Input -> Additional Dependencies: opengl32.lib Foundation.lib OpenMaya.lib OpenMayaUI.lib OpenMayaAnim.lib OpenMayaFX.lib OpenMayaRender.lib Linker -> CommandLine -> Additional Options: /export:initializePlugin /export:uninitializePlugin

Required Code (main.cpp) #include MStatus initializePlugin(MObject obj) { MStatus stat; MFnPlugin plugin(obj, "Brent Haley", “1.0", “8.0"); return(stat); } MStatus unintializePlugin(MObject obj) { MStatus stat; MFnPlugin plugin(obj); return(stat); } Initialize plugin procedure is an entry point that gets called when you load your plugin in Maya Uninitialize plugin procedure is an entry point that gets called when you unload your plugin from Maya Remember these were specified under the project settings Through these entry points we tell Maya what Nodes and Commands our Plugin has

Topics Day 1 –Plug-in Introduction –How to Create a MLL –Command Basics –Node Basics –Warnings Day 2 –VC++ Examples

Example Command Specification class GeomToDensityCmd: public MPxCommand { public: //creator function static void *creator(); //command execution functions virtual MStatus doIt(const MArgList &args); virtual MStatus redoIt(); virtual MStatus undoIt(); virtual bool isUndoable() const; private: //graph modifier, used to support undo and redo MDagModifier dagMod; }; Implementation (except doIt) void *GeomToDensityCmd::creator() { return new GeomToDensityCm; } MStatus GeomToDensityCmd::redoIt() { //commit the work set in doIt MStatus stat = dagMod.doIt(); return(stat); } MStatus GeomToDensityCmd::undoIt() { //erase any work set in doIt MStatus stat = dagMod.undoIt(); return(stat); } bool GeomToDensityCmd::isUndoable() const {return(true);}

doIt Where the actual work is done Changes made to the graph Get nodes through selection Get data through those nodes “plugs” Be careful not to setup a cyclic graph See day 2 VC++ examples

(De)Register the Command Register commands in the initializePlugin procedure (from the required bit of code) stat = plugin.registerCommand( “geom2smoke", GeomToDensityCmd::creator); if (!stat) MGlobal::displayError("register MudBoxCommand failed"); Deregister commands in the unitializePlugin procedure stat = plugin.deregisterCommand(“geom2smoke"); if (!stat) MGlobal::displayError("deregister MudBoxCommand failed");

Topics Day 1 –Plug-in Introduction –How to Create a MLL –Command Basics –Node Basics –Warnings Day 2 –VC++ Examples

Example Node Specification class SmokeNode : public MPxNode { public: //identifier static MTypeId id; //attributes static MObject filterSize; … //creator function static void *creator(); //initializer for the node static MStatus initialize(); //computational function to do the real work virtual MStatus compute (const MPlug &plug, MDataBlock &data); private: … }; Implementation (no compute) void *SmokeNode::creator() {return new SmokeNode;} MStatus SmokeNode::initialize() { //create the attributes MFnNumericAttribute fsAttribute; filterSize = fsAttribute.create(“filterSize", “fs", MFnNumericData::kInt, 0);... //add the attributes to the node addAttribute(filterSize);... //specify attribute relations attributeAffects(filterSize,is2D);... //return without error return(MS::kSuccess); }

Compute Where the actual work is done MStatus SmokeNode::compute (const MPlug &plug, MDataBlock &data) { MStatus stat; //determine which output plug needs to be computed if (plug == is2D) { //get input data handles MDataHandle filterSizeData = data.inputValue(filterSize);... //turn input handles into data int fs = filterSizeData.asInt();... //get output data handles MDataHandle cfdData = data.outputValue(is2D); //turn output handles into data //set the output data and mark the plug cfdData.set(false); data.setClean(plug); } else //the plug is for an ancestor, return unknown stat = MS::kUnknownParameter; return(stat);}

(De)Register the Node Register nodes in the initializePlugin procedure stat = plugin.registerNode( “SmokeNode", SmokeNode::id, SmokeNode::creator, SmokeNode::initialize ); if (!stat) MGlobal::displayError("register SmokeNode failed"); Deregister nodes in the uninitializePlugin procedure stat = plugin.deregisterNode(SmokeNode::id); if (!stat) MGlobal::displayError("deregister SmokeNode failed");

Topics Day 1 –Plug-in Introduction –How to Create a MLL –Command Basics –Node Basics –Warnings Day 2 –VC++ Examples

Warnings (1) Node Ids need to be unique Bad: Good: In NodeA’s implementation: MTypeId NodeA::id(0x43215); In NodeB’s implementation: MTypeId NodeB::id(0x43215); In NodeA’s implementation: MTypeId NodeA::id(0x43215); In NodeB’s implementation: MTypeId NodeB::id(0x43216);

Warnings (2) Attribute affects shouldn’t be multi-level Create several nodes instead of trying to accomplish everything in a single node Bad: Good: In NodeA’s initialize() procedure: attributeAffects(X,Y); attributeAffects(Y,Z); In NodeA’s initialize() procedure: attributeAffects(X,Y); In NodeB’s initialize() procedure: attributeAffects(S,T); Where Y’s output is plugged into S’s input

Warnings (3) Don’t create cyclic structures in the hypergraph (can result in infinite loops)

Warnings (4) Per-frame node evaluation will occur in chunks if you use the rendering farm –Don’t rely on old values from the previous frame in your code since they may not exist –Alternatively (if you really need to), Explicitly step the time back for each frame Particles can be cached Dynamics can be forced to run from the start time to the current time before rendering each frame

Topics Day 1 –Plug-in Introduction –How to Create a MLL –Command Basics –Node Basics –Warnings Day 2 –VC++ Examples