TimeValue Manual

About

maxon::TimeValue is a MAXON API class used to create an object capable of handling time-related actions. A maxon::TimeValue object stores information on different time-scale basis, actually from hours to nanoseconds, making it possible to deliver unprecedented time granularity.

Creation and Initialization

A maxon::TimeValue can be created on the stack and initialized through the proper method:

// This example allocates a few maxon::TimeValue objects showing the different allocation methods.
// just allocate a TimeValue object
const maxon::TimeValue timevalue;
// allocate and init a TimeValue object
const maxon::TimeValue initdTimeValue(maxon::TimeValue::NOW);
// allocate and init a TimeValue object using frame and framerate
const maxon::TimeValue framebasedTimeValue(10, FRAMERATE_FILM_NTSC);
// allocate a TimeValue object by cloning an existing one
const maxon::TimeValue clonedTimeValue(initdTimeValue);
The TimeValue class encapsulates a timer value.
Definition: timevalue.h:33
static const CurrentTime NOW
Definition: timevalue.h:37
const Float64 FRAMERATE_FILM_NTSC
Modified movie frame rate to avoid frame roll when transfering video to NTSC, approx....
Definition: timevalue.h:18

A value can be assigned to a maxon::TimeValue by using the assignment operator:

// This example shows how to assign a value to a TimeValue object.
// allocate a TimeValue object
maxon::TimeValue timevalue;
// assign it the current time
Definition: timevalue.h:35

Standard Operations

A maxon::TimeValue can be modified by using standard operators:

// This examples shows how to operate with mathematical-like operators.
// allocate a TimeValue object
// allocate a second TimeValue object
const maxon::TimeValue timevalueB = timevalueA * 2;
// evaluate the sum
const maxon::TimeValue sumAB = timevalueA + timevalueB;
// evaluate the "right-assigned" sum
sum0A += timevalueA;
// evaluate the difference
const maxon::TimeValue differenceBA = timevalueB - timevalueA;
// evaluate the product
maxon::TimeValue productA3 = timevalueA * 3.0;
// evaluate the right-assigned product
maxon::TimeValue productA6(productA3);
productA6 *= 2.0;
// evaluate the quotient between two TimeValue objects
const maxon::Float quotientAB = timevalueB / timevalueA;
// evaluate the quotient between a TimeValue object and a Float value
const maxon::TimeValue quotientA3by2 = productA3 / 2.0;
Float64 Float
Definition: apibase.h:211

Comparison

A maxon::TimeValue can be compared by using standard mathematical-like operators:

// This example shows how to compare two TimeValue instances.
// allocate a TimeValue object
// allocate a second TimeValue object
const maxon::TimeValue timevalueB = timevalueA * 2;
// compare for the smaller
if (timevalueA < timevalueB)
DiagnosticOutput(diagIDString + "timevalueA [@] is smaller than timevalueB [@]", timevalueA, timevalueB);
// compare for equality
else if (timevalueA == timevalueB)
DiagnosticOutput(diagIDString + "timevalueA [@] is equal to timevalueB [@]", timevalueA, timevalueB);
else
DiagnosticOutput(diagIDString + "timevalueA [@] is grater than timevalueB [@]", timevalueA, timevalueB);
#define DiagnosticOutput(formatString,...)
Definition: debugdiagnostics.h:170
Note
From the above operators all the remaining operators (!=, >, >=, <=) are build and can thus be used as normal, too.

Get and Set operations

The value stored in a maxon::TimeValue can be set using:

Similarly the value stored in a maxon::TimeValue can be retrieved using:

