CAWeightMgr Class Reference

#include <lib_ca.h>

Detailed Description

Represents the Weight Manager.

Since
R19
Note
Weight manager data and settings are per document. Any change on a document does not affect other opened documents.

Private Member Functions

 CAWeightMgr ()=delete
 
 ~CAWeightMgr ()=delete
 

Manager Update

static Bool Update (BaseDocument *doc)
 
static Bool SetDirty (BaseDocument *doc)
 
static Bool SetParameter (BaseDocument *doc, Int32 id, const GeData &newValue)
 
static Bool GetParameter (BaseDocument *doc, Int32 id, GeData &value)
 

List Access

static Int32 GetTagCount (BaseDocument *doc)
 
static Int32 GetJointCount (BaseDocument *doc, Int32 tagIdx)
 
static Int32 GetTagIndex (BaseDocument *doc, const CAWeightTag *tag)
 
static Bool GetJointIndex (BaseDocument *doc, const CAWeightTag *tag, const BaseObject *joint, Int32 &tagIdx, Int32 &jointIdx)
 
static UInt64 GetJointId (BaseDocument *doc, const CAWeightTag *tag, const BaseObject *joint)
 
static BaseObjectGetJointObject (BaseDocument *doc, Int32 tagIdx, Int32 jointIdx)
 
static BaseObjectGetJointObject (BaseDocument *doc, UInt64 id)
 
static CAWeightTagGetWeightTag (BaseDocument *doc, Int32 tagIdx)
 
static BaseObjectGetMeshObject (BaseDocument *doc, Int32 tagIdx)
 
static Bool ValidateJointIndex (BaseDocument *doc, Int32 tagIdx, Int32 jointIdx)
 

Selection

static Bool IsJointSelected (BaseDocument *doc, Int32 tagIdx, Int32 jointIdx)
 
static Bool IsJointSelected (BaseDocument *doc, UInt64 id)
 
static Bool SelectJoint (BaseDocument *doc, Int32 tagIdx, Int32 jointIdx)
 
static Bool SelectJoint (BaseDocument *doc, UInt64 id)
 
static Bool UnselectJoint (BaseDocument *doc, Int32 tagIdx, Int32 jointIdx)
 
static Bool UnselectJoint (BaseDocument *doc, UInt64 id)
 
static void SelectAllJoints (BaseDocument *doc)
 
static void UnselectAllJoints (BaseDocument *doc)
 
static Bool UnselectAllJointListNodes (BaseDocument *doc)
 

Locks

static Bool IsJointLocked (BaseDocument *doc, Int32 tagIdx, Int32 jointIdx)
 
static Bool IsJointLocked (BaseDocument *doc, UInt64 id)
 
static Bool LockAllJoints (BaseDocument *doc)
 
static Bool LockSelectedJoints (BaseDocument *doc)
 
static Bool UnlockAllJoints (BaseDocument *doc)
 
static Bool UnlockSelectedJoints (BaseDocument *doc)
 

Weighting Functions

static Bool NormalizeWeights (BaseDocument *doc)
 
static Bool ClearWeights (BaseDocument *doc)
 
static Bool AutoWeight (BaseDocument *doc, Bool allowNull)
 
static Bool MirrorWeights (BaseDocument *doc)
 
static Bool BakeWeights (BaseDocument *doc, Bool normalize)
 
static Bool CopyWeights (BaseDocument *doc)
 
static Bool PasteWeights (BaseDocument *doc, Bool merge)
 
static Bool FlipWeights (BaseDocument *doc)
 
static Bool SmoothWeights (BaseDocument *doc)
 
static Bool ApplyWeightFunction (BaseDocument *doc, Bool allPoints)
 

Constructor & Destructor Documentation

§ CAWeightMgr()

CAWeightMgr ( )
privatedelete

§ ~CAWeightMgr()

~CAWeightMgr ( )
privatedelete

Member Function Documentation

§ Update()

static Bool Update ( BaseDocument doc)
static

Updates the internal weighted object list.

Call before using other methods of CAWeightMgr if the Weight Manager dialog is closed and if the weight tool is inactive. Any of the two condition is enough to have the update run automatically each frame.

Also call if the weighted object list was changed programmatically. For instance after adding a new tag, performing undo redo, or any reason where an update is needed immediately.

