BaseTime Manual

Table of Contents

• About
• Access
• Time and Frame
• Properties
  • Set Time
  • Numerator/Denominator
• Compare
• Disc I/O
• Further Reading

About

A BaseTime object is used to define a point in time in a BaseDocument. If only frame numbers were used, changing the frame rate would cause keys either to overlap or disappear. If only float values (seconds) were used instead, there would be problems because of the limited data precision. For instance when using 30 fps the frame 29 = 29/30 could easily be misinterpreted as frame 28.

BaseTime internally stores the time values as exact fractions independent of the frame rate. For example frame 29 is stored as fraction with nominator 29 and denominator 30. The class always tries to keep the nominator and denominator as small as possible. Hence 15/30 is stored as 1/2, so if using 30 fps BaseTime::GetFrame() would return 15, but if using 24 fps it would return frame 12.

Access

The current time of a BaseDocument can be handled using:

• BaseDocument::GetTime(): Returns a BaseTime storing the current time.
• BaseDocument::SetTime(): Sets the current time of the document using a BaseTime object.
• SetDocumentTime(): Sets the given document's time.

For timeline dimensions, preview time and used time see BaseDocument Manual.

To retrieve and modify BaseTime objects stored in a BaseContainer respectively use:

• BaseContainer::GetTime(): Returns the BaseTime stored at the given ID.
• BaseContainer::SetTime(): Sets the BaseTime stored at the given ID.

See also BaseContainer Manual.

To retrieve and modify BaseTime objects stored in a GeData object (GeData type is DA_TIME) respectively use:

• GeData::GetTime(): Return the BaseTime object.
• GeData::SetBaseTime(): Stores the BaseTime object.

See also GeData Manual.

Please notice that Cinema 4D can only handle a limited number of frames:

• MAXTIME: The maximum number of frames Cinema 4D can handle in a timeline.

Animation keys are placed at certain frames. These frames can be respectively retrieved and modified using:

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

  // This example checks if the given object is a particle emitter.
  // If so, the emission start time is read and the current document time is set.
 
  BaseObject* const object = doc->GetActiveObject();
  if (object == nullptr)
    return maxon::IllegalArgumentError(MAXON_SOURCE_LOCATION);
 
  // check if the given object is a standard particle emitter
  if (object->GetType() == Oparticle)
  {
    GeData data;
 
    // read the "Start Emission" parameter
    if (!object->GetParameter(ConstDescID(DescLevel(PARTICLEOBJECT_START)), data, DESCFLAGS_GET::NONE))
      return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
    const BaseTime time = data.GetTime();
    doc->SetTime(time);
  }

Time and Frame

The frame number equivalent of the stored time depends on the current framerate:

• BaseTime::Get(): Returns the time in seconds.
• BaseTime::GetFrame(): Returns the frame equivalent to the stored time based on the given framerate.
• BaseTime::Quantize(): Quantizes the internally stored value so that it is a multiple of the given framerate.

  // This example prints the current frame of the given document.
 
  const BaseTime now = doc->GetTime();
  const Int32    fps = doc->GetFps();
  const Int32    frame = now.GetFrame(fps);
 
  ApplicationOutput("Current Frame: " + String::IntToString(frame));

Properties

Set Time

BaseTime objects can be constructed by setting a time in seconds of by giving a frame and a framerate.

  // This example adds a keyframe to the given animation track at the position 1.0 seconds.
 
  CCurve* const curve = track->GetCurve();
  if (curve != nullptr)
  {
    const BaseTime    time { 1.0 };
    const CKey* const key = curve->AddKey(time);
 
    if (key == nullptr)
      return maxon::UnknownError(MAXON_SOURCE_LOCATION);
  }

  // This example adds a keyframe to the given animation track at the position of frame 25.
 
  CCurve* const curve = track->GetCurve();
 
  if (curve != nullptr)
  {
    const Int32       fps = doc->GetFps();
    const BaseTime    time(25, fps);
    const CKey* const key = curve->AddKey(time);
 
    if (key == nullptr)
      return maxon::UnknownError(MAXON_SOURCE_LOCATION);
  }

Numerator/Denominator

The internal value of a BaseTime object is represented by a numerator and denominator. Both values can be retrieved and modified using:

• BaseTime::GetNumerator(): Returns the numerator part of the internally stored time.
• BaseTime::SetNumerator(): Sets the numerator part of the internally stored time.
• BaseTime::GetDenominator(): Returns the denominator part of the internally stored time.
• BaseTime::SetDenominator(): Sets the denominator part of the internally stored time.

Compare

Two BaseTime objects can be compared using a special function or the usual operators:

• BaseTime::TimeDif(): Compares the BaseTime object with the given BaseTime.
• BaseTime::operator==(): Returns true if the two BaseTime objects are equal.
• BaseTime::operator!=(): Returns true if the two BaseTime objects are not equal.
• BaseTime::operator<(): Returns true if the BaseTime object is less then the given object.
• BaseTime::operator<=(): Returns true if the BaseTime object is less than or equal to the given object.
• BaseTime::operator>=(): Returns true if the BaseTime object is greater than or equal to the given object.
• BaseTime::operator>(): Returns true if the BaseTime object is greater then the given object.

  // This example compares the current document time with the value of one second.
 
  const BaseTime oneSecond { 1.0 };
  const BaseTime now = doc->GetTime();
 
  const Int32 compare = now.TimeDif(oneSecond);
 
  if (compare == -1)
    ApplicationOutput("The current frame is less than one second");
  else if (compare == 1)
    ApplicationOutput("The current frame is greater than one second");

Disc I/O

BaseTime objects can be stored in a HyperFile using:

• HyperFile::ReadTime(): Reads a BaseTime object from the HyperFile.
• HyperFile::WriteTime(): Writes a BaseTime object into the HyperFile.

See also HyperFile Manual on BaseTime.

Further Reading

• GeData Manual
• BaseContainer Manual
• BaseDocument Manual