- Main Page
- Related Pages
- Modules
- Namespaces
- Classes
- Examples

- Class List
- Class Hierarchy
- Class Members

Public Member Functions | Protected Member Functions

# MPxMayaAsciiFilter Class Reference
OpenMaya - API module for common classes | Proxy classes

This reference page is linked to from the following overview topics: Extension for Autodesk Maya 2013, Example C++ plug-in descriptions.

Search for all occurrences

## Detailed Description

Translator to output filtered Maya ASCII files.

MPxMayaAsciiFilter allows output to the Maya ASCII (.ma) file format to be filtered by a plug-in. The file is output using the same internal mechanism that is used for normal Maya ASCII output, but allows your plug-in to prevent certain lines (such as createNodes or connectAttrs) from being output to the file. In addition, it allows you to write directly to the file at specific points during output.

MPxMayaAsciiFilter allows your plug-in to write out files similar to Maya ASCII in a custom format. It can be used, for example, to partition a scene into several files, each of which has been filtered to write out different parts of the scene. Note that the order of the file cannot be changed - for example, connectAttrs are always written after createNodes - but it does allow you to control which connectAttrs and createNodes are output.

MPxMayaAsciiFilter inherits from MPxFileTranslator. It overrides the haveWriteMethod(), haveReadMethod(), reader(), and writer() methods in MPxFileTranslator in such a way that the internal Maya mechanism for reading and writing Maya ASCII files is used. Because of this, it is not advised that you override these methods in your plug-in. If you do, make sure you first call these methods in MPxMayaAsciiFilter. A pseudo-code example is shown here:

    MyAsciiFilter::writer(...)
    {
        // do something before writing to file here
        ...

        // we will now write to the file

        MStatus result = MPxMayaAsciiFilter::writer(...);

        if (result == MStatus::kSuccess)
        {
            ... // do something after writing the file here
        }

        return result;
    }

To determine if a given line should be output, override the methods writesCreateNode(), writesSetAttr() and so on. Each of these methods takes as its arguments the relevant data which is about to be processed and your plug-in can use this to determine whether or not the line will be output.

For example, you may want to write out everything but render layer data. The code to do this might look something like what is shown here:

    bool
    MyAsciiFilter::writesCreateNode( const MObject& node )
    {
        if (node.hasFn(MFn::kRenderLayer))
        {
            return true;
        }

        return false;
    }

    bool
    MyAsciiFilter::writesConnectAttr( const MPlug& srcPlug,
                                      const MPlug& destPlug )
    {
        if (srcPlug.node().hasFn(MFn::kRenderLayer) ||
            dstPlug.node().hasFn(MFn::kRenderLayer))
        {
            return true;
        }

        return false;
    }

Note that writesConnectAttr() has to be overridden as well (as would writesSetAttr(), writesSelectAttr(), and so on). This is because each line is handled separately, and nothing clever is done in the base class' implementation of writesConnectAttr(), such as having a default behaviour of only outputting connectAttrs for nodes that are being output. This gives you the most flexible control over what will be written.

If you were using this class to save a segmented file, a master file might have to know about the locations of each of the segments. If your file saved everything but render layers in one file, and render layers in another, the first file might need to contain a pointer to the second, so that when the first file is loaded the second gets read into memory too. To do this, you would use MPxMayaAsciiFilter's ability to write directly to the stream during file output.

You can write to the stream during output by overriding the methods writePreCreateNodesBlock(), writePostCreateNodesBlock() and so on. These give you a simple mechanism to write directly to the file. Each of these methods take an MPxMayaAsciiFilterOutput as its only argument. To write to the file, simply use the output operator (MPxMayaAsciiFilterOutput::operator<<() ) and output the string you wish.

In the example above, the pointer to the render layer file might be inserted into the main file after all nodes have been created. The code to do this would look something like what is shown here:

    MStatus
    MyAsciiFilter::writePostCreateNodesBlock( MPxMayaAsciiFilterOutput& fileIO )
    {
        fileIO << "eval(\"importRenderLayerFile \\\"MyLayerFile.maf\\\";\")\n";
    }

In the above example, after the createNode block was output, the line

    eval("importRenderLayerFile \"MyLayerFile.maf\"");

was output. When the file is read in, Maya would reach the line above and execute it like any other MEL command. It is assumed in this example that there would be a custom command plug-in called importRenderLayerFile which would do the work of actually importing the layer file.

Note: MPxMayaAsciiFilter gives you the ability to create your own custom file formats based on standard Maya ASCII files. However, Autodesk does not support such custom files as they will not, by definition, be standard Maya ASCII files.

