CAWeightMgr Manual

Table of Contents

• About
• Settings
• Update
• Weight Tags
• Joints
  • Selection
  • Locked
• Functions
• Further Reading

About

The CAWeightMgr class represents the Weight Manager dialog window and its functionality. It gives access to the displayed tags (of type CAWeightTag) and joints.

Settings

The settings presented by the Weight Manager dialog are stored with the BaseDocument. They can be safely accessed with these functions:

• CAWeightMgr::SetParameter(): Set the Weight Manager setting.
• CAWeightMgr::GetParameter(): Returns the Weight Manager setting.

The setting IDs are defined in oweightmgr.h.

  // This example changes the settings that are displayed in the Weight Manager dialog.
 
  // enable "Display Weighting"
  CAWeightMgr::SetParameter(doc, ID_CA_WEIGHT_MGR_ENABLE_DISPLAY, true);
  // enable "Draw All Joints"
  CAWeightMgr::SetParameter(doc, ID_CA_WEIGHT_MGR_DISPLAY_ALL_WEIGHTS, true);
  // enable "Points"
  CAWeightMgr::SetParameter(doc, ID_CA_WEIGHT_MGR_DISPLAY_POINTS, true);

Update

The CAWeightMgr class accesses an internal cache. This internal cache is automatically updated if the Weight Manger window is opened or the weight tool is active. If this is not the case the internal cache must be updated manually to handle scene changes.

• CAWeightMgr::Update(): Updates the internal cache.
• CAWeightMgr::SetDirty(): Sets the Weight Manager dirty to force an update on the next call to CAWeightMgr::Update().

  // This example creates and adds a weight tag and a skin object
  // to the given polygon object. The joints stored in the given BaseArray
  // are linked in the weight tag. The weight manager is updated
  // and used to create auto-weights.
 
  // add weight tag and skin object
 
  AutoAlloc<CAWeightTag> wTag;
  AutoAlloc<BaseObject>  sObject { Oskin };
 
  if (wTag == nullptr)
    return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
  if (sObject == nullptr)
    return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
  CAWeightTag* const weightTag  = wTag.Release();
  BaseObject* const  skinObject = sObject.Release();
 
  polyObject->InsertTag(weightTag);
  doc->InsertObject(skinObject, polyObject, nullptr);
 
  // add joints from a BaseArray
  const Int jointCount = joints.GetCount();
 
  for (Int i = 0; i < jointCount; ++i)
  {
    BaseObject* const joint = joints[i];
    weightTag->AddJoint(joint);
  }
 
  // select tag
  doc->SetActiveTag(weightTag, SELECTION_NEW);
 
  // update weight manager
  CAWeightMgr::Update(doc);
 
  // select all joints
  CAWeightMgr::SelectAllJoints(doc);
 
  // auto weight
  CAWeightMgr::AutoWeight(doc);

Weight Tags

The Weight Manager dialog displays the joints of multiple (selected) weight tags.

• CAWeightMgr::GetTagCount(): Returns the number of displayed tags.
• CAWeightMgr::GetWeightTag(): Returns the CAWeightTag at the given index.
• CAWeightMgr::GetMeshObject(): Returns the host object of the weight tag at the given index.
• CAWeightMgr::GetTagIndex(): Returns the index of the given CAWeightTag.

  // This example loops through all Weight Tags
  // displayed in the Weight Manager window.
 
  // get tag count
 
  const Int32 tagCount = CAWeightMgr::GetTagCount(doc);
  if (tagCount == 0)
    return maxon::IllegalArgumentError(MAXON_SOURCE_LOCATION);
 
  // loop through all tags
  for (Int32 tagIndex = 0; tagIndex < tagCount; ++tagIndex)
  {
    // print tag name
    const CAWeightTag* const tag = CAWeightMgr::GetWeightTag(doc, tagIndex);
    if (tag == nullptr)
      return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
    ApplicationOutput("Weight Tag: " + tag->GetName());
 
    // print host object name
    const BaseObject* const hostObject = CAWeightMgr::GetMeshObject(doc, tagIndex);
    if (hostObject == nullptr)
      return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
    ApplicationOutput("Host Object: " + hostObject->GetName());
  }

Joints

Each CAWeightTag stores weights for joints. These joints are displayed in the Weight Manager dialog.

• CAWeightMgr::GetJointCount(): Returns the number of joint objects of the tag with the given index.
• CAWeightMgr::GetJointIndex(): Returns the index of the given joint object.
• CAWeightMgr::GetJointId(): Returns the ID of the given joint object.
• CAWeightMgr::GetJointObject(): Returns the joint object at the given index and tag index or ID.
• CAWeightMgr::ValidateJointIndex(): Returns true if the given tag/joint index pair exists.

  // This example loops through all joints (influences)
  // handled in the weight tag at the given index.
 
  // get count
  const Int32 jointCount = CAWeightMgr::GetJointCount(doc, tagIndex);
 
  // loop through all joints
  for (Int32 i = 0; i < jointCount; ++i)
  {
    const BaseObject* const joint = CAWeightMgr::GetJointObject(doc, tagIndex, i);
    if (joint == nullptr)
      return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
    // print joint name
    ApplicationOutput("Joint: " + joint->GetName());
  }

Selection

It is possible to select joint objects in the Weight Manager. Several operations only apply to such selected objects.

• CAWeightMgr::IsJointSelected(): Returns true if the joint object with the given index or ID is selected.
• CAWeightMgr::SelectJoint(): Selects the joint object with the given index or ID.
• CAWeightMgr::UnselectJoint(): Deselects the joint object with the given index or ID.

The selection state of all joint objects can easily be managed with:

