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 maxon::Result< Int32 > GetAutoWeightAlgoIndex (BaseDocument *doc, const maxon::Id &id)
 
static maxon::Result< maxon::Id > GetAutoWeightAlgoId (BaseDocument *doc, Int index)
 
static maxon::Result< void > GetAutoWeightRef (BaseDocument *doc, const maxon::Id &autoweightId, maxon::AutoWeightRef &autoWeightRef)
 
static maxon::Result< maxon::DataDictionary > GetAutoWeightDictionary (BaseDocument *doc, const maxon::Id &autoweightId)
 
static maxon::Result< void > SetAutoWeightDictionary (BaseDocument *doc, maxon::DataDictionary dataDictionary, maxon::Id autoweightId)
 
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 BaseObject * GetJointObject (BaseDocument *doc, Int32 tagIdx, Int32 jointIdx)
 
static BaseObject * GetJointObject (BaseDocument *doc, UInt64 id)
 
static CAWeightTag * GetWeightTag (BaseDocument *doc, Int32 tagIdx)
 
static BaseObject * GetMeshObject (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)
 
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.

◆ GetAutoWeightAlgoIndex()

static maxon::Result<Int32> GetAutoWeightAlgoIndex ( BaseDocument *  doc,
const maxon::Id &  id 
)
static

Get the AutoWeightRef algorithm's index associated with the given id.

Parameters
[in]docThe active document.
[in]idThe autoweight id.
Returns
The index of the autoweight id.

◆ GetAutoWeightAlgoId()

static maxon::Result<maxon::Id> GetAutoWeightAlgoId ( BaseDocument *  doc,
Int  index 
)
static

Get the AutoWeightRef algorithm's id associated with the given index.

Parameters
[in]docThe active document.
[in]indexThe autoweight int.
Returns
The index of the autoweight id.

◆ GetAutoWeightRef()

static maxon::Result<void> GetAutoWeightRef ( BaseDocument *  doc,
const maxon::Id &  autoweightId,
maxon::AutoWeightRef &  autoWeightRef 
)
static

Get the AutoWeightRef from the given id.

Parameters
[in]docThe document for the Weight Manager. The caller owns the pointed BaseDocument..
[in]autoweightIdThe maxon id of the autoweight algorithm.
Returns
OK on success.

◆ GetAutoWeightDictionary()

static maxon::Result<maxon::DataDictionary> GetAutoWeightDictionary ( BaseDocument *  doc,
const maxon::Id &  autoweightId 
)
static

Get autoweight dictionary of the Weight Manager.

Parameters
[in]docThe document for the Weight Manager. The caller owns the pointed BaseDocument..
[in]autoweightIdThe maxon id of the autoweight algorithm.
Returns
The data dictionary with the autoweight parameters inside.

◆ SetAutoWeightDictionary()

static maxon::Result<void> SetAutoWeightDictionary ( BaseDocument *  doc,
maxon::DataDictionary  dataDictionary,
maxon::Id  autoweightId 
)
static

Set autoweight dictionary of the Weight Manager.

Parameters
[in]docThe document for the Weight Manager. The caller owns the pointed BaseDocument..
[in]dataDictionaryThe data dictionary with the autoweight parameters inside.
[in]autoweightIdThe maxon id of the autoweight algorithm.
Returns
OK on success.

◆ 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)
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.
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.