Maya - API samples

Here you can download a sample project which demonstrates the basic features of the API. To build the C++ project, you will need Visual Studio 2008 on Windows, XCode 4 or above on OS X and scons on Linux. The Visual Studio and XCode projects contain Debug and Release configurations for each supported Maya version (2008-2012). To specify the configuration for the Linux build, set the environment variable BUILD_CONFIG to the string Debug or Release followed by the desired Maya version number before running scons, e.g.:

user@host:~/MaxwellMayaAPISample$ BUILD_CONFIG='Debug2012' scons

If BUILD_CONFIG is not set, scons will try to build the Release configuration for Maya 2012.

The project will build a plug-in called MaxwellMayaAPISample. Load it into Maya using the plug-in manager, then open the file cppsample.ma which is provided in the archive. You will see a scene containing a plane, a sphere, three boxes and a locator:

The boxes and locator are set as custom objects. The sample plug-in will replace the first box with a sphere, the second box with a particle system, the third box with a sphere with two instances and the locator with an instance of the blue sphere at the top:

The first box uses the custom export command maxwellAPISample -exportMesh, which ends up calling the method MaxwellMayaAPISample::ExportMesh. This demonstrates the use of the  MaxwellMayaAPI::CreateMesh method and MaxwellMayaMesh interface to create a sphere. The resulting object is passed to MaxwellMayaAPI::SetCurrentShapeOutput, so that Maxwell applies the material from the original box to the sphere created by the plug-in. The vertex positions are specified in centimeters, but the plug-in performs the correct unit conversion because needsScaling was set to true.

The export command for the second box is maxwellAPISample -exportExtension and the corresponding method is ExportExtension. This creates a procedural geometry object using the MaxwellParticles extension and passes a few random particles to it. As in the example above, Maxwell handles transformations and material assignment.

The third box uses maxwellAPISample -exportInstancer which corresponds to ExportInstancer. The method first creates a sphere, then makes two instances of that sphere. Since more than one object is created, SetCurrentShapeOutput cannot be used, so we use  MaxwellMayaAPI::GetCurrentShapeShaders,  MaxwellMayaAPI::TranslateMaterial and MaxwellMayaShape::SetMaterial to retrieve the shader assigned to the Maya object, convert it to a Maxwell material and assign it to the sphere. If motion blur is on, the method also makes the first instance move 2 Maya units along positive X, and the second instance describe a 90 degree arc around the origin. The motion is exported at the same time the objects are created, so the method does nothing when called in the ExporterState_ProcessingMotion state.

Finally, the locator uses maxwellAPISample -exportSecondPhase which calls ExportSecondPhaseObj. The goal is to make an instance of the sphere at the top. In order to make sure that the sphere has already been exported when our export code runs, we've marked the locator to be processed in the second export phase by adding the maxwellCustomExportPhase attribute to the shape node and setting it to 1. The export code creates the instance when called in the ExporterState_ProcessingShapes state and it also makes an emitter material which is applied to the object. During the motion steps, the plug-in retrieves the transformation of the node and offsets it by 1 unit along positive X, so that the object renders 1 cm to the right of where the locator originally was. Since we haven't used SetCurrentShapeOutput in the shape processing stage, we cannot call MaxwellMayaAPI::GetCurrentMotionShape to obtain a handle to the object during motion processing. Instead, we use MaxwellMayaAPI::FindShape to locate the object by name.

The plug-in also installs hooks for all the available export events. The hooks don't perform any modifications on the Maxwell scene, they just print a message to show that they are called.

The Python sample is provided in the MaxwellMayaPySample.py file and has identical functionality to the C++ sample. To load the sample code, you will need to to something like this in a Python tab of the Maya script editor:

import sys
sys.path.append(r'/path/to/extracted/sample')
import MaxwellMayaPySample

After running this, open the file pythonsample.ma from the sample archive and you should see the same effects as in the C++ sample.