C++ API Reference
MPxFileTranslator Class Reference

Base Class for creating Maya File Translators. More...

#include <MPxFileTranslator.h>

+ Inheritance diagram for MPxFileTranslator:

Public Types

enum  MFileKind { kIsMyFileType, kCouldBeMyFileType, kNotMyFileType }
 How the translator identifies this file. More...
 
enum  FileAccessMode {
  kUnknownAccessMode, kOpenAccessMode, kReferenceAccessMode, kImportAccessMode,
  kSaveAccessMode, kExportAccessMode, kExportActiveAccessMode
}
 Type of file access. More...
 

Public Member Functions

 MPxFileTranslator ()
 The class constructor.
 
virtual ~MPxFileTranslator ()
 The class destructor.
 
virtual MStatus reader (const MFileObject &file, const MString &optionsString, FileAccessMode mode)
 This routine is called by Maya when it is necessary to load a file of a type supported by this translator. More...
 
virtual MStatus writer (const MFileObject &file, const MString &optionsString, FileAccessMode mode)
 This routine is called by Maya when it is necessary to save a file of a type supported by this translator. More...
 
virtual bool haveReadMethod () const
 This routine is called by Maya while it is executing in the MPxFileTranslator constructor. More...
 
virtual bool haveWriteMethod () const
 This routine is called by Maya while it is executing in the MPxFileTranslator constructor. More...
 
virtual bool haveNamespaceSupport () const
 When a file is imported or referenced into an existing scene, there is the possibility that nodes in the incoming file will have the same names as nodes already in the scene. More...
 
virtual bool haveReferenceMethod () const
 This method is called by Maya to see if the translator implements its own custom file referencing. More...
 
virtual MString defaultExtension () const
 This routine is called by Maya whenever it needs to know the default extension of a translator. More...
 
virtual MString filter () const
 This virtual method may be overloaded in a derived class to set the filter extension that will be used by the file dialog. More...
 
virtual bool canBeOpened () const
 This routine is called by Maya while it is executing in the MPxFileTranslator constructor. More...
 
virtual MPxFileTranslator::MFileKind identifyFile (const MFileObject &file, const char *buffer, short size) const
 This routine is called by Maya when a file selection dialog accesses a new directory. More...
 

Static Public Member Functions

static MPxFileTranslator::FileAccessMode fileAccessMode ()
 This routine returns the fileAccess mode maya is currently in. More...
 

Detailed Description

Base Class for creating Maya File Translators.

This class provides the connection to Maya by which user written file translators can be added as plug-ins.

This class provides a base class from which one derives in order to implement Maya "File Translator Plug-Ins." A file translator plug-in allows Maya to read or write 3rd party file formats.

The identifyFile method is called whenever Maya's file save or restore dialogs are run, and identifyFile uses the filename and first few bytes of the file to determine whether it is of a type supported by the translator. If it is, then Maya will display the file with the "name" and "icon" specified as arguments to MFnPlugin::registerFileTranslator.

If an attempt is made to read the file, the "reader" method in the derived class is called, if an attempt is made to write the file, the "writer" method is called.

Examples:
AbcImport/AlembicImportFileTranslator.h, animExportUtil/animExportUtil.h, animImportExport/animImportExport.cpp, animImportExport/animImportExport.h, atomImportExport/atomImportExport.cpp, atomImportExport/atomImportExport.h, colorTransformData/colorTransformData.cpp, lepTranslator/lepTranslator.cpp, maTranslator/maTranslator.cpp, objExport/objExport.cpp, polyRawExporter/polyExporter.h, and polyX3DExporter/polyExporter.h.

Member Enumeration Documentation

enum MFileKind

How the translator identifies this file.

Enumerator
kIsMyFileType 

Translator understands how to read/write this file.

kCouldBeMyFileType 

Translator is not best available to read/write this file.

kNotMyFileType 

Translator does not understand how to read/write this file.

Type of file access.

Enumerator
kUnknownAccessMode 

This mode is set when no file operation is currently in progress.

kOpenAccessMode 

This mode is set when data is being read into a new scene.

(i.e.: file -open True)

kReferenceAccessMode 

This mode is set when a referenced file is being read.

This mode can be temporary if the parent file was opened or imported in. For example, if a parent file is being opened, the file access mode will be set to kOpenAccessMode but when the reference file is being read, it will be set to kReferenceAccessMode. It will be set back to kOpenAccessMode once the reference file has been read.

kImportAccessMode 

This mode is set when data is being read into the current scene.

kSaveAccessMode 

This mode is set when the user saves the file.

(i.e.: file -save True)

kExportAccessMode 

This mode is set when the user chooses to export all or a referenced file is being written out.

