meshOpCmd/polyModifierCmd.h

//-
// ==========================================================================
// Copyright 1995,2006,2008 Autodesk, Inc. All rights reserved.
//
// Use of this software is subject to the terms of the Autodesk
// license agreement provided at the time of installation or download,
// or which otherwise accompanies this software in either electronic
// or hard copy form.
// ==========================================================================
//+

#ifndef _polyModifierCmd
#define _polyModifierCmd
//
// 
// File: polyModifierCmd.h
//
// MEL Command: polyModifierCmd
//
// Author: Lonnie Li
//
// Overview:
//
//      polyModifierCmd is a generic base class designed to aid in modifying
//      polygonal meshes. All polys in Maya possess two features: construction
//      history and tweaks. Both of these have a large impact on the structure
//      of the object as well as how it can be further manipulated. However,
//      they cannot be easily implemented, which is the why we need this abstracted
//      class. polyModifierCmd will automatically handle the DG maintenance of
//      construction history and tweaks on a polygonal mesh.
//
//      To understand what effect both construction history and tweaks have on
//      a mesh, we need to understand the states of a node. There are three things
//      which will affect the state of a node regarding construction history and
//      tweaks. That is:
//
//      (1) Does construction history exist?
//      (2) Do tweaks exist?
//      (3) Is construction history turned on?
//
//      The answer to each of these questions changes how the mesh is interpreted,
//      which in turn affects how the mesh can be accessed/modified. Under each
//      circumstance, new modifications on the mesh go through a standard series
//      of events. To further illustrate how these affect the interpretation of
//      a mesh, we'll delve into each case separately looking at the problems
//      that we face in each case.
//
//      In the case where construction history exists, the existence of construction
//      history informs us that there is a single linear DG chain of nodes upstream
//      from the mesh node. That chain is the history chain. At the top of the chain
//      we have the "original" mesh and at the bottom we have the "final" mesh,
//      where "original" and "final" represent the respective state of the node with
//      regards to mesh's history. Each of these nodes are adjoined via the
//      inMesh/outMesh attributes, where in and out designate the dataflow into
//      and out of the node. Now, with that aside, attempting to modify a node
//      via mutator methods will always write the information onto the inMesh
//      attribute (except in the case of tweaks, where it writes to the cachedInMesh).
//      This presents a problem if history exists since a DG evaluation will overwrite
//      the inMesh of the mesh node, due to the connection from the outMesh of the
//      node directly upstream from the mesh. This will discard any modifications
//      made to the mesh.
//
//      So obviously modifying a mesh directly isn't possible when history exists.
//      To properly modify a mesh with history, we introduce the concept of a modifier
//      node. This polyModifierNode will encapsulate the operations on the mesh
//      and behave similarly to the other nodes in the history chain. The node will
//      then be inserted into the history chain so that on each DG evaluation, it
//      is always accounted for. The diagram below shows the before and after
//      of modifying a mesh with history.
//
//
//      Before modification:
//
//        ____                   ____
//       /    \                 /    \
//      | Hist | O --------> O | mesh | O
//       \____/  |           |  \____/  |
//            outMesh      inMesh    outMesh
//
//
//      After modification:
//
//        ____                   ________                   ____
//       /    \                 /        \                 /    \
//      | Hist | O --------> O | modifier | O --------> O | mesh | O
//       \____/  |           |  \________/  |           |  \____/  |
//            outMesh      inMesh        outMesh      inMesh    outMesh
//
//
//      (Figure 1. Nodes with History)
//
//
//      In the case of tweaks: Tweaks are stored on a hidden attribute on the
//      mesh. Tweaks are manual component modifications on a mesh (eg. repositioning
//      a vertex). During a DG evaluation, the DG takes the inMesh attribute of
//      the node and adds the tweak values onto it to get the final value. From this
//      knowledge we can see that inserting a modifier node ahead of the mesh node
//      reverses the order of operations which can be crucial to the structure of the
//      resulting mesh if the modification is a topological change. To avoid this
//      problem, we retrieve the tweaks off of the mesh, remove it from the mesh and
//      place the tweaks into a polyTweak node. The tweak node is then inserted ahead
//      of the modifier node to preserve the order of operations:
//
//
//      Before modification:
//
//                               Tweak
//        ____                   __O__
//       /    \                 /     \
//      | Hist | O --------> O | mesh  | O
//       \____/  |           |  \_____/  |
//            outMesh      inMesh     outMesh
//
//
//      After modification:
//
//                                                                      Empty Tweak
//        ____                _____                ________                __O__
//       /    \              /     \              /        \              /     \
//      | Hist | O -----> O | Tweak | O -----> O | modifier | O -----> O | mesh  | O
//       \____/  |        |  \_____/  |        |  \________/  |        |  \_____/  |
//            outMesh   inMesh     outMesh   inMesh        outMesh   inMesh     outMesh
//
//
//      (Figure 2. Node with Tweaks)
//      
//
//      The last of the questions deals with whether or not the user has construction
//      history turned on or off. This will change how the node should be modified
//      as well as what the node will look like in the DG following the operation. With
//      history turned on, the user has selected that they would like to keep a
//      history chain. So in that case, the resulting mesh would look like the above
//      diagrams following the operation. On the other hand, with history turned off,
//      the user has selected that they would not like to see a history chain. From here
//      there are two possible choices to modify the mesh:
//
//      (1) Operate on the mesh directly
//      (2) Use the DG, like in the above diagrams, then collapse the nodes down into the mesh.
//
//      The only exception to note out of this case is that if the node already possesses
//      history (as would be answered by the first question), this preference is ignored.
//      If a node has history, we continue to use history. The user is imposed with the
//      task of deleting the history on the object first if they would not like to continue
//      using history.
//
//
//      With History:
//
//        ____                   ____
//       /    \                 /    \
//      | Hist | O --------> O | mesh | O
//       \____/  |           |  \____/  |
//            outMesh      inMesh    outMesh
//
//
//      Without History:
//
//            ____
//           /    \
//        O | mesh | O     (All history compressed onto the inMesh attribute)
//        |  \____/  |
//      inMesh    outMesh
//
//
//      (Figure 3. Node with History preference)
//
//
//      This section has described the "why" part of the question regarding this command.
//      Following sections will provide a more in depth look at "how" this command
//      treats each of these situations and what it really does behind the scenes
//      to handle the above cases.
//
//
// How it works:
//
//      This command approaches the various node state cases similarly to the way
//      Maya works with construction history and tweaks in polygons. It is important
//      to note that history and tweaks are independent states having no effect on
//      each other (in terms of their state). Thus this section will describe each
//      case independently:
//
//      1) History
//
//          For history, there are 4 cases that need to be considered:
//
//          (a) History (yes)   -   RecordHistory (yes)
//          (b) History (yes)   -   RecordHistory (no)
//          (c) History (no)    -   RecordHistory (yes)
//          (d) History (no)    -   RecordHistory (no)
//
//          For (a) and (b), this command treats the node identically. Regardless of
//          whether recording history is turned on or off, if history already exists
//          on the node, we treat the node as though recording history is on. As such
//          the command performs the following steps:
//
//              (i)     Create a modifier node.
//              (ii)    Find the node directly upstream to the mesh node.
//              (iii)   Disconnect the upstream node and the mesh node.
//              (iv)    Connect the upstream node to the modifier node.
//              (v)     Connect the modifier node to the mesh node.
//              (vi)    Done!
//
//          For (c), polyModifierCmd needs to generate an input mesh to drive the
//          modifier node. To do this, the mesh node is duplicated and connected
//          like the upstream node in the previous two cases:
//
//              (i)     Create a modifier node.
//              (ii)    Duplicate the mesh node.
//              (iii)   Connect the duplicate mesh node to the modifier node
//              (iv)    Connect the modifier node to the mesh node
//              (v)     Done!
//
//          For (d), this command is a bit more complicated. There are two approaches
//          that can be done to respect the fact that no history is desired. The first
//          involves using the approach in case (c) and simply "baking" or "flattening"
//          the nodes down into the mesh node. Unfortunately, this presents some
//          serious problems with undo, as the Maya API in its current state does not
//          support construction history manipulation. Resorting to the MEL command:
//          "delete -ch" would be possible, however undoing the operation would not be
//          trivial as calling an undo from within an undo could destabilize the undo
//          queue.
//
//          The second alternative and one that is currently implemented by this class
//          is to respect the "No Construction History" preference strictly by
//          not modifying the history chain at all and simply operating directly on the
//          mesh. In order to do this and maintain generality, a hook is provided for
//          derived classes to override and place in the code used to directly modify the
//          mesh. polyModifierCmd will only call this method under the circumstances
//          of case (d). To prevent code duplication between the operations done in the
//          modifierNode and the command's directModifier implementation, the concept of
//          a factory is used. It is recommended that an instance of such a factory is
//          stored locally on the command much like it will be on the node. See
//          polyModifierNode.h and polyModifierFty.h for more details.
//
//
//      2) Tweaks
//
//          Tweaks are handled as noted above in the description section. However, how
//          they are treated is dependent on the state of history. Using the four cases
//          above:
//
//          For (a), (b) and (c), it is as described in the description section:
//
//              (i)     Create a tweak node.
//              (ii)    Extract the tweaks from the mesh node.
//              (iii)   Copy the tweaks onto the tweak node.
//              (iv)    Clear the tweaks from the mesh node.
//              (v)     Clear the tweaks from the duplicate mesh node (for case (c) only!)
//
//          For (d), we have yet another limitation. Tweaks are not handled in this case
//          because of the same circumstances which give rise to the limitation in the
//          history section. As such, topological changes may result in some odd behaviour
//          unless the workaround provided in the limitations section is used.
//
//
// How to use:
//
//      To use this command there are several things that are required based on the needs
//      of the command:
//
//      Step 1: polyModifierFty
//
//      1) Create a factory derived from polyModifierFty
//      2) Find and assign any inputs that your modifier will need onto the factory.
//      3) Override the polyModifierFty::doIt() method of the factory
//      4) Place your modifier code into the doIt() method of the factory
//
//      Step 2: polyModifierNode
//
//      1) Create a node derived from polyModifierNode
//      2) Add any additional input attributes onto the node
//      3) Associate the attributes (ie. inMesh --> affects --> outMesh)
//      4) Add an instance of your polyModifierFty to the node
//      5) Override the MPxNode::compute() method
//      6) Retrieve inputs from attributes, setup the factory and call its doIt() in compute()
//
//      Step 3: polyModifierCmd
//
//      1) Create a command derived from polyModifierCmd
//
//      ---
//
//      2) Override the polyModifierCmd::initModifierNode() method
//      3) Place your node setup code inside the initModifierNode()
//
//      ---
//
//      4) Add an instance of your polyModifierFty to the command
//      5) Cache any input parameters for the factory on the command
//      6) Override the polyModifierCmd::directModifier() method
//      7) Place your factory setup code and call its doIt() in directModifier()
//
//      ---
//
//      8) Override the MPxCommand::doIt() method
//      9) Place your setup code inside the doIt()
//      10) Place the polyModifierCmd setup code inside the doIt()
//          (ie. setMeshNode(), setModifierNodeType())
//      11) Call polyModifierCmd::doModifyPoly() inside the doIt()
//
//      ---
//
//      12) Override the MPxCommand::redoIt() method
//      13) Call polyModifierCmd::redoModifyPoly() in redoIt()
//
//      ---
//
//      14) Override the MPxCommand::undoIt() method
//      15) Call polyModifierCmd::undoModifyPoly() in undoIt()
//
//      For more details on each of these steps, please visit the associated method/class
//      headers.
//
//
// Limitations:
//
//      There is one limitation in polyModifierCmd:
//
//      (1) Duplicate mesh created under the "No History / History turned on" case not undoable
//
//      Case (1):
//
//          Under the "No History / History turned on" case, history is allowed so the DG
//          is used to perform the operation. However, every polyModifierNode requires
//          an input mesh and without any prior history, a mesh input needs to be created.
//          polyModifierCmd compensates for this by duplicating the meshNode and marking
//          it as an intermediate object.
//
//          The problem with this duplication is that the only duplicate method in the
//          Maya API resides in MFnDagNode, which does not have an associated undo/redo
//          mechanism. Attempting to manually delete the node by use of a DGmodifier or
//          the MEL delete command will break the undo/redo mechanism for the entire
//          command. As a result, this duplicate mesh is a remnant of each instance of the
//          command excluding undo/redo.
//
//          To work past this limitation, a manual delete from the MEL command line is
//          required.
//

