MFnAssembly Class Reference

#include <MFnAssembly.h>

Class Description

Function set for scene assembly.

An assembly is a node that is used to maintain a list of representations, and to keep one as the active representation. Correspondingly, representations can be activated and inactivated. In general, a representation can be a full hierarchy of animated geometry, but can also be as simple as a locator or a bounding box. The assembly can be used to activate the representation that best corresponds to a given task: a simple, fast-loading, fast-drawing representation for overall planning, or a more detailed representations for fine tuning.

The assembly API does not specify the implementation of representations. For example, representations can be actual DAG nodes, or data structures internal to the assembly that can be used to generate DAG nodes in the Maya scene graph on representation activation. In this function set as well as in MPxAssembly, representations are identified only by a string identifier. Representations in a single MPxAssembly must have unique string names. Representation name strings must not contain spaces and quotes, as these characters would cause argument parsing to fail when names are used in commands.

Representations are created from a set of representation types, which each assembly type must define. A representation of a given type will share properties (such as viewport appearance, or memory size) with other representations of the same type. Examples could include a "BoundingBox" representation type, or a "BakedGeometry" representation type. As with representation names, representation type name strings must not contain spaces and quotes. Representation type names are not used in the UI, and are not localized. Rather, each representation type has a corresponding type label that is used for this purpose. The representation type label can contain spaces and quotes, and should be localized.

An assembly object is also a DAG container. As such, operations on containers can be done on assemblies. For use of container functionality on assemblies, see function set MFnContainerNode.

Scene Assembly Services

Scene assembly nodes are DAG container nodes that provide the following services:

Fidelity / performance tradeoff

Assembly nodes have a single active representation, chosen from a list of available representations, to best suit the task at hand, and / or the size of the data set.

Scene segmentation

Assembly nodes represent a part of a scene that can be loaded and unloaded efficiently as a block, and that can be worked upon separately and cooperatively.

Non-destructive edits

Assembly nodes can track certain edits done on their members. These edits are non-destructive and recorded separately from the representation data onto which they are applied.

Plugin extensibility

Scene assembly is fully exposed through the OpenMaya API, and its Autodesk reference implementation is done through this API, to ensure parity of capability between third-party scene assembly node implementations, and Autodesk implementations.

DAG containment
Scene assembly nodes inherit the same capabilities as their DAG container class parents, namely an embodiment in the 3D scene hierarchy as transforms, as well as encapsulating containment of their member nodes, which are created by activating a representation.
+ Examples:
+ Inheritance diagram for MFnAssembly:

Public Member Functions

virtual MFn::Type type () const
 Function set type. More...
 
virtual ~MFnAssembly ()
 Destructor.
 
 MFnAssembly ()
 Default constructor.
 
 MFnAssembly (MObject &object, MStatus *ReturnStatus=NULL)
 Constructor. More...
 
 MFnAssembly (const MDagPath &object, MStatus *ret=NULL)
 Constructor. More...
 
MString createRepresentation (const MString &input, const MString &type, MDagModifier *undoRedo=NULL, MStatus *status=NULL)
 Create a representation and add it to the list of those managed by this node. More...
 
MString createRepresentation (const MString &input, const MString &type, const MString &representation, MDagModifier *undoRedo=NULL, MStatus *status=NULL)
 Create a representation and add it to the list of those managed by this node. More...
 
MStatus postLoad ()
 Method to initialize assemblies after their creation. More...
 
MStatus activate (const MString &representation)
 Activate a representation. More...
 
MString getActive (MStatus *status=NULL) const
 Get the active representation in the list of representations. More...
 
MStatus activateNonRecursive (const MString &representation)
 Activate a representation, but prevent any nested assemblies created and initialized during this activation from activating any of their representations. More...
 
bool canActivate (MStatus *status=NULL) const
 Determines whether this assembly can activate a representation, for the node attached to this function set. More...
 
bool isActive (const MString &representation, MStatus *status=NULL) const
 Determines whether the given representation is the active representation for the node attached to this function set. More...
 
MString getInitialRep (MStatus *status=NULL) const
 
MString getInitialRep (bool &hasInitialRep, MStatus *status=NULL) const
 Get the initial representation to use when the assembly is first loaded. More...
 
MStringArray getRepresentations (MStatus *status=NULL) const
 Returns an array of the representations managed by the node attached to this function set. More...
 
MString getRepType (const MString &representation, MStatus *status=NULL) const
 Get the type of the specified representation. More...
 
MString getRepLabel (const MString &representation, MStatus *status=NULL) const
 Get the label of the specified representation. More...
 
MStringArray repTypes (MStatus *status=NULL) const
 Return the list of representation types that can be created for this assembly node. More...
 
MStatus deleteRepresentation (const MString &representation)
 Delete a representation managed by the node attached to this function set. More...
 
MStatus deleteAllRepresentations ()
 Delete all representations managed by the node attached to this function set. More...
 
MString getRepNamespace (MStatus *status=NULL) const
 Get the representations namespace of this assembly node. More...
 
MString setRepName (const MString &representation, const MString &newName, MStatus *status=NULL)
 Rename a representation. More...
 
MStatus setRepLabel (const MString &representation, const MString &label)
 Change the representation label. More...
 
MStatus importFile (const MString &fileName, const char *type=NULL, bool preserveReferences=false, const char *nameSpace=NULL, bool ignoreVersion=false)
 Import the scene elements from the given file into this assembly. More...
 
MString getAbsoluteRepNamespace (MStatus *status=NULL) const
 Get the fully-qualified (absolute) namespace for representations of this assembly node. More...
 
bool isTopLevel (MStatus *status=NULL) const
 Returns whether this assembly node is a top-level assembly. More...
 
bool supportsEdits (MStatus *status=NULL) const
 Does this assembly support edit tracking? More...
 
