MFnWeightGeometryFilter Class Reference
[OpenMayaAnim - API module for animation, FunctionSet classes]

#include <MFnWeightGeometryFilter.h>

Inheritance diagram for MFnWeightGeometryFilter:

[legend]

Collaboration diagram for MFnWeightGeometryFilter:

[legend]

List of all members.

---

Detailed Description

Weight geometry filter function set.

MFnWeightGeometryFilter is the function set for weight geometry filters. Weight geometry filter nodes include clusters, cluster flexors, and user-defined deformers derived from MPxDeformerNode. The purpose of the weight geometry filter is to store the weights for each component of each geometry that is deformed. The weight geometry filter is independent of any algorithm that calculates a deformation based on the component weight values. Clusters, cluster flexors, and user-defined deformers each have their own algorithm to determine the deformation based on the component weights.

This function set provides methods for getting and setting weights on weight geometry filter nodes. In addition to getting and settings weights on components, this class provides methods for accessing the weight geometry filter's input and output geometry through its parent class, MFnGeometryFilter.

When getting and setting weights on components, it is more efficient to use the methods that take a plug index. The plug index is a sparse array index, and is the same index used in MEL scripts to index into an array of plugs.

Examples:

clusterWeightFunction.cpp, and exportJointClusterDataCmd.cpp.

Public Member Functions
virtual MFn::Type	type () const
	Function set type.
virtual	~MFnWeightGeometryFilter ()
	Destructor.
	MFnWeightGeometryFilter ()
	Default constructor.
	MFnWeightGeometryFilter (MObject &object, MStatus *ReturnStatus=NULL)
	Constructor.
MStatus	getWeights (unsigned int index, const MObject &components, MFloatArray &weights) const
MStatus	getWeights (const MDagPath &path, const MObject &components, MFloatArray &weights) const
MStatus	setWeight (const MDagPath &path, unsigned int index, const MObject &components, float weight, MFloatArray *oldValues=NULL)
MStatus	setWeight (const MDagPath &path, const MObject &components, float weight, MFloatArray *oldValues=NULL)
MStatus	setWeight (const MDagPath &path, unsigned int index, const MObject &components, MFloatArray &values)
MStatus	setWeight (const MDagPath &path, const MObject &components, MFloatArray &values)
MString	weightPlugStrings (const MSelectionList &list, MStatus *ReturnStatus=NULL) const
MStatus	getWeightPlugStrings (const MSelectionList &list, MStringArray &plugStringArray) const
	MFnWeightGeometryFilter (const MObject &object, MStatus *ReturnStatus=NULL)
	Constructor.
MStatus	getWeightPlugStrings (const MSelectionList &list, MString &plugStrings) const
	NO SCRIPT SUPPORT.
Protected Member Functions
virtual const char *	className () const
	Class name.

---

Constructor & Destructor Documentation

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