// General Includes
//
#include <maya/MIntArray.h>
#include <maya/MFloatVectorArray.h>
#include <maya/MDagPath.h>
#include <maya/MDGModifier.h>
#include <maya/MDagModifier.h>
#include <maya/MPlug.h>

// Proxies
//
#include <maya/MPxCommand.h>


class polyModifierCmd : public MPxCommand
{
public:

                            polyModifierCmd();
    virtual                 ~polyModifierCmd();

// Restrict access to derived classes only
//
protected:

    // polyModifierCmd Initialization //

    // Target polyMesh to modify
    //
    void                            setMeshNode( MDagPath mesh );
    MDagPath                        getMeshNode() const;

    // Modifier Node Type
    //
    void                            setModifierNodeType( MTypeId type );
    void                            setModifierNodeName( MString name );
    MTypeId                         getModifierNodeType() const;
    MString                         getModifierNodeName() const;

    // polyModifierCmd Execution //

    // initModifierNode - Derived classes should override this method if
    //                    they wish to initialize input attributes on the 
    //                    modifierNode
    //
    virtual MStatus                 initModifierNode( MObject modifierNode );

    // directModifier - Derived classes should override this method to provide
    //                  direct modifications on the meshNode in the case where
    //                  no history exists and construction history is turned off.
    //                  (ie. no DG operations desired)
    //
    //                  This method is called only if history does not exist and
    //                  history is turned off. At this point, a handle to the
    //                  meshNode is passed in so a derived class may directly
    //                  modify the mesh.
    //
    virtual MStatus                 directModifier( MObject mesh );