bool supportsMemberChanges (MStatus *status=NULL) const
 Can members of the assembly be changed? More...
 
bool canRepApplyEdits (const MString &representation, MStatus *status=NULL) const
 Determines whether the given representation can apply edits to its data, for the node attached to this function set. More...
 
bool handlesAddEdits (MStatus *status=NULL) const
 Determines whether the assembly supplies edits to its data, for the node attached to this function set. More...
 
MObject getParentAssembly (MStatus *status=NULL) const
 Return the immediate parent assembly of this assembly if there is one, otherwise return a null object. More...
 
MObjectArray getSubAssemblies (MStatus *status=NULL) const
 Returns a list containing direct children of this assembly that are themselves assemblies, for the currently active representation. More...
 
 MFnAssembly (const MObject &object, MStatus *ret=NULL)
 Constructor. More...
 
- Public Member Functions inherited from MFnDagNode
virtual ~MFnDagNode ()
 Destructor. More...
 
 MFnDagNode ()
 Class Constructor. More...
 
 MFnDagNode (MObject &object, MStatus *ret=NULL)
 This method is not available in Python. More...
 
 MFnDagNode (const MDagPath &object, MStatus *ret=NULL)
 Class Constructor. More...
 
MObject create (const MTypeId &typeId, MObject &parent=MObject::kNullObj, MStatus *ReturnStatus=NULL)
 Creates a new DAG node with the given type tag. More...
 
MObject create (const MTypeId &typeId, const MString &name, MObject &parent=MObject::kNullObj, MStatus *ReturnStatus=NULL)
 Creates a new DAG node with the given type tag. More...
 
MObject create (const MString &type, MObject &parent=MObject::kNullObj, MStatus *ReturnStatus=NULL)
 Creates a new DAG node with the given type tag. More...
 
MObject create (const MString &type, const MString &name, MObject &parent=MObject::kNullObj, MStatus *ReturnStatus=NULL)
 Creates a new DAG node with the given type tag. More...
 
unsigned int parentCount (MStatus *ReturnStatus=NULL) const
 Determines the number of parent Nodes of the Node. More...
 
MObject parent (unsigned int i, MStatus *ReturnStatus=NULL) const
 Queries the DAG Node attached to the Function Set for the parent Node corresponding to the given index. More...
 
MStatus addChild (MObject &child, unsigned int index=kNextPos, bool keepExistingParents=false)
 Makes the given DAG Node a child of the DAG Node to which this instance of the Function Set is attached. More...
 
MStatus removeChild (MObject &child)
 Removes the given DAG Node from the parent. More...
 
MStatus removeChildAt (unsigned int index)
 Removes the child at the given index from the parent. More...
 
unsigned int childCount (MStatus *ReturnStatus=NULL) const
 Determines the number of child Nodes of the Node. More...
 
MObject child (unsigned int i, MStatus *ReturnStatus=NULL) const
 Queries the DAG Node attached to the Function Set for the child Node corresponding to the given index. More...
 
MObject dagRoot (MStatus *ReturnStatus=NULL)
 Determines the root of the first DAG Path to the DAG Node attached to the Function Set. More...
 
bool hasParent (const MObject &node, MStatus *ReturnStatus=NULL) const
 Determines whether or not the given Node is a parent of the DAG Node attached to the Function Set. More...
 
bool hasChild (const MObject &node, MStatus *ReturnStatus=NULL) const
 Determines whether or not the given Node is a child of the DAG Node attached to the Function Set. More...
 
bool isChildOf (const MObject &node, MStatus *ReturnStatus=NULL) const
 Determines whether or not the DAG Node attached to the Function Set is a child of the given node. More...
 
bool isParentOf (const MObject &node, MStatus *ReturnStatus=NULL) const
 Determines whether or not the DAG Node attached to the Function Set is a parent of the given node. More...
 
bool inUnderWorld (MStatus *ReturnStatus=NULL) const
 Determines whether or not the DAG Node is an underworld node. More...
 
bool inModel (MStatus *ReturnStatus=NULL) const
 Determines whether or not the DAG Node is in the model. More...
 
bool isInstanceable (MStatus *ReturnStatus=NULL) const
 Returns true if the DAG node can be instanced, and false otherwise. More...
 
MStatus setInstanceable (const bool how)
 Sets whether or not the DAG node is instanceable. More...
 
bool isInstanced (bool indirect=true, MStatus *ReturnStatus=NULL) const
 Determines whether the DAG Node attached to the Function Set is directly or indirectly instanced. More...
 
bool isInstancedAttribute (const MObject &attr, MStatus *ReturnStatus=NULL) const
 Returns true if the specified attribute is instanced. More...
 
unsigned int instanceCount (bool total, MStatus *ReturnStatus=NULL) const
 Determines the number of times the Node attached to the Function Set is instanced. More...
 
MObject duplicate (bool instance=false, bool instanceLeaf=false, MStatus *ReturnStatus=NULL) const
 This method duplicates the DAG hierarchy rooted at the current node. More...
 
MStatus getPath (MDagPath &path) const
 Returns a DAG Path to the DAG Node attached to the Function Set. More...
 
MStatus getAllPaths (MDagPathArray &paths) const
 Determines all DAG Paths to the DAG Node attached to the Function Set. More...
 
MString fullPathName (MStatus *ReturnStatus=NULL) const
 Return a string representing the full path from the root of the dag to this object. More...
 
MString partialPathName (MStatus *ReturnStatus=NULL) const
 Return a string representing the partial path from the root of the dag to this object. More...
 
MMatrix transformationMatrix (MStatus *ReturnStatus=NULL) const
 Returns the object space transformation matrix for this DAG node. More...
 
