Maya - Exporter states and callbacks in detail

Owned by Systems Next Limit (Unlicensed)
22 Sept, 2016
3 min read

When exporting a scene to Maxwell, the plug-in passes through the following states in order:

  • Pre-scene: the renderable camera and exposure parameters have been determined and the Maya time is set to the shutter open time, but no objects have been processed yet. Callbacks of type ExportCallbackType_BeforeScene are run at this stage.
  • Shape processing: the shapes in the Maya scenes are processed and supported objects are exported. The custom export commands are called for objects which define them. This process happens in two phases, as described in the introduction. The render options and lighting environment settings are exported before any shapes are processed.
  • Motion processing: if motion blur is on, the exporter will advance the Maya time for each sub-step and export object motion. In the last sub-step (when the shutter closes) it also exports the vertex positions and normals for all meshes, if deformation blur is on. Custom export commands will be called at each step, so it's important to use GetExporterState to distinguish between this and the shape processing step (you do not want to create your custom objects again during motion processing). Callbacks of type ExportCallbackType_BeforeSubstep and ExportCallbackType_AfterSubstep are run before and after going through the shape list at each step, respectively.
  • Post-scene: all the objects have been processed, but the scene file hasn't been written to disk yet. Callbacks of type ExportCallbackType_AfterScene are executed now.

You are not forced to follow these steps precisely in your code. For example, if you can determine the motion and deformation of your object in the shape processing stage, you can set them up at the same time you create the object, and then do nothing when you are called during motion processing. You can create objects at any time, though when debug messages are on, the API will print a warning if you create objects during motion processing, since that usually indicates a problem in the code (it will still work, so you can ignore the warning if you really meant to do that).

If you are only interested in creating the geometry for an object, you can let the Maxwell plug-in handle material translation, motion and other details. To do this, create the object during shape processing and pass it to SetCurrentShapeOutput. Depending on the processing flags you specify, the Maxwell plug-in can do the following:

  • ProcessingFlag_Material: the shader assigned to the object will be translated into a Maxwell material and applied on the object. If the shader cannot be translated or does not exist, an error material is used (diffuse red).
  • ProcessingFlag_InitialTransform: the transformation of the object at the shutter open time is computed and applied. If ProcessingFlag_UnitConversion is also specified, the matrix will contain scaling which transforms the object from Maya work units into meters, since Maxwell always works in meters. This scaling factor will also include the global scaling set in the Maxwell render options.
  • ProcessingFlag_Motion: if motion blur is on, the transformation at each motion substep is computed and applied. ProcessingFlag_UnitConversion also affects these matrices. Your export function will be called after the transformation has been set at each substep, in case you want to make modifications. During motion processing you will be able to call GetCurrentMotionShape to obtain the pointer to the object you have previously created. If you do not specify this flag, Maxwell will not export any motion information and your code will not be called during motion processing, so if you still want motion blur, you will have to set it up during shape creation.
  • ProcessingFlag_RenderFlags: the render flags and object ID color will be set. The code looks for the mxHideToCamera, mxHideToSecRays, mxHideToGI, mxHideToZClip, mxSpecifyObjIdColor and mxObjIdColor attributes on the Maya shape node to determine this information. The flags default to false if the attributes are not present.
  • ProcessingFlag_Instances: If there are Maya instances of the shape node in the scene, the plug-in will automatically create Maxwell instances of the object you have created. Your export code will not be called for those instances. The exception is when the object you have created is already an instance; in that case, Maxwell calls your export code for the other Maya instances too and does not try to handle them automatically.

If you do not call SetCurrentShapeOutput, the plug-in won't apply any processing to the objects you create. You will be responsible for setting up materials, transformations and flags. Your export code will still be called at each substep during motion processing, but GetCurrentMotionShape will return NULL, so if you need to perform actions at that stage, you will have to keep track of the created object(s) yourself.

Note that because all the callbacks are executed after the renderable camera has been determined, you cannot change the motion parameters such as shutter open time or motion interval length. You can create or edit cameras at any time and set the shutter speed you want, but the new setting will only affect the image exposure, not the motion blur length.