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

#include <MFnBlendShapeDeformer.h>
Inheritance diagram for MFnBlendShapeDeformer:
Inheritance graph
[legend]
Collaboration diagram for MFnBlendShapeDeformer:
Collaboration graph
[legend]

List of all members.

Detailed Description

blend shape deformer function set

MFnBlendShapeDeformer is the function set for blend shape deformers. A blend shape deformer takes a base shape (polygonal surface, curve, surface, or lattice) and blends it with other target shapes based on weight values.

The blend shape deformer is actually a small network of dependency nodes in the dependency graph. This function set is provided to make manipulation of the network easier. The main deformer node should be given to this function set as its object.

There are three parts to a blend shape deformer. There are the base objects, the target objects, and the weight values.

The base objects are the shapes that are to be deformed. There must be at least one base object. The base objects will change form as the targets and deformation parameters are modified.

Each base object has a list of target objects that affect its shape. Each target is associated with one of the the deformer's weight values. When the weight value increases, the target has more influence on the base shape.

There is just one array of weight values between all of the base objects and targets. So, it is possible for targets of different base objects to share the same weight index. When the weight value changes, it will affect all of the base objects that have targets using that weight value.

It is also possible to chain together target shapes so that a base object will deform through each shape one at a time as the weight value increases. This is done by adding multiple targets to a base shape using the same weight index for all of them. When each target is added, a weight value is specified at which that target will be in full effect. Give each target a different full weight value.

For example, one could take a sphere and make it blend into a cone and then into a cylinder. One way to do this is to make sphere the base shape. Then, add the cone as a target for the sphere at weight index 0 with a full effect weight of 0.5. Next, add the cylinder as a second target for the sphere also at weight index 0, but with a full effect weight of 1.0. Now, as the weight goes from 0 to 1, the base shape will start as a sphere, morph into a cone, and then into a cylinder.

It is not necessary for the base shape and its targets to have identical vertex/CV counts, but the blend will be more effective if they do.


Public Types
enum   Origin { kLocalOrigin, kWorldOrigin }
  Specifies the space to use for the deformation origin. More...
enum   HistoryLocation { kFrontOfChain, kNormal }
  Specifies where in the shape's history to place the deformer. More...

Public Member Functions
virtual MFn::Type  type () const
  Function set type.
virtual  ~MFnBlendShapeDeformer ()
  Destructor.
  MFnBlendShapeDeformer ()
  Default constructor.
  MFnBlendShapeDeformer (MObject &object, MStatus *ReturnStatus=NULL)
  Constructor.
MObject  create (MObject baseObject, Origin originSpace=kLocalOrigin, MStatus *ReturnStatus=NULL)
MObject  create (const MObjectArray &baseObjects, Origin originSpace=kLocalOrigin, HistoryLocation=kNormal, MStatus *ReturnStatus=NULL)
MStatus  addBaseObject (MObject &object)
MStatus  getBaseObjects (MObjectArray &objects) const
MStatus  addTarget (const MObject &baseObject, int weightIndex, const MObject &newTarget, double fullWeight)
MStatus  removeTarget (const MObject &baseObject, int weightIndex, const MObject &target, double fullWeight)
MStatus  getTargets (MObject baseObject, int weightIndex, MObjectArray &targetObjects) const
unsigned int  numWeights (MStatus *ReturnStatus=NULL) const
MStatus  weightIndexList (MIntArray &indexList) const
MStatus  targetItemIndexList (unsigned int targetIndex, MObject baseObject, MIntArray &inbetweens) const
float  weight (unsigned int index, MStatus *ReturnStatus=NULL) const
MStatus  setWeight (unsigned int index, float weight)
float  envelope (MStatus *ReturnStatus=NULL) const
MStatus  setEnvelope (float envelope)
Origin  origin (MStatus *ReturnStatus=NULL) const
MStatus  setOrigin ( Origin space)
  MFnBlendShapeDeformer (const MObject &object, MStatus *ReturnStatus=NULL)
  Constructor.