This mode can be temporary if the parent file was saved or exported out. For example, if a parent file is being saved, the file access mode will be set to kSaveAccessMode but when the reference file is being written, it will be set to kExportAccessMode. It will be set back to kSaveAccessMode once the reference file has been written.

kExportActiveAccessMode 

This mode is set when only the selected items are to be exported.

Member Function Documentation

MStatus reader ( const MFileObject file,
const MString optionsString,
MPxFileTranslator::FileAccessMode  mode 
)
virtual

This routine is called by Maya when it is necessary to load a file of a type supported by this translator.

This virtual method must be overloaded in derived classes, as the default version defined in MPxFileTranslator simply fails unconditionally. The only parameter is an MFileObject that contains the pathname of the file to be loaded. This routine is responsible for reading the contents of the given file, and creating Maya objects via API or MEL calls to reflect the data in the file.

Parameters
[in]filethe name of the file to read
[in]optionsStringa string representation of any file options
[in]modethe method used to read the file - open or import
Returns
MS::kSuccess if the read succeeds, and a failure code if it does not

Reimplemented in MPxMayaAsciiFilter.

Examples:
AbcImport/AlembicImportFileTranslator.h, animImportExport/animImportExport.h, atomImportExport/atomImportExport.h, lepTranslator/lepTranslator.cpp, maTranslator/maTranslator.cpp, and objExport/objExport.cpp.
MStatus writer ( const MFileObject file,
const MString optionsString,
MPxFileTranslator::FileAccessMode  mode 
)
virtual

This routine is called by Maya when it is necessary to save a file of a type supported by this translator.

This virtual method must be overloaded in derived classes, as the default version defined in MPxFileTranslator simply fails unconditionally. The only parameter is an MFileObject that contains the pathname of the file to be written to. This routine is responsible for traversing all objects in the current Maya scene, and writing a representation to the given file in the supported format.

It is not essential that all information in the current Maya scene be written out, although if it is not, the scene will not be recreated when this file is read via the "reader" method.

Parameters
[in]filethe name of the file to write
[in]optionsStringa string representation of any file options
[in]modethe method used to write the file - save, export, or export active.
Returns
MS::kSuccess if the write succeeds, and a failure code if it does not

Reimplemented in MPxMayaAsciiFilter.

Examples:
animExportUtil/animExportUtil.h, animImportExport/animImportExport.h, atomImportExport/atomImportExport.h, colorTransformData/colorTransformData.cpp, lepTranslator/lepTranslator.cpp, maTranslator/maTranslator.cpp, objExport/objExport.cpp, polyRawExporter/polyExporter.h, and polyX3DExporter/polyExporter.h.
bool haveReadMethod ( ) const
virtual

This routine is called by Maya while it is executing in the MPxFileTranslator constructor.

Maya uses this entry point to query the translator and determine if it provides a reader method.

This virtual method must be overloaded in derived classes if a reader method exists, as the default version defined in MPxFileTranslator unconditionally returns false.

Returns
true if the class has a read method and false otherwise otherwise.

Reimplemented in MPxMayaAsciiFilter.

Examples:
AbcImport/AlembicImportFileTranslator.h, animImportExport/animImportExport.h, atomImportExport/atomImportExport.h, colorTransformData/colorTransformData.cpp, lepTranslator/lepTranslator.cpp, maTranslator/maTranslator.cpp, objExport/objExport.cpp, polyRawExporter/polyExporter.h, and polyX3DExporter/polyExporter.h.
bool haveWriteMethod ( ) const
virtual

This routine is called by Maya while it is executing in the MPxFileTranslator constructor.

Maya uses this entry point to query the translator and determine if it provides a write method.

This virtual method must be overloaded in derived classes if a writer method exists, as the default version defined in MPxFileTranslator unconditionally returns false.

Returns
true if the class has a write method and false otherwise

Reimplemented in MPxMayaAsciiFilter.

Examples:
animExportUtil/animExportUtil.h, animImportExport/animImportExport.h, atomImportExport/atomImportExport.h, colorTransformData/colorTransformData.cpp, lepTranslator/lepTranslator.cpp, maTranslator/maTranslator.cpp, objExport/objExport.cpp, polyRawExporter/polyExporter.h, and polyX3DExporter/polyExporter.h.
bool haveNamespaceSupport ( ) const
virtual

When a file is imported or referenced into an existing scene, there is the possibility that nodes in the incoming file will have the same names as nodes already in the scene.

Although DAG nodes may legally have the same name so long as their DAG paths are different, in all other cases node names must be unique.