MFnWeightGeometryFilter::MFnWeightGeometryFilter	(	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 MFnWeightGeometryFilter::type

(

)

const [virtual]

Function set type.

Return the class type : MFn::kWeightGeometryFilt

Reimplemented from MFnGeometryFilter.

MStatus MFnWeightGeometryFilter::getWeights	(	unsigned int	index,
		const MObject &	components,
		MFloatArray &	weights
	)			const

Gets the weights of the components that correspond to the geometry at the specified plug index.

The relationship between the weights and the components can be determined by iterating through the components using the MItGeometry iterator. The iterator iterates through the components in the same order as the weights array.

Parameters:

[in]	index	the plug index corresponding to the shape that has the components
[out]	components	the components whose weights are requested
[out]	weights	the weight values of the components

Returns:

• MS::kSuccess operation successful
• MS::kFailure function set does not have a valid object
• MS::kInvalidParameter component parameter is invalid

MStatus MFnWeightGeometryFilter::getWeights	(	const MDagPath &	path,
		const MObject &	components,
		MFloatArray &	weights
	)			const

Gets the weights of the components that correspond to the geometry whose DAG path is specified.

If the plug index is already known, it is more efficient to call the other getWeights method than this one. This getWeights method calls indexForOutputShape internally to find the plug index.

The relationship between the weights and the components can be determined by iterating through the components using the MItGeometry iterator. The iterator iterates through the components in the same order as the weights array.

Parameters:

[in]	path	the path of the DAG object that has the components
[in]	components	the components whose weights are requested
[out]	weights	the weight values of the components

Returns:

• MS::kSuccess operation successful
• MS::kFailure operation failed
• MS::kInvalidParameter component parameter is invalid

MStatus MFnWeightGeometryFilter::setWeight	(	const MDagPath &	path,
		unsigned int	index,
		const MObject &	components,
		float	weight,
		MFloatArray *	oldValues = NULL
	)

Sets the weights of the specified components of the object whose DAG path is specified.

In order to undo the setWeight operation, it is necessary to save the oldValues array and call setWeight with the oldValues array at the time of undo.

Parameters:

[in]	path	the DAG path for the object whose components' weights are being set
[in]	index	the plug index for the specified shape
[in]	components	the components of the object
[in]	weight	weight value for the components
[in]	oldValues	an array of old values for the components

Returns:

• MS::kSuccess operation successful
• MS::kFailure function set does not have a valid object
• MS::kInvalidParameter component parameter is invalid

Examples:

clusterWeightFunction.cpp.

MStatus MFnWeightGeometryFilter::setWeight	(	const MDagPath &	path,
		const MObject &	components,
		float	weight,
		MFloatArray *	oldValues = NULL
	)

Sets the weights of the specified components of the object whose DAG path is specified.

If the plug index is already known, it is more efficient to call the corresponding setWeight method that takes a plugIndex. This setWeight method is a convenience method which calls indexForOutputShape internally to find the plug index.

In order to undo the setWeight operation, it is necessary to save the oldValues array and call setWeight with the oldValues array at the time of undo.

Parameters:

[in]	path	the DAG path for the object whose components' weights are being set
[in]	components	the components of the object
[in]	weight	weight value for the components
[in]	oldValues	an array of old values for the components

Returns:

• MS::kSuccess operation successful
• MS::kFailure operation failed
• MS::kInvalidParameter component parameter is invalid

MStatus MFnWeightGeometryFilter::setWeight	(	const MDagPath &	path,
		unsigned int	index,
		const MObject &	components,
		MFloatArray &	values
	)

Sets the weights of the specified components of the object whose DAG path is specified.

This method is useful in conjunction with the setWeight methods that return an oldValues array. This method can be called with those oldValues to restore the weights to the previous values.

Parameters:

[in]	path	the DAG path for the object whose components' weights are being set
[in]	index	the plug index for the specified shape
[in]	components	the components of the object
[in]	values	the value array of the components

Returns:

• MS::kSuccess operation successful
• MS::kFailure function set does not have a valid object
• MS::kInvalidParameter component parameter is invalid

MStatus MFnWeightGeometryFilter::setWeight	(	const MDagPath &	path,
		const MObject &	components,
		MFloatArray &	values
	)

Sets the weights of the specified components of the object whose DAG path is specified.

This method is useful in conjunction with the setWeight methods that return an oldValues array. This method can be called with those oldValues to restore the weights to the previous values.

If the plug index is already known, it is more efficient to call the corresponding setWeight method that takes a plugIndex. This setWeight method is a convenience method which calls indexForOutputShape internally to find the plug index.

Parameters:

[in]	path	the DAG path for the object whose components' weights are being set
[in]	components	the components of the object
[in]	values	the value array of the components

Returns:

• MS::kSuccess operation successful
• MS::kFailure operation failed
• MS::kInvalidParameter component parameter is invalid

MString MFnWeightGeometryFilter::weightPlugStrings	(	const MSelectionList &	list,
		MStatus *	ReturnStatus = NULL
	)			const

Sets the plugStrings argument to be a string (separated by spaces) containing the names of the plugs on this node that correspond to the components in the selection list. The method can be useful in conjunction with setting keys on a number of plugs. The operation will fail if none of the items in the selection list correspond to components weighted by this cluster.

Parameters:

[in]	list	selection list that contains components
[out]	ReturnStatus	Status code

Returns:

A string containing the names of the plugs on this node that correspond to the components in the selection list

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure operation failed

MStatus MFnWeightGeometryFilter::getWeightPlugStrings	(	const MSelectionList &	list,
		MStringArray &	plugStringArray
	)			const

Set the plugStringArray argument to contain the names of the plugs on this node that correspond to the components in the selection list. The operation will fail if none of the items in the selection list correspond to components weighted by this cluster.

Parameters:

[in]	list	selection list that contains components
[out]	plugStringArray	string array containing the names of the plugs on this node that correspond to the components in the selection list; each of the plugs is put in a separate string

Returns:

• MS::kSuccess operation successful
• MS::kFailure operation failed

MStatus MFnWeightGeometryFilter::getWeightPlugStrings	(	const MSelectionList &	list,
		MString &	plugStrings
	)			const

NO SCRIPT SUPPORT.

Sets the plugStrings argument to be a string (separated by spaces) containing the names of the plugs on this node that correspond to the components in the selection list. The method can be useful in conjunction with setting keys on a number of plugs. The operation will fail if none of the items in the selection list correspond to components weighted by this cluster.

Python Notes

This method is not supported in Python. See the version which returns a string.

Parameters:

[in]	list	selection list that contains components
[in]	plugStrings	string containing the names of the plugs on this node that correspond to the components in the selection list

Returns:

• MS::kSuccess operation successful
• MS::kFailure operation failed