Timer routines

Summary
This is an abstract data type representing a timer object.
Install a new timer.
Uninstall the timer specified.
Start the timer specified.
Stop the timer specified.
Return true if the timer specified is currently started.
Return the timer’s speed, in seconds.
Set the timer’s speed, i.e.
Return the timer’s counter value.
Change a timer’s counter value.

Macros

conversion macros

ALLEGRO_USECS_TO_SECSmicroseconds to seconds
ALLEGRO_MSECS_TO_SECSmilliseconds to seconds
ALLEGRO_BPS_TO_SECSbeats per second to seconds
ALLEGRO_BPM_TO_SECSbeats per minute to seconds
ALLEGRO_SECS_TO_MSECSseconds to milliseconds
ALLEGRO_SECS_TO_USECSseconds to microseconds These macros convert from various time units into milliseconds.

Types

ALLEGRO_TIMER

This is an abstract data type representing a timer object.  A timer object can act as an event source so can be casted to ALLEGRO_EVENT_SOURCE*.

Functions

al_install_timer

AL_FUNC(ALLEGRO_TIMER*,
al_install_timer,
(double speed_secs))

Install a new 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.

The system driver must be installed before this function can be called.

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

al_uninstall_timer

AL_FUNC(void,
al_uninstall_timer,
(ALLEGRO_TIMER *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.

TIMER may not be NULL.

al_start_timer

AL_FUNC(void,
al_start_timer,
(ALLEGRO_TIMER *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.

al_stop_timer

AL_FUNC(void,
al_stop_timer,
(ALLEGRO_TIMER *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.

al_timer_is_started

AL_FUNC(bool,
al_timer_is_started,
(ALLEGRO_TIMER *timer))

Return true if the timer specified is currently started.

al_get_timer_speed

AL_FUNC(double,
al_get_timer_speed,
(ALLEGRO_TIMER *timer))

Return the timer’s speed, in seconds.

al_set_timer_speed

AL_FUNC(void,
al_set_timer_speed,
(ALLEGRO_TIMER *timer, double speed_secs))

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 occured precisely at the last tick.

speed_secs has exactly the same meaning as with al_install_timer.

al_get_timer_count

AL_FUNC(long,
al_get_timer_count,
(ALLEGRO_TIMER *timer))

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

al_set_timer_count

AL_FUNC(void,
al_set_timer_count,
(ALLEGRO_TIMER *timer, long count))

Change a timer’s counter value.  The timer can be started or stopped.  COUNT value may be positive or negative, but will always be incremented by +1.

AL_FUNC(ALLEGRO_TIMER*,
al_install_timer,
(double speed_secs))
Install a new timer.
AL_FUNC(void,
al_uninstall_timer,
(ALLEGRO_TIMER *timer))
Uninstall the timer specified.
AL_FUNC(void,
al_start_timer,
(ALLEGRO_TIMER *timer))
Start the timer specified.
AL_FUNC(void,
al_stop_timer,
(ALLEGRO_TIMER *timer))
Stop the timer specified.
AL_FUNC(bool,
al_timer_is_started,
(ALLEGRO_TIMER *timer))
Return true if the timer specified is currently started.
AL_FUNC(double,
al_get_timer_speed,
(ALLEGRO_TIMER *timer))
Return the timer’s speed, in seconds.
AL_FUNC(void,
al_set_timer_speed,
(ALLEGRO_TIMER *timer, double speed_secs))
Set the timer’s speed, i.e.
AL_FUNC(long,
al_get_timer_count,
(ALLEGRO_TIMER *timer))
Return the timer’s counter value.
AL_FUNC(void,
al_set_timer_count,
(ALLEGRO_TIMER *timer, long count))
Change a timer’s counter value.