CTrack Manual

About

A CTrack represents an animation track of a parameter of an object in Cinema 4D. The tracks are stored with the animated object and contain curves and keys.

CTrack objects are an instance of CTbase.

// This example creates a track for the "Camera" parameter of the given Stage object.
// Two keyframes for the given two camera objects are created.
// search for the track and create a new one if needed
CTrack* track = stage->FindCTrack(trackID);
if (track == nullptr)
{
track = CTrack::Alloc(stage, trackID);
if (track == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
// add track to stage object
stage->InsertTrackSorted(track);
}
CCurve* const curve = track->GetCurve();
if (curve == nullptr)
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
// Create first key
CKey* const key1 = curve->AddKey(BaseTime(0.0));
if (key1 == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
{
GeData data;
data.SetBaseList2D(camera1);
key1->SetGeData(curve, data);
}
// Create second key
CKey* const key2 = curve->AddKey(BaseTime(1.0));
if (key2 == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
{
GeData data;
data.SetBaseList2D(camera2);
key2->SetGeData(curve, data);
}

Access

The animation tracks of an object's parameters are stored with the object itself:

Note
The keyframe selection is defined with the BaseList2D class, see BaseList2D Manual.
// This snippet loops through all animation tracks of the given object.
const CTrack* track = obj->GetFirstCTrack();
while (track)
{
ApplicationOutput("Track: " + track->GetName());
track = track->GetNext();
}

Allocation/Deallocation

A CTrack can be created with the usual tools:

A newly created CTrack must be added to a host object:

// This example checks if an animation track for the position X parameter
// exists in the given object. If not, the track will be created.
const DescLevel vectorXLevel = DescLevel(VECTOR_X, DTYPE_REAL, 0);
const DescID id = DescID(relPosLevel, vectorXLevel);
CTrack* track = obj->FindCTrack(id);
if (track == nullptr)
{
track = CTrack::Alloc(obj, id);
if (track == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
track->SetName("My New Animation Track"_s);
obj->InsertTrackSorted(track);
}

To create special tracks the ID of that special track must be used. The special tracks are:

// This example adds a sound track to the given object
// and sets the referenced sound file.
const DescLevel soundTrackID = DescLevel(CTsound, CTsound, 0);
CTrack* const soundTrack = CTrack::Alloc(obj, soundTrackID);
if (soundTrack == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
soundTrack->SetName("New Sound Track"_s);
obj->InsertTrackSorted(soundTrack);
// This example adds a PLA track to the polygon object.
const DescID plaID = DescLevel(CTpla, CTpla, 0);
CTrack* const plaTrack = CTrack::Alloc(polyObject, plaID);
if (plaTrack == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
polyObject->InsertTrackSorted(plaTrack);
CCurve* curve = plaTrack->GetCurve();
if (curve == nullptr)
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
// set first key
CKey* const key1 = curve->AddKey(BaseTime(0.0));
if (key1 == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
plaTrack->FillKey(doc, polyObject, key1);
// change polygon object randomly
Random random;
for (Int32 i = 0; i < count; ++i)
points[i] = points[i] + Vector(0, 100.0 * random.Get01(), 0.0);
polyObject->Message(MSG_UPDATE);
// set second key
CKey* const key2 = curve->AddKey(BaseTime(1.0));
if (key2 == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
plaTrack->FillKey(doc, polyObject, key2);

Navigation

CTrack objects are stored in a list:

// This snippet loops through all animation tracks of the given object.
const CTrack* track = obj->GetFirstCTrack();
while (track)
{
ApplicationOutput("Track: " + track->GetName());
track = track->GetNext();
}
Note
The GeListHead object that is the parent of the tracks can be obtained with BaseList2D::GetCTrackRoot().

Read-Only Properties

Several values can be read from a CTrack:

The track categories are:

// This example checks if the given track is a "value" track.
// If so, the current value is printed to the console.
// check if the track is "value" track (float)
if (track->GetTrackCategory() == CTRACK_CATEGORY_VALUE)
{
const BaseTime now = doc->GetTime();
const Float value = track->GetValue(doc, now);
}

See also CKey Value.

Properties

Parameters

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

// This example sets the color to display the track's f-curve:
track->SetParameter(ID_CTRACK_USE_PREF, false, DESCFLAGS_SET::NONE);
const Vector red(1.0, 0, 0);
track->SetParameter(ID_CTRACK_FCURVE_COLOR, GeData(red), DESCFLAGS_SET::NONE);

Selection

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

// This example selects the given track if it does not contain any keys.
const CCurve* const curve = track->GetCurve();
if (curve)
{
const Int32 keyCount = curve->GetKeyCount();
if (keyCount == 0)
track->ChangeNBit(NBIT::TL1_SELECT, NBITCONTROL::SET);
else
track->ChangeNBit(NBIT::TL1_SELECT, NBITCONTROL::CLEAR);
}

See also CKey Selection.

Description ID

The parameter animated using a certain track is defined with its DescID. This DescID can be accessed:

// This example clones a track and sets the new description ID of that clone.
const DescLevel vectorXLevel(VECTOR_X, DTYPE_REAL, 0);
const DescID ID = DescID(relPosLevel, vectorXLevel);
// find track
CTrack* const track = obj->FindCTrack(ID);
if (track == nullptr)
return maxon::OK;
// get track root
GeListHead* const trackRoot = obj->GetCTrackRoot();
if (trackRoot == nullptr)
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
// clone track
CTrack* const clone = static_cast<CTrack*>(track->GetClone(COPYFLAGS::NONE, nullptr));
if (clone == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
// insert and set new ID
const DescLevel vectorYLevel(VECTOR_Y, DTYPE_REAL, 0);
const DescID targetID = DescID(relPosLevel, vectorYLevel);
trackRoot->InsertLast(clone);
clone->SetDescriptionID(obj, targetID);

Loop Settings

The loop settings define how an animation track should behave before the first key and after the last key.

The loop types are:

// This example defines the loop settings of the given track.

Points in time beyond the defined animation track can be mapped into time inside the track.

  • CTrack::Remap(): Remaps the given time into a position inside the animation track.
// This example calculates the remapped time for each given time in seconds.
// loop from 0.0 to 1.0
for (Float64 t = 0.0; t < 10.0; t = t + 0.1)
{
Float64 remapTime;
Int32 cycle;
track->Remap(t, &remapTime, &cycle);
ApplicationOutput("Remap Time: " + String::FloatToString(remapTime));
}

Time Track

The behavior of an animation track depends on the current time which is typically the current time of the BaseDocument. But the time that controls a track can be also defined with a time track.

// This example applies the found time track to all other tracks.
// serach for time track
CTrack* const timeTrack = obj->FindCTrack(CTtime);
if (timeTrack == nullptr)
return maxon::OK;
// apply time track to other tracks
CTrack* track = obj->GetFirstCTrack();
while (track)
{
const DescID id = track->GetDescriptionID();
// check if the track is not a "Time" track
if (id[0].id != CTtime)
track->SetTimeTrack(timeTrack);
track = track->GetNext();
}

Timeline Height

An animation track can be displayed in a Timeline window.

Track Information

An animation track can provide additional information for each key or the current time in form of a String.

// This example prints the information for each key of the track.
CKey* key = curve->GetKey(i);
if (key == nullptr)
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
String info;
track->TrackInformation(doc, key, &info, false);

Synchronisation

Multiple tracks can be synchronized. Typically this applies to tracks of the components of a Vector parameter.

Functionality

Since a track might be displayed in the GUI (Timeline window) it can draw an image:

// This example calls the "Draw" function of the given sound track
// and displays the result image.
if (clipMap == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
if (clipMap->Init(400, 100, 32) != IMAGERESULT::OK)
return maxon::UnknownError(MAXON_SOURCE_LOCATION);
clipMap->BeginDraw();
soundTrack->Draw(clipMap, BaseTime(0), BaseTime(1.0));
clipMap->EndDraw();
ShowBitmap(clipMap->GetBitmap());

Further utility functions are:

// This eample accesses the CCurve from the given animation track.
CCurve* const curve = track->GetCurve();
if (curve)
{
// do something with the curve
}

See also CCurve Manual.

Further Reading