Note
Update has no effect if nothing dirty is detected. Call EventAdd() to refresh the Weight Manager UI to show the updated changes.
Parameters
[in]docThe document for the Weight Manager. The caller owns the pointed BaseDocument.
Returns
true if successful, otherwise false.

§ SetDirty()

static Bool SetDirty ( BaseDocument doc)
static

Sets the Weight Manager dirty to force an update on the next call to Update().

If the Weight Manager dialog is opened or if the Weight Manager is active, the update happens automatically at the next frame.

To force an update after a parameter change, use SetDirty(), then call Update(). Call SetDirty() if a Weight Manager's parameter was directly modified in its container.

Note
Call EventAdd() to refresh the Weight Manager UI to show the updated changes.
Parameters
[in]docThe document for the Weight Manager. The caller owns the pointed BaseDocument.
Returns
true if successful, otherwise false.

§ SetParameter()

static Bool SetParameter ( BaseDocument doc,
Int32  id,
const GeData newValue 
)
static

Sets a parameters of the Weight Manager.

Result is the same as setting a parameter on the Weight Manager's container directly except that SetParameter() allows to specify the document in which to set the parameter.

Warning
Setting parameters directly into the Weight Manager's container is not recommended. Doing so requires to make the Weight Manager dirty and to update it manually.
Note
Call EventAdd() to refresh the Weight Manager UI to show the updated changes.
Parameters
[in]docThe document for the Weight Manager. The caller owns the pointed BaseDocument.
[in]idThe ID of the parameter to set.
[in]newValueThe parameter data to set.
Returns
true if successful, otherwise false.

§ GetParameter()

static Bool GetParameter ( BaseDocument doc,
Int32  id,
GeData value 
)
static

Retrieves a parameter of the Weight Manager.

Parameters
[in]docThe document for the Weight Manager. The caller owns the pointed BaseDocument.
[in]idThe ID of the parameter to set.
[out]valueThe parameter data.
Returns
true if successful, otherwise false.

§ GetTagCount()

static Int32 GetTagCount ( BaseDocument doc)
static

Queries the number of weight tags in the scene.

Parameters
[in]docThe document for the Weight Manager. The caller owns the pointed BaseDocument.
Returns
The weight tags count.

§ GetJointCount()

static Int32 GetJointCount ( BaseDocument doc,
Int32  tagIdx 
)
static

Queries the number of joints bound to a weight tag.

Parameters
[in]docThe document for the Weight Manager. The caller owns the pointed BaseDocument.
[in]tagIdxThe tag index in the list: 0 <= tagIdx < GetTagCount().
Returns
The joints count.

§ GetTagIndex()

static Int32 GetTagIndex ( BaseDocument doc,
const CAWeightTag tag 
)
static

Finds a tag's index in the joint list.

Parameters
[in]docThe document for the Weight Manager. The caller owns the pointed BaseDocument.
[in]tagThe weight tag to search for. The caller owns the pointed CAWeightTag.
Returns
The tag's index in the list, or NOTOK if not found.

§ GetJointIndex()

static Bool GetJointIndex ( BaseDocument doc,
const CAWeightTag tag,
const BaseObject joint,
Int32 tagIdx,
Int32 jointIdx 
)
static

Finds a joint's main (tag) and sub (joint) indices in the joint list.

Note
The joint index might not match the joint index on the tag. It is not recommended to keep indices over time, some operations might change the list ordering or length. Only IDs to reference joints can be kept over time.
Parameters
[in]docThe document for the Weight Manager. The caller owns the pointed BaseDocument.
[in]tagThe tag's address. The caller owns the pointed CAWeightTag.
[in]jointThe joints's address. The caller owns the pointed BaseObject.
[out]tagIdxThe tag's index in the joint list, or NOTOK if not found.
[out]jointIdxThe joint's index in the joint list, or NOTOK if not found.
Returns
true if successful, otherwise false.

§ GetJointId()

static UInt64 GetJointId ( BaseDocument doc,
const CAWeightTag tag,
const BaseObject joint 
)
static

Returns the unique Id of a joint. This Id remains valid even if the joint list changes or if undo/redo is used.