bool isIntermediateObject (MStatus *ReturnStatus=NULL) const
 Returns true if this object is an intermediate in a geometry calculation. More...
 
MStatus setIntermediateObject (bool isIntermediate)
 Sets whether this object is an intermediate in a geometry calculation. More...
 
int objectColor (MStatus *ReturnStatus=NULL) const
 This method is obsolete. More...
 
MStatus setObjectColor (int color)
 Sets the index for the current user defined inactive color used by the node. More...
 
bool usingObjectColor (MStatus *ReturnStatus=NULL) const
 
MStatus setUseObjectColor (bool useObjectColor)
 
MObjectColorType objectColorType (MStatus *ReturnStatus=NULL) const
 Determines whether or not the user defined inactive color will be used for the node, or whether the default inactive color will be used. More...
 
MStatus setObjectColorType (MObjectColorType type)
 Sets whether or not the user defined inactive object color will be used. More...
 
MStatus setObjectColor (const MColor &color)
 Sets the color value for the current user defined inactive color used by the node. More...
 
MColor objectColorRGB (MStatus *ReturnStatus=NULL) const
 Determines the RGB color for the current user defined inactive color used by the node. More...
 
int objectColorIndex (MStatus *ReturnStatus=NULL) const
 Determines the index for the current user defined inactive color used by the node. More...
 
MColor hiliteColor (MStatus *ReturnStatus=NULL) const
 Determines the current hilite color used by the node. More...
 
bool usingHiliteColor (MStatus *ReturnStatus=NULL) const
 Determines whether or not the hilite color will be used for the node. More...
 
MColor dormantColor (MStatus *ReturnStatus=NULL) const
 Determines the dormant color used by this node. More...
 
MColor activeColor (MStatus *ReturnStatus=NULL) const
 Determines the active color used by this node. More...
 
bool drawOverrideEnabled (MStatus *ReturnStatus=NULL) const
 Determines whether or not draw override is turned on for this node. More...
 
bool drawOverrideIsReference (MStatus *ReturnStatus=NULL) const
 Determines whether or not Display Type of the draw override is Reference for this node. More...
 
bool drawOverrideIsTemplate (MStatus *ReturnStatus=NULL) const
 Determines whether or not Display Type of the draw override is Template for this node. More...
 
bool drawOverrideColor (MColor &color, MStatus *ReturnStatus=NULL) const
 Determines the draw override color used by this node. More...
 
MStatus getConnectedSetsAndMembers (unsigned int instanceNumber, MObjectArray &sets, MObjectArray &comps, bool renderableSetsOnly) const
 Returns all the sets connected to the specified instance of this DAG object. More...
 
MBoundingBox boundingBox (MStatus *ReturnStatus=NULL) const
 Returns the bounding box for the dag node in object space. More...
 
MDagPath dagPath (MStatus *ReturnStatus=NULL) const
 Returns the DagPath to which the Function Set is attached. More...
 
virtual MStatus setObject (const MDagPath &path)
 Attaches Function Set to the DAG Node that has the given DAG Path. More...
 
virtual MStatus setObject (MObject &object)
 Attaches Function Set to given DAG Node. More...
 
MObject model (MStatus *ReturnStatus=NULL) const
 This method is obsolete. More...
 
 MFnDagNode (const MObject &object, MStatus *ret=NULL)
 No script support. More...
 
virtual MStatus setObject (const MObject &object)
 No script support. More...
 
- Public Member Functions inherited from MFnDependencyNode
virtual ~MFnDependencyNode ()
 Destructor.
 
 MFnDependencyNode ()
 Default constructor.
 
 MFnDependencyNode (MObject &object, MStatus *ReturnStatus=NULL)
 Constructor. More...
 
MObject create (const MTypeId &typeId, MStatus *ReturnStatus=NULL)
 Creates a new dependency node with the given type tag. More...
 
MObject create (const MTypeId &typeId, const MString &name, MStatus *ReturnStatus=NULL)
 Creates a new dependency node with the given type tag. More...
 
MObject create (const MString &type, MStatus *ReturnStatus=NULL)
 Creates a new dependency node with the given type. More...
 
MObject create (const MString &type, const MString &name, MStatus *ReturnStatus=NULL)
 Creates a new dependency node with the given type. More...
 
MTypeId typeId (MStatus *ReturnStatus=NULL) const
 Returns the type id of this node. More...
 
MString typeName (MStatus *ReturnStatus=NULL) const
 Returns the type name of this node. More...
 
MString name (MStatus *ReturnStatus=NULL) const
 Returns the name of this node. More...
 
MString absoluteName (MStatus *ReturnStatus=NULL) const
 Returns the absolute name of this node. More...
 
MString pluginName (MStatus *ReturnStatus=NULL) const
 Returns the name of the plug-in this MFnDependendencyNode was defined in. More...
 
MString setName (const MString &name, bool createNamespace=false, MStatus *ReturnStatus=NULL)
 Sets the name of this node. More...
 
MUuid uuid (MStatus *ReturnStatus=NULL) const
 Returns the node's UUID. More...
 
void setUuid (const MUuid &uuid, MStatus *ReturnStatus=NULL)
 Sets the node's UUID. More...
 
MStatus getConnections (MPlugArray &array) const
 Get all of the current connections to this node as an array of plugs. More...
 
unsigned int attributeCount (MStatus *ReturnStatus=NULL) const
 Returns the number of attributes that this node has. More...
 
MObject attribute (unsigned int index, MStatus *ReturnStatus=NULL) const
 Finds the attribute of this node at the given index. More...
 
MObject reorderedAttribute (unsigned int index, MStatus *ReturnStatus=NULL) const
 Some nodes, such as the various animCurve nodes, require that their attributes be set in a specific order for proper operation. More...
 
