Timers & Tweens

Timers & Tweens

Timing and Tweening events in 32blit share some common fundamentals. At their core they are a callback function registered with the API to be called under certain conditions.

A tween function is generally called continuously, and is used to do something such as animating a value over a period of time.

A timer callback is usually called once after a set duration, and is used to do something in the future or - in combination with looping - at a set interval.

Timers

The timer-test example is a very simple demonstration of counting to 10 using a timer.

First a Timer must be created, it should be given a descriptive name:

blit::Timer counter;

Next, a callback function should be defined. This is the function that the timer calls when it has elapsed. It should accept one argument: a blit::Timer and return void:

void counter_update(blit::Timer &t){
  count++;
}

Then, usually during the init() phase of a 32blit game, the timer should be set up with a callback function, interval (in milliseconds) and loop count (-1 to loop indefinitely):

void init() {
  counter.init(counter_update, 1000, -1);
}

In this example the timer will call the callback function once every 1000ms (every second) and loop forever.

Finally the timer must be started:

counter.start();

At this point the 32blit API takes over and will call the timer continuously every 1000ms until it is stopped with:

counter.stop();

Timers At A Glance

• init(TimerCallback callback, uint32_t duration, int32_t loops); - Initialise a Timer with callback function, duration and loop count
• start() - Start the Timer
• stop() - Stop the Timer
• is_running() - Returns true if Timer state is RUNNING
• is_paused() - Returns true if Timer state is PAUSED
• is_stopped() - Returns true if Timer state is STOPPED
• is_finished() - Returns true if Timer state is FINISHED

Tweens

The tween-test example demonstrates using some of the built-in tweening functions to tween a couple of values continuously.

First a Tween must be created, it should be given a descriptive name:

blit::Tween bounce;

An existing easing function can be used as the tween callback, these are:

• tween_sine - Tween between the start and end value using a sine wave
• tween_linear - Tween linearly from the start to the end value over the tween duration - a direct, robotic motion
• tween_ease_in_quad - Tween into a quadratic curve, starting slow and ramping up in speed - like a rocket ship speeding away
• tween_ease_out_quad - Tween out of a quadratic curve, starting fast and slowing down - like a door, sliding closed
• tween_ease_in_out_quad - Start slow, ramp up in speed, and end slow - like a car, speeding up and coming to a stop

Alternatively a custom easing function can be defined and should follow the template:

  float tween_sine(uint32_t t, float b, float c, uint32_t d) {
    return 0.0;
  }

Where t is the current time, b is the original value, c is the destination value and d is the duration.

The tween should be set up, usually during the init() phase of a 32blit game, with a tweening function, start and end value, duration and loop count:

bounce.init(tween_sine, 200.0f, 0.0f, 5000, -1);

In this case it will "bounce" from 200 down to 0 every 5000ms (5sec) forever (-1 = loop indefinitely.)

Finally the tween must be started:

bounce.start();

At this point the 32blit API takes over and will update the tween based on the supplied parameters.

The value property will now contain the calculated result of the tween function, and can be used in code:

screen.circle(Point(160, 20+bounce.value), 20);

The tween will run until the loop count expires, or until it is stopped with:

bounce.stop();

Tweens At A Glance

• init(TweenFunction function, float start, float end, uint32_t duration, int32_t loops) - Initialise a Tween with tween function, start/end values, duration and loop count
• start() - Start a Tween
• stop() - Stop a Tween
• is_running() - Returns true if Tween state is RUNNING
• is_paused() - Returns true if Tween state is PAUSED
• is_stopped() - Returns true if Tween state is STOPPED
• is_finished() - Returns true if Tween state is FINISHED