Time and Timers

Time

Time is an essential thing. It is utilized in every computer game, it is used in game logic, animations, visual effects and user input handling.

But how exactly time is measured on WOWCube device?

As we already know, the WOWCube device is built out of eight modules with its own CPU and memory. Each runs CubiOS operating system that hadles hardware components of the module. One of the components is a clock, a device that produces ticks at some very high, constant frequency. Once module is started, it begins to do these ticks and it never stops. So knowing the number of ticks passed between two moments we can actually see how long it took or how much time passed.

Time ticks are very important for all CubiOS internal function too. Graphics on screens, memory, sensors and power - all this obeys the rhythm set by the internal clock. All ongoing processes that run insinde WOWCube use time. If internal clock stops, device turns unresponsive.

So in order to create a cubeapp that implements any kind of dynamics, we would want to use the time as well, right?

But how do we know that tick has elapsed? How do we know how fast this happened?

For that, on_Tick(uint32_t currentTime, uint32_t deltaTime) callback is used. It is called by CubiOS every time new tick passes, as frequent as device can do.

Using this callback, we can do multiple useful things with time. Most typical tasks are to calculate time elapsed from the last iteration of game logic (i.e last frame) and implement a timer that ticks with given periodicity.

Let's take a look at the example.

Getting elapsed time

Firstly, we would want to know time elapsed between two calls of on_Tick() callback.

This is extremely simple thing to do since the value we're looking for is already provided as a second parameter of the callback, deltaTime. Its value is measured in milliseconds.

A millisecond (from milli- and second; symbol: ms) is a thousandth (0.001 or 1/1000) of a second.

Pay attention!

The calling frequency of on_Tick() callback is not guaranteed to be constant, may vary and depends on the actual CPU load of the module. The load, in turn, depends on a complexity of a code on_Tick() callback implements. More complex the code is, more CPU load is put.

Implementing a programmable timer

Timer is a specialized type of clock used for measuring specific time intervals.

Programmable Timer is a software object that is used for measuring equal time intervals, which can be uniquely identified, started or put on hold or destroyed.

As we know, each cubeapp is derived from Cubios::Application application class. This class provide the following functions to manage programmable timers:

1bool SetTimer(uint8_t id, uint32_t delay, bool suspended = false) 
2    Create a programmable timer object with particular id, ticking frequency and initial state.
3 
4bool StartTimer(uint8_t id)
5    Start a programmable timer with id. 
6 
7bool StopTimer(uint8_t id)
8    Stop a programmable timer with id. 
9 
10void KillTimer(uint8_t id)
11    Stop and destroy a programmable timer with id. 
12 

Using programmable timers it is very easy to implement recurrent in-game actions that happen each 1, or 5, or 10 seconds.

Let's see the code. First, a timer must be created and initialized. This is done in InitializeResources() function that is called from OnInit() callback when cubeapp is started:

1void OnInit(Cubios::AppManager& appMgr) 
2{
3    TimeAndTimers* theApp = new TimeAndTimers();
4 
5    appMgr.SetApplication(theApp,"AAbbCCddEE");
6 
7    theApp->InitializeResources();
8}
9 
10void TimeAndTimers::InitializeResources()
11{
12    //Set a timer that ticks once a second
13    this->SetTimer(Timers::myTimer,1000);
14}
15 

The timer delay is initialized with 1000 milliseconds or 1 second. This means the on_Timer(uint8_t timerID) callback will be called every second as long as the timer is running:

1void TimeAndTimers::on_Timer(uint8_t timerID)
2{
3    switch(timerID)
4    {
5        case Timers::myTimer:
6        {
7            this->seconds++;
8            if(this->seconds>99) this->seconds = 0;
9        }
10        break;
11        default:
12        break;
13    }
14}
15 

Measuring FPS

Frame rate (expressed in frames per second or FPS) is the frequency (rate) at which consecutive images (frames) are displayed on module screens.

FPS is one of the most important metrics of any computer game with graphics. It is essential to keep it at acceptable rates while the game plays. Sudden drops of FPS value may get user dissatisfied with the game.

The way of calculation of FPS is rather trivial: as long as we know deltaTime, the FPS value would be calculated as

11000.0/deltaTime
2 

Rendering results

It's a final part of the excercise, and it is quite simple.

In order to render time values, three simple steps are taken inside on_Render() callback:

• Clear the screen

• Render the text with values

• Commit changes

  Time and Timers

  CPP

  1  char buff[256];
  2  
  3  for(auto it = screens.begin(); it != screens.end(); ++it)
  4  {
  5      Cubios::GFX_setRenderTarget(it->ID());
  6      Cubios::GFX_clear(Colors::black);
  7 
  8      sprintf(buff,"dt: %d ms",this->deltaTime);
  9      Cubios::GFX_drawText(120,80, TEXT_SIZE, 0, Cubios::text_align_t::TEXT_ALIGN_CENTER, Colors::white, buff);
  10 
  11      sprintf(buff,"fps: %.2f",this->fps);
  12      Cubios::GFX_drawText(120,120, TEXT_SIZE, 0, Cubios::text_align_t::TEXT_ALIGN_CENTER, Colors::green, buff);
  13 
  14      sprintf(buff,"timer: %d s",this->seconds);
  15      Cubios::GFX_drawText(120,160, TEXT_SIZE, 0, Cubios::text_align_t::TEXT_ALIGN_CENTER, Colors::blue, buff);
  16 
  17      Cubios::GFX_render();
  18  }
  19 

  Wrapped for easier reading. Turn wrap off to inspect exact line lengths.

  WrappedExplain with AIAI