MObject attribute (const MString &attrName, MStatus *ReturnStatus=NULL) const
 Finds the attribute of this node that has the given name. More...
 
MAttrClass attributeClass (const MObject &attr, MStatus *ReturnStatus=NULL) const
 Returns the class (normal, dynamic, extension) of the specified attribute. More...
 
MStatus getAffectedAttributes (const MObject &attr, MObjectArray &affectedAttributes) const
 Returns an array of attributes that are affected by the attribute passed in. More...
 
MStatus getAffectedByAttributes (const MObject &attr, MObjectArray &affectedByAttributes) const
 Returns an array of attributes that affect the attribute passed in, attr. More...
 
MPlug findPlug (const MObject &attr, bool wantNetworkedPlug, MStatus *ReturnStatus=NULL) const
 Attempt to find a plug for the given attribute. More...
 
MPlug findPlug (const MString &attrName, bool wantNetworkedPlug, MStatus *ReturnStatus=NULL) const
 Attempt to find a plug for the given attribute. More...
 
MPlug findPlug (const MObject &attr, MStatus *ReturnStatus=NULL) const
 This method is obsolete. More...
 
MPlug findPlug (const MString &attrName, MStatus *ReturnStatus=NULL) const
 This method is obsolete. More...
 
MStatus addAttribute (const MObject &attr)
 Add a new dynamic attibute to this node. More...
 
MStatus removeAttribute (const MObject &attr)
 Remove a dynamic attribute from a node. More...
 
MPxNodeuserNode (MStatus *ReturnStatus=NULL) const
 If the function set's node is a plug-in node, then this method will extract the MPxNode pointer from it. More...
 
bool isFromReferencedFile (MStatus *ReturnStatus=NULL) const
 Indicates whether or not this node came from a referenced file. More...
 
bool isShared (MStatus *ReturnStatus=NULL) const
 Indicates whether or not this node is shared. More...
 
bool isTrackingEdits (MStatus *ReturnStatus=NULL) const
 Returns whether or not edits on the given node are being tracked by the generalized edit system. More...
 
bool hasUniqueName (MStatus *ReturnStatus=NULL) const
 Indicates whether or not this node's name is unique within the scene. More...
 
MString parentNamespace (MStatus *ReturnStatus=NULL) const
 Returns the name of the namespace in which this node resides. More...
 
bool isLocked (MStatus *ReturnStatus=NULL) const
 Indicates whether or not this node is locked. More...
 
MStatus setLocked (bool locked)
 Locks or unlocks this node. More...
 
bool isNewAttribute (const MObject &attr, MStatus *ReturnStatus=NULL) const
 Indicates whether or not the specified attribute was added to this node within the current scene. More...
 
MStatus setFlag (unsigned int flag, bool state)
 Sets the state of the specified flag for the node. More...
 
bool isFlagSet (unsigned int flag, MStatus *ReturnStatus=NULL) const
 Retrieves the current state of the specified flag for a node. More...
 
bool isDefaultNode (MStatus *ReturnStatus=NULL) const
 Returns true if the node is a default node. More...
 
MStatus setDoNotWrite (bool flag)
 Use this method to mark the "do not write" state of this node. More...
 
bool canBeWritten (MStatus *ReturnStatus=NULL) const
 Returns the do not write state of the node. More...
 
bool hasAttribute (const MString &name, MStatus *ReturnStatus=NULL) const
 Returns true if the node already has an attribute with the given name. More...
 
MObject getAliasAttr (bool force, MStatus *ReturnStatus=NULL)
 Returns the node's alias attribute, which is a special attribute used to store information about the node's attribute aliases. More...
 
