Timer

Detailed Description

v1.00 (22 June 2023)
The Timer interface manages all timing related stuff: timer control, Render Frame Rate, Logic Frame Rate and microbenchmarks.

The Timer must be initiated with Timer::init().
One of the most important features is the fixed virtual logic frame rate with interpolation which is implemented on this interface and in Main::update() method:

• Render Frame Rate(RFR) is asynchronous and does not stop your main loop, it just render all enabled and visible screens at the preferred rate.
  This rate is not guaranteed as some Render frames could be dropped to keep stable the Logic Frame Rate.
  When vsync is enabled, it is recommended to set it to 0 in order to get the smoothest rendering output.
• Logic Frame Rate(LFR) will slow down your main loop in order to accommodate it to this rate.
  In a normal situation, let's say the hardware can execute the logic rate at the preferred ratio, this rate will be quite stable.

By default, no preferred Render and Logic Frame Rate are set (they are equal to 0) so if you want to use specific values, you must use setRate().
The rates can be adjusted (throttle down) but the upper limit is imposed by the underlying hardware where the application is executed, there is also a synergy between upper limits and ConfigMgr::iMTFriendly value.
It is important to say that the Render Frame Rate (if enabled) will be used for all enabled and visible screens.

There is a micro-benchmarking system. It is used for benchmarking small snippets of code. It runs your code, measures the time and then calculate some statistical analysis on those measurements.
Although the system is not fully thread-safe, it can easily be "thread-safe" following the below steps:

• the microbenchmarks are created on the same thread, usually the main one
• each one is used on different threads
• once finished, they are closed from the same thread, again, usually the main on

It can be used on several ways but the most commons are for testing a function in a deterministic way as the following example:

Main &mC64 = Main::Instance();
Timer::Stats myStats;
Sint32 iRuns = 1000;
Sint32 idBench = mC64.ITimer().benchBegin("myBench", iRuns); // iRuns is an estimation of the amount of test runs, in this case we know it
for(Sint32 i = 0; i < iRuns; ++i)
{
  mC64.ITimer().benchBegin(idBench);
  func_to_be_tested();
  mC64.ITimer().benchEnd(idBench);
}
mC64.ITimer().benchStats(idBench, myStats); // myStats struct has the results.
// Optionally and before closing, we could call to mC64.ITimer().info() to use the default log for displaying the stats.
mC64.ITimer().benchClose(idBench);

Or for measuring the behaviour of your application and getting a final report once the application exists as shown below:

Main &mC64 = Main::Instance();
Timer::Stats myStats;
Sint32 iRuns = 10000;
Sint32 idBenchL = mC64.ITimer().benchBegin("myBench-Logic", iRuns); // iRuns is an estimation of the amount of test runs, if more are needed, they are allocated
Sint32 idBenchR = mC64.ITimer().benchBegin("myBench-Render", iRuns);
 
while(iDone == 0)
{
  // Logic stuff
  mC64.ITimer().benchBegin(idBenchL);
  ...
  mC64.ITimer().benchEnd(idBenchL);
 
  // Render stuff
  mC64.ITimer().benchBegin(idBenchR);
  ...
  mC64.ITimer().benchEnd(idBenchR);
}
 
mC64.ITimer().info();
mC64.ITimer().benchClose(idBenchL);
mC64.ITimer().benchClose(idBenchR);

Only a single instance of the Timer interface exists which is created once Main is instantiated.
You can get a reference to this interface using Main::ITimer() method.

Note

The Timer interface is automatically released when Main::Terminate() is called.
At this time, any resource still loaded, will be released avoding resource leaks.

Classes
class	CRM64Pro::Timer
	Timer class. More...

Enumerations
enum	CRM64Pro::eTimerState { CRM64Pro::TS_INIT = 0 , CRM64Pro::TS_RESET = 1 }
	Timer init state. More...

Functions
Sint32	CRM64Pro::Timer::info (Sint32 iMode=0)
	Request Timer Interface information.
Sint32	CRM64Pro::Timer::init (eTimerState tsOpt=TS_INIT)
	Initialize the timer system.