    MStatus                         doModifyPoly();
    MStatus                         redoModifyPoly();
    MStatus                         undoModifyPoly();

private:

    // polyModifierCmd Internal Processing Data //

    // This structure is used to maintain the data vital to the modifyPoly method.
    // It is necessary to simplify parameter passing between the methods used inside
    // modifyPoly (specifically inside connectNodes()). The diagram below dictates
    // the naming style used:
    //
    // NOTE: modifierNode is intentionally left out of this structure since it
    //       is given protected access to derived classes.
    //
    // Before:
    //
    // (upstreamNode) *src -> dest* (meshNode)
    //
    // After:
    //
    // (upstreamNode) *src -> dest* (modifierNode) *src -> dest* (meshNode)
    //
    struct modifyPolyData
    {
        MObject meshNodeTransform;
        MObject meshNodeShape;
        MPlug   meshNodeDestPlug;
        MObject meshNodeDestAttr;

        MObject upstreamNodeTransform;
        MObject upstreamNodeShape;
        MPlug   upstreamNodeSrcPlug;
        MObject upstreamNodeSrcAttr;

        MObject modifierNodeSrcAttr;
        MObject modifierNodeDestAttr;

        MObject tweakNode;
        MObject tweakNodeSrcAttr;
        MObject tweakNodeDestAttr;
    };