Parameters
[in]docThe document for the Weight Manager. The caller owns the pointed BaseDocument.
[in]tagThe tag's address. The caller owns the pointed CAWeightTag.
[in]jointThe joint's address. The caller owns the pointed BaseObject.
Returns
The joint unique Id, or maxon::LIMIT<UInt64>::MAX if not found.

§ GetJointObject() [1/2]

static BaseObject* GetJointObject ( BaseDocument doc,
Int32  tagIdx,
Int32  jointIdx 
)
static

Finds a joint object from its indices.

Parameters
[in]docThe doc containing the tag and joint. The caller owns the pointed BaseDocument.
[in]tagIdxThe tag's index in the joint list.
[in]jointIdxThe joint's index in the joint list.
Returns
The joint object, or nullptr if not found. The CAWeightMgr owns the pointed BaseObject.

§ GetJointObject() [2/2]

static BaseObject* GetJointObject ( BaseDocument doc,
UInt64  id 
)
static

Finds a joint object from its unique Id in the joint list.

Parameters
[in]docThe doc that contains the tag and joint. The caller owns the pointed BaseDocument.
[in]idThe Id of the joint in the Weight Manager joint list.
Returns
The joint object, or nullptr if not found. The CAWeightMgr owns the pointed BaseObject.

§ GetWeightTag()

static CAWeightTag* GetWeightTag ( BaseDocument doc,
Int32  tagIdx 
)
static

Finds a weight tag from its index in the joint list.

Parameters
[in]docThe document for the Weight Manager. The caller owns the pointed BaseDocument.
[in]tagIdxThe tag's index in the joint list.
Returns
The weight tag, or nullptr if not found. The CAWeightMgr owns the pointed CAWeightTag.

§ GetMeshObject()

static BaseObject* GetMeshObject ( BaseDocument doc,
Int32  tagIdx 
)
static

Finds the object owning the weight tag from a tag index in the joint list.

Parameters
[in]docThe document for the Weight Manager. The caller owns the pointed BaseDocument.
[in]tagIdxThe tag's index in the joint list.
Returns
The mesh object, or nullptr if not found. The CAWeightMgr owns the pointed BaseObject.

§ ValidateJointIndex()

static Bool ValidateJointIndex ( BaseDocument doc,
Int32  tagIdx,
Int32  jointIdx 
)
static

Validates tag/joint indices before access.

Note
Call before using functions that require tag/joint indices to avoid crashes.
Parameters
[in]docThe doc that contains the tags and joints. The caller owns the pointed BaseDocument.
[in]tagIdxThe tag's index in the joint list.
[in]jointIdxThe joint's index in the joint list.
Returns
true if tag and joint indices are valid, otherwise false.

§ IsJointSelected() [1/2]

static Bool IsJointSelected ( BaseDocument doc,
Int32  tagIdx,
Int32  jointIdx 
)
static

Checks if a joint of the Weight Manager list is selected. Joint is identified by tag-joint index pair.

Parameters
[in]docThe document for the Weight Manager. The caller owns the pointed BaseDocument.
[in]tagIdxThe tag's index in the joint list.
[in]jointIdxThe joint's index in the weight tag.
Returns
true if the joint was found and is selected, otherwise false.

§ IsJointSelected() [2/2]

static Bool IsJointSelected ( BaseDocument doc,
UInt64  id 
)
static

Checks if a joint of the Weight Manager list is selected. Joint is identified by Id.

Parameters
[in]docThe document for the Weight Manager. The caller owns the pointed BaseDocument.
[in]idThe joint's Id.
Returns
true if the joint was found and is selected, otherwise false.

§ SelectJoint() [1/2]

static Bool SelectJoint ( BaseDocument doc,
Int32  tagIdx,
Int32  jointIdx 
)
static

Selects a joint of the Weight Manager list. Joint is identified by tag-joint index pair.

Parameters
[in]docThe document for the Weight Manager. The caller owns the pointed BaseDocument.
[in]tagIdxThe tag's index in the joint list.
[in]jointIdxThe joint's index in the weight tag.
Returns
true if the joint was selected, otherwise false.

§ SelectJoint() [2/2]

static Bool SelectJoint ( BaseDocument doc,
UInt64  id 
)
static

Selects a joint of the Weight Manager list. Joint is identified by Id.

