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...
MPxNode *	userNode (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::Associations *	metadata (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]	object	The MObject to attach the function set to
[out]	ReturnStatus	the 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]	object	The const MDagPath to attach the function set to
[out]	ReturnStatus	The 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]	object	The MObject to attach the function set to
[out]	ReturnStatus	the 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.

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]	input	Input data for representation creation.
[in]	type	Type of representation to create.
[out]	undoRedo	Pointer to MDagModifier object, for undo / redo purposes.
[out]	status	Return 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]	input	Input data for representation creation.
[in]	type	Type of representation to create.
[in]	representation	Representation name starting point.
[out]	undoRedo	Pointer to MDagModifier object, for undo / redo purposes.
[out]	status	Return 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]

representation

Representation 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]

status

Return 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]

representation

Representation 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]

status

Return 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]	representation	Representation to query.
[out]	status	Return 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]

status

Return 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]	hasInitialRep	Return whether or not we have an initial representation
[out]	status	Return 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]

status

Return 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]	representation	Representation whose type must be returned.
[out]	status	Return 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]	representation	Representation whose label must be returned.
[out]	status	Return 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]

status

Return 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]

representation

Representation 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]

status

Return 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]	representation	Current representation name.
[in]	newName	New representation name starting point.
[out]	status	Return 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]	representation	Representation name.
[in]	label	New 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]	fileName	name of the file from which to import objects
[in]	type	if 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]	preserveReferences	Boolean to indicate whether the references need to be preserved.
[in]	nameSpace	optional name of the namespace to use when importing objects. Use NULL for default of no namespace.
[in]	ignoreVersion	Boolean 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]

status

Return 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]

status

Return 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]

status

Return 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]

status

Return 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]	representation	Representation to query.
[out]	status	Return 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]

status

Return 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]

status

Return 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]

status

Return 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