CKey Manual

Table of Contents

• About
• Access
• Allocation/Deallocation
• Handle
• Properties
  • Parameters
  • Selection
  • Time
  • Value
  • Tangents
  • Interpolation
  • Quaternion Interpolation
  • Preset
• Copy
• Functionality
• Bits
• Further Reading

About

A CKey represents a key of an animation track. CKey objects are stored in a CCurve which in return is stored in a CTrack object.

CKey objects are an instance of CKbase.

  // 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

CKey objects are accessed via the host CCurve:

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

See CCurve Manual.

  // 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);
  }

The host objects are accessed with:

• CKey::GetCurve(): Returns the CCurve of the key.
• CKey::GetTrack(): Returns the CTrack of the key.

Allocation/Deallocation

A CKey object can be created with the usual tools:

• CKey::Alloc(): Creates a new CKey.
• CKey::Free(): Deletes the given CKey.
• CCurve::InsertKey(): Inserts a key into the CCurve. The CCurve takes ownership.

But typically keys are created using the host CCurve:

• 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.

Keys can also be created using auto key functionality of the BaseDocument:

• BaseDocument::RecordKey(): Creates a key at the given time for the given parameter.
• BaseDocument::AutoKey(): Creates keys automatically if auto key mode is enabled.
• BaseDocument::Record(): Creates keyframes for all selected objects. Parameters must be added to the keyframe selection.

The default settings of a key are defined in the BaseDocument:

• BaseDocument::GetDefaultKey(): Returns the default key template.
• BaseDocument::SetDefaultKey(): Sets the default key template.

See also BaseDocument Animate.

Handle

CKey objects are manipulated with the host CCurve object.

• 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 keys dirty.
• CCurve::SetKeyDefault(): Sets the default settings for the key at the given index.
• CTrack::FillKey(): Fills the given key with default values.

  // 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);

Properties

Parameters

The parameters of a key can be edited as usual with C4DAtom::SetParameter() and C4DAtom::GetParameter(). The parameter IDs are defined in ckvalue.h.

  // This example sets the "Break Tangents" parameter of the first key.
 
  CKey* key = curve->GetKey(0);
  if (key)
  {
    key->SetParameter(ConstDescID(DescLevel(ID_CKEY_BREAK)), true, DESCFLAGS_SET::NONE);
  }

Note

The boolean parameters of a key are stored internally as bits, see Bits.

Selection

In Cinema 4D there can be up to four Timeline windows. A key can be selected in one or multiple of these windows. The selection state is stored as a bit:

• NBIT::TL1_SELECT : Selection bit for Timeline window 1.
• NBIT::TL2_SELECT : Selection bit for Timeline window 2.
• NBIT::TL3_SELECT : Selection bit for Timeline window 3.
• NBIT::TL4_SELECT : Selection bit for Timeline window 4.

  // This example selects the first key in the first timeline window.
 
  CKey* key = curve->GetKey(0);
  if (key)
  {
    key->ChangeNBit(NBIT::TL1_SELECT, NBITCONTROL::SET);
  }

Time

An animation key is defined by its position in time:

• CKey::GetTime(): Returns the time position of the key.
• CKey::SetTime(): Sets the time position of the key.

  // This example moves the current key one frame along the timeline.
 
  BaseTime time = key->GetTime();
  time = time + BaseTime(1, doc->GetFps());
 
  key->SetTime(curve, time);

See also BaseTime Manual.

Value

An animation key defines a certain value at a certain time:

• CKey::GetValue(): Returns the float value of the key.
• CKey::SetValue(): Sets the float value of the key.
• CKey::GetGeData(): Returns the generic data of the key (see also GeData Manual).
• CKey::SetGeData(): Sets the generic data of the key.

Note

Data of special tracks can be read and set using C4DAtom::GetParameter() and C4DAtom::SetParameter().

To set the keyframe for a Vector parameter one must define tracks and keyframes for each vector component.

    // This example handles the key value depending on the track category.
 
    // check if the track is "value" track (float)
    if (track->GetTrackCategory() == CTRACK_CATEGORY_VALUE)
    {
      Float value = key->GetValue();
      value = value + 1.0;
      key->SetValue(curve, value);
    }
    // check if the track is "data" track
    else if (track->GetTrackCategory() == CTRACK_CATEGORY_DATA)
    {
      GeData data = key->GetGeData();
      // handle GeData
      key->SetGeData(curve, data);
    }

See also CTrack Read-Only Properties and CCurve Animation.

Tangents

A key also defines the local tangents. These tangents influence the interpolation between the keys.

• CKey::GetAutomaticTangentMode(): Returns the AutoTangent mode of the key.
• CKey::SetAutomaticTangentMode(): Sets the AutoTangent mode of the key.

The modes are:

• CAUTOMODE::CLASSIC : AutoTangent first implementation.
• CAUTOMODE::FIXEDSLOPE : AutoTangent with fixed slope for given time.

The left and right tangents are defined by two points. These two points are defined by time and value.

The time property of the tangents can be accessed with:

