CKey Manual

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)
{
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:

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:

Allocation/Deallocation

A CKey object can be created with the usual tools:

But typically keys are created using the host CCurve:

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

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

See also BaseDocument Animate.

Handle

CKey objects are manipulated with the host CCurve object.

// 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)
{
}
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:

// This example selects the first key in the first timeline window.
CKey* key = curve->GetKey(0);
if (key)
{
}

Time

An animation key is defined by its position in time:

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

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

The modes are:

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:

The value property of the tangents can be accessed with:

The left and right tangent can be adjusted with:

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

Interpolation modes are:

// This example sets the interpolation of the given key to linear.

Quaternion Interpolation

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

See also BaseObject Quaternion Rotation Mode.

Preset

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

The preset modes are:

// 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::CLASSICAUTO)
{
// change preset
}

Copy

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

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

Bits

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

See also Parameters.

Further Reading