Parameters
[in]docThe document for the Weight Manager. The caller owns the pointed BaseDocument.
[in]idThe joint's Id.
Returns
true if the joint was selected, otherwise false.

§ UnselectJoint() [1/2]

static Bool UnselectJoint ( BaseDocument doc,
Int32  tagIdx,
Int32  jointIdx 
)
static

Deselects a joint of the Weight Manager list. Joint is identified by tag-joint index pair.

Parameters
[in]docThe document for the Weight Manager. The caller owns the pointed BaseDocument.
[in]tagIdxThe tag's index in the joint list.
[in]jointIdxThe joint's index in this tag.
Returns
true if the joint was deselected, otherwise false.

§ UnselectJoint() [2/2]

static Bool UnselectJoint ( BaseDocument doc,
UInt64  id 
)
static

Deselects a joint of the Weight Manager list. Joint is identified by Id.

Parameters
[in]docThe document for the Weight Manager. The caller owns the pointed BaseDocument.
[in]idThe joint's Id.
Returns
true if the joint was deselected, otherwise false.

§ SelectAllJoints()

static void SelectAllJoints ( BaseDocument doc)
static

Selects all joints of all tags in the Weight Manager list.

Parameters
[in]docThe document for the Weight Manager. The caller owns the pointed BaseDocument.

§ UnselectAllJoints()

static void UnselectAllJoints ( BaseDocument doc)
static

Deselects all joints of all tags in the Weight Manager list.

Parameters
[in]docThe document for the Weight Manager. The caller owns the pointed BaseDocument.

§ UnselectAllJointListNodes()

static Bool UnselectAllJointListNodes ( BaseDocument doc)
static

Deselects all of the nodes in the Weight Manager joint list. This includes all type of nodes (mesh/tag/folder/joint).

Note
The API does not allow selecting/deselecting mesh and tags at the moment, so use this function to get rid of any mesh/tag that could have been already selected. Because a parent mesh, tag, or folder activates the child joints for painting.
Parameters
[in]docThe document in which to deselect all nodes. The caller owns the pointed BaseDocument.
Returns
true if successful, otherwise false.

§ IsJointLocked() [1/2]

static Bool IsJointLocked ( BaseDocument doc,
Int32  tagIdx,
Int32  jointIdx 
)
static

Checks if a joint of the Weight Manager list is locked. Joint is identified by tag-joint index pair.

Parameters
[in]docThe document for the Weight Manager. The caller owns the pointed BaseDocument.
[in]tagIdxThe tag's index in the joint list.
[in]jointIdxThe joint's index in the weight tag.
Returns
true if the joint was found and is locked, otherwise false.

§ IsJointLocked() [2/2]

static Bool IsJointLocked ( BaseDocument doc,
UInt64  id 
)
static

Checks if a joint of the Weight Manager list is locked. Joint is identified by Id.

Parameters
[in]docThe document for the Weight Manager. The caller owns the pointed BaseDocument.
[in]idThe joint's id.
Returns
true if the joint was found and is locked, otherwise false.

§ LockAllJoints()

static Bool LockAllJoints ( BaseDocument doc)
static

Locks all joints of all tags in the Weight Manager list.

Parameters
[in]docThe document for the Weight Manager. The caller owns the pointed BaseDocument.
Returns
true if all joints got locked, otherwise false.

§ LockSelectedJoints()

static Bool LockSelectedJoints ( BaseDocument doc)
static

Locks selected joints in the Weight Manager list.

Parameters
[in]docThe document for the Weight Manager. The caller owns the pointed BaseDocument.
Returns
true if successful, otherwise false.

§ UnlockAllJoints()

static Bool UnlockAllJoints ( BaseDocument doc)
static

Unlocks all joints of all tags in the Weight Manager list.

Parameters
[in]docThe document for the Weight Manager. The caller owns the pointed BaseDocument.
Returns
true if successful, otherwise false.

§ UnlockSelectedJoints()

static Bool UnlockSelectedJoints ( BaseDocument doc)
static

Unlocks selected joints in the Weight Manager list.

Parameters
[in]docThe document for the Weight Manager. The caller owns the pointed BaseDocument.
Returns
true if successful, otherwise false.

§ NormalizeWeights()

static Bool NormalizeWeights ( BaseDocument doc)
static