Examples:

  filteredAsciiFile.cpp.

`#include <MPxMayaAsciiFilter.h>`

Inheritance diagram for MPxMayaAsciiFilter:
[legend]

List of all members.

## Public Member Functions
| MPxMayaAsciiFilter ()
| The class constructor.
virtual | ~MPxMayaAsciiFilter ()
| The class destructor.
virtual bool | haveWriteMethod () const
| Overrides MPxFileTranslator::haveWriteMethod() to indicate that this translator has a write method.
virtual bool | haveReadMethod () const
| Overrides MPxFileTranslator::haveReadMethod() to indicate that this translator has a read method.
virtual MStatus | reader (const MFileObject &file, const MString &optionsString, FileAccessMode mode)
| Reader method for the ascii filter translator.
virtual MStatus | writer (const MFileObject &file, const MString &optionsString, FileAccessMode mode)
| Writer method for the ascii filter translator.
## Protected Member Functions
const MFileObject | file () const
| Returns the MFileObject associated with the file currently being read or written, allowing access to the file's name, path and so on.
virtual MStatus | processReadOptions (const MString &optionsString)
| Allows the translator to handle any options passed into the reader() method, above.
virtual MStatus | processWriteOptions (const MString &optionsString)
| Allows the translator to handle any options passed into the reader() method, above.
virtual bool | writesRequirements () const
| Determines if "requires" commands should be written in the file.
virtual bool | writesMetadata () const
| Asserts that "dataStructure/addMetadata/applyMetadata" commands should be written in the file.
virtual bool | writesCreateNode (const MObject &node) const
| Determines if a "createNode" command should be written for a particular node.
virtual bool | writesSetAttr (const MPlug &srcPlug) const
| Determines if a "setAttr" command should be written for a particular node.
virtual bool | writesConnectAttr (const MPlug &srcPlug, const MPlug &destPlug) const
| Determines if a "connectAttr" command should be written for a particular node.
virtual bool | writesDisconnectAttr (const MPlug &srcPlug, const MPlug &destPlug) const
| Determines if a "disconnectAttr" command should be written for a particular connection.
virtual bool | writesParentNode (const MDagPath &parent, const MDagPath &child) const
| Determines if a "parent" command should be written for a particular parent and child.
virtual bool | writesSelectNode (const MObject &node) const
| Determines if a "select" command should be written for a particular node.
virtual bool | writesFileReference (const MFileObject &referenceFile) const
| Determines if a "fileReference" command should be written for a file.
virtual MStatus | writePostHeader (MPxMayaAsciiFilterOutput &fileIO)
| Allows data to be written out to the file after the header block.
virtual MStatus | writePostRequires (MPxMayaAsciiFilterOutput &fileIO)
| Allows data to be written out to the file after the requires block.
virtual MStatus | writePreCreateNodesBlock (MPxMayaAsciiFilterOutput &fileIO)
| Allows data to be written out to the file before the create nodes block.
virtual MStatus | writePostCreateNodesBlock (MPxMayaAsciiFilterOutput &fileIO)
| Allows data to be written out to the file after the create nodes block.
virtual MStatus | writePreConnectAttrsBlock (MPxMayaAsciiFilterOutput &fileIO)
| Allows data to be written out to the file before the connect attrs block.
virtual MStatus | writePostConnectAttrsBlock (MPxMayaAsciiFilterOutput &fileIO)
| Allows data to be written out to the file after the connect attrs block.
virtual MStatus | writePreTrailer (MPxMayaAsciiFilterOutput &fileIO)
| Allows data to be written out to the file before the trailer block.

## Member Function Documentation

bool haveWriteMethod | ( |  | ) | const`[virtual]`

Search for all occurrences

Overrides MPxFileTranslator::haveWriteMethod() to indicate that this translator has a write method.

In general this should not be overridden.

Returns:
  true

Reimplemented from MPxFileTranslator.

bool haveReadMethod | ( |  | ) | const`[virtual]`

Search for all occurrences

Overrides MPxFileTranslator::haveReadMethod() to indicate that this translator has a read method.

In general this should not be overridden.

Returns:
  true

Reimplemented from MPxFileTranslator.

MStatus reader | ( | const MFileObject & | file,
|  | const MString & | optionsString,
|  | FileAccessMode | mode
| ) |  | `[virtual]`

Search for all occurrences

Reader method for the ascii filter translator.

In general this should not be overridden, since internal Maya methods are called in this method.

Note: To process any options passed in in the optionsString variable, subclasses should override the processReadOptions() method, below.

