CAPoseMorphTag Manual

Table of Contents

• About
• Access
• Allocation/Deallocation
• Properties
• Morphs
• PSD
• Mode
• Further Reading

About

The CAPoseMorphTag class represents a pose morph tag. Such a tag stores multiple morphs that can be applied to the host object (and it's child objects) to modify and animate it. The class is defined in the lib_ca.h header file.

CAPoseMorphTag objects are an instance of Tposemorph.

  // This example creates a cube with a CAPoseMorphTag.
  // A base morph and an additional morph are added to the tag.
 
  // create cube
 
  BaseObject* const cube = BaseObject::Alloc(Ocube);
  if (cube == nullptr)
    return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
  doc->InsertObject(cube, nullptr, nullptr);
 
  // create morph tag
 
  CAPoseMorphTag* const poseMorphTag = CAPoseMorphTag::Alloc();
  if (poseMorphTag == nullptr)
    return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
  cube->InsertTag(poseMorphTag);
 
  poseMorphTag->InitMorphs();
 
  // configure tag
  poseMorphTag->SetParameter(ID_CA_POSE_PARAM, true, DESCFLAGS_SET::NONE);
 
  // edit morphs
 
  poseMorphTag->ExitEdit(doc, true);
 
  // add base morph
  CAMorph* const baseMorph = poseMorphTag->AddMorph();
  if (baseMorph == nullptr)
    return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
  baseMorph->Store(doc, poseMorphTag, CAMORPH_DATA_FLAGS::ASTAG);
 
  // modify cube
  cube->SetParameter(PRIM_CUBE_LEN, Vector(200, 400, 200), DESCFLAGS_SET::NONE);
 
  // add morph
  CAMorph* const morph = poseMorphTag->AddMorph();
  if (morph == nullptr)
    return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
  // store current state in morph
  morph->SetName("Scaled Size");
  morph->Store(doc, poseMorphTag, CAMORPH_DATA_FLAGS::ASTAG);
 
  poseMorphTag->UpdateMorphs();
 
  // switch to "Animate" mode
  poseMorphTag->SetParameter(ID_CA_POSE_MODE, ID_CA_POSE_MODE_ANIMATE, DESCFLAGS_SET::NONE);
 
  // set strength
  const DescID sliderID = poseMorphTag->GetMorphID(1);
  poseMorphTag->SetParameter(sliderID, 0.5, DESCFLAGS_SET::NONE);

Access

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

  // This example accesses the selected pose morph tag and
  // prints the names of all it's morphs.
 
  // get tag
 
  BaseTag* const tag = doc->GetActiveTag();
  if (tag == nullptr || !tag->IsInstanceOf(Tposemorph))
    return maxon::IllegalArgumentError(MAXON_SOURCE_LOCATION);
 
  CAPoseMorphTag* const poseMorphTag = static_cast<CAPoseMorphTag*>(tag);
 
  // loop through all morphs
 
  const Int32 morphCount = poseMorphTag->GetMorphCount();
 
  for (Int32 i = 0; i < morphCount; ++i)
  {
    CAMorph* const morph = poseMorphTag->GetMorph(i);
    if (morph != nullptr)
    {
      // print morph name
      ApplicationOutput("Morph: " + morph->GetName());
    }
  }

Allocation/Deallocation

CAPoseMorphTag instances are created with the usual tools, see Entity Creation and Destruction Manual (Classic).

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

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

After creation, the tag must be initialized.

• CAPoseMorphTag::InitMorphs(): Initializes the morph tag.

Properties

The parameters of CAPoseMorphTag can be edited with C4DAtom::SetParameter() and C4DAtom::GetParameter(). The parameter IDs are defined in tcaposemorph.h.

Note

Several settings of the active morph must be set on the morph tag using C4DAtom::SetParameter().

  // This example enables "Points", adds a new morph and
  // switches to "Animate" mode.
 
  // mix points
  poseMorphTag->SetParameter(ID_CA_POSE_POINTS, true, DESCFLAGS_SET::NONE);
 
  // add new morph
  CAMorph* const morph = poseMorphTag->AddMorph();
  if (morph == nullptr)
    return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
  morph->SetName("New Morph");
 
  // set morph as the active morph
  const Int32 index = poseMorphTag->GetMorphIndex(morph);
  poseMorphTag->SetActiveMorphIndex(index);
 
  // update
  poseMorphTag->UpdateMorphs(doc);
 
  // enable "Post Deformers" for the active morph
  poseMorphTag->SetParameter(ID_CA_POSE_MIXING_DEFORMED, true, DESCFLAGS_SET::NONE);
 
  // switch to animate mode
  poseMorphTag->SetParameter(ID_CA_POSE_MODE, ID_CA_POSE_MODE_ANIMATE, DESCFLAGS_SET::NONE);

Morphs

Any change to the morph data must be encompassed by the following functions:

• CAPoseMorphTag::ExitEdit(): Must be called before doing anything to a morph tag.
• CAPoseMorphTag::UpdateMorphs(): Updates the tag's internal data after any change to the morphs.

The stored morphs are accessed with:

• CAPoseMorphTag::GetMorphCount(): Returns the number of morphs.
• CAPoseMorphTag::GetMorph(): Returns the CAMorph for the given index.
• CAPoseMorphTag::GetMorphID(): Returns the strength DescID for the morph with the given index. This DescID is used to set the strength or to create animation tracks etc.
• CAPoseMorphTag::GetActiveMorph(): Returns the currently active CAMorph.
• CAPoseMorphTag::GetActiveMorphIndex(): Returns the index of the currently active morph.
• CAPoseMorphTag::SetActiveMorphIndex(): Selects the morph with the given index.
• CAPoseMorphTag::GetMorphBase(): Returns the base morph (index 0).
• CAPoseMorphTag::GetMorphIndex(): Returns the index of the given CAMorph.
• CAPoseMorphTag::AddMorph(): Creates and adds a new CAMorph.
• CAPoseMorphTag::RemoveMorph(): Removes the morph with the given index.

See also CAMorph Manual.

  // This example lists the names and strengths
  // of all morphs in the given tag.
 
  const Int32 morphCount = poseMorphTag->GetMorphCount();
 
  for (Int32 i = 0; i < morphCount; ++i)
  {
    CAMorph* const morph = poseMorphTag->GetMorph(i);
    if (morph == nullptr)
      return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
    // print morph name
    ApplicationOutput("Morph: " + morph->GetName());
 
    // ignore base morph
    if (i != 0)
    {
      // print current strength of the morph
 
      const DescID id = poseMorphTag->GetMorphID(i);
 
      GeData data;
      poseMorphTag->GetParameter(id, data, DESCFLAGS_GET::NONE);
      const Float strength = data.GetFloat();
 
      ApplicationOutput("Strength: " + String::FloatToString(strength));
    }
  }

  // This example deletes the currently selected morph.
 
  poseMorphTag->ExitEdit(doc, true);
 
  // delete active morph
  const Int32 activeIndex = poseMorphTag->GetActiveMorphIndex();
  poseMorphTag->RemoveMorph(activeIndex);
 
  poseMorphTag->UpdateMorphs();

PSD

Several Pose Space Deformation related settings can be edited with these functions:

• CAPoseMorphTag::GetPSDFeedbackColor(): Returns the feedback color.
• CAPoseMorphTag::SetPSDFeedbackColor(): Sets the feedback color.
• CAPoseMorphTag::GetPSDFeedbackColorEnabled(): Checks if feedback color is enabled.
• CAPoseMorphTag::SetPSDFeedbackColorEnabled(): Enables or disables feedback color use.
• CAPoseMorphTag::GetPSDOrientThreshold(): Returns the orient radian threshold.
• CAPoseMorphTag::SetPSDOrientThreshold(): Sets the orient radian threshold.
• CAPoseMorphTag::GetPSDTwistThreshold(): Returns the twist radian threshold.
• CAPoseMorphTag::SetPSDTwistThreshold(): Sets the twist radian threshold.
• CAPoseMorphTag::GetPSDPositionThreshold(): Returns the position distance threshold.
• CAPoseMorphTag::SetPSDPositionThreshold(): Sets the position distance threshold.
• CAPoseMorphTag::GetMorphPSDID(): Returns the DescID for the parameter of the given morph index and attribute ID.

See also CAReferencePSD Manual.

  // This example changes the PSD display settings on the given pose morph tag.
 
  CAPoseMorphTag* const poseMorphTag = static_cast<CAPoseMorphTag*>(tag);
 
  if (poseMorphTag)
  {
    // enable color
    poseMorphTag->SetPSDFeedbackColorEnabled(true);
    // set color to red
    poseMorphTag->SetPSDFeedbackColor(Vector(1.0, 0.0, 0.0));
  }

Mode

A CAPoseMorphTag can either be in "edit" or "animate" mode:

• CAPoseMorphTag::GetMode(): Returns the current mode of the tag.

Note

To change the mode use C4DAtom::SetParameter() with DescID ID_CA_POSE_MODE.

Further Reading

• Character Animation Overview
• CAMorph Manual
• CAMorphNode Manual
• CAReferencePSD Manual