MaxwellMayaAPI class

Description

This is the main interface to the Maxwell plug-in API. You obtain a pointer to this class by calling the GetMaxwellMayaAPI() function exported by the maxwell plug-in, or by using the convenience static method MaxwellMayaAPI::LoadAPI. For details on the loading process, see this page.

The interface allows you to:

• query the exporter state and scene settings.
• create new objects in the Maxwell scene.
• locate existing objects in the Maxwell scene.
• translate, create or find materials.
• add extension objects to the scene (Maxwell plug-ins which perform modifications at render time).
• list the available Maxwell extensions and their parameters.

Methods

void EnableDebugMessages(bool enable)

When the argument is true, the Maxwell plug-in will print API-related messages in the Maya script editor during export. Particularly, whenever an API method fails (from any of the API interface classes), a descriptive message is shown. The state of the debug messages can also be controlled by using the -setAPIDebug flag of the maxwell MEL command.

ExporterState GetExporterState() const

Returns the current state of the exporter as a member of the ExporterState enum. See this page for a discussion of the various states.

double GetScalingFactor() const

Returns the global scaling factor that the plug-in uses for converting between Maya work units and Maxwell units (which are always meters). Includes the global scale factor set in the Maxwell render options.

MotionBlurType GetGlobalMotionBlurType() const

Returns the motion blur type set in the Maxwell render options as a member of the MotionBlurType enum:

• MotionBlurType_None: motion blur is off. The exporter will never reach the ExporterState_ProcessingMotion state and the pre- and post-substep callbacks will not be executed.
• MotionBlurType_MovementOnly: the user has requested movement-only blur, without geometry deformation.
• MotionBlurType_Deformation: the user wants full motion blur, including deformation for the objects which support it.

You can still export motion and deformation regardless of this setting and Maxwell will render the blur for your objects, but you shouldn't, because you would be overriding the user setting.

MObject GetMaxwellRenderOptionsNode() const

Returns a MObject handle to the Maxwell render options dependency node. The type of this node is maxwellRenderOptions.

unsigned int GetNumMotionSteps() const

Returns the number of motion sub-steps set by the user in the Maxwell render options. In the motion processing stage, the exporter will advance the time once for each substep and call your export code.

When you create your objects, you can use a different number of substeps, but the plug-in will still call you once for each substep requested by the user. If you find it necessary to do this, you will probably have to implement your own way of sampling the motion at each substep and ignore the plug-in when it calls you in the motion processing stage.

double GetRenderCamExposure() const

Returns the exposure time of the render camera in seconds. This value does not change if you modify the renderable camera. It is extracted once at the start of the export process and used for determining the length of the motion for motion blur.

double GetShutterOpenTime() const

Returns the Maya frame when the camera shutter opened. This can be a fractional value if the shutter open offset is not 0 or if the user is rendering a non-integer frame.

double GetShutterCloseTime() const

Returns the Maya frame when the camera shutter closes. This is most likely a fractional value, because the exposure time is seldom equal to an entire frame.

double GetCurrentMotionTime() const

Returns the current time inside the movement interval as a fraction of the exposure time. The value ranges from 0.0 (shutter open) to 1.0 (shutter close). The value will be 0 when the exporter is in the shape processing state and will increase with 1.0/(GetNumMotionSteps() - 1) at each step during motion processing, reaching 1.0 in the last step.

bool GetCurrentShapePath(MDagPath& path) const

Retrieves a MDagPath object for the shape node currently being processed. The method will return false if called in an invalid state, e.g. when the exporter is not running. The Python version returns the MDagPath object directly and raises an exception if the state is invalid.

const MObjectArray& GetCurrentShapeShaders() const

Returns an array of MObject handles to the shaders which are assigned to the shape node being processed. The array can be empty if the object doesn't have any shaders applied in Maya. The Python version returns a Python list of MObject handles, not a MObjectArray instance.

bool GetCurrentShapeWorldMatrix(MMatrix& worldMatrix) const

Retrieves the world matrix for the shape node being processed. The C++ function returns false if called in an invalid state. The Python version returns the MMatrix object directly and raises an exception in case of error.

bool SetCurrentShapeOutput(MaxwellMayaShape* shape, unsigned int processingFlags)

Tells the Maxwell plug-in that the object produced by the custom export process is shape. The processingFlags argument controls what kind of processing is applied to the object. This method is discussed in detail on this page.

MaxwellMayaShape* GetCurrentMotionShape() const

If you have used SetCurrentShapeOutput during the shape processing stage, you can call this method during motion processing to retrieve a pointer to the object you have created. Otherwise, this method returns NULL in C++ or raises an exception in Python.

bool GetExportedShapeName(MString& name, const MDagPath& path) const

