timeline

struct timeline

struct timeline

A timeline holds a sequence of events on a, well.. time line. Each event has a start time, a duration and a callback function. The callback gets called each time the timeline is updated, as long as the event is active.

You can use a time line to sequence animations, cut-scenes, in-level scenes and other event-driven behaviors.

Events in a timeline cannot overlap. If you need events to overlap (such as in a dialogue) you will need to create more than one timeline, just like you would have separate tracks in a video editor or an animation software.

struct timeline_event

struct timeline_event

Timeline event holds a single registered event in a timeline. Timeline events can have a gap of time between the last scheduled event. Timeline events can also have a duration, which makes them long-running events. The manifestation of a timeline event is a callback call.

create_timeline

struct timeline *create_timeline(void)

Allocate and prepare a new timeline ready for use.

Return
- an allocated, ready to use timeline.

destroy_timeline

void destroy_timeline(struct timeline *timeline)

Destroy a previously created timeline

append_event

int append_event(struct timeline * timeline, uint32_t wait, uint32_t duration, void *(*callback)(void *data, float elapsed_ms, float progress))

Append an event to the timeline

Return
-1 on error or the new event index
Parameters
  • timeline -

    Timeline to append the event to

  • wait -

    Time to wait after the last event

  • duration -

    Time to actively call the callback or 0 for a single call

  • callback -

    Callback function to call to

append_events

int append_events(struct timeline *timeline, int nevents, struct timeline_event events[])

Append an set of events to the timeline

Return
-1 on error or the number of appended events
Parameters
  • timeline -

    Timeline to append the events to

  • nevents -

    Number of events to append

  • events -

    timeline_event array

update_timeline

void *update_timeline(struct timeline *timeline, void *data, float elapsed_ms)

Update the timeline timers and invoke event callbacks

init_timeline

void init_timeline(struct timeline *timeline)

Used to prepare an already allocated timeline

pause_timeline

void pause_timeline(struct timeline *timeline)

Pause a running timeline, stopping any running timer accounting.

reset_timeline

void reset_timeline(struct timeline *timeline)

Reset & restart a running or completed timeline.

cleanup_timeline

void cleanup_timeline(struct timeline *timeline)

Cleans a used timeline, but does not deallocate it

Easing

Using easing interpolation functions you can use the progress argument in the timeline callbacks to create a factor value for animation effects such as smoothing the motion of a game title or even bouncing a ball.

Functions

float interpolate(float from, float to, float amount, float (*easing)(float))

Interpolate two values using an easing function

Return
interpolated value
Parameters
  • from -

    start value

  • to -

    end value

  • amount -

    a value from 0 to 1

  • easing -

    one of the following easing functions

float linear_interpolation(float p)

Function Graph: 

|                      _.-'
|                 _,,-'
|             _.-'
|         ,,-'
|    _,-''
|,.-'
+---------------------------

float quadratic_ease_in(float p)

Function Graph: 

|                          '
|                        ,'
|                      ,'
|                   _,'
|              _,.-'
| .........--''
+---------------------------

float quadratic_ease_out(float p)

Function Graph: 

|            _..,----''''---
|        ,,-'
|     ,-'
|   ,'
| ,'
|<
+---------------------------

float quadratic_ease_in_out(float p)

Function Graph: 

|                   _,,..--
|                ,-'
|              ,'
|             '
|          _,'
|--....,-''
+---------------------------

float cubic_ease_in(float p)

Function Graph: 

|                          '
|                        ,'
|                      ,'
|                   _,'
|              _,.-'
| .........--''
+---------------------------

float cubic_ease_out(float p)

Function Graph: 

|            _..,----''''---
|        ,,-'
|     ,-'
|   ,'
| ,'
|<
+---------------------------

float cubic_ease_in_out(float p)

Function Graph: 

|                   _,,..--
|                ,-'
|              ,'
|             '
|          _,'
|--....,-''
+---------------------------

float quartic_ease_in(float p)

Function Graph: 

|                          /
|                         /
|                        /
|                      ,'
|                  _,-'
|...________,,..--'
+---------------------------

float quartic_ease_out(float p)

