About

The CAWeightTag class represents a weight tag. A weight tag stores weights that define the influence a joint object has on a deformed mesh. The class is defined in the lib_ca.h header file.

CAWeightTag objects are an instance of Tweights.

Access

A CAWeightTag tag can be accessed like any other tag, see BaseTag and VariableTag Manual.

  // This example accesses the selected weight tag
  // and prints the names of weighted joints.
 
  // get weight tag
 
  BaseTag* const tag = doc->GetActiveTag();
 
  if (tag == nullptr || !tag->IsInstanceOf(Tweights))
    return maxon::IllegalArgumentError(MAXON_SOURCE_LOCATION);
 
  CAWeightTag* const weightTag = static_cast<CAWeightTag*>(tag);
 
  // loop through all joints
 
  const Int32 jointCount = weightTag->GetJointCount();
 
  for (Int32 i = 0; i < jointCount; ++i)
  {
    const BaseObject* const joint = weightTag->GetJoint(i, doc);
    if (joint == nullptr)
      return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
    ApplicationOutput("Joint: " + joint->GetName());
  }

Allocation/Deallocation

CAWeightTag instances are created with the usual tools, see Entity Creation and Destruction Manual (Cinema API).

CAWeightTag::Alloc(): Creates a new CAWeightTag.
CAWeightTag::Free(): Deletes the given CAWeightTag.

  // This example creates a new CAWeightTag
  // and adds it to the given polygon object.
 
  CAWeightTag* const weightTag = CAWeightTag::Alloc();
  if (weightTag == nullptr)
    return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
  polygonObject->InsertTag(weightTag);

Properties

Standard parameters on a CAWeightTag can be edited with C4DAtom::GetParameter() and C4DAtom::SetParameter(). The parameter IDs are defined in tcaweight.h.

Joints

A CAWeightTag manages a list of references to various joint objects.

CAWeightTag::AddJoint(): Adds a joint to the list.
CAWeightTag::RemoveJoint(): Removes the given joint from the list.
CAWeightTag::GetJointCount(): Returns the number of joints in the list.
CAWeightTag::GetJoint(): Returns the joint at the given index.
CAWeightTag::FindJoint(): Returns the index of the given joint object.

  // This example adds all selected joint objects to the given weight tag.
 
  AutoAlloc<AtomArray> objects;
  if (objects == nullptr)
    return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
  // get selected objects
  doc->GetActiveObjects(objects, GETACTIVEOBJECTFLAGS::CHILDREN);
 
  // loop through all objects
  const Int32 objectCount = objects->GetCount();
 
  for (Int32 i = 0; i < objectCount; ++i)
  {
    C4DAtom* const    atom = objects->GetIndex(i);
    BaseObject* const baseObject = static_cast<BaseObject*>(atom);
    if (baseObject == nullptr)
      return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
    // only add joint objects
    if (baseObject->IsInstanceOf(Ojoint))
    {
      weightTag->AddJoint(baseObject);
    }
  }

For each joint the reset (or rest) state is stored:

CAWeightTag::GetJointRestState(): Returns the JointRestState for the joint at the given index.
CAWeightTag::SetJointRestState(): Sets the JointRestState for the joint at the given index.

The JointRestState structure has these members:

JointRestState::m_bMg: The global matrix of the bone between two joints.
JointRestState::m_bMi: The inverse matrix of m_bMg.
JointRestState::m_oMg: The global matrix of the joint object.
JointRestState::m_oMi: The inverse matrix of m_oMg.
JointRestState::m_Len: The bone rest length.

  // This example loops through all joints known by the given weight tag
  // and prints the rest state length to the console.
 
  // loop through all joints
 
  const Int32 jointCount = weightTag->GetJointCount();
 
  for (Int32 i = 0; i < jointCount; ++i)
  {
    const JointRestState state = weightTag->GetJointRestState(i);
 
    const Float length = state.m_Len;
 
    ApplicationOutput("Rest Length: " + String::FloatToString(length));
  }

Weights

A CAWeightTag stores weights for each point and joint.

CAWeightTag::GetWeightCount(): Returns the total number of stored weights for the given joint index.
CAWeightTag::GetWeightMap(): Fills the given map with weights for the given joint index.
CAWeightTag::SetWeightMap(): Sets the weights for the given joint index.

Note: The order of weight values does not correspond to the point order.

      // This example loads the weights stored for the given joint
      // and prints them to the console window.
 
      // check if any weights are stored
      const Int32 weightCount = weightTag->GetWeightCount(jointIndex);
      if (weightCount == 0)
        continue;
 
      const Int32 pointCount = polyObject->GetPointCount();
 
      // allocate memory
      maxon::BaseArray<Float32> weights;
      weights.Resize(pointCount) iferr_return;
 
      // load weights
 
      Float32* const handle = weights.GetFirst();
      weightTag->GetWeightMap(jointIndex, handle, pointCount);
 
      // print weights
 
      for (Int32 weightIndex = 0; weightIndex < pointCount; ++weightIndex)
      {
        const Float32 weight = weights[weightIndex];
        ApplicationOutput("Weight: " + String::FloatToString(weight));
      }

CAWeightTag::GetIndexWeight(): Retrieves the point index and weight value for the given joint index and weight index.
CAWeightTag::GetWeight(): Returns the weight value for the given joint and point index.
CAWeightTag::SetWeight(): Sets the weight value for the given joint and point index.
CAWeightTag::GetWeightDirty(): Returns the dirty state of weights.
CAWeightTag::WeightDirty(): Sets the dirty state for weights. Call this to update the weights after any change.

      // This example loops through all points to receive weights for each point.
 
      // loop through all points
      const Int32 pointCount = polyObject->GetPointCount();
 
      for (Int32 pointIndex = 0; pointIndex < pointCount; ++pointIndex)
      {
        const Float weight = weightTag->GetWeight(jointIndex, pointIndex);
 
        ApplicationOutput("Point " + String::IntToString(pointIndex) + " : " + String::FloatToString(weight));
      }

Matrix

CAWeightTag::GetGeomMg(): Returns the global matrix for the bind geometry.
CAWeightTag::SetGeomMg(): Sets the global matrix for the bind geometry.

Functions

CAWeightTag offers these functions:

CAWeightTag::ResetBindPose(): Resets the bind pose.
CAWeightTag::SetBindPose(): Sets the bind pose.
CAWeightTag::CalculateBoneStates(): Initializes the joint at the given index (or NOTOK for all).
CAWeightTag::TransferWeightMap(): Transfers the weights to the given target tag.

  // This example moves a joint and its rest state
  // and updates the rest state data.
 
  // update rest state
 
  JointRestState state = weightTag->GetJointRestState(1);
 
  state.m_oMg.off = state.m_oMg.off + Vector(0, 100.0, 0);
  state.m_oMi = ~state.m_oMg;
 
  weightTag->SetJointRestState(1, state);
 
  // update joint object position
  BaseObject* const joint = weightTag->GetJoint(1, doc);
  if (joint)
    joint->SetMg(state.m_oMg);
 
  // calculate states
  weightTag->CalculateBoneStates(NOTOK);

Table of Contents