Formats the name of the Maya shape node represented by the given path in a way suitable for Maxwell. This usually retrieves the name of the transformation node above the shape, so that objects are exported as "pSphere1" instead of "pSphereShape1".

MaxwellMayaShape* FindShape(const MString& name) const

Tries to find an object by name in the Maxwell scene. The C++ version returns NULL if the object can't be found. The Python version raises an exception in that case.

MaxwellMayaCamera* CreateCamera(const MString& name, unsigned int numMotionSteps)

Creates a camera with the given name and number of motion steps. You are not forced to set the same number of motion steps as that used for object motion, but it is advisable to do so, otherwise differences in the interpolation process between the camera movement and the object movement can produce unwanted effects.

This method does not exist in Python. Use a regular constructor there to create the object, e.g. camera = maxwell.Camera(name, numMotionSteps).

MaxwellMayaCamera* FindCamera(const MString& name) const

Tries to locate the named camera in the Maxwell scene. The C++ version returns NULL if the camera can't be found, while the Python version raises an exception.

MaxwellMayaCamera* GetActiveCamera() const

Returns the renderable camera, or NULL if it can't be found or if the exporter is not running. The Python version raises an exception in case of error.

MaxwellMayaMaterial* TranslateMaterial(const MObject& materialNode)

Attempts to translate the given shader handle into a Maxwell material. The C++ call returns NULL if the translation fails, while the Python version raises an exception.

MaxwellMayaMaterial* FindMaterial(const MString& name) const

Locates a material in the exported Maxwell scene by name. The C++ call returns NULL if the material does not exist, while the Python version raises an exception.

MaxwellMayaReferencedMaterial* CreateReferencedMaterial(const MString& name)

Creates a referenced material with the given name, i.e. a material which will be loaded at render time from a specified MXM file. This method does not exist in Python, where you can construct the type directly, e.g. mat = maxwell.ReferencedMaterial(name).

MaxwellMayaEmbeddedMaterial* CreateEmbeddedMaterial(const MString& name)

Creates a Maxwell layered material with the given name. The settings for this kind of material are embedded in the exported scene. This method does not exist in Python, where you can construct the type directly, e.g. mat = maxwell.EmbeddedMaterial(name).

MaxwellMayaEmbeddedMaterial* LoadMaterial(const MString& fileName)

Creates an embedded material and loads its settings from the specified MXM file. This method can be called outside the export process if you need to parse MXM files. When the exporter is running, it is equivalent to using CreateEmbeddedMaterial and then calling LoadFromFile on the returned pointer. The method returns NULL in C++ if the file cannot be read, or raises an exception in Python.

MaxwellMayaExtensionParams* CreateExtensionParamBlock(const MString& extensionName)

Creates a parameter block for the given extension name. The returned interface can be used to specify the attributes for the extension and then to instantiate the extension object. The method can return NULL if the creation failed. This method does not exist in Python, where you can construct the type directly, e.g. params = maxwell.ExtensionParams(extensionName).

MaxwellMayaMesh* CreateMesh(const MString& name, unsigned int numVertices, unsigned int numNormals, unsigned int numTriangles, unsigned int numSteps)

Creates a triangle mesh object with the given name, vertex count, normal count, triangle count and number of vertex motion steps. The number of motion steps is used for deformation motion blur and can be 1 (no deformation, one position per vertex) or 2 (deformation enabled, two positions per vertex). Maxwell does not support more than 2 positions per vertex at the moment, and considers only linear motion when two positions are specified. If the creation fails, the method returns NULL. This method does not exist in Python, where you can construct the type directly, e.g. mesh = maxwell.Mesh(name, numVertices, numNormals, numTriangles, numSteps).

MaxwellMayaInstance* CreateInstance(const MString& name, const MaxwellMayaShape* originalShape)
MaxwellMayaInstance* CreateInstance(const MString& name, const MString& originalShapeName)

Creates an instance of an object. The object can either be specified as a shape pointer, or by name. The second form is equivalent to first calling FindShape to locate the object, then using the first form on the returned pointer. The methods return NULL if the instance creation fails. These functions don't exist in Python, where you can construct the type directly, e.g. inst = maxwell.Instance(shape). The constructor of the maxwell.Instance Python class accepts either a shape, corresponding to the first form of the method, or a string, corresponding to the second form.

MaxwellMayaExtensionShape* CreateExtensionShape(const MString& name, ExtensionShapeType type, const MaxwellMayaExtensionParams* params)

Creates an extension object of the given type and with the given parameters. The type parameter can be:

• ExtensionShapeType_Procedural: objects of this type compute ray intersections procedurally at render time. An example of this type is the MaxwellParticles extension which renders procedural spheres specified as a the center position and radius (which is more efficient in terms of execution speed and memory usage than using a triangle approximation of the spheres).
• ExtensionShapeType_Loader: objects of this type load or generate the geometry at render time from an external resource, creating triangles in the scene. Examples of this include the RFMeshes extension, which loads triangle meshes at render time from mesh files written by RealFlow; and MaxwellMesher, which generates triangle meshes from particles written by RealFlow.

The parameters of the extension object have to be set before making this call by using the methods in the MaxwellMayaExtensionParams interface. Setting parameters after the create call may not work, so it's safer to set everything first.

This method does not exist in Python, where you can construct the type directly by calling shape = maxwell.ExtensionShape(name, type, params).

MaxwellMayaMXSReference* CreateMXSReference(const MString& name, const MString& fileName)

Creates a MXS reference object, which loads the geometry at render time from the specified MXS file. This method does not exist in Python, where you can construct the type directly by calling mxsref = maxwell.MXSReference(name, fileName).

bool AddSceneModifierExtension(const MaxwellMayaExtensionParams* params)

Adds a scene modifier in the exported scene. Extensions of this type can perform changes to the scene at render time before the ray tracing process begins. The method returns false in C++ if it fails or raises an exception in Python.

bool AddSkyExtension(const MaxwellMayaExtensionParams* params)

Adds a sky extension in the exported scene. When a sky extension is present, Maxwell uses it to determine the sky color, instead of using its built-in physical sky model. The method returns false in C++ if it fails or raises an exception in Python.

unsigned int GetNumExtensions(MaxwellMayaExtensionInfo::ExtensionType type) const

Returns the number of Maxwell extensions of the given type which were found when the Maxwell plug-in was loaded. This method does not exist in Python.

MaxwellMayaExtensionInfo* GetExtensionInfo(MaxwellMayaExtensionInfo::ExtensionType type, unsigned int index) const

Returns an interface which can be used to query the attributes of the extension with the given type and index. This method does not exist in Python. It is replaced by maxwell.GetExtensions(), which returns a Python list with all the extensions which were found when the Maxwell plug-in was loaded.

MaxwellMayaExtensionInfo* GetExtensionInfo(const MString& name) const

Returns an interface which can be used to query the attributes of the extension with the given name. This method is called GetExtensionByName in Python. If no extension with the given name is present, it returns NULL in C++ and raises an exception in Python.

unsigned int GetCurrentAPIVersion() const

Returns the API version for the Maxwell plug-in. This is not necessarily the same value as the macro MAXWELL_MAYA_API_VERSION; if your plug-in uses an older API version which is still supported, the API will load correctly and this method will return a number larger than the API version you used when building your plug-in.

unsigned int GetLowestSupportedAPIVersion() const

Returns the earliest API version which is supported by the Maxwell plug-in.

static const char* GetStateName(ExporterState state)

Returns a human-readable name for the given state enum.

static bool SetExportCallback(const MString& pluginName, ExportCallbackType type, const MString& command, ExportCallbackLanguage language)

Adds a callback for the export event specified by the type argument. The pluginName argument is needed to distinguish between callbacks registered by different plug-ins, so always use the name of your plug-in here. There can only be one callback of each type for each plug-in, so calling this method a second time with the same type will overwrite the command set by the first call. The language argument specifies if the callback command uses MEL or Python. This argument is optional in Python, where it defaults to ExportCallbackLanguage_Python if not specified.

This method manipulates the g_maxwellExportCallbacks global MEL variable as described in this section. If you do not need it and want to prevent it from being declared, you can define the MAXWELL_MAYA_NO_CALLBACK_HELPERS macro before including MaxwellMayaAPI.h.

static bool RemoveExportCallback(const MString& pluginName, ExportCallbackType type)

Remove the callback of the given type. This method can also be disabled by defining MAXWELL_MAYA_NO_CALLBACK_HELPERS, as above.

static bool RemoveExportCallbacks(const MString& pluginName)

Removes all the callbacks registered by the given plug-in. It is recommended to call this in the uninitializePlugin function of your plug-in, to make sure you don't leave behind any invalid callbacks when you are unloaded. This method can also be disabled by defining MAXWELL_MAYA_NO_CALLBACK_HELPERS, as above.

static MaxwellMayaAPI* LoadAPI()

Attempts to open the Maxwell plug-in and return the interface pointer. Use this method if you don't want to handle all the details about loading the shared library and calling the entry point yourself. The method will return NULL if the interface pointer cannot be obtained. The declaration of this method can be inhibited by defining the macro MAXWELL_MAYA_NO_LOAD_HELPER before including MaxwellMayaAPI.h.

This method does not exist in Python, since the API loading is handled automatically in that case.