    // polyModifierCmd Internal Methods //

    bool                    isCommandDataValid();
    void                    collectNodeState();

    // Modifier node methods
    //
    MStatus                 createModifierNode( MObject& modifierNode );

    // Node processing methods (need to be executed in this order)
    //
    MStatus                 processMeshNode( modifyPolyData& data );
    MStatus                 processUpstreamNode( modifyPolyData& data );
    MStatus                 processModifierNode( MObject modifierNode,
                                                 modifyPolyData& data );
    MStatus                 processTweaks( modifyPolyData& data );

    // Node connection method
    //
    MStatus                 connectNodes( MObject modifierNode );

    // Mesh caching methods - Only used in the directModifier case
    //
    MStatus                 cacheMeshData();
    MStatus                 cacheMeshTweaks();

    // Undo methods
    //
    MStatus                 undoCachedMesh();
    MStatus                 undoTweakProcessing();
    MStatus                 undoDirectModifier();

    // polyModifierCmd Utility Methods //

    MStatus                 getFloat3PlugValue( MPlug plug, MFloatVector& value );
    MStatus                 getFloat3asMObject( MFloatVector value, MObject& object );

    // polyModifierCmd Data //

    // polyMesh
    //
    bool                fDagPathInitialized;
    MDagPath            fDagPath;
    MDagPath            fDuplicateDagPath;

