Public Member Functions | Protected Member Functions

MFnAssembly Class Reference

This reference page is linked to from the following overview topics: Extension for Autodesk Maya 2013.


Search for all occurrences

Detailed 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.

#include <MFnAssembly.h>

Inheritance diagram for MFnAssembly:
Inheritance graph
[legend]

List of all members.

Public Member Functions

virtual MFn::Type type () const
 Function set type.
virtual ~MFnAssembly ()
 Destructor.
 MFnAssembly ()
 Default constructor.
 MFnAssembly (MObject &object, MStatus *ReturnStatus=NULL)
 Constructor.
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.
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.
MStatus postLoad ()
 Method to initialize assemblies after their creation.
MStatus activate (const MString &representation)
 Activate representation in list of representations.
MString getActive (MStatus *status=NULL) const
 Get the active representation in the list of representations.
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.
MString getInitialRep (MStatus *status=NULL) const
 Get the initial representation to use when the assembly is first loaded.
MStringArray getRepresentations (MStatus *status=NULL) const
 Returns an array of the representations managed by the node attached to this function set.
MString getRepType (const MString &representation, MStatus *status=NULL) const
 Get the type of the specified representation.
MString getRepLabel (const MString &representation, MStatus *status=NULL) const
 Get the label of the specified representation.
MStringArray repTypes (MStatus *status=NULL) const
 Return the list of representation types that can be created for this assembly node.
MStatus deleteRepresentation (const MString &representation)
 Delete a representation managed by the node attached to this function set.
MStatus deleteAllRepresentations ()
 Delete all representations managed by the node attached to this function set.
MString getRepNamespace (MStatus *status=NULL) const
 Get the representations namespace of this assembly node.
MString setRepName (const MString &representation, const MString &newName, MStatus *status=NULL)
 Rename a representation.
MStatus setRepLabel (const MString &representation, const MString &label)
 Change the representation label.
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.
MString getAbsoluteRepNamespace (MStatus *status=NULL) const
 Get the fully-qualified (absolute) namespace for representations of this assembly node.
bool isTopLevel (MStatus *status=NULL) const
 Returns whether this assembly node is a top-level assembly.
bool supportsEdits (MStatus *status=NULL) const
 Does this assembly support edit tracking?
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.
MObject getParentAssembly (MStatus *status=NULL) const
 Return the immediate parent assembly of this assembly if there is one, otherwise return a null object.
MObjectArray getSubAssemblies (MStatus *status=NULL) const
 Returns a list containing direct children of this assembly that are themselves assemblies, for the currently active representation.
 MFnAssembly (const MObject &object, MStatus *ReturnStatus=NULL)
 Constructor.

Protected Member Functions

virtual const char * className () const
 Class name.

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:
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:

Member Function Documentation

MFn::Type type ( ) const [virtual]

Function set type.

Return the class type : MFn::kAssembly.

Reimplemented from MFnDagNode.

const char * className ( ) const [protected, virtual]

Class name.

Return the class name : "MFnAssembly".

Reimplemented from MFnDagNode.

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.

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 representation in list of representations.

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.
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:
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:
MString getInitialRep ( MStatus status = NULL) const

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:
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:
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:
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:
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:
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:
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:
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:
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:
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.

MFnAssembly MFnAssembly MFnAssembly MFnAssembly MFnAssembly MFnAssembly MFnAssembly MFnAssembly MFnAssembly MFnAssembly
MFnAssembly MFnAssembly MFnAssembly MFnAssembly MFnAssembly MFnAssembly MFnAssembly MFnAssembly MFnAssembly MFnAssembly