• CAWeightMgr::SelectAllJoints(): Selects all joint objects
• CAWeightMgr::UnselectAllJoints(): Deselects all joint objects.
• CAWeightMgr::UnselectAllJointListNodes(): Deselects all of the nodes in the Weight Manager joint list.

  // This example loops through all selected objects. If the object
  // is a joint it will also be selected in the weight manager.
 
  // get all selected objects
 
  AutoAlloc<AtomArray> objects;
  if (objects == nullptr)
    return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
  doc->GetActiveObjects(objects, GETACTIVEOBJECTFLAGS::CHILDREN);
 
  // deselect all influences
  CAWeightMgr::UnselectAllJoints(doc);
 
  // loop through all objects
  for (Int32 i = 0; i < objects->GetCount(); ++i)
  {
    // get object
    C4DAtom* const    atom  = objects->GetIndex(i);
    BaseObject* const joint = static_cast<BaseObject*>(atom);
    if (joint == nullptr)
      return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
    // check if joint
    if (joint->IsInstanceOf(Ojoint))
    {
      // get id
      const UInt64 id = CAWeightMgr::GetJointId(doc, weightTag, joint);
 
      if (id != maxon::LIMIT<UInt64>::MAX)
      {
        // check if selected
        if (joint->GetBit(BIT_ACTIVE))
          CAWeightMgr::SelectJoint(doc, id);
      }
    }
  }

Locked

The Weight Manager can lock a joint object to prevent unintended changes.

• CAWeightMgr::IsJointLocked(): Returns true if the joint object with the given index or ID is locked.
• CAWeightMgr::LockSelectedJoints(): Locks the selected joint objects.
• CAWeightMgr::UnlockSelectedJoints(): Unlocks the selected joint objects.

The lock state of all joint objects can be managed with:

• CAWeightMgr::LockAllJoints(): Locks all joint objects.
• CAWeightMgr::UnlockAllJoints(): Unlocks all joint objects.

  // This example inverts the lock state of all influences
  // in the weight tag with the given index.
 
  // deselect all
  CAWeightMgr::UnselectAllJoints(doc);
 
  // get count
  const Int32 jointCount = CAWeightMgr::GetJointCount(doc, tagIndex);
 
  // loop through all joints
  for (Int32 i = 0; i < jointCount; ++i)
  {
    // check if locked
    if (CAWeightMgr::IsJointLocked(doc, tagIndex, i) == false)
    {
      // select unlocked
      CAWeightMgr::SelectJoint(doc, tagIndex, i);
    }
  }
 
  // unlock all
  CAWeightMgr::UnlockAllJoints(doc);
 
  // lock selected
  CAWeightMgr::LockSelectedJoints(doc);

Functions

The weight algorithms are edited with these static functions:

• CAWeightMgr::GetAutoWeightAlgoIndex(): Returns the index of the given auto weight algorithm (used with ID_CA_WEIGHT_MGR_AUTOWEIGHT_MODE).
• CAWeightMgr::GetAutoWeightAlgoId(): Returns the maxon::Id of the given auto weight algorithm index.
• CAWeightMgr::GetAutoWeightRef(): Returns the auto weight reference. See AutoWeightInterface Implementation.
• CAWeightMgr::GetAutoWeightDictionary(): Returns the DataDictionary with the algorithm's settings.
• CAWeightMgr::SetAutoWeightDictionary(): Sets the DataDictionary of the given algorithm.

Note

The auto weight algorithm IDs are defined in maxon/autoweight.h, the settings in maxon/autoweight_attributes.h.

Several weight tools of the Weight Manager can be invoked with dedicated functions. These functions add an undo step.

• CAWeightMgr::NormalizeWeights(): Applies a normalization.
• CAWeightMgr::ClearWeights(): Clears all weights.
• CAWeightMgr::AutoWeight(): Runs an auto weight algorithm.
• CAWeightMgr::MirrorWeights(): Mirrors the weights.
• CAWeightMgr::BakeWeights(): Bakes the effector weights.
• CAWeightMgr::FlipWeights(): Flips the weights.
• CAWeightMgr::SmoothWeights(): Smooths the weights.
• CAWeightMgr::ApplyWeightFunction(): Applies the currently selected weighting function.

Note

The functions take the selection state of a joint object into account.

Copy and paste functions are:

• CAWeightMgr::CopyWeights(): Copies the weights of the selected joint objects.
• CAWeightMgr::PasteWeights(): Pastes the copied weights on the selected joint objects.

  // This example configures the Weight Manager settings and applies the "Auto Weight" function.
 
  // get modes
 
  const maxon::Id    targetMode = maxon::AutoWeightAlgos::BoneglowClass().GetId();
  const maxon::Int64 index = CAWeightMgr::GetAutoWeightAlgoIndex(doc, targetMode) iferr_return;
 
  // set mode
  GeData geData;
  geData.SetInt32(index);
  CAWeightMgr::SetParameter(doc, ID_CA_WEIGHT_MGR_AUTOWEIGHT_MODE, geData);
 
  // get settings
  maxon::DataDictionary data = CAWeightMgr::GetAutoWeightDictionary(doc, targetMode) iferr_return;
 
  // set settings
  data.Set(maxon::ANIMATION::AUTOWEIGHT::BONEGLOW::USEVISIBILITY, true) iferr_return;
  data.Set(maxon::ANIMATION::AUTOWEIGHT::BONEGLOW::VISIBILITYRATIO, 0.3_f) iferr_return;
  CAWeightMgr::SetAutoWeightDictionary(doc, data, targetMode) iferr_return;
 
  // apply
  CAWeightMgr::AutoWeight(doc);

Further Reading

• Character Animation Overview
• CAWeightTag Manual