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 != 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:

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:

  • CKEYPRESET::CLASSICAUTO : Auto, Classical, Clamp.
  • CKEYPRESET::NEWAUTO : Auto, Classical, remove Overshooting.
  • CKEYPRESET::NEWAUTOWEIGHTED : Auto, Fixed Slope, remove Overshooting.
  • 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
}

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

CKEYPRESET::AUTO_CLAMP
@ AUTO_CLAMP
Auto, Auto Angle, Clamp.
CKey::GetKeyPreset
CKEYPRESET GetKeyPreset(void) const
Definition: c4d_canimation.h:336
NBITCONTROL::SET
@ SET
Set bit.
CKey::SetTime
void SetTime(CCurve *seq, const BaseTime &t)
Definition: c4d_canimation.h:96
CKey::GetGeData
const GeData & GetGeData(void) const
Definition: c4d_canimation.h:163
BaseTime
Definition: c4d_basetime.h:24
CKEYPRESET
CKEYPRESET
Definition: ge_prepass.h:3990
BaseDocument::GetFps
Int32 GetFps(void) const
CKey::SetValue
void SetValue(CCurve *seq, Float v)
Definition: c4d_canimation.h:157
GeListNode::ChangeNBit
Bool ChangeNBit(NBIT bit, NBITCONTROL bitmode)
CCurve::GetKey
const CKey * GetKey(Int32 index) const
Definition: c4d_canimation.h:377
Float
maxon::Float Float
Definition: ge_sys_math.h:66
ID_CKEY_BREAK
@ ID_CKEY_BREAK
Definition: ckvalue.h:20
CCurve
Definition: c4d_canimation.h:354
CCurve::InsertKey
Bool InsertKey(CKey *ckey, Bool bUndo=false, Bool SynchronizeKeys=false)
Definition: c4d_canimation.h:431
MAXON_SOURCE_LOCATION
#define MAXON_SOURCE_LOCATION
Definition: memoryallocationbase.h:66
CCurve::AddKey
CKey * AddKey(const BaseTime &time, Int32 *nidx=nullptr, Bool bUndo=false, Bool SynchronizeKeys=false)
Definition: c4d_canimation.h:412
CKey::SetInterpolation
void SetInterpolation(CCurve *seq, CINTERPOLATION inter)
Definition: c4d_canimation.h:214
DESCFLAGS_SET::NONE
@ NONE
None.
CTrack
Definition: c4d_canimation.h:659
CTRACK_CATEGORY_DATA
#define CTRACK_CATEGORY_DATA
Data track.
Definition: c4d_canimation.h:623
CKey::SetKeyPreset
void SetKeyPreset(CCurve *seq, CKEYPRESET preset)
Definition: c4d_canimation.h:344
FINDANIM::LEFT
@ LEFT
Search left.
CTrack::FillKey
Bool FillKey(BaseDocument *doc, BaseList2D *bl, CKey *key)
Definition: c4d_canimation.h:810
C4DAtom::SetParameter
Bool SetParameter(const DescID &id, const GeData &t_data, DESCFLAGS_SET flags)
CKey::GetTimeLeft
BaseTime GetTimeLeft(void) const
Definition: c4d_canimation.h:102
CTrack::GetNext
CTrack * GetNext() const
Definition: c4d_canimation.h:705
BaseDocument::GetTime
BaseTime GetTime(void) const
CKey::GetValue
Float GetValue(void) const
Definition: c4d_canimation.h:150
CKey::SetGeData
void SetGeData(CCurve *seq, const GeData &d)
Definition: c4d_canimation.h:170
CTrack::GetTrackCategory
Int32 GetTrackCategory() const
Definition: c4d_canimation.h:830
CKEYPRESET::AUTO_OVERSHOOT
@ AUTO_OVERSHOOT
Auto, Auto Angle, remove Overshooting.
GeData
Definition: c4d_gedata.h:82
Int32
maxon::Int32 Int32
Definition: ge_sys_math.h:60
ApplicationOutput
#define ApplicationOutput(formatString,...)
Definition: debugdiagnostics.h:207
CKey::SetTimeLeftAdjustValue
Bool SetTimeLeftAdjustValue(CCurve *seq, const BaseTime &t)
Definition: c4d_canimation.h:315
CKey
Definition: c4d_canimation.h:57
CKey::GetTime
BaseTime GetTime(void) const
Definition: c4d_canimation.h:89
CINTERPOLATION::LINEAR
@ LINEAR
Linear.
CTRACK_CATEGORY_VALUE
#define CTRACK_CATEGORY_VALUE
Value track.
Definition: c4d_canimation.h:622
NBIT::TL1_SELECT
@ TL1_SELECT
Selection bit for Timeline 1.
CCurve::SetKeyDefault
void SetKeyDefault(BaseDocument *doc, Int32 kidx)
CTrack::GetCurve
CCurve * GetCurve(CCURVE type=CCURVE::CURVE, Bool bCreate=true)
Definition: c4d_canimation.h:824
CCurve::FindKey
const CKey * FindKey(const BaseTime &time, Int32 *idx=nullptr, FINDANIM match=FINDANIM::EXACT) const
Definition: c4d_canimation.h:393
BaseList2D::GetFirstCTrack
CTrack * GetFirstCTrack()
CCurve::GetKeyCount
Int32 GetKeyCount(void) const
Definition: c4d_canimation.h:370
CKey::GetClone
CKey * GetClone(AliasTrans *trans) const
Definition: c4d_canimation.h:252