    // Modifier Node Type
    //
    bool                fModifierNodeTypeInitialized;
    bool                fModifierNodeNameInitialized;
    MTypeId             fModifierNodeType;
    MString             fModifierNodeName;

    // Node State Information
    //
    bool                fHasHistory;
    bool                fHasTweaks;
    bool                fHasRecordHistory;

    // Cached Tweak Data (for undo)
    //
    MIntArray           fTweakIndexArray;
    MFloatVectorArray   fTweakVectorArray;

    // Cached Mesh Data (for undo in the 'No History'/'History turned off' case)
    //
    MObject             fMeshData;

    // DG and DAG Modifier
    //
    //    - We need both DAG and DG modifiers since the MDagModifier::createNode()
    //      method is overridden and specific to DAG nodes. So to keep
    //      the operations consistent we will only use the fDagModifier
    //      when dealing with the DAG.
    //
    //    - There is a limitation between the reparentNode() and deleteNode()
    //      methods on the MDagModifier. The deleteNode() method does some
    //      preparation work before it enqueues itself in the MDagModifier list
    //      of operations, namely, it looks at it's parents and children and
    //      deletes them as well if they are the only parent/child of the node
    //      scheduled to be deleted.
    //
    //      This conflicts with our call to MDagModifier::reparentNode(),
    //      since we want to reparent the shape of a duplicated node under
    //      another node and then delete the transform of that node. Now you 
    //      can see that since the reparentNode() doesn't execute until after
    //      the MDagModifier::doIt() call, the scheduled deleteNode() call
    //      still sees the child and marks it for delete. The subsequent
    //      doIt() call reparents the shape and then deletes both it and the
    //      transform.
    //
    //      To avoid this conflict, we separate the calls individually and
    //      perform the reparenting (by calling a doIt()) before the deleteNode()
    //      method is enqueued on the modifier.
    //
    MDGModifier         fDGModifier;
    MDagModifier        fDagModifier;
};

//
// Inlines
//

// polyMesh
//
inline void polyModifierCmd::setMeshNode( MDagPath mesh )
{
    fDagPath = mesh;
    fDagPathInitialized = true;
}

inline MDagPath polyModifierCmd::getMeshNode() const
{
    return fDagPath;
}

// Modifier Node Type
//
inline void polyModifierCmd::setModifierNodeType( MTypeId type )
{
    fModifierNodeType = type;
    fModifierNodeTypeInitialized = true;
}

inline void polyModifierCmd::setModifierNodeName( MString name )
{
    fModifierNodeName = name;
    fModifierNodeNameInitialized = true;
}

inline MTypeId polyModifierCmd::getModifierNodeType() const
{
    return fModifierNodeType;
}

inline MString polyModifierCmd::getModifierNodeName() const
{
    return fModifierNodeName;
}

#endif