Maya has a number of different algorithms which the user may select to resolve name clashes. (See the file command for more details.) Some of these algorithms involve creating a separate namespace for the incoming file and placing some or all of its nodes within that namespace.

As some translators may have difficulty dealing with namespaces, Maya will first call the translator's haveNamespaceSupport() method to see if it can handle them.

If the user requests that namespaces be used to resolve clashes and the translator does not support namespaces, then Maya will simply place all incoming nodes into the current namespace and it will be up to the translator to ensure that no clashes occur, otherwise there will be errors during the import/reference.

If a translator can deal with having Maya placing some or all of a file's nodes into a separate namespace, then its derived class should override this virtual method to return true.

By default the method returns false.

Returns
true if the class can deal with namespaces and false otherwise
Examples:
AbcImport/AlembicImportFileTranslator.h, and lepTranslator/lepTranslator.cpp.
bool haveReferenceMethod ( ) const
virtual

This method is called by Maya to see if the translator implements its own custom file referencing.

If this function returns true, every time a file of this translator's type is referenced and its parent is being saved or exported the write method of this translator will be called, so the custom file referencing can add information to its files.

If it returns false, Maya's file referencing system will be used by default.

This function returns false by default.

Examples:
lepTranslator/lepTranslator.cpp.
MString defaultExtension ( ) const
virtual

This routine is called by Maya whenever it needs to know the default extension of a translator.

This virtual method may be overloaded in derived classes if a default extension exists, as the default version defined in MPxFileTranslator unconditionally returns an empty string.

Returns
A string containing the default extension of the translator, excluding the period at the beginning.
Examples:
AbcImport/AlembicImportFileTranslator.h, animExportUtil/animExportUtil.h, animImportExport/animImportExport.h, atomImportExport/atomImportExport.h, colorTransformData/colorTransformData.cpp, filteredAsciiFile/filteredAsciiFile.cpp, lepTranslator/lepTranslator.cpp, maTranslator/maTranslator.cpp, objExport/objExport.cpp, polyRawExporter/polyExporter.h, and polyX3DExporter/polyExporter.h.
MString filter ( ) const
virtual

This virtual method may be overloaded in a derived class to set the filter extension that will be used by the file dialog.

If the defaultExtension method is not implemented in a derived class, the standard filter *.* will be returned by MPxFileTranslator and used by the file dialog. If defaultExtension is implemented in a derived class, that extension will be used in the proper format.

Returns
A string containing the filter mask of the translator, Must be of the form *.obj
Examples:
AbcImport/AlembicImportFileTranslator.h.
bool canBeOpened ( ) const
virtual

This routine is called by Maya while it is executing in the MPxFileTranslator constructor.

Maya uses this entry point to query the translator and determine if it can open files. The default is true.

Returns
  • true if the class can open and import files
  • false if the class can only import files
Examples:
animImportExport/animImportExport.h, atomImportExport/atomImportExport.h, lepTranslator/lepTranslator.cpp, polyRawExporter/polyExporter.h, and polyX3DExporter/polyExporter.h.
MPxFileTranslator::MFileKind identifyFile ( const MFileObject file,
const char *  buffer,
short  size 
) const
virtual

This routine is called by Maya when a file selection dialog accesses a new directory.

It will potentially be called once for every file in the directory.

The routine is given an MFileObject indicating the file being checked, as well as a pointer to the initial file contents. The size parameter indicates the number of bytes available at the pointer location.

This routine must use this data to determine if the file is of a type supported by this translator. This virtual method must be overloaded in derived classes, as the default version defined in MPxFileTranslator unconditionally returns kNotMyFileType.

A typical use of this method is to check the file extension of the file in question, and return a status indicating whether or not the file is of the type expected by this MPxFileTranslator. See the plugin example animImportExport for an example.

Parameters
[in]filethe name of the file to check
[in]buffera pointer to the initial contents of the file
[in]sizethe number of valid bytes in the buffer
Returns
  • MFileKind::kIsMyFileType this file is understood by this translator
  • MFileKind::kNotMyFileType this file is not understood by this translator
  • MFileKind::kCouldBeMyFileType this file is understood by this translator, but this translator is not the best one to use for reading or writing it
Examples:
AbcImport/AlembicImportFileTranslator.h, animExportUtil/animExportUtil.h, animImportExport/animImportExport.h, atomImportExport/atomImportExport.h, lepTranslator/lepTranslator.cpp, maTranslator/maTranslator.cpp, and objExport/objExport.cpp.
MPxFileTranslator::FileAccessMode fileAccessMode ( )
static

This routine returns the fileAccess mode maya is currently in.

Returns
See MPxFileTranslator::FileAccessMode for a list of possible return values and what they mean.

The documentation for this class was generated from the following files: