CCurve Manual

Table of Contents

• About
• Access
• Keys
  • Access Keys
  • Add Keys
  • Handle Keys
  • Unmuted Keys
• Animation
• Time
• Further Reading

About

A CCurve represents an animation curve that stores and interpolates animation keys. A CCurve is stored in a CTrack object.

CCurve objects are an instance of CSbase.

  // This code loops through all tracks and all keys of the given object.
 
  CTrack* track = activeObject->GetFirstCTrack();
 
  while (track != nullptr)
  {
    CCurve* const curve = track->GetCurve();
    if (curve == nullptr)
      continue;
 
    const Int32 keyCount = curve->GetKeyCount();
    for (Int32 i = 0; i < keyCount; ++i)
    {
      CKey* const key = curve->GetKey(i);
      if (key)
      {
        // do something with the key
        ApplicationOutput("Found a key!");
      }
    }
 
    track = track->GetNext();
  }

Access

CCurve objects cannot be created on their own. They are created with a CTrack that contains the CCurve object.

• CTrack::GetCurve(): Returns the CCurve object stored with a CTrack. See example above.
• CCurve::GetTrack(): Returns the CTrack that stores the CCurve.

Keys

Access Keys

The CCurve objects stores the animation keys and provides access to these:

• CCurve::GetKeyCount(): Returns the number of keys.
• CCurve::GetKey(): Returns the CKey at the given index.
• CCurve::FindKey(): Returns the (next) CKey at the given time.
  • FINDANIM::EXACT : Searches for a CKey at the exact given time.
  • FINDANIM::LEFT : Searches for a CKey on the left side of the given time.
  • FINDANIM::RIGHT : Searches for a CKey on the right side of the given time.

  // This example searches for a key left from the given time.
 
  const BaseTime time = doc->GetTime();
 
  CKey* const leftKey = curve->FindKey(time, nullptr, FINDANIM::LEFT);
 
  if (leftKey)
  {
    // move this key to the current time
    leftKey->SetTime(curve, time);
  }

Add Keys

A CCurve object can create and receive keys:

• CCurve::AddKey(): Adds a new key to the CCurve.
• CCurve::AddKeyAdaptTangent(): Adds a new key to the CCurve but retains the curve's current curvature.
• CCurve::InsertKey(): Inserts a key into the CCurve. The CCurve takes ownership.

  // This example creates keys along the timeline.
 
  const Int32    fps = doc->GetFps();
  const Int32    min = doc->GetMinTime().GetFrame(fps);
  const Int32    max = doc->GetMaxTime().GetFrame(fps);
  const Int32    range = max - min;
  const Int32    step  = range / 10;
  const BaseTime stepTime = BaseTime(step, fps);
 
  BaseTime keyTime = doc->GetMinTime();
 
  for (Int32 i = 0; i <= 10; ++i)
  {
    if (curve->AddKey(keyTime, nullptr) == nullptr)
      return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
    keyTime = keyTime + stepTime;
  }

See also CKey Allocation/Deallocation.

Handle Keys

A CCurve object can be used to manipulate its keys:

• CCurve::DelKey(): Deletes the key at the given index.
• CCurve::MoveKey(): Moves the key at the given index.
• CCurve::FlushKeys(): Removes all keys from the curve.
• CCurve::SetKeyDirty(): Sets the key dirty.
• CCurve::SetKeyDefault(): Sets the default settings for the key at the given index.

  // This example creates a new key and sets the default values.
 
  Int32       index;
  CKey* const newKey = curve->AddKey(time, &index);
  if (newKey == nullptr)
    return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
  track->FillKey(doc, obj, newKey);
  curve->SetKeyDefault(doc, index);

Unmuted Keys

A key can be muted so it is ignored.

• CCurve::FindNextUnmuted(): Returns the next unmuted key searching from the given index. (included)
• CCurve::FindPrevUnmuted(): Returns the previous unmuted key searching from the given index. (included)

  // This example searches for the first unmuted key.
 
  const CKey* const key = curve->FindNextUnmuted(0);
 
  if (key)
  {
    const Float time = key->GetTime().Get();
    ApplicationOutput("Found unmuted key at " + String::FloatToString(time));
  }

See also CKey Bits.

Animation

The interpolation between the keys defines the dynamics of an animation. This interpolation is refined with the tangents.

• CCurve::CalcHermite(): Calculates the Hermite spline between two sets of key values.
• CCurve::CalcSoftTangents(): Calculates the soft tangents (i.e. auto interpolation) around the key of the given index.
• CCurve::GetTangents(): Computes the tangents of a key, taking into account all options like zero slope, link slope etc.
• CCurve::GetValue(): Returns the value calculated at the given time, taking into account things like time curves.

  // This example samples the curve.
 
  BaseTime       time(0.0);
  const BaseTime step(0.1);
 
  for (Int32 i = 0; i < 10; ++i)
  {
    const Float value = curve->GetValue(time);
    ApplicationOutput("Value: " + String::FloatToString(value));
 
    time = time + step;
  }

Time

A CCurve is confined by a first and a last key:

• CCurve::GetStartTime(): Returns the start time of the curve.
• CCurve::GetEndTime(): Returns the end time of the curve.

  // This example sets the loop time dimensions based on the start
  // and end time of the given curve.
 
  const BaseTime start = curve->GetStartTime();
  const BaseTime end = curve->GetEndTime();
 
  doc->SetLoopMinTime(start);
  doc->SetLoopMaxTime(end);

Further Reading

• Animation Overview
• CTrack Manual
• CKey Manual
• BaseList2D Manual
• BaseTime Manual