Maya Plug-in Development Setup for MS Visual Studio

This tutorial explains a little background on Alias|Wavefront Maya plug-ins, VC++ development setup, a little example and how to run it. This Tutorial will be review to a 2006 Maya 8 version + a "Makefile" for compiling you Maya Plug-ins under Linux, Unix etc.

Author : Cesboa
Date : 11. April - 2003
From : Wouz Production ( www.wouz.dk )

Note
Sins this is my first tutorial ever and English isn’t my native language you have to put up with lack of fancy words and “educational” skills. You need no knowledge of programming or Maya to complete this tutorial but it makes a whole lot easier.

Background
Alias|Wavefront’s Maya is one of the greatest and most complex computer programs ever made. This 3D software program has the ability to be viciously strong as a “off the shelf” tool and even stronger when you need to develop your own features.

Even though Maya has many features as default it can’t do everything and that is what you have to compensate with if you want to “bend” Maya in your direction! From my point of view there are two scenarios where developing your own functionality in Maya comes in hands:

1. Automate and simplify tasks: Advanced Macros, Your own GUI, alternating existing Objects etc.
2. Add new features that aren’t incorporated: Create new File formats, Create new object types and behaviours for them, new dynamics and animations components etc

A good example on how strong the possibilities are is that plug-ins like Fur, Live and Cloth in Maya Unlimited is made via the Mel/API.

There are two ways to develop your own stuff I Maya; via the Mel (Maya Embedded Language) and through the Maya API (Application Programmer Interface). Mel is Maya’s own scripting language/engine in which you can reach almost every function in Maya. The Maya API gives you almost unlimited access to the Maya Interface and because C++ is the language to do so it is up to ten times faster than Mel and you have access to many 3. party libraries and packages not included in Maya API.

Sins this tutorial is about Plug-in development via the Maya C++ API there will be no further explanation of the Mel language besides as far as I know if you want to create GUI via the Maya Interface you have to use Mel.

The Maya API gives access to the internal Maya interface with the following libraries:
(copy-paste from Maya Development Toolkit)

OpenMaya
Contains fundamental classes for defining nodes and commands and for assembling them into a plug-in.

OpenMayaUI
Contains classes necessary for creating new user interface elements such as manipulators, contexts, and locators.

OpenMayaAnim
Contains classes for animation, including deformers and inverse kinematics.

OpenMayaFX
Contains classes for dynamics.

OpenMayaRender
Contains classes for performing rendering functions.

VC++ Development Setup
Because I using use Microsoft Visual C++ as my Maya plug-in development environment and Maya for Win32 platform I have only included environment settings for this IDE application and Operative System. On the other hand you could adapt the settings to other IDE tools (like CodeWarrior) and other platform Maya is running on (including Irix, OS X, Redhat Linux).

Sins I only have tried this for Maya 4.0/4.5 and Microsoft VC++ 6.0 (SP5) I can’t bounce for any thing else. It is crucial that you do every step!! If you have created DLL for before this shouldn’t be to hard ;-)

1. Create a Project for your plug-in
1. Open Microsoft VC++
2. Choose File -> New
3. Choose the Projects tab
4. Type a Project Name
5. Enter the directory to your plug-in location directory.
6. Double-click the Win32 Dynamic-Link Library
7. Select “An empty DLL Project” in the “Win32 Dynamic-Link Library – Step 1 of 1” box
8. Select Finish.
9. Select OK in the “New Project Information” box.

2. Add a new Cpp file to your project
1. From Microsoft VC++ choose Project -> Add To Project -> Files.
2. Enter a File name
3. Double-click “C++ Source File”
4. If you need additional files loop step 1-2 and select the file(s) needed for your plug-in.

3. Define and include Maya API directory to your project setting
1. From Microsoft VC++ choose Project -> Settings
2. Select “All Configurations” in the “Settings For” combo box
3. Choose the C/C++ tab
4. Select “Preprocessor” in the “Category” combo box
5. Add “NT_PLUGIN” to the “Preprocessor definitions” list. (Use comma to separate)
6. Add your Maya include directory: “C:Program FilesAliasWavefrontMaya4.5include”*
7. Click OK, your changes are now saved to the project settings.

4. Additional Maya API libraries to your project settings
1. From Microsoft VC++ choose Project -> Settings
2. Select “All Configurations” in the “Settings For” combo box
3. Choose the Link tab
4. Select “General” in the “Category” combo box
5. Add the Maya API libraries: “Foundation.lib” and “OpenMaya.lib” in the “Object/library module” Use space to separate the libs.
6. Select “Input” in the Category” combo box
7. Add “C:Program FilesAliasWavefrontMaya4.5lib”* to the “Additional library path.
8. Click OK, your changes are now saved to the project settings.

5. Configure the Run-time library settings
1. From Microsoft VC++ choose Project -> Settings
2. Select “All Configurations” in the “Settings For” combo box
3. Choose the C/C++ tab
4. Select “Code Generation” in the “Category” combo box
5. Select “Multithreaded DLL” in the “Use run-time library” combo box
6. Click OK, your changes are now saved to the project settings.