Parameters:

  [in] | file | The file to be read
  [in] | optionsString | Any file options to be handled. Passed to processReadOptions(), below
  [in] | mode | The access mode (read or import). Currently this is ignored

Returns:
  - MS::kSuccess file read was successful
  - MS::kFailure an error occurred while reading the file

Reimplemented from MPxFileTranslator.

MStatus writer | ( | const MFileObject & | file,
|  | const MString & | optionsString,
|  | FileAccessMode | mode
| ) |  | `[virtual]`

Search for all occurrences

Writer method for the ascii filter translator.

In general this should not be overridden, since internal Maya methods are called in this method.

Note: To process any options passed in in the optionsString variable, subclasses should override the processWriteOptions() method, below.

Parameters:

  [in] | file | The file to be read
  [in] | optionsString | Any file options to be handled. Passed to processWriteOptions(), below
  [in] | mode | The access mode (save, export, or export active). Currently this is ignored.

Returns:
  - MS::kSuccess file read was successful
  - MS::kFailure an error occurred while reading the file

Reimplemented from MPxFileTranslator.

const MFileObject file | ( |  | ) | const`[protected]`

Search for all occurrences

Returns the MFileObject associated with the file currently being read or written, allowing access to the file's name, path and so on.

Returns:
  The file object. Only valid while a read or write is happpening

MStatus processReadOptions | ( | const MString & | optionsString | ) | `[protected, virtual]`

Search for all occurrences

Allows the translator to handle any options passed into the reader() method, above.

This call is made before the file is actually read. The default implementation does nothing.

Parameters:

  [in] | optionsString | The file options to be handled.

Returns:
  MS::kSuccess Options were properly handled, and file read can commence. If any other value is returned, file read is aborted.

Examples:
  filteredAsciiFile.cpp.

MStatus processWriteOptions | ( | const MString & | optionsString | ) | `[protected, virtual]`

Search for all occurrences

Allows the translator to handle any options passed into the reader() method, above.

This call is made before the file is actually read. The default implementation does nothing.

Parameters:

  [in] | optionsString | The file options to be handled.

Returns:
  MS::kSuccess Options were properly handled, and file read can commence. If any other value is returned, file write is aborted.

Examples:
  filteredAsciiFile.cpp.

bool writesRequirements | ( |  | ) | const`[protected, virtual]`

Search for all occurrences

Determines if "requires" commands should be written in the file.

By default true is always returned.

Returns:
  bool true if "requires" commands should be written; false otherwise.

Examples:
  filteredAsciiFile.cpp.

bool writesMetadata | ( |  | ) | const`[protected, virtual]`

Search for all occurrences

Asserts that "dataStructure/addMetadata/applyMetadata" commands should be written in the file.

Normally these are always written but you may want to override this to prevent metadata from being added to Maya files if you export it in other ways.

Returns:
  bool true if metadata commands should be written; false otherwise.

bool writesCreateNode | ( | const MObject & | node | ) | const`[protected, virtual]`

Search for all occurrences

Determines if a "createNode" command should be written for a particular node.

By default this method returns true for all nodes.

Parameters:

  [in] | node | The node in question.

Returns:
  True if the createNode should be written, false otherwise.

Examples:
  filteredAsciiFile.cpp.

bool writesSetAttr | ( | const MPlug & | srcPlug | ) | const`[protected, virtual]`

Search for all occurrences

Determines if a "setAttr" command should be written for a particular node.

By default this method returns true for all plugs.

Parameters:

  [in] | srcPlug | The plug to be set.

Returns:
  bool true if the setAttr should be written; false otherwise.

Examples:
  filteredAsciiFile.cpp.

bool writesConnectAttr | ( | const MPlug & | srcPlug,
|  | const MPlug & | destPlug
| ) |  | const`[protected, virtual]`

Search for all occurrences

Determines if a "connectAttr" command should be written for a particular node.

By default this method returns true for all connections.

Parameters:

  [in] | srcPlug | The source plug in the connection.
  [in] | destPlug | The destination plug in the connection.

Returns:
  bool true if the connectAttr should be written; false otherwise.

Examples:
  filteredAsciiFile.cpp.

bool writesDisconnectAttr | ( | const MPlug & | srcPlug,
|  | const MPlug & | destPlug
| ) |  | const`[protected, virtual]`

Search for all occurrences

Determines if a "disconnectAttr" command should be written for a particular connection.

By default this method returns true for all connection.

Parameters:

  [in] | srcPlug | The source plug in the connection.
  [in] | destPlug | The destination plug in the connection.

Returns:
  bool true if the disconnectAttr should be written; false otherwise.