• CKey::GetTimeLeft(): Returns the time of the left tangent.
• CKey::SetTimeLeft(): Sets the time of the left tangent.
• CKey::GetTimeRight(): Returns the time of the right tangent.
• CKey::SetTimeRight(): Sets the time of the right tangent.

The value property of the tangents can be accessed with:

• CKey::GetValueLeft(): Returns the value of the left tangent.
• CKey::SetValueLeft(): Sets the value of the left tangent.
• CKey::GetValueRight(): Returns the value of the right tangent.
• CKey::SetValueRight(): Sets the value of the right tangent.

The left and right tangent can be adjusted with:

• CKey::SetTimeLeftAdjustValue(): Sets time of the left tangent and adjusts the value so the angle stays the same.
• CKey::SetTimeRightAdjustValue(): Sets time of the right tangent and adjusts the value so the angle stays the same.

  // This example shortens the left tangent by one frame
  // while preserving the angle by adapting the value.
 
  BaseTime time = key->GetTimeLeft();
 
  time = time + BaseTime(1, doc->GetFps());
 
  key->SetTimeLeftAdjustValue(curve, time);

Interpolation

There are different ways to interpolate between the values of the animation keys. The interpolation from one key to the next is defined per key:

• CKey::GetInterpolation(): Returns the interpolation.
• CKey::SetInterpolation(): Sets the interpolation.

Interpolation modes are:

• CINTERPOLATION::SPLINE : Spline interpolation.
• CINTERPOLATION::LINEAR : Linear interpolation.
• CINTERPOLATION::STEP : Step interpolation.

    // This example sets the interpolation of the given key to linear.
 
    key->SetInterpolation(curve, CINTERPOLATION::LINEAR);

Quaternion Interpolation

Quaternion interpolation can be used on the rotation of a BaseObject. The kind of interpolation can be refined per key.

• CKey::GetQuatInterpolation(): Returns the interpolation mode.
• CKey::SetQuatInterpolation(): Sets the interpolation mode.
• ::ROTATIONINTERPOLATION_QUATERNION: The rotation interpolation mode.
  • ROTATIONINTERPOLATION_QUATERNION::SLERP: Quaternion Spherical LERP Interpolation (Linear)
  • ROTATIONINTERPOLATION_QUATERNION::CUBIC: Quaternion Smooth Cubic Interpolation (formerly known as Losch)

See also BaseObject Quaternion Rotation Mode.

Preset

Several presets exist to manage the clamp, slope and overshoot behaviour of a key.

• CKey::GetKeyPreset(): Return the preset mode of the key.
• CKey::SetKeyPreset(): Sets the preset mode of the key.

The preset modes are:

• CKEYPRESET::AUTO_CLAMP : Auto, Classical, Clamp.
• CKEYPRESET::AUTO_OVERSHOOT : Auto, Auto Angle, remove Overshooting.
• CKEYPRESET::AUTO_OVERSHOOTWEIGHTED : Auto, Auto Angle, remove Overshooting, weighted.
• CKEYPRESET::FIXED_OVERSHOOTWEIGHTED : Auto, Fixed Angle, remove Overshooting, weighted.
• CKEYPRESET::CUSTOM : User Defined.

    // This example checks the preset used by the given key.
    // If certain preset is used, a different preset is set.
 
    const CKEYPRESET preset = key->GetKeyPreset();
 
    if (preset == CKEYPRESET::AUTO_CLAMP)
    {
      // change preset
      key->SetKeyPreset(curve, CKEYPRESET::AUTO_OVERSHOOT);
    }

Copy

A new CKey can be created by copying an existing one.

• CKey::CopyDataTo(): Copies the data of the key into the given CKey.
• CKey::GetClone(): Returns a copy of the CKey.

  // This example creates a clone of the given key
  // and places it one second "later" in the timeline.
 
  CKey* const clone = key->GetClone(nullptr);
  if (clone == nullptr)
    return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
 
  const BaseTime time = key->GetTime() + BaseTime(1.0);
 
  clone->SetTime(curve, time);
  curve->InsertKey(clone);

Functionality

The data stored in a key can easily be flushed.

• CKey::FlushData(): Empties and resets data of the key.

Bits

The boolean parameters of a key are stored internally as bits. These bits can be edited directly.

• NBIT::CKEY_LOCK_T: Lock key time.
• NBIT::CKEY_LOCK_V: Lock key value.
• NBIT::CKEY_MUTE: Mute key.
• NBIT::CKEY_CLAMP: Clamp key tangents.
• NBIT::CKEY_BREAK: Break key tangents.
• NBIT::CKEY_KEEPVISUALANGLE: Keep visual angle.
• NBIT::CKEY_LOCK_O: Lock key tangents angles.
• NBIT::CKEY_LOCK_L: Lock key tangents length.
• NBIT::CKEY_AUTO: Key auto tangents
• NBIT::CKEY_WEIGHTEDTANGENT: Weighted Tangent.
• NBIT::CKEY_REMOVEOVERSHOOT: Remove Overshooting.
• NBIT::CKEY_AUTOWEIGHT: Automatic Weighting.

See also Parameters.

Further Reading

• Animation Overview
• CTrack Manual
• CCurve Manual
• BaseList2D Manual
• BaseTime Manual
• GeData Manual