6. Configure the export plug-in external entry point(s)
1. From Microsoft VC++ choose Project -> Settings
2. Select “Win32 Release” in the “Settings For” combo box
3. Choose the Link tab
4. In the “Project Options” text area box scroll down to the bottom and append “/export:initializePlugin /export:uninitializePlugin”
5. Select “Win32 Debug” in the “Settings For” combo box
6. In the “Project Options” text area box scroll down to the bottom and append “/export:initializePlugin /export:uninitializePlugin”
7. Click OK, your changes are now saved to the project settings.

7. Change plug-in extensions from mll to dll (optional)
This is not vital but if you don’t do it you have to change the file extension every time you compile your project
1. From Microsoft VC++ choose Project -> Settings
2. Select “Win32 Release” in the “Settings For” combo box
3. Choose the Link tab
4. Select “General” in the “Category” combo box
5. Change the extions from .dll to .mll in the “Output file name” text box.
6. Select “Win32 Debug” in the “Settings For” combo box
7. Change the extions from .dll to .mll in the “Output file name” text box.
8. Click OK, your changes are now saved to the project settings.

When all this is done save your workspace (file->save workspace) and select either Release or Debug under Build->Set Active Configuration. Without closing the workspace project you just created go on to the next section.

8. Debugging (optional)
Debugging is not vital for making Maya Plug-ins but if you have coded before you know how important to have good debugging possibilities, without debugging it’s very difficult to find errors in your code.

1. Make sure you don’t have Maya open
2. From Microsoft VC++ open Project -> Settings
3. Select “Win32 Debug” in the “Settings For” combo box
4. Select the debug tab
5. Select the arrow button located to the right of the “Executable for debug session” and click on browse
6. Locate your maya.exe file on your harddrive: C:Program FilesAliasWavefrontMaya4.5binmaya.exe”* and double click it
7. Select “Additional DLLs” in the “Category” combo box
8. Click in the “Modules” list (an editable text field should appear)
9. Select the “…” button in the newly created text field
10. Select Browse
11. Locate your .mll file in your project debug directory (you may have to set the “File of type” to “All Files(*.*)” and double click it

You can now debug in Microsoft Visual C++ but you need to have a deeper knowledge of debugging before you can use this. This is not covert in this tutorial.

Your First Maya Plug-in
Copy-Paste this code to your C++ Source file

#include
DeclareSimpleCommand( whatzUp, "Maya User", "4.5");

MStatus whatzUp::doIt( const MArgList& ) {
printf("Whatz Up...n");
return MS::kSuccess;
};

Try building/compiling your project. Build -> Build “your project name”. If the compiler throws no errors you are newly born Maya Plug-in programmer. If you want to jump over this step you can download the workspace file at the bottom of this tutorial.

Running the Plug-in in Maya
After you build your project you should find a .mll file under either the debug or release directory depending on which you compiled. Copy this file to the Maya Plug-in directory “C:Program FilesAliasWavefrontMaya4.5binplug-ins”*. You can use the MAYA_PLUG_IN_PATH environment variable to locate an external plug-in directory but this will be covered in a later tutorial on “User Preferences, Essential settings and environment variables”.

From inside Maya load a plug-in use the following Mel command in the commandline at the bottom of the screen (remember all commands used in the commandline are casesensitive):

loadPlugin “plugin_file_name”;

The plugin_file_name represent the .mll file you copied from your VC++ project directory, as default it should be the workspace name + .mll. You can also load a plug-in via the Window->Settings/Preferences->Plug-in Manager, here you can also unload and browse for a plug-in from outside your Maya plug-in directory (fixed path).

You can also load a fixed path in your loadPlugin command (use frontslash “/” instead of backslash “” – Maya originated from UNIX/IRIX). To load a plug-in in a fixed path using the following Mel command:

loadPlugin “c:/maya_plugin/plugin_file_name”;

If you pasted the code from above you can fire off the command:

whatzUp;

An output window will open with the words “What Up…” in it. There you go!! You have made contact with your own plug-in!

It’s easy to unload a plug-in again just use the following Mel command (doesn’t matter if it’s loaded from the plug-in directory or from a fixed path):

unloadPlugin “plugin_file_name”;

Final Words
This completes this tutorial! I hoped you enjoyed it. It’s not very complex but it is the essential part in becoming a Maya Plug-in programmer.

Microsoft VC++ Workspace (10 kilobyte zip)

Other Maya Plug-in development resources
Maya Library files on “Mel Commands” and “Developer’s toolkit”. (“Start Maya”->Help ->Library)

Complete Maya Programming - By David a. D. Gould (ISBN: 1-55860-835-4)

Alias|Wavefront Maya API “White Paper”

* If Maya isn’t installed you have to redirect to the right one:
"Drive Letter:< ><><>"

- 28.10.2006. 02:41 | Author: Cesboa