Protected Member Functions
virtual const char *  className () const
  Class name.

Member Enumeration Documentation

enum MFnBlendShapeDeformer::Origin

Specifies the space to use for the deformation origin.

Enumerator:
kLocalOrigin   
kWorldOrigin   

enum MFnBlendShapeDeformer::HistoryLocation

Specifies where in the shape's history to place the deformer.

Enumerator:
kFrontOfChain   
kNormal   

Constructor & Destructor Documentation

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

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

Member Function Documentation

MFn::Type MFnBlendShapeDeformer::type (  )  const [virtual]

Function set type.

Return the class type : MFn::kBlendShape

Reimplemented from MFnDependencyNode.

MObject MFnBlendShapeDeformer::create ( MObject  baseObject,
Origin  originSpace = kLocalOrigin,
MStatus *  ReturnStatus = NULL  
)

Creates a new blend shape deformer in the dependency graph with the specified shape as the baseObject.

Parameters:
[in]  baseObject  a base object for the deformer
[in]  originSpace  origin about which to deform
[out]  ReturnStatus  return status
Returns:
A handle to the new deformer
Status Codes:

MObject MFnBlendShapeDeformer::create ( const MObjectArray &  baseObjects,
Origin  originSpace = kLocalOrigin,
HistoryLocation  historyLoc = kNormal,
MStatus *  ReturnStatus = NULL  
)

Creates a new blend shape deformer in the dependency graph. This method differs from the other MFnBlendShapeDeformer::create in that it allows multiple base shapes to be supplied at create time and it allows the use of the front-of-chain history location, which puts the blendShape ahead of other deformers such as skinning deformers.

Parameters:
[in]  baseObjects  base object(s) for the deformer
[in]  originSpace  origin about which to deform
[in]  historyLoc  where in the shape's history to place the deformer
[out]  ReturnStatus  return status
Returns:
A handle to the new deformer
Status Codes:

MStatus MFnBlendShapeDeformer::addBaseObject ( MObject &  object  ) 

Adds a new base object to the deformer. This object will be deformed as targets are added for it and the deformation parameters change.

Parameters:
[in]  object  new base object
Returns:
Return status
Status Codes:

MStatus MFnBlendShapeDeformer::getBaseObjects ( MObjectArray &  objects  )  const

Get a list of all of the base objects for this deformer. The objects returned will be the deformed versions of the base objects.

Parameters:
[out]  objects  storage for the array of base objects
Returns:
Return status
Status Codes:

MStatus MFnBlendShapeDeformer::addTarget ( const MObject &  baseObject,
int  weightIndex,
const MObject &  newTarget,
double  fullWeight  
)

Adds a new target object for the given base object. The weight index says which of the deformer's weight values will control this target's affects on the base object. The full weight argument determines at what weight the target is in full effect. If a base object has no other targets and the weight is set to the 'full weight', then the base object will look just like the target object.

Parameters:
[in]  baseObject  base object for the target
[in]  weightIndex  weight index to use for target's effect
[in]  newTarget  new target object for the given base
[in]  fullWeight  weight value at which the target is in full effect
Returns:
Return status
Status Codes:

MStatus MFnBlendShapeDeformer::removeTarget ( const MObject &  baseObject,
int  weightIndex,
const MObject &  target,
double  fullWeight  
)

Remove a target object for the given base object. The weight index specifies the index at which target is connected. The full weight argument specifies at what weight the target is in full effect.

Parameters:
[in]  baseObject  base object for the target
[in]  weightIndex  weight index corresponding to the target
[in]  target  target object for the given base to be removed
[in]  fullWeight  weight value at which the target is in full effect
Returns:
Return status
Status Codes:

MStatus MFnBlendShapeDeformer::getTargets ( MObject  baseObject,
int  weightIndex,
MObjectArray &  targetObjects  
) const

Get a list of all of the target objects for the given base object that affect it based on the given weight index.