Applies a normalization on the selected joints. Some joints can be locked prior to normalization to avoid touching some joints.

Note
Adds an undo.
Parameters
[in]docThe document for the Weight Manager. The caller owns the pointed BaseDocument.
Returns
true if successful, otherwise false.

§ ClearWeights()

static Bool ClearWeights ( BaseDocument doc)
static

Clears all weights on the selected joints.

Note
Adds an undo.
Parameters
[in]docThe document for the Weight Manager. The caller owns the pointed BaseDocument.
Returns
true if successful, otherwise false.

§ AutoWeight()

static Bool AutoWeight ( BaseDocument doc,
Bool  allowNull 
)
static

Runs an auto weight algorithm on the selected joints. Uses the parameters currently set in the Weight Manager's container for the document.

Note
Adds an undo.
Parameters
[in]docThe document for the Weight Manager. The caller owns the pointed BaseDocument.
[in]allowNulltrue to add null objects to the weight tag, otherwise false.
Returns
true if successful, otherwise false.

§ MirrorWeights()

static Bool MirrorWeights ( BaseDocument doc)
static

Mirrors the weights for the selected joints. Uses the parameters currently set in the Weight Manager's container for the document.

Note
Adds an undo.
Parameters
[in]docThe document for the Weight Manager. The caller owns the pointed BaseDocument.
Returns
true if successful, otherwise false.

§ BakeWeights()

static Bool BakeWeights ( BaseDocument doc,
Bool  normalize 
)
static

Bakes the effector weights. Uses the parameters currently set in the Weight Manager's container for the document.

Note
Adds an undo.
Parameters
[in]docThe document for the Weight Manager. The caller owns the pointed BaseDocument.
[in]normalizetrue to normalize after bake operation, otherwise false.
Returns
true if successful, otherwise false.

§ CopyWeights()

static Bool CopyWeights ( BaseDocument doc)
static

Copies the weights of the selected joints into the weights clipboard.

Note
Document must be in either point, edge or polygon edit mode. If no selection is present on the mesh, all the point are copied, otherwise only the selected points are copied.
Parameters
[in]docThe document for the Weight Manager. The caller owns the pointed BaseDocument.
Returns
true if successful, otherwise false.

§ PasteWeights()

static Bool PasteWeights ( BaseDocument doc,
Bool  merge 
)
static

Pastes the copied weights on the selected joints. Uses the parameters currently set in the Weight Manager's container for the document.

Note
Adds an undo.
Parameters
[in]docThe document for the Weight Manager. The caller owns the pointed BaseDocument.
[in]mergetrue to merge with target weights, false to replace target weights:
  • true adds the source weights to the target weights. For instance, source point with null weight does not affect the final result.
  • false replaces all the target weights with the source weights including null source weights. For instance, all target weights are lost and replaced with source weights.
Returns
true if successful, otherwise false.

§ FlipWeights()

static Bool FlipWeights ( BaseDocument doc)
static

Flips the weights of the selected joints. Each joint is flipped on itself using the local axis specified in Weight Manager container.

Note
Both zero and non zero weights are flipped.
Parameters
[in]docThe document for the Weight Manager. The caller owns the pointed BaseDocument.
Returns
true if successful, otherwise false.

§ SmoothWeights()

static Bool SmoothWeights ( BaseDocument doc)
static

Smooths the weights of the selected joints. Uses the parameters currently set in the Weight Manager's container for the document.

Note
Does not support use of the interactive mode smooth. Smooth always acts on all the points of the mesh.
Parameters
[in]docThe document for the Weight Manager. The caller owns the pointed BaseDocument.
Returns
true if successful, otherwise false.

§ ApplyWeightFunction()

static Bool ApplyWeightFunction ( BaseDocument doc,
Bool  allPoints 
)
static

Applies the currently selected weighting function to the selected joints (add, smooth, remap etc.). Uses the parameters currently set in the Weight Manager's container for the document.

Note
The point selection is fetched from the actual component mode or from point mode if the document is not in component mode.
Parameters
[in]docThe document for the Weight Manager. The caller owns the pointed BaseDocument.
[in]allPointstrue to apply on all the points of the mesh, false to apply on point selection.
Returns
true if successful, otherwise false.