// This example shows how to set the value of a TimeValue by specifying the desired time unit
// and retrieve its value using a specific time unit.
// allocate another TimeValue object
maxon::TimeValue timevalueSet, timevalueFinal;
// populate the object with the intended values
timevalueSet.SetHours(10.0);
timevalueFinal += timevalueSet;
timevalueSet.SetMinutes(20.0);
timevalueFinal += timevalueSet;
timevalueSet.SetSeconds(30.0);
timevalueFinal += timevalueSet;
timevalueSet.SetMilliseconds(444.0);
timevalueFinal += timevalueSet;
timevalueSet.SetMicroseconds(555.0);
timevalueFinal += timevalueSet;
timevalueSet.SetNanoseconds(666.0);
timevalueFinal += timevalueSet;
// extract hours, remaining minutes, remaining seconds and remaining millsecs
const Int hours = (maxon::Int)timevalueFinal.GetHours();
const Int minutes = ((maxon::Int)timevalueFinal.GetMinutes() - (hours * 60));
const Int seconds = ((maxon::Int)timevalueFinal.GetSeconds() - ((hours * 60 + minutes) * 60));
const Float millsecs = timevalueFinal.GetMilliseconds() - (maxon::Float)(((hours * 60 + minutes) * 60) + seconds) * 1000;
Float64 GetMinutes() const
Definition: timevalue.h:198
void SetMinutes(Float64 minutes)
Definition: timevalue.h:207
Float64 GetMilliseconds() const
Definition: timevalue.h:234
void SetHours(Float64 hours)
Definition: timevalue.h:189
void SetMilliseconds(Float64 milliseconds)
Definition: timevalue.h:252
void SetSeconds(Float64 seconds)
Definition: timevalue.h:225
void SetMicroseconds(Float64 microseconds)
Definition: timevalue.h:279
Float64 GetSeconds() const
Definition: timevalue.h:216
void SetNanoseconds(Float64 nanoseconds)
Definition: timevalue.h:306
Float64 GetHours() const
Definition: timevalue.h:180
maxon::Float Float
Definition: ge_sys_math.h:62
maxon::Int Int
Definition: ge_sys_math.h:60
Int64 Int
signed 32/64 bit int, size depends on the platform
Definition: apibase.h:202

Timer

Benchmarking or profiling parts of code can be delivered using the functions:

// This example shows how to use the TimeValue as a timer to accomplish profiling operations
// allocate a TimeValue object and set the current time
DiagnosticOutput(diagIDString + "timer started at: @", timer);
// do your "time-consuming" stuff like filling an array
const maxon::Int itemsCnt = 1024;
hugearray.Resize(itemsCnt) iferr_return;
rndm.Init(1234);
while (itBegin != hugearray.End())
{
*itBegin = rndm.Get01();
itBegin++;
}
// stop the timer
timer.Stop();
DiagnosticOutput(diagIDString + "Filling @ float items in the array have required @", itemsCnt, timer);
MAXON_ATTRIBUTE_FORCE_INLINE ConstIterator Begin() const
Definition: basearray.h:1486
ResultMem Resize(Int newCnt, COLLECTION_RESIZE_FLAGS resizeFlags=COLLECTION_RESIZE_FLAGS::DEFAULT)
Definition: basearray.h:1218
MAXON_ATTRIBUTE_FORCE_INLINE ConstIterator End() const
Definition: basearray.h:1506
Definition: block.h:105
Definition: lib_math.h:19
FLOAT Get01()
Returns the next random value in the range of [0..1].
static TimeValue GetTime()
const TimeValue & Stop()
#define iferr_return
Definition: resultbase.h:1524

Conversion

A maxon::TimeValue can be converted to/from a different type using:

// This example shows how to accomplish TimeValue conversion to/from maxon::String.
// allocate a TimeValue and get it represented via a string
const maxon::String stringNow = timevalueNow.ToString(nullptr);
// convert from string to timevalue
const maxon::String stringSeconds { "30.00" };
maxon::TimeValue timevalueSec;
// convert from timevalue to string
const maxon::String seconds = timevalueSec.TimeToString();
// convert from string to timevalue
const maxon::String stringPAL { "750.00" };
maxon::TimeValue timevaluePAL;
// convert to frame using a standard PAL frame rate (25fps)
const maxon::String framesInPAL = timevaluePAL.TimeToString(TIMEFORMAT::FRAMES, FRAMERATE_PAL);
// convert from string to timevalue
const maxon::String stringDEFAULT { "900.00" };
maxon::TimeValue timevalueDEFAULT;
// convert to frame using a default frame rate (30fps)
const maxon::String framesInDEFAULT = timevalueDEFAULT.TimeToString(TIMEFORMAT::FRAMES, FRAMERATE_DEFAULT);
// convert from string to timevalue
const maxon::String stringNTSC { "899.10" };
maxon::TimeValue timevalueNTSC;
// convert to frame using a standard NTSC frame rate (29.97fps)
const maxon::String framesInNTSC = timevalueNTSC.TimeToString(TIMEFORMAT::FRAMES, FRAMERATE_NTSC);
// convert from string to timevalue
const maxon::String stringFILM { "720.00" };
maxon::TimeValue timevalueFILM;
// convert to frame using a standard filmic frame rate (24fps)
const maxon::String framesInFILM = timevalueFILM.TimeToString(TIMEFORMAT::FRAMES, FRAMERATE_FILM);
// convert from string to timevalue
const maxon::String stringSMTPE { "00:15:26:05" };
maxon::TimeValue timevalueSMTPE;
// convert to standard SMTP time representation using film frame rate (24fps)
const maxon::String framesInSMTPE = timevalueSMTPE.TimeToString(TIMEFORMAT::SMPTE, FRAMERATE_FILM);
Definition: string.h:1237
Result< void > TimeFromString(const String &str, TIMEFORMAT timeFormat, Float64 frameRate)
String TimeToString(TIMEFORMAT timeFormat=TIMEFORMAT::SECONDS, Float64 frameRate=1) const
const Float64 FRAMERATE_PAL
PAL frame rate is 25 fps.
Definition: timevalue.h:16
const Float64 FRAMERATE_DEFAULT
Default frame rate of 30 fps.
Definition: timevalue.h:14
const Float64 FRAMERATE_FILM
Movie frame rate is 24 fps.
Definition: timevalue.h:17
const Float64 FRAMERATE_NTSC
NTSC frame rate is approximately 29.97 fps.
Definition: timevalue.h:15
FRAMES
display time as a frame number
Definition: timevalue.h:1
SMPTE
display time as SMPTE time code
Definition: timevalue.h:2
SECONDS
display time in seconds
Definition: timevalue.h:0

Utilities

A few helpful methods are provided with the maxon::TimeValue as utilities:

// This example shows how to use the utilities found in the TimeValue class
// allocate a TimeValue object
// retrieve the hashcode of the object
const maxon::UInt hashNow = now.GetHashCode();
// allocate a TimeValue object and set to 200ms (note 1 PAL frame is 40ms)
maxon::TimeValue timevalue;
timevalue.SetMilliseconds(200);
const Int framePAL = timevalue.GetFrame(FRAMERATE_PAL);
// define a delta TimeValue and set to 45 millisecs
maxon::TimeValue timeoffset;
timeoffset.SetMilliseconds(45);
// add previous timevalue to delta
timeoffset += timevalue;
// quantize to the nearest PAL frame
timevalue.Quantize(FRAMERATE_PAL);
const Int quantizedframePAL = timeoffset.GetFrame(FRAMERATE_PAL);
void Quantize(Float64 frameRate)
quantize the time for a given frame rate, so that its frame value is a multiple of the specified fram...
Int GetFrame(Float64 frameRate) const
UInt64 UInt
unsigned 32/64 bit int, size depends on the platform
Definition: apibase.h:203

A maxon::TimeValue object can be read from and written to disk by serializing the data contained using the conventional functions.

// This example shows how to store and retrieve a TimeValue from a file.
const maxon::TimeValue savedTimevalue(maxon::TimeValue::NOW);
// file URL
const maxon::Url url = (targetFolder + "timevalue.txt"_s)iferr_return;
const maxon::Id fileID { "net.maxonexample.timevalue" };
// save to file
// read from file
maxon::TimeValue loadedTimevalue;
maxon::ReadDocument(url, fileID, loadedTimevalue) iferr_return;
Definition: apibaseid.h:243
Definition: url.h:942
std::enable_if< GetCollectionKind< T >::value==COLLECTION_KIND::ARRAY, Result< void > >::type ReadDocument(const Url &url, const Id &id, T &object, const DataDictionary &dict=DataDictionary())
Definition: io.h:40
Result< void > WriteDocument(const Url &url, OPENSTREAMFLAGS flags, const Id &id, const T &object, IOFORMAT format=IOFORMAT::DEFAULT, const DataDictionary &dict=DataDictionary())
Definition: io.h:72
@ NONE
No flags set.

Further Reading