TimeValue Manual

Table of Contents

• About
• Creation and Initialization
• Standard Operations
• Comparison
• Get and Set operations
• Timer
• Conversion
• Utilities
• Further Reading

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:

• maxon::TimeValue::TimeValue(): creates maxon::TimeValue initialized with zero;
• maxon::TimeValue::TimeValue(ENUM_DONT_INITIALIZE): creates an uninitialized maxon::TimeValue object for faster allocation;
• maxon::TimeValue::TimeValue(const TimeValue& src): creates a maxon::TimeValue initialized with the passed parameter;
• maxon::TimeValue::TimeValue(CurrentTime): creates a maxon::TimeValue initialized with the current time

    // 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);
 

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

• maxon::TimeValue::operator=(): left-assigns the maxon::TimeValue in the expression.

    // This example shows how to assign a value to a TimeValue object.
 
    // allocate a TimeValue object
    maxon::TimeValue timevalue;
 
    // assign it the current time
    timevalue = maxon::TimeValue(maxon::TimeValue::CurrentTime());

Standard Operations

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

• maxon::TimeValue::operator+(): returns the sum of the two maxon::TimeValue;
• maxon::TimeValue::operator+=(): assigns the sum of the current value and of the maxon::TimeValue;
• maxon::TimeValue::operator-(): returns the difference of the two maxon::TimeValue;
• maxon::TimeValue::operator-=(): assigns the difference of the current value and of the maxon::TimeValue;
• maxon::TimeValue::operator*(): returns the product of a maxon::TimeValue by the Float64;
• maxon::TimeValue::operator*=(): assigns the product of the current value by the Float64;
• maxon::TimeValue::operator/(const TimeValue& a, const TimeValue& b): returns the quotient of the two maxon::TimeValue;
• maxon::TimeValue::operator/(const TimeValue& a, const Float64 b): returns the quotient of a maxon::TimeValue by the Float64.

    // This examples shows how to operate with mathematical-like operators.
 
    // allocate a TimeValue object
    const maxon::TimeValue timevalueA(maxon::TimeValue::NOW);
 
    // 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
    maxon::TimeValue sum0A;
    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;

Comparison

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

• maxon::TimeValue::operator==(): compares two maxon::TimeValue(s) used in expression checking values for equality;
• maxon::TimeValue::operator<(): compares two maxon::TimeValue(s) used in expression checking the first being smaller than the second;

    // This example shows how to compare two TimeValue instances.
 
    // allocate a TimeValue object
    const maxon::TimeValue timevalueA(maxon::TimeValue::NOW);
 
    // 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);

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:

• maxon::TimeValue::SetHours(): set the value using the provided number of hours;
• maxon::TimeValue::SetMinutes(): set the value using the provided number of minutes;
• maxon::TimeValue::SetSeconds(): set the value using the provided number of seconds;
• maxon::TimeValue::SetMicroseconds(): set the value using the provided number of milliseconds;
• maxon::TimeValue::SetMilliseconds(): set the value using the provided number of microseconds;
• maxon::TimeValue::SetNanoseconds(): set the value using the provided number of nanoseconds.

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

• maxon::TimeValue::GetHours(): return the value stored in hours;
• maxon::TimeValue::GetMinutes(): returns the value stored in minutes;
• maxon::TimeValue::GetSeconds(): returns the value stored in seconds;
• maxon::TimeValue::GetMicroseconds(): returns the value stored in milliseconds;
• maxon::TimeValue::GetMilliseconds(): returns the value stored in microseconds;
• maxon::TimeValue::GetNanoseconds(): returns the value stored in nanoseconds;

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

Timer

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

• maxon::TimeValue::GetTime(): returns the current timestamp;
• maxon::TimeValue::Stop(): returns the difference between the current timestamp and the value stored in the maxon::TimeValue instance.

    // This example shows how to use the TimeValue as a timer to accomplish profiling operations
 
    // allocate a TimeValue object and set the current time
    maxon::TimeValue timer = maxon::TimeValue::GetTime();
    DiagnosticOutput(diagIDString + "timer started at: @", timer);
 
    // do your "time-consuming" stuff like filling an array
    const maxon::Int        itemsCnt = 1024;
    maxon::BaseArray<Float> hugearray;
    hugearray.Resize(itemsCnt) iferr_return;
 
    maxon::BaseArray<Float>::Iterator itBegin = hugearray.Begin();
 
    maxon::LinearCongruentialRandom<maxon::Float32> rndm;
    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);

Conversion

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

• maxon::TimeValue::TimeFromString(): converts a properly formatted string in a maxon::TimeValue object;
• maxon::TimeValue::TimeToString(): converts a maxon::TimeValue object in a properly formatted string;
• maxon::TimeValue::ToString(): returns a maxon::String representation of the maxon::TimeValue object.

    // This example shows how to accomplish TimeValue conversion to/from maxon::String.
 
    // allocate a TimeValue and get it represented via a string
    const maxon::TimeValue timevalueNow(maxon::TimeValue::NOW);
    const maxon::String    stringNow = timevalueNow.ToString(nullptr);
 
    // convert from string to timevalue
    const maxon::String stringSeconds { "30.00" };
    maxon::TimeValue    timevalueSec;
    timevalueSec.TimeFromString(stringSeconds, TIMEFORMAT::SECONDS, FRAMERATE_DEFAULT) iferr_return;
    // 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;
    timevaluePAL.TimeFromString(stringPAL, TIMEFORMAT::FRAMES, FRAMERATE_PAL) iferr_return;
    // 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;
    timevalueDEFAULT.TimeFromString(stringDEFAULT, TIMEFORMAT::FRAMES, FRAMERATE_DEFAULT) iferr_return;
    // 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;
    timevalueNTSC.TimeFromString(stringNTSC, TIMEFORMAT::FRAMES, FRAMERATE_NTSC) iferr_return;
    // 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;
    timevalueFILM.TimeFromString(stringFILM, TIMEFORMAT::FRAMES, FRAMERATE_FILM) iferr_return;
    // 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;
    timevalueSMTPE.TimeFromString(stringSMTPE, TIMEFORMAT::SMPTE, FRAMERATE_FILM) iferr_return;
    // convert to standard SMTP time representation using film frame rate (24fps)
    const maxon::String framesInSMTPE = timevalueSMTPE.TimeToString(TIMEFORMAT::SMPTE, FRAMERATE_FILM);
 

Utilities

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

• maxon::TimeValue::GetHashCode(): returns the hash code of the maxon::TimeValue object;
• maxon::TimeValue::GetFrame(): returns the frame number at a given frame rate;
• maxon::TimeValue::Quantize(): returns the time for a given frame rate so that its frame value is an integer multiple of the specified frame rate;

    // This example shows how to use the utilities found in the TimeValue class
 
    // allocate a TimeValue object
    const maxon::TimeValue now(maxon::TimeValue::NOW);
 
    // 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);
 

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
        maxon::WriteDocument(url, maxon::OPENSTREAMFLAGS::NONE, fileID, savedTimevalue, maxon::IOFORMAT::JSON) iferr_return;
 
    // read from file
    maxon::TimeValue loadedTimevalue;
    maxon::ReadDocument(url, fileID, loadedTimevalue) iferr_return;

Further Reading

• Data & Algorithms
• Time-based Types
• DescribeIO Manual