Sint32	CRM64Pro::Timer::setRate (Uint16 iR, Uint16 iL)
	Set preferred Render and Logic Frame Rate.
Sint32	CRM64Pro::Timer::getLFR ()
	Get the preferred Logic Frame Rate.
Sint32	CRM64Pro::Timer::getRFR ()
	Get the preferred Render Frame Rate.
float	CRM64Pro::Timer::getAverageRFR ()
	Get the average Render Frame Rate since the last timer init or reset.
float	CRM64Pro::Timer::getAverageLFR ()
	Get the average Logic Frame Rate since the last timer init or reset.
Uint32	CRM64Pro::Timer::getCurrentRFR ()
	Get current Render Frame Rate during last recent second.
Uint32	CRM64Pro::Timer::getCurrentLFR ()
	Get current Logic Frame Rate during last recent second.
Uint32	CRM64Pro::Timer::getRenderFrames ()
	Get total render frames since the last timer init or reset.
Uint32	CRM64Pro::Timer::getLogicFrames ()
	Get total logic frames since the last timer init or reset.
float	CRM64Pro::Timer::getTime ()
	Get the execution time (in seconds) since the last timer init or reset.
Uint64	CRM64Pro::Timer::getTicks ()
	Get the execution time (in milliseconds) since the last timer init or reset.
Uint64	CRM64Pro::Timer::getTicksNow ()
	Get the execution time (in milliseconds) since the last timer init or reset.
Uint64	CRM64Pro::Timer::getHiResTime ()
	Get the execution time (in nanoseconds) since the last timer init or reset.
Sint32	CRM64Pro::Timer::benchBegin (const string &sName, Sint32 iRuns=0)
	Create and begin a microbenchmark test.
Sint32	CRM64Pro::Timer::benchBegin (Sint32 idBench)
	Begin a microbenchmark test.
Sint32	CRM64Pro::Timer::benchEnd (Sint32 idBench)
	End a microbenchmark test.
Sint32	CRM64Pro::Timer::benchClose (Sint32 idBench)
	Close a microbenchmark test.
Sint32	CRM64Pro::Timer::benchStats (Sint32 idBench, Stats &stats)
	Calculate the statistical analysis given the current measurements.

Enumeration Type Documentation

eTimerState

enum CRM64Pro::eTimerState

Timer init state.

Enumerator
TS_INIT	'tsOpt' parameter in Timer::init(), initializes or resets all timer settings.
TS_RESET	'tsOpt' parameter in Timer::init(), only resets the timer if it was previously initialized keeping RFR and LFR rates.

Function Documentation

info()

Sint32 CRM64Pro::Timer::info

(

Sint32

iMode = 0

)

Request Timer Interface information.

For displaying the information, it uses the default log.

Parameters

iMode

-1 for displaying only Manager information. 0 for displaying Manager and all Objects information. This is the default value.

Returns

0 on success or a negative error code on failure.

init()

Sint32 CRM64Pro::Timer::init

(

eTimerState

tsOpt = TS_INIT

)

Initialize the timer system.

The first call to this method, SDL timer subsystem will be initialized.

Parameters

tsOpt

Check eTimerState enum for further information. By default TS_INIT is set.

Returns

0 on success or a negative error code on failure.

Note

init(TS_RESET) is called internally by Main::cleanUp().

setRate()

Sint32 CRM64Pro::Timer::setRate	(	Uint16	iR,
		Uint16	iL
	)

Set preferred Render and Logic Frame Rate.

Parameters

iR	an integer value with preferred Render Frame Rate. By default it is set to 0 which does not limit this rate. Maximum value is 500.
iL	an integer value with preferred Logic Frame Rate. By default it is set to 0 which does not limit this rate. Maximum value is 20000.

Returns

0 on success or a negative error code on failure.

getLFR()

Sint32 CRM64Pro::Timer::getLFR

(

)

Get the preferred Logic Frame Rate.

Returns

0 or positive value on success or -1 on failure.

getRFR()

Sint32 CRM64Pro::Timer::getRFR

(

)

Get the preferred Render Frame Rate.

