# Timer routines

These functions are declared in the main Allegro header file:

~~~~c
 #include <allegro5/allegro.h>
~~~~

## API: ALLEGRO_TIMER

This is an abstract data type representing a timer object.

## API: ALLEGRO_USECS_TO_SECS

Convert microseconds to seconds.

## API: ALLEGRO_MSECS_TO_SECS

Convert milliseconds to seconds.

## API: ALLEGRO_BPS_TO_SECS

Convert beats per second to seconds.

## API: ALLEGRO_BPM_TO_SECS

Convert beats per minute to seconds.

## API: al_create_timer

Allocates and initializes a timer. If successful, a pointer to a new timer
object is returned, otherwise NULL is returned.  *speed_secs* is in seconds per
"tick", and must be positive. The new timer is initially stopped and needs to
be started with [al_start_timer] before [ALLEGRO_EVENT_TIMER] events are sent.

Usage note: typical granularity is on the order of microseconds, but with
some drivers might only be milliseconds.

See also: [al_start_timer], [al_destroy_timer]

## API: al_start_timer

Start the timer specified.  From then, the timer's counter will increment
at a constant rate, and it will begin generating events. Starting a
timer that is already started does nothing. Starting a timer that was stopped
will reset the timer's counter, effectively restarting the timer from the
beginning.

See also: [al_stop_timer], [al_get_timer_started], [al_resume_timer]

## API: al_resume_timer

Resume the timer specified.  From then, the timer's counter will increment
at a constant rate, and it will begin generating events. Resuming a
timer that is already started does nothing. Resuming a stopped timer will not
reset the timer's counter (unlike [al_start_timer]).

See also: [al_start_timer], [al_stop_timer], [al_get_timer_started]

## API: al_stop_timer

Stop the timer specified.  The timer's counter will stop incrementing and
it will stop generating events.  Stopping a timer that is already stopped
does nothing.

See also: [al_start_timer], [al_get_timer_started], [al_resume_timer]

## API: al_get_timer_started

Return true if the timer specified is currently started.

## API: al_destroy_timer

Uninstall the timer specified. If the timer is started, it will
automatically be stopped before uninstallation. It will also
automatically unregister the timer with any event queues.

Does nothing if passed the NULL pointer.

See also: [al_create_timer]

## API: al_get_timer_count

Return the timer's counter value. The timer can be started or stopped.

See also: [al_set_timer_count]

## API: al_set_timer_count

Set the timer's counter value. The timer can be started or stopped.
The count value may be positive or negative, but will always be incremented
by +1 at each tick.

See also: [al_get_timer_count], [al_add_timer_count]

## API: al_add_timer_count

Add *diff* to the timer's counter value.  This is similar to writing:

~~~~c
al_set_timer_count(timer, al_get_timer_count(timer) + diff);
~~~~

except that the addition is performed atomically, so no ticks will be lost.

See also: [al_set_timer_count]

## API: al_get_timer_speed

Return the timer's speed, in seconds. (The same value passed to
[al_create_timer] or [al_set_timer_speed].)

See also: [al_set_timer_speed]

## API: al_set_timer_speed

Set the timer's speed, i.e. the rate at which its counter will be
incremented when it is started. This can be done when the timer is
started or stopped. If the timer is currently running, it is made to
look as though the speed change occurred precisely at the last tick.

*speed_secs* has exactly the same meaning as with [al_create_timer].

See also: [al_get_timer_speed]

## API: al_get_timer_event_source

Retrieve the associated event source. Timers will generate events of
type [ALLEGRO_EVENT_TIMER].