Parameters:
[in]  baseObject  The base shape of interest.
[in]  weightIndex  The index of the weight attribute. Since the weight indices may be sparse, the weightIndexList method should be used to find the weight indices used by a given blendShape.
[out]  targetObjects  Storage for the returned array of target objects.
Returns:
Return status
Status Codes:

unsigned int MFnBlendShapeDeformer::numWeights ( MStatus *  ReturnStatus = NULL  )  const

Return the number of weight values that this blend shape deformer has. The number of weight values is equal to the number of targets. Targets are either shapes in the dag or baked data on the blendShape node (when a target shape is deleted).

Parameters:
[out]  ReturnStatus  return status
Returns:
The number of weight indices
Status Codes:

MStatus MFnBlendShapeDeformer::weightIndexList ( MIntArray &  indexList  )  const

Return the array index numbers corresponding to the targets. The resulting index list will be the length of MFnBlendShape::numWeights. This method exists because the indices of the targets can be sparse. For example, if a target has been removed using Deform -> Edit BlendShape -> Remove.

Parameters:
[out]  indexList  the array index numbers for the blendShape targets
Returns:
The return status
Status Codes:

MStatus MFnBlendShapeDeformer::targetItemIndexList ( unsigned int  targetIndex,
MObject  baseObject,
MIntArray &  inbetweens  
) const

Return the "inputTargetItem" array indices for the specified target. The "inputTargetItem" array indices correspond to the weight where the targets take affect according to the formula: index = wt * 1000 + 5000. For example, if you have only a single target, and no in-betweens, the index will typically be 6000 since the default weight for the initial target is 1.0.

Parameters:
[in]  inbetweens  array index values of the inbetweens
Returns:
Return status
Status Codes:
  • MS::kSuccess operation successful
  • MS::kFailure function set does not have a valid object
  • MS::kInvalidIndex no target exists at the specified target index

float MFnBlendShapeDeformer::weight ( unsigned int  index,
MStatus *  ReturnStatus = NULL  
) const

Get the weight value at the given index. To be valid, a weight value should only be requested at index values returned by MFnBlendShapeDeformer::weightIndexList.

Parameters:
[in]  index  index of weight value
[out]  ReturnStatus  return status
Returns:
The weight value
Status Codes:

MStatus MFnBlendShapeDeformer::setWeight ( unsigned int  index,
float  weight  
)

Set the weight value at the given index.

Parameters:
[in]  index  index of weight value
[in]  weight  new weight value
Returns:
Return status
Status Codes:

float MFnBlendShapeDeformer::envelope ( MStatus *  ReturnStatus = NULL  )  const

Gets the envelope value of the deformer.

The envelope is a global scale factor that is applied to all of the weight values in the deformer. The envelope can be used increase or decrease the effects of all of the targets at the same time.

Parameters:
[out]  ReturnStatus  return status
Returns:
Envelope value
Status Codes:

MStatus MFnBlendShapeDeformer::setEnvelope ( float  envelope  ) 

Sets the envelope value of the deformer.

The envelope is a global scale factor that is applied to all of the weight values in the deformer. The envelope can be used increase or decrease the effects of all of the targets at the same time.

Parameters:
[in]  envelope  envelope value
Returns:
Return status
Status Codes:

MFnBlendShapeDeformer::Origin MFnBlendShapeDeformer::origin ( MStatus *  ReturnStatus = NULL  )  const

Gets the origin space. It defines the point around which the differences in the geometry are calculated.

Parameters:
[out]  ReturnStatus  return status
Returns:
The origin space
Status Codes:

MStatus MFnBlendShapeDeformer::setOrigin ( Origin  space  ) 

Sets the origin space. It defines the point around which the differences in the geometry are calculated.

Parameters:
[in]  space  origin space
Returns:
The origin space
Status Codes:
Autodesk® Maya® 2011 © 1997-2010 Autodesk, Inc. All rights reserved. Generated with doxygen 1.5.6