bool writesParentNode | ( | const MDagPath & | parent,
|  | const MDagPath & | child
| ) |  | const`[protected, virtual]`

Search for all occurrences

Determines if a "parent" command should be written for a particular parent and child.

By default this method returns true for all parents and children.

Parameters:

  [in] | parent | The dag path to the parent.
  [in] | child | The dag path to the child.

Returns:
  bool true if the disconnectAttr should be written; false otherwise.

bool writesSelectNode | ( | const MObject & | node | ) | const`[protected, virtual]`

Search for all occurrences

Determines if a "select" command should be written for a particular node.

By default this method returns true for all nodes.

Parameters:

  [in] | node | The node to select

Returns:
  bool true if the select should be written; false otherwise.

Examples:
  filteredAsciiFile.cpp.

bool writesFileReference | ( | const MFileObject & | referenceFile | ) | const`[protected, virtual]`

Search for all occurrences

Determines if a "fileReference" command should be written for a file.

By default this method returns true for all files.

Parameters:

  [in] | referenceFile | The file to be referenced.

Returns:
  bool true if the fileReference should be written; false otherwise.

Examples:
  filteredAsciiFile.cpp.

MStatus writePostHeader | ( | MPxMayaAsciiFilterOutput & | filterOutput | ) | `[protected, virtual]`

Search for all occurrences

Allows data to be written out to the file after the header block.

By default this method does nothing.

Parameters:

  [in] | filterOutput | the output stream to be written to (using the << operator)

Returns:
  bool true if the disconnectAttr should be written; false otherwise.

MStatus writePostRequires | ( | MPxMayaAsciiFilterOutput & | filterOutput | ) | `[protected, virtual]`

Search for all occurrences

Allows data to be written out to the file after the requires block.

By default this method does nothing.

Parameters:

  [in] | filterOutput | the output stream to be written to (using the << operator)

Returns:
  MS::kSuccess Output was successfull.

Examples:
  filteredAsciiFile.cpp.

MStatus writePreCreateNodesBlock | ( | MPxMayaAsciiFilterOutput & | filterOutput | ) | `[protected, virtual]`

Search for all occurrences

Allows data to be written out to the file before the create nodes block.

By default this method does nothing.

Parameters:

  [in] | filterOutput | the output stream to be written to (using the << operator)

Returns:
  MS::kSuccess Output was successfull.

MStatus writePostCreateNodesBlock | ( | MPxMayaAsciiFilterOutput & | filterOutput | ) | `[protected, virtual]`

Search for all occurrences

Allows data to be written out to the file after the create nodes block.

By default this method does nothing.

Parameters:

  [in] | filterOutput | the output stream to be written to (using the << operator)

Returns:
  MS::kSuccess Output was successfull.

Examples:
  filteredAsciiFile.cpp.

MStatus writePreConnectAttrsBlock | ( | MPxMayaAsciiFilterOutput & | filterOutput | ) | `[protected, virtual]`

Search for all occurrences

Allows data to be written out to the file before the connect attrs block.

By default this method does nothing.

Parameters:

  [in] | filterOutput | the output stream to be written to (using the << operator)

Returns:
  MS::kSuccess Output was successfull.

MStatus writePostConnectAttrsBlock | ( | MPxMayaAsciiFilterOutput & | filterOutput | ) | `[protected, virtual]`

Search for all occurrences

Allows data to be written out to the file after the connect attrs block.

By default this method does nothing.

Parameters:

  [in] | filterOutput | the output stream to be written to (using the << operator)

Returns:
  MS::kSuccess Output was successfull.

MStatus writePreTrailer | ( | MPxMayaAsciiFilterOutput & | filterOutput | ) | `[protected, virtual]`

Search for all occurrences

Allows data to be written out to the file before the trailer block.

By default this method does nothing.

Parameters:

  [in] | filterOutput | the output stream to be written to (using the << operator)

Returns:
  MS::kSuccess Output was successfull.

MPxMayaAsciiFilter MPxMayaAsciiFilter MPxMayaAsciiFilter MPxMayaAsciiFilter MPxMayaAsciiFilter MPxMayaAsciiFilter MPxMayaAsciiFilter MPxMayaAsciiFilter MPxMayaAsciiFilter MPxMayaAsciiFilter
MPxMayaAsciiFilter MPxMayaAsciiFilter MPxMayaAsciiFilter MPxMayaAsciiFilter MPxMayaAsciiFilter MPxMayaAsciiFilter MPxMayaAsciiFilter MPxMayaAsciiFilter MPxMayaAsciiFilter MPxMayaAsciiFilter