Writing a plugin exporter (File Translator)

 

 

 

If you wish to write an exporter that can be used within Maya from the `Export All` menu item, then you will need to overload the MPxFileTranslator class.

This class basically contains a reader and a writer method which we can overload to import and export our files.

In addition to the actual plugin, we can optionally provide a mel script to create a user interface for the exporter options.

The best example of this is the framework project.

 

  

 

 

Deriving From MPxFileTranslator

Initially you want to derive a class form the base API class MPxFileTranslator. This class allows you to impliment a plugin capable of importing or exporting files from maya. The example provided here simply impliments the very minimum to create a working exporter. The source example extends this and also demonstrates what would be required for an importer.

The main routine within the class is the writer method which we need to overload in order to write our file. We also need to overload the haveWriteMethod() member so that Maya knows that this File Translator should be used as an exporter.

We are also able to overload the function defaultExtension to return an extension specific to our file type.

We will also need to specify a function to create a new instance of our class. This is the purpose of the creator method.

 

 

  

// our plugin file translator class. This must inherit
// from the base class MPxFileTranslator
class MayaFileTranslator : public MPxFileTranslator
{
public:

 

MayaFileTranslator() : MPxFileTranslator() {};
~MayaFileTranslator() {};

// we overload this method to perform any
// file export operations needed
MStatus writer( const MFileObject& file,
const MString& optionsString,
FileAccessMode mode);


// returns true if this class can export files
bool haveWriteMethod() const {

  return true;

}
// returns the default extension of the file supported
// by this FileTranslator.
MString defaultExtension() const {

  return "mod";

}
// Used by Maya to create a new instance of our
// custom file translator
static void* creator(){

  return new MayaFileTranslator;

}

// some option flags set by the mel script
bool m_bOption1;
bool m_bOption2;

};

 

 

The Export Options

Maya allows us to specify a mel script which is used to create a user interface set of controls. This script can communicate with our plugin by passing a single text string back and forth.

 

This text string is the only place where the users settings will be stored for your exporter.

 

The script must be able to handle two seperate actions. The first is "post" where you should create a user interface and set the UI elements values by parsing the initial options string ($settings).

 

The second action is "query" where we need to construct an option string by querying the current state of the user interface controls.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 
// This mel script should be saved as
// "MayaFileExportScript.mel" and placed inside your scripts
// directory. This is usually "my documents/maya/scripts" or
// "~/maya/scripts" on linux. This procedure will be called
//
//
// $parent - the parent UI layout
// $action - "post" or "query"
// $settings - the initial exporter settings
// $callback - the function to call
//
global proc int MayaFileExportScript( string $parent,
string $action,
string $settings,
string $callback ) {

{

  // if we need to create the user interface...
if ($action == "post") {
  // attachs the GUI to the correct parent layout
setParent $parent;

// create a simple layout for the controls
columnLayout -adj true;

// create 2 radio button groups for our options
radioButtonGrp
  -bgc 0.7 0.8 0.9
-l "Option1"
-nrb 2 -cw3 175 75 75
-la2 "On" "Off" -sl 1 option1;
radioButtonGrp
  -bgc 0.7 0.8 0.9
-l "Option2"
-nrb 2 -cw3 175 75 75
-la2 "On" "Off" -sl 1 option2;

// split the previous set of options
string $options[];
int $ntokens=`tokenize $settings " " $options`;

// loop through each option
for( $i=0; $i<$ntokens; ++$i ) {
  // get this option
$option = $options[$i];

if($options=="-option1") {
  // if set to off, update the GUI
if( $options[++$i] == "0" ) {
radioButtonGrp -e -sl 2 option1;
}

}
else
if($option=="-option2") {
  // if set to off, update the GUI
if( $options[++$i] == "0" ) {
radioButtonGrp -e -sl 2 option2;
}
}
}
}
else
if ($action == "query") {
  string $option="-option1 ";


if(`radioButtonGrp -q -sl option1` == 1)
  $option += "1 ";
else
  $option += "0 ";
$option+="-option2 "


if(`radioButtonGrp -q -sl option2` == 1)
  $option += "1 ";
else
  $option += "0 ";

eval( $callback + "\"" + $option + "\"" );

}

return 1;

}

 

 

MPxFileTranslator::writer

The first task you should perform in the writer method, is to check all of the options that were passed to your plugin. In this case we simply check for "-option1" and "-option2" and set the member variables accordingly.

 

Within Maya, the user can invoke your exporter using either the "Export All" of "Export Selected" options. This is reflected with the mode parameter. if the mode is equal to kExportActiveAccessMode, then we are only exporting the selected items.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

  


// This function is called when we need to export any data.
//
// file - info about the file we should be writing
// options - the option string passed through from mel
// mode - are we exporting all or just the selected items?
//

MStatus MayaFileTranslator::writer( const MFileObject& file,
const MString& options,
FileAccessMode mode)

{

 

// this will store our option strings
MStringArray optionList;

// seperate the option string
options.split(' ', optionList);

// check all of the options
int len = optionList.length();
for( i = 0; i < length; ++i ){

  MString Option = optionList[i];

// if we recognised option 1
if( Option == "-option1" ) {
  // check for true or false
if(optionList[++i]=="0")
  m_bOption1=false;
else
  m_bOption1=true;

}

// if we recognised our second option
if( Option == "-option2" ) {
  // check for true or false
if(optionList[++i]=="0")
  m_bOption2=false;
else
  m_bOption2=true;

}

}

// Get the output filename
MString output_filename = file.fullName();

if(mode == kExportActiveAccessMode) {

  // export selected objects only

} else {

  // export all objects

}

// writing of file was sucessful
return MS::kSuccess;

};

 

 

Registering the Plugin

Any Maya plugin requires two functions to be exported. initializePlugin is called when the dll is loaded, uninitializePlugin is called when the plugin is un-loaded from Maya.

Within these functions you need to make use of the MFnPlugin function set to register any file translators, nodes, contexts, mel commands, etc, that your plugin will be adding into Maya.

When we register a file translator with Maya, we can also specify a script to run for the export options GUI. We can also specify a default set of export options.

In this case we just inform Maya about the MayaFileExportScript UI script, and provide default values for our "-option1" and "-option2" export options.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

  


#include <maya/MStatus.h>
#include <maya/MObject.h>
#include <maya/MFnPlugin.h>

// under WIN32 we need to export two functions
// under linux compiling with -shared does the job...
#ifdef WIN32
#define MLL_EXPORT __declspec(dllexport)
#else
#define MLL_EXPORT
#endif

// specifies a script for the Export Options UI
char* g_OptionScript = "MayaFileExportScript";

// the default option string
char* g_DefaultExportOptions = "-option1 1 -option2 1";

// this function is called when the plugin is loaded. It is
// used to register any file translators, mel commands,
// custom nodes etc that your plugin is adding to Maya
MLL_EXPORT MStatus initializePlugin( MObject obj )
{

 

// attach a plugin function set to register our file
// translator with Maya
MFnPlugin plugin( obj, "Rob", "1.0", "Any");

// an error code
MStatus stat;

// register the file translator with Maya
stat = plugin.registerFileTranslator( "MayaExport",
  "none",
MayaFileTranslator::creator,
(char*)g_OptionScript,
(char*)g_DefaultExportOptions );

if (stat != MS::kSuccess) {

  stat.perror("Error - initializePlugin");

}
return stat;

}

// This function is called when you un-load your plugin.
// it is used to de-register anything you have added to Maya
MLL_EXPORT MStatus uninitializePlugin( MObject obj )
{

 

// attach a plugin function set to register our file
// translator with Maya
MFnPlugin plugin( obj );

// an error code
MStatus stat;

// de-register the file translator with Maya
stat = plugin.deregisterFileTranslator("MayaExport");

if (stat != MS::kSuccess) {

  stat.perror("Error - uninitializePlugin");

}
return stat;

}

 



 

 

What Next?

Writing A Command Line Exporter

FileIO In The Maya API

Traversing The Scene

Accessing Attributes

Accessing Node Connections

index

Rob Bateman [2004]

[HOME] [MEL] [API]