Returns

0 or positive value on success or -1 on failure.

getAverageRFR()

float CRM64Pro::Timer::getAverageRFR

(

)

Get the average Render Frame Rate since the last timer init or reset.

Returns

0 or positive value on success or -1 on failure.

getAverageLFR()

float CRM64Pro::Timer::getAverageLFR

(

)

Get the average Logic Frame Rate since the last timer init or reset.

Returns

0 or positive value on success or -1 on failure.

getCurrentRFR()

Uint32 CRM64Pro::Timer::getCurrentRFR

(

)

Get current Render Frame Rate during last recent second.

Returns

Render Frame Rate.

getCurrentLFR()

Uint32 CRM64Pro::Timer::getCurrentLFR

(

)

Get current Logic Frame Rate during last recent second.

Returns

Logic Frame Rate.

getRenderFrames()

Uint32 CRM64Pro::Timer::getRenderFrames

(

)

Get total render frames since the last timer init or reset.

Returns

Total number of Render frames.

getLogicFrames()

Uint32 CRM64Pro::Timer::getLogicFrames

(

)

Get total logic frames since the last timer init or reset.

Returns

Total number of Logic frames.

getTime()

float CRM64Pro::Timer::getTime

(

)

Get the execution time (in seconds) since the last timer init or reset.

This time will be constant inside the same Logic Frame iteration and will be updated on Main::update() if a new Logic Frame must be produced.

Returns

0 or positive value on success or -1 on failure.

getTicks()

Uint64 CRM64Pro::Timer::getTicks

(

)

Get the execution time (in milliseconds) since the last timer init or reset.

This time will be constant inside the same Logic Frame iteration and will be updated on Main::update() if a new Logic Frame must be produced.

Returns

unsigned int 32bits with the milliseconds.

getTicksNow()

Uint64 CRM64Pro::Timer::getTicksNow

(

)

Get the execution time (in milliseconds) since the last timer init or reset.

This time will be exactly the "now" time, on other words, it is not linked anyway to the Logic Frame iteration.

Returns

unsigned int 32bits with the milliseconds.

getHiResTime()

Uint64 CRM64Pro::Timer::getHiResTime

(

)

Get the execution time (in nanoseconds) since the last timer init or reset.

This is the high resolution timer when you need more accurate time precision.

Returns

unsigned 64bits with the nanoseconds.

benchBegin() [1/2]

Sint32 CRM64Pro::Timer::benchBegin	(	const string &	sName,
		Sint32	iRuns = 0
	)

Create and begin a microbenchmark test.

Parameters

sName	string with the name of this benchmark.
iRuns	estimated number of runs. By default it is set to 0. In any case, it is automatically managed.

Returns

greater than 0 on success(the Bench id) or a negative error code on failure.

Note

If the benchmark already exists, it just begin the benchmark. In this case is better to use benchBegin() using the Bench id.
Each benchBegin() must be followed by a benchEnd().

benchBegin() [2/2]

Sint32 CRM64Pro::Timer::benchBegin

(

Sint32

idBench

)

Begin a microbenchmark test.

Parameters

idBench

Bench id.

Returns

0 on success or a negative error code on failure.

Note

Each benchBegin() must be followed by a benchEnd().

benchEnd()

Sint32 CRM64Pro::Timer::benchEnd

(

Sint32

idBench

)

End a microbenchmark test.

Parameters

idBench

Bench id.

Returns

0 on success or a negative error code on failure.

Note

Each benchBegin() must be followed by a benchEnd().

benchClose()

Sint32 CRM64Pro::Timer::benchClose

(

Sint32

idBench

)

Close a microbenchmark test.

Free the resources of the test and the stats.

Parameters

idBench

Bench id.

Returns

0 on success or a negative error code on failure.

benchStats()

Sint32 CRM64Pro::Timer::benchStats	(	Sint32	idBench,
		Stats &	stats
	)

Calculate the statistical analysis given the current measurements.

Parameters

idBench	Bench id.
stats	a Stats struct to be filled with current stats. The values are given in milliseconds.

Returns

0 on success or a negative error code on failure.