Function Graph: 

|          _,..,---------...
|     ,,-''
|   ,'
|  /
| /
|`
+---------------------------

float quartic_ease_in_out(float p)

Function Graph: 

|                  _..------
|                ,'
|              .-
|              +
|            _/
|..____,,.--'
+---------------------------

float quintic_ease_in(float p)

Function Graph: 

|                           |
|                           |
|                          /
|                        ,'
|                   _,.-'
|..............--'''
+---------------------------

float quintic_ease_out(float p)

Function Graph: 

|        __..--'''''''''''--
|    ,-''
|  ,'
| /
||
||
+---------------------------

float quintic_ease_in_out(float p)

Function Graph: 

|                 _..-------
|               ,'
|              |
|              '
|             /
|..__,,....--'
+---------------------------

float sine_ease_in(float p)

Function Graph: 

|                         _,
|                       ,'
|                     ,'
|                 _.-'
|             _.-'
|..._,,..,--''
+---------------------------

float sine_ease_out(float p)

Function Graph: 

|                  __...----
|            _,.-''
|         ,,'
|     _.-'
|  ,-'
|-'
+---------------------------

float sine_ease_in_out(float p)

Function Graph: 

|                      ___..
|                  ,-''
|               ,-'
|             ,-
|        __.-'
|.,----''
+---------------------------

float circular_ease_in(float p)

Function Graph: 

|                          |
|                         ,'
|                      _,'
|                  _,-'
|          _,.--'''
|__...---''
+---------------------------

float circular_ease_out(float p)

Function Graph: 

|                 _,,.....,-
|        _,,.---''
|    _,-'
|  ,'
|,'
|/
+---------------------------

float circular_ease_in_out(float p)

Function Graph: 

|                  _,..-----
|              ,-''
|             '.
|             ]
|        _,,.-
|_,.---''
+---------------------------

float exponential_ease_in(float p)

Function Graph: 

|                           .
|                           |
|                           |
|                         ,'
|                     _,-'
|..._________.....--''
+---------------------------

float exponential_ease_out(float p)

Function Graph: 

|       _,.--''''''''''`----
|    ,,'
|  ,'
| /
|.'
||
+---------------------------

float exponential_ease_in_out(float p)

Function Graph: 

1               _,,--'''''--
|              /
|             |
|             |
|            ,'
|..._,,....--
+---------------------------

float elastic_ease_in(float p)

Function Graph: 

1                          )
|                         .'
|                         |
|                         |
|                _..     |
|__...----.   ,--   ;    /
+----------`''-------+--+---
|                    `-

float elastic_ease_out(float p)

Function Graph: 

| ,--
1 |   `.   <''`.__
| |    :_ ,'      `'------'
| |      '
||
||
||
+---------------------------

float elastic_ease_in_out(float p)

Function Graph: 

|             _,\      _.._
1             /   `._,''
|            .'
|            |
|           |
|          .'
|_,,-'';   '
+-------`=+-----------------

float back_ease_in(float p)

Function Graph: 

1                          ,
|                        ,'
|                       /
|                     ,'
|                   ,'
|._               ,'
+--`..=------=,,-'----------
|     `'''''

float back_ease_out(float p)

Function Graph: 

|        _,.------...__
1      ,-'              `--.
|    ,'
|   /
|  /
| /
|/
+---------------------------

float back_ease_in_out(float p)

Function Graph: 

|               _,----..
1               /        `-.
|              /
|             |
|             '
|            /
|_          /
+-`.=-----,'----------------
|   ``-''

float bounce_ease_in(float p)

Function Graph: 

|                        _,.
|                     ,-'
|                    /
|              _    .'
| _._ ,-'-. ,-' `-. |
|-   '     '       '
+---------------------------

float bounce_ease_out(float p)

Function Graph: 

|         \     `.   ,'. _.
|        | `-.-'  `-'   '
|        /
|       /
|     ,'
|..--'
+---------------------------

float bounce_ease_in_out(float p)

Function Graph: 

|                 /\   '_,'/
|                ,' `-'
|              ,'
|          ,'-'
|     .--.|
|,-`.'   '|
+---------------------------