bool setAlias (const MString &alias, const MString &name, const MPlug &plug, bool add=true, MStatus *ReturnStatus=NULL)
 Sets or removes an alias (i.e. More...
 
bool findAlias (const MString &alias, MObject &attrObj, MStatus *ReturnStatus=NULL) const
 Retrieves the attribute with the given alias. More...
 
bool getAliasList (MStringArray &strArray, MStatus *ReturnStatus=NULL)
 Returns a list of all attribute aliases for this node. More...
 
MString plugsAlias (const MPlug &plug, MStatus *ReturnStatus=NULL)
 Returns the alias for the plug's attribute or the empty string if that attribute has no alias. More...
 
MStatus setIcon (const MString &filename)
 Associates a custom icon with the node for display in the Maya UI. More...
 
MString icon (MStatus *ReturnStatus=NULL) const
 Returns the custom icon filename associated with the node. More...
 
MStatus getExternalContent (MExternalContentInfoTable &table) const
 Returns the external content (files) that this node depends on. More...
 
MStatus addExternalContentForFileAttr (MExternalContentInfoTable &table, const MObject &attr) const
 Adds content info to the specified table from a file path attribute. More...
 
MStatus setExternalContentForFileAttr (const MObject &attr, const MExternalContentLocationTable &table)
 Sets content info in the specified attribute from the table. More...
 
MStatus setExternalContent (const MExternalContentLocationTable &table)
 Changes the location of external content. More...
 
MString setName (const MString &name, MStatus *ReturnStatus)
 OBSOLETE FUNCTION, NO SCRIPT SUPPORT. More...
 
 MFnDependencyNode (const MObject &object, MStatus *ReturnStatus=NULL)
 NO SCRIPT SUPPORT. More...
 
bool getPlugsAlias (const MPlug &plug, MString &aliasName, MStatus *ReturnStatus=NULL)
 NO SCRIPT SUPPORT. More...
 
virtual const adsk::Data::Associationsmetadata (MStatus *ReturnStatus=NULL) const
 This method is not available in Python. More...
 
virtual MStatus setMetadata (const adsk::Data::Associations &)
 This method is not available in Python. More...
 
virtual MStatus deleteMetadata ()
 This method is not available in Python. More...
 
virtual MStatus validateMetadata (MString &errors) const
 This method is not available in Python. More...
 
MStatus dgTimerOn ()
 Indicates that this node should collect DG timing data whenever DG timing is enabled. More...
 
MStatus dgTimerOff ()
 Indicates that this node should no longer collect DG timing data when DG timing is enabled. More...
 
MdgTimerState dgTimerQueryState (MStatus *ReturnStatus=NULL)
 The function returns the current on/off state of the node's timer. More...
 
MStatus dgTimerReset ()
 The function resets the dependency graph timers and counters for this node to zero. More...
 
double dgTimer (const MdgTimerMetric timerMetric, const MdgTimerType timerType, MStatus *ReturnStatus=NULL) const
 The function returns the specified timer value for the current node. More...
 
MStatus dgCallbacks (const MdgTimerType type, MStringArray &callbackName, MDoubleArray &value)
 Node callbacks that occur when timing is enabled get logged with the node and can be queried via this method. More...
 
MStatus dgCallbackIds (const MdgTimerType type, const MString &callbackName, MCallbackIdArray &callbackId, MDoubleArray &value)
 This method provides a further breakdown of the per-callback time returned via dgCallbacks() by returning the data on a per-callbackId basis. More...
 
MStatus addAttribute (const MObject &attr, MAttrClass type)
 This method is obsolete. More...
 
MStatus removeAttribute (const MObject &attr, MAttrClass type)
 This method is obsolete. More...
 
- Public Member Functions inherited from MFnBase
virtual ~MFnBase ()
 Class Destructor. More...
 
bool hasObj (MFn::Type) const
 Determines whether or not the Function Set is compatible with the specified Maya Object within the API RTTI system. More...
 
bool hasObj (const MObject &) const
 Determines whether or not the Function Set is compatible with the specified Maya Object within the API RTTI system. More...
 
MObject object (MStatus *ReturnStatus=NULL) const
 Returns the MObject that is attached to the Function Set. More...
 

Static Public Member Functions

static MObjectArray getTopLevelAssemblies ()
 Returns a list containing top-level assemblies. More...
 
- Static Public Member Functions inherited from MFnDependencyNode
static MString classification (const MString &nodeTypeName)
 Retrieves the classification string for a node type. More...
 
static unsigned int allocateFlag (const MString pluginName, MStatus *ReturnStatus=NULL)
 Allocates a node flag for sole use by the caller. More...
 
static MStatus deallocateFlag (const MString pluginName, unsigned int flag)
 Deallocates a node flag which was previously allocated by a call to allocateFlag. More...
 
static MStatus deallocateAllFlags (const MString pluginName)
 Deallocates all of the node flags which are currently allocated to the specified plugin. More...
 
static void enableDGTiming (bool enable)
 Globally enables or disables the DG node timing mechanism. More...
 
- Static Public Member Functions inherited from MFnBase
static const char * className ()
 Returns the name of this class. More...
 

Protected Member Functions

virtual const char * className () const
 Class name. More...
 

Additional Inherited Members

- Public Types inherited from MFnDagNode
enum  { kNextPos = 0xff }
 Anonymous enum to store constant values. More...
 
enum  MObjectColorType { kUseDefaultColor = 0, kUseIndexColor, kUseRGBColor }
 Enum to set how an object is colored. More...
 
- Public Types inherited from MFnDependencyNode
enum  MAttrClass { kLocalDynamicAttr = 1, kNormalAttr, kExtensionAttr, kInvalidAttr }
 Specifies the scope of the attribute. More...
 
enum  MdgTimerState { kTimerOff, kTimerOn, kTimerUninitialized, kTimerInvalidState }
 Possible states for the node's timer. More...
 
enum  MdgTimerMetric {
  kTimerMetric_callback, kTimerMetric_compute, kTimerMetric_dirty, kTimerMetric_draw,
  kTimerMetric_fetch, kTimerMetric_callbackViaAPI, kTimerMetric_callbackNotViaAPI, kTimerMetric_computeDuringCallback,
  kTimerMetric_computeNotDuringCallback, kTimerMetrics
}
 The different timer metrics which can be queried. More...
 
enum  MdgTimerType { kTimerType_self, kTimerType_inclusive, kTimerType_count, kTimerTypes }
 The types of timers which can be queried. More...
 

Constructor & Destructor Documentation

MFnAssembly ( MObject object,
MStatus ReturnStatus = NULL 
)

Constructor.

Class constructor that initializes the function set to the given MObject.

Parameters
[in]objectThe MObject to attach the function set to
[out]ReturnStatusthe return status
Status Codes:
  • MS::kSuccess if the function set is successfully attached
  • MS::kInvalidParameter if the MObject does not represent a valid Maya object or if the function set is not allowed to attach to this MObject
MFnAssembly ( const MDagPath object,
MStatus ReturnStatus = NULL 
)

Constructor.

Class constructor that initializes the function set to the given constant MDagPath object.

Parameters
[in]objectThe const MDagPath to attach the function set to
[out]ReturnStatusThe return status
Status Codes:
  • MS::kSuccess if the function set is successfully attached
  • MS::kInvalidParameter if the MObject does not represent a valid Maya object or if the function set is not allowed to attach to this MObject
MFnAssembly ( const MObject object,
MStatus ReturnStatus = NULL 
)

Constructor.

Class constructor that initializes the function set to the given MObject.

Parameters
[in]objectThe MObject to attach the function set to
[out]ReturnStatusthe return status
Status Codes:
  • MS::kSuccess if the function set is successfully attached
  • MS::kInvalidParameter if the MObject does not represent a valid Maya object or if the function set is not allowed to attach to this MObject

Member Function Documentation

MFn::Type type ( ) const
virtual

Function set type.

Return the class type : MFn::kAssembly.

Reimplemented from MFnDagNode.

OPENMAYA_MAJOR_NAMESPACE_OPEN const char * className ( ) const
protectedvirtual

Class name.

Return the class name : "MFnAssembly".

Reimplemented from MFnDagNode.

MObjectArray getTopLevelAssemblies ( )
static

Returns a list containing top-level assemblies.

These are assemblies that are not nested inside another assembly.

The runtime complexity of this method is linear in the number of top-level assemblies and top-level file references.

Returns
Array of top-level assemblies.
MString createRepresentation ( const MString input,
const MString type,
MDagModifier undoRedo = NULL,
MStatus status = NULL 
)

Create a representation and add it to the list of those managed by this node.

The input argument string is used as input data to the representation creation process. The semantics of this input are defined by the assembly derived class. The representation return value string is the representation name, after it has been added. The type of the representation is a property of the representation that expresses its commonality with other representations of this assembly type, for example a "Bounding Box" representation type. See the getRepType() method.

Parameters
[in]inputInput data for representation creation.
[in]typeType of representation to create.
[out]undoRedoPointer to MDagModifier object, for undo / redo purposes.
[out]statusReturn status.
Returns
Added representation name.
Status Codes:
  • MS::kSuccess Representation creation succeeded.
  • MS::kFailure No valid node attached to function set, or representation creation failed.
MString createRepresentation ( const MString input,
const MString type,
const MString representation,
MDagModifier undoRedo = NULL,
MStatus status = NULL 
)

Create a representation and add it to the list of those managed by this node.

See alternate createRepresentation() overload for documentation. This overload version of createRepresentation() allows passing in a representation name. If passed in non-empty, the representation argument is used as a starting point for the representation name. This string value can be modified by the derived implementation to meet representation name uniqueness, or other constraints. If empty, the implementation is responsible for creating the representation name. The final representation name is returned by this method, after it has been added to the assembly.

Parameters
[in]inputInput data for representation creation.
[in]typeType of representation to create.
[in]representationRepresentation name starting point.
[out]undoRedoPointer to MDagModifier object, for undo / redo purposes.
[out]statusReturn status.
Returns
Added representation name.
Status Codes:
  • MS::kSuccess Representation creation succeeded.
  • MS::kFailure No valid node attached to function set, or representation creation failed.
MStatus postLoad ( )

Method to initialize assemblies after their creation.

In general, postLoad() does not need to be called explicity by a plugin. Maya will call it automatically on any assembly node created by representation activation, to initialize the assembly node. See MPxAssembly::postLoad() for more details.

However, if an existing assembly needs to be re-initialized, because of a parameter change for example, the representation activation code path is obviously not involved. In such a case, the postLoad() re-initialization can be done by calling this method explicitly, so that Maya is made aware that the node is being re-initialized, and that for example, no edits should be recorded during this re-initialization.

Returns
Return status
Status Codes:
  • MS::kSuccess The assembly was successfully initialized after creation
  • MS::kFailure No valid node attached to function set
MStatus activate ( const MString representation)

Activate a representation.

The representation to activate is specified as a string name. Passing in an empty string argument means inactivate the previously-active representation (if any), and activate no representation.

If canActivate() is false, activate() will return failure.

Parameters
[in]representationRepresentation to activate.
Returns
Return status.
Status Codes:
  • MS::kSuccess The representation was successfuly activated.
  • MS::kFailure No valid node attached to function set, or activation of the representation failed.
MString getActive ( MStatus status = NULL) const

Get the active representation in the list of representations.

If the list of representations is empty, the status code will be kSuccess, and the return string will be empty.

Parameters
[out]statusReturn status.
Returns
The active representation.
Status Codes:
  • MS::kSuccess The method succeeded.
  • MS::kFailure No valid node attached to function set.
MStatus activateNonRecursive ( const MString representation)

Activate a representation, but prevent any nested assemblies created and initialized during this activation from activating any of their representations.

Normal activation of a representation can create nested assemblies in the representation. Maya will call MPxAssembly::postLoad() automatically on these nested assemblies to initialize them. This initialization of nested assemblies can, in turn, call activate on a representation. activateNonRecursive() causes canActivate() to return false on these nested assemblies. An implementation of MPxAssembly::postLoad() should check canActivate() to determine whether it can activate a representation. Stopping the activation at the current assembly prunes recursive activation of representations.

If canActivate() is false, activateNonRecursive() will return failure.

The representation is specified as a string identifier. Passing in an empty string argument means inactivate the previously-active representation (if any), and activate no representation.

Parameters
[in]representationRepresentation to activate.
Returns
Return status.
Status Codes:
  • MS::kSuccess The representation was successfuly activated.
  • MS::kFailure No valid node attached to function set, or activation of the representation failed.
bool canActivate ( MStatus status = NULL) const

Determines whether this assembly can activate a representation, for the node attached to this function set.

For example, this method will return false for a nested assembly, during a call to activateNonRecursive() on the parent assembly.

If canActivate() is false, activate() and activateNonRecursive() will return failure.

Parameters
[out]statusReturn status.
Returns
true if activation is allowed, false otherwise.
Status Codes:
  • MS::kSuccess The method succeeded.
  • MS::kFailure No valid node attached to function set.
bool isActive ( const MString representation,
MStatus status = NULL 
) const

Determines whether the given representation is the active representation for the node attached to this function set.

Parameters
[in]representationRepresentation to query.
[out]statusReturn status.
Returns
true if the representation is active, false otherwise.
Status Codes:
  • MS::kSuccess The method succeeded.
  • MS::kInvalidParameter The argument is not a representation.
  • MS::kFailure No valid node attached to function set.
MString getInitialRep ( MStatus status = NULL) const
Deprecated:
Use the method MFnAssembly::getInitialRep(bool&, MStatus*) instead

Get the initial representation to use when the assembly is first loaded.

This method is to be called by the assembly to determine which representation should be activated when the assembly is first initialized. An empty string will be returned if no initial representation is specified.

Plug-in writers can customize the manner in which the initial representation is determined. Refer to MPxAssembly::getInitialRep().

Parameters
[out]statusReturn status
Returns
The initial representation to use, if any, else an empty string.
Status Codes:
  • MS::kSuccess The method successfully completed
  • MS::kFailure The method encountered a failure condition
MString getInitialRep ( bool &  hasInitialRep,
MStatus status = NULL 
) const

Get the initial representation to use when the assembly is first loaded.

This method returns the representation which should be activated when the assembly is first initialized. The hasInitialRep parameter will be set to true if the assembly has an initial representation or false if no initial representation has been set. If the returned representation is the empty string and hasInitialRep is true it means that assembly has been explicitly set to have no initial representation

Plug-in writers can customize the manner in which the initial representation is determined. Refer to MPxAssembly::getInitialRep().

Parameters
[out]hasInitialRepReturn whether or not we have an initial representation
[out]statusReturn status
Returns
The initial representation to use, if any, else an empty string.
Status Codes:
  • MS::kSuccess The method successfully completed
  • MS::kFailure The method encountered a failure condition
MStringArray getRepresentations ( MStatus status = NULL) const

Returns an array of the representations managed by the node attached to this function set.

Parameters
[out]statusReturn status.
Returns
Return representations array.
Status Codes:
  • MS::kSuccess The method was successful.
  • MS::kFailure No valid node attached to function set, or the array of representations could not be obtained.
MString getRepType ( const MString representation,
MStatus status = NULL 
) const

Get the type of the specified representation.

The type string does not have to be user-readable, and does not have to be localized; the type label should be used for UI purposes. If the specified representation is not found in this assembly, an empty string is returned.

Parameters
[in]representationRepresentation whose type must be returned.
[out]statusReturn status.
Returns
The representation type.
Status Codes:
  • MS::kSuccess The method succeeded.
  • MS::kFailure No valid node attached to function set.
MString getRepLabel ( const MString representation,
MStatus status = NULL 
) const

Get the label of the specified representation.

The label of a representation is a string that is meant to be shown in the UI and identify the representation meaningfully to a user. The representation label should support localization requirements. If the specified representation is not found in this assembly, an empty string is returned.

Parameters
[in]representationRepresentation whose label must be returned.
[out]statusReturn status.
Returns
The representation label.
Status Codes:
  • MS::kSuccess The method succeeded.
  • MS::kFailure No valid node attached to function set.
MStringArray repTypes ( MStatus status = NULL) const

Return the list of representation types that can be created for this assembly node.

Parameters
[out]statusReturn status.
Returns
Array of representation types.
MStatus deleteRepresentation ( const MString representation)

Delete a representation managed by the node attached to this function set.

Parameters
[in]representationRepresentation to delete.
Returns
Return status.
Status Codes:
  • MS::kSuccess The method was successful.
  • MS::kFailure No valid node attached to function set, or the representation delete failed.
  • MS::kInvalidParameter Invalid representation name.
MStatus deleteAllRepresentations ( )

Delete all representations managed by the node attached to this function set.

Returns
Return status.
Status Codes:
  • MS::kSuccess The method was successful.
  • MS::kFailure No valid node attached to function set, or the delete of all representations failed.
MString getRepNamespace ( MStatus status = NULL) const

Get the representations namespace of this assembly node.

This is the namespace where nodes created by the activation of a representation will be added. This namespace is shared by all representations. The name can be updated by Maya if a name clash occurs when the namespace is added to its parent namespace (see MPxAssembly::updateRepNamespace() for details).

Parameters
[out]statusReturn status.
Returns
Namespace for representations.
Status Codes:
  • MS::kSuccess The method was successful.
  • MS::kFailure No valid node attached to function set.
MString setRepName ( const MString representation,
const MString newName,
MStatus status = NULL 
)

Rename a representation.

The newName argument is used as a starting point for the new representation name. This string value can be modified by the derived implementation to meet representation name uniqueness, or other constraints. This method returns the final representation name.

Parameters
[in]representationCurrent representation name.
[in]newNameNew representation name starting point.
[out]statusReturn status.
Returns
New representation name.
Status Codes:
  • MS::kSuccess Representation successfully renamed.
  • MS::kFailure No valid node attached to function set, or renaming the representation failed.
MStatus setRepLabel ( const MString representation,
const MString label 
)

Change the representation label.

Parameters
[in]representationRepresentation name.
[in]labelNew representation label.
Returns
Return status.
Status Codes:
  • MS::kSuccess Representation label successfully set.
  • MS::kFailure No valid node attached to function set, or changing the label failed.
MStatus importFile ( const MString fileName,
const char *  type = NULL,
bool  preserveReferences = false,
const char *  nameSpace = NULL,
bool  ignoreVersion = false 
)

Import the scene elements from the given file into this assembly.

See MFileIO::importFile() for more information. All elements imported from the file become members of the assembly. DAG nodes in the imported file that are parented to world are parented to the assembly. DAG nodes in the imported file whose parent is not world keep their existing parenting relationship.

Parameters
[in]fileNamename of the file from which to import objects
[in]typeif NULL, Maya will try to deduce the type of the file. If not NULL, it must contain a file type to use when importing the file.
[in]preserveReferencesBoolean to indicate whether the references need to be preserved.
[in]nameSpaceoptional name of the namespace to use when importing objects. Use NULL for default of no namespace.
[in]ignoreVersionBoolean to control whether to ignore version when importing a file.
Returns
  • MS::kSuccess Import succeeded.
  • MS::kFailure No valid node attached to function set, or import failed.
MString getAbsoluteRepNamespace ( MStatus status = NULL) const

Get the fully-qualified (absolute) namespace for representations of this assembly node.

This is the namespace where nodes created by the activation of a representation will be added. This namespace is shared by all representations.

This namespace starts at the root namespace, contains the namespace of the assembly node, and ends (inclusively) with the representation namespace.

Two namespaces are optionally involved when dealing with an assembly node: the namespace of the assembly node itself, and the namespace of its representations. The representation namespace is a child of its assembly node's namespace. The assembly node's namespace is set by its containing assembly, if it is nested, or by the top-level file. Either the assembly node's namespace, or the representation namespace, or both, can be the empty string.

It should be noted that if the assembly node is nested, the assembly node's namespace will be (by virtue of its nesting) the representation namespace of its containing assembly.

Parameters
[out]statusReturn status.
Returns
The fully-qualified (absolute) namespace for representations of this assembly node. The name can be empty if the namespace has not been created yet.
Status Codes:
  • MS::kSuccess The method was successful.
  • MS::kFailure Namespace has not been created yet or no valid node attached to function set.
bool isTopLevel ( MStatus status = NULL) const

Returns whether this assembly node is a top-level assembly.

An assembly node is a top-level assembly if no container in its (possibly empty) chain of nesting parent containers is an assembly. Of course, this includes the trivial case of its immediate parent container being null.

Parameters
[out]statusReturn status.
Returns
Whether the assembly node is a top-level assembly.
Status Codes:
  • MS::kSuccess The method was successful.
  • MS::kFailure No valid node attached to function set.
bool supportsEdits ( MStatus status = NULL) const

Does this assembly support edit tracking?

Parameters
[out]statusReturn status
Returns
Whether the assembly supports tracking of edits on its nodes
Status Codes:
  • MS::kSuccess The method was successful.
  • MS::kFailure No valid node attached to function set.
bool supportsMemberChanges ( MStatus status = NULL) const

Can members of the assembly be changed?

If the assembly does not use Maya's edit tracking system (see supportsEdits()), does it support changes to its member nodes, outside of activation? If so, this means that any mutating operation on Maya nodes (parenting, connecting, disconnecting, renaming, deleting, setting attributes, adding attributes, removing attributes, locking) can be performed on member nodes of the assembly.

This method is only used if supportsEdits() returns false. If supportsEdits() returns true, Maya will track edits to assembly members, and the return value of supportsMemberChanges() will have no meaning.

When this method returns false, any mutating operation to member nodes of the assembly is prevented, and the assembly behaves as a read-only container of nodes. When this method returns true, the assembly supports changes to its member nodes.

This predicate is only used outside of representation activation. During activation, all types of changes to the assembly's members are allowed, including of course deleting the previous representation's nodes, and creating nodes for the new representation.

Parameters
[out]statusReturn status
Returns
Whether the assembly supports changes to its nodes
Status Codes:
  • MS::kSuccess The method was successful.
  • MS::kFailure No valid node attached to function set.
bool canRepApplyEdits ( const MString representation,
MStatus status = NULL 
) const

Determines whether the given representation can apply edits to its data, for the node attached to this function set.

If an empty string is passed in as the representation name, this method will return false, since an invalid (or 'None') representation does not have any data and thus, cannot have edits applied to it. method will return false.

Parameters
[in]representationRepresentation to query.
[out]statusReturn status.
Returns
true if the representation can apply edits, false otherwise.
Status Codes:
  • MS::kSuccess The method succeeded.
  • MS::kFailure No valid node attached to function set.
bool handlesAddEdits ( MStatus status = NULL) const

Determines whether the assembly supplies edits to its data, for the node attached to this function set.

If this method returns true, Maya will call MPxAssembly::addEdits(). These edits will later be applied, either by Maya, or by the assembly through MPxAssembly::applyEdits(), if MPxAssembly::handlesApplyEdits() returns true.

Adding edits can be done by a plugin that implements its own persistency scheme. When an assembly node is brought into Maya through activation of a representation, this assembly can carry edits and make them known to Maya through the addEdits() method.

Edits can be added for any node in the assembly's representations, which includes edits to any nested assembly of this assembly. In a scene with multiple levels of nested assemblies, if more than one nested assembly has edits to a given lower-level nested assembly, edits are applied by Maya starting at the most nested assembly level, moving up the chain of nesting assemblies. In this way, the most nested assembly's edit are overridden by less nested assembly edits, if they edit the same attribute or connection.

Parameters
[out]statusReturn status.
Returns
true if the assembly adds edits, false if no edits are added.
Status Codes:
  • MS::kSuccess The method succeeded.
  • MS::kFailure No valid node attached to function set.
MObject getParentAssembly ( MStatus status = NULL) const

Return the immediate parent assembly of this assembly if there is one, otherwise return a null object.

An assembly with no parent is a top level assembly.

Parameters
[out]statusReturn status.
Returns
Parent assembly, or a null object if this assembly has no parent assembly
Status Codes:
  • MS::kSuccess The method was successful.
  • MS::kFailure No valid node attached to function set, or the array of children could not be obtained.
MObjectArray getSubAssemblies ( MStatus status = NULL) const

Returns a list containing direct children of this assembly that are themselves assemblies, for the currently active representation.

The returned list will be empty if there are no assembly children of the currently active representation.

Parameters
[out]statusReturn status.
Returns
Array of child assemblies.
Status Codes:
  • MS::kSuccess The method was successful.
  • MS::kFailure No valid node attached to function set, or the array of children could not be obtained.

The documentation for this class was generated from the following files:
  • MFnAssembly.h
  • MFnAssembly.cpp