<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
<html><head><title>
Allegro Manual: Timer routines
</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta http-equiv="Content-Style-Type" content="text/css">
<link rel="stylesheet" title="Default" type="text/css" href="allegro.css"></head><body bgcolor=white text=black link="#0000ee" alink="#ff0000" vlink="#551a8b">
<h1><a name="Timer routines">Timer routines</a></h1>
<ul>
<li><a href="#END_OF_FUNCTION">END_OF_FUNCTION</a> — Locks the code used by a timer.
<li><a href="#install_int">install_int</a> — Installs a user timer handler.
<li><a href="#install_int_ex">install_int_ex</a> — Adds or modifies a timer.
<li><a href="#install_param_int">install_param_int</a> — Installs a timer routine with a customizable parameter.
<li><a href="#install_param_int_ex">install_param_int_ex</a> — Adds or modifies a timer with a customizable parameter.
<li><a href="#install_timer">install_timer</a> — Installs the Allegro timer interrupt handler.
<li><a href="#LOCK_FUNCTION">LOCK_FUNCTION</a> — Locks the memory of a function used by a timer.
<li><a href="#LOCK_VARIABLE">LOCK_VARIABLE</a> — Locks the memory of a variable used by a timer.
<li><a href="#remove_int">remove_int</a> — Removes a timers.
<li><a href="#remove_param_int">remove_param_int</a> — Removes a timer with a customizable parameter.
<li><a href="#remove_timer">remove_timer</a> — Removes the Allegro time handler.
<li><a href="#rest">rest</a> — Waits a specified number of milliseconds or yields CPU.
<li><a href="#rest_callback">rest_callback</a> — Like rest(), but calls the callback during the wait.
<li><a href="#retrace_count">retrace_count</a> — Retrace count simulator.
</ul>
<p>
Allegro can set up several virtual timer functions, all going at different
speeds.
<p>
Under DOS it will constantly reprogram the clock to make sure they are all
called at the correct times. Because they alter the low level timer chip
settings, these routines should not be used together with other DOS timer
functions like the DJGPP uclock() routine. Moreover, the FPU state is not
preserved across Allegro interrupts so you ought not to use floating point
or MMX code inside timer interrupt handlers.
<p>
Under other platforms, they are usually implemented using threads, which run
parallel to the main thread. Therefore timer callbacks on such platforms
will not block the main thread when called, so you may need to use
appropriate synchronisation devices (eg. mutexes, semaphores, etc.) when
accessing data that is shared by a callback and the main thread. (Currently
Allegro does not provide such devices.)
<p><br>
<div class="al-api"><b>int <a name="install_timer">install_timer</a>();</b></div><br>
Installs the Allegro timer interrupt handler. You must do this before
installing any user timer routines, and also before displaying a mouse
pointer, playing FLI animations or MIDI music, and using any of the GUI
routines.
<p><b>Return value:</b>
Returns zero on success, or a negative number on failure (but you may
decide not to check the return value as this function is very unlikely to
fail).
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#remove_timer" title="Removes the Allegro time handler.">remove_timer</a>,
<a class="xref" href="#install_int" title="Installs a user timer handler.">install_int</a>.</blockquote>
<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg046.html#Available Allegro examples" title="">Available Allegro examples</a>.</blockquote>
<div class="al-api"><b>void <a name="remove_timer">remove_timer</a>();</b></div><br>
Removes the Allegro timer handler (and, under DOS, passes control of the
clock back to the operating system). You don't normally need to bother
calling this, because allegro_exit() will do it for you.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#install_timer" title="Installs the Allegro timer interrupt handler.">install_timer</a>,
<a class="xref" href="alleg000.html#allegro_exit" title="Closes down the Allegro system.">allegro_exit</a>.</blockquote>
<div class="al-api"><b>int <a name="install_int">install_int</a>(void (*proc)(), int speed);</b></div><br>
Installs a user timer handler, with the speed given as the number of
milliseconds between ticks. This is the same thing as
install_int_ex(proc, MSEC_TO_TIMER(speed)). If you call this routine
without having first installed the timer module, install_timer() will be
called automatically. Calling again this routine with the same timer
handler as parameter allows you to adjust its speed.
<p><b>Return value:</b>
Returns zero on success, or a negative number if there is no room to add
a new user timer.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#install_timer" title="Installs the Allegro timer interrupt handler.">install_timer</a>,
<a class="xref" href="#remove_int" title="Removes a timers.">remove_int</a>,
<a class="xref" href="#install_int_ex" title="Adds or modifies a timer.">install_int_ex</a>,
<a class="xref" href="#install_param_int" title="Installs a timer routine with a customizable parameter.">install_param_int</a>.</blockquote>
<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg046.html#exscn3d" title="Using the 3d scene functions.">exscn3d</a>,
<a class="eref" href="alleg046.html#exswitch" title="Controlling the console switch mode for background running.">exswitch</a>,
<a class="eref" href="alleg046.html#extimer" title="Using the timer (delays and interrupts).">extimer</a>,
<a class="eref" href="alleg046.html#exzbuf" title="Z-buffered polygons demo.">exzbuf</a>.</blockquote>
<div class="al-api"><b>int <a name="install_int_ex">install_int_ex</a>(void (*proc)(), int speed);</b></div><br>
Adds a function to the list of user timer handlers or, if it is already
installed, retroactively adjusts its speed (i.e makes as though the speed
change occurred precisely at the last tick). The speed is given in hardware
clock ticks, of which there are 1193181 a second. You can convert from
other time formats to hardware clock ticks with the macros:
<blockquote class="text"><pre>
SECS_TO_TIMER(secs) - give the number of seconds between
each tick
MSEC_TO_TIMER(msec) - give the number of milliseconds
between ticks
BPS_TO_TIMER(bps) - give the number of ticks each second
BPM_TO_TIMER(bpm) - give the number of ticks per minute
</pre></blockquote>
There can only be sixteen timers in use at a time, and some other parts of
Allegro (the GUI code, the mouse pointer display routines, rest(), the FLI
player, and the MIDI player) need to install handlers of their own, so you
should avoid using too many at the same time. If you call this routine
without having first installed the timer module, install_timer() will be
called automatically.
<p>
Your function will be called by the Allegro interrupt handler and not
directly by the processor, so it can be a normal C function and does not
need a special wrapper. You should be aware, however, that it will be
called in an interrupt context, which imposes a lot of restrictions on
what you can do in it. It should not use large amounts of stack, it must
not make any calls to the operating system, use C library functions, or
contain any floating point code, and it must execute very quickly. Don't
try to do lots of complicated code in a timer handler: as a general rule
you should just set some flags and respond to these later in your main
control loop.
<p>
In a DOS protected mode environment like DJGPP, memory is virtualised and
can be swapped to disk. Due to the non-reentrancy of DOS, if a disk swap
occurs inside an interrupt handler the system will die a painful death,
so you need to make sure you lock all the memory (both code and data)
that is touched inside timer routines. Allegro will lock everything it
uses, but you are responsible for locking your handler functions. The
macros LOCK_VARIABLE (variable), END_OF_FUNCTION (function_name),
END_OF_STATIC_FUNCTION (function_name), and LOCK_FUNCTION (function_name)
can be used to simplify this task. For example, if you want an interrupt
handler that increments a counter variable, you should write:
<blockquote class="code"><pre>
volatile int counter;
void my_timer_handler()
{
counter++;
}
<a href="#END_OF_FUNCTION" class="autotype" title="Locks the code used by a timer.">END_OF_FUNCTION</a>(my_timer_handler)
</pre></blockquote>
and in your initialisation code you should lock the memory:
<blockquote class="code"><pre>
<a href="#LOCK_VARIABLE" class="autotype" title="Locks the memory of a variable used by a timer.">LOCK_VARIABLE</a>(counter);
<a href="#LOCK_FUNCTION" class="autotype" title="Locks the memory of a function used by a timer.">LOCK_FUNCTION</a>(my_timer_handler);
</pre></blockquote>
Obviously this can get awkward if you use complicated data structures and
call other functions from within your handler, so you should try to keep
your interrupt routines as simple as possible.
<p><b>Return value:</b>
Returns zero on success, or a negative number if there is no room to add
a new user timer.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#install_timer" title="Installs the Allegro timer interrupt handler.">install_timer</a>,
<a class="xref" href="#remove_int" title="Removes a timers.">remove_int</a>,
<a class="xref" href="#install_int" title="Installs a user timer handler.">install_int</a>,
<a class="xref" href="#install_param_int_ex" title="Adds or modifies a timer with a customizable parameter.">install_param_int_ex</a>.</blockquote>
<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg046.html#excamera" title="Viewing a 3d world from an arbitrary camera position.">excamera</a>,
<a class="eref" href="alleg046.html#exsprite" title="Datafiles access and sprite animation.">exsprite</a>,
<a class="eref" href="alleg046.html#extimer" title="Using the timer (delays and interrupts).">extimer</a>,
<a class="eref" href="alleg046.html#exunicod" title="Using Unicode string functions.">exunicod</a>,
<a class="eref" href="alleg046.html#exupdate" title="Supporting different screen update methods in a single program.">exupdate</a>.</blockquote>
<div class="al-api"><b>Macro <a name="LOCK_VARIABLE">LOCK_VARIABLE</a>(variable_name);</b></div><br>
Due to interrupts, you are required to lock all the memory used by your
timer routines. See the description of install_int_ex() for a more
detailed explanation and usage example.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#install_int" title="Installs a user timer handler.">install_int</a>,
<a class="xref" href="#install_int_ex" title="Adds or modifies a timer.">install_int_ex</a>.</blockquote>
<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg046.html#exscn3d" title="Using the 3d scene functions.">exscn3d</a>,
<a class="eref" href="alleg046.html#exsprite" title="Datafiles access and sprite animation.">exsprite</a>,
<a class="eref" href="alleg046.html#exswitch" title="Controlling the console switch mode for background running.">exswitch</a>,
<a class="eref" href="alleg046.html#extimer" title="Using the timer (delays and interrupts).">extimer</a>,
<a class="eref" href="alleg046.html#exupdate" title="Supporting different screen update methods in a single program.">exupdate</a>,
<a class="eref" href="alleg046.html#exzbuf" title="Z-buffered polygons demo.">exzbuf</a>.</blockquote>
<div class="al-api"><b>Macro <a name="LOCK_FUNCTION">LOCK_FUNCTION</a>(function_name);</b></div><br>
Due to interrupts, you are required to lock all the memory used by your
timer routines. See the description of install_int_ex() for a more
detailed explanation and usage example.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#install_int" title="Installs a user timer handler.">install_int</a>,
<a class="xref" href="#install_int_ex" title="Adds or modifies a timer.">install_int_ex</a>.</blockquote>
<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg046.html#exkeys" title="How to get input from the keyboard in different ways.">exkeys</a>,
<a class="eref" href="alleg046.html#exscn3d" title="Using the 3d scene functions.">exscn3d</a>,
<a class="eref" href="alleg046.html#exsprite" title="Datafiles access and sprite animation.">exsprite</a>,
<a class="eref" href="alleg046.html#exswitch" title="Controlling the console switch mode for background running.">exswitch</a>,
<a class="eref" href="alleg046.html#extimer" title="Using the timer (delays and interrupts).">extimer</a>,
<a class="eref" href="alleg046.html#exupdate" title="Supporting different screen update methods in a single program.">exupdate</a>,
<a class="eref" href="alleg046.html#exzbuf" title="Z-buffered polygons demo.">exzbuf</a>.</blockquote>
<div class="al-api"><b>Macro <a name="END_OF_FUNCTION">END_OF_FUNCTION</a>(function_name);</b></div><br>
Due to interrupts, you are required to lock all the code used by your
timer routines. See the description of install_int_ex() for a more
detailed explanation and usage example.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#install_int" title="Installs a user timer handler.">install_int</a>,
<a class="xref" href="#install_int_ex" title="Adds or modifies a timer.">install_int_ex</a>.</blockquote>
<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg046.html#exkeys" title="How to get input from the keyboard in different ways.">exkeys</a>,
<a class="eref" href="alleg046.html#exscn3d" title="Using the 3d scene functions.">exscn3d</a>,
<a class="eref" href="alleg046.html#exsprite" title="Datafiles access and sprite animation.">exsprite</a>,
<a class="eref" href="alleg046.html#exswitch" title="Controlling the console switch mode for background running.">exswitch</a>,
<a class="eref" href="alleg046.html#extimer" title="Using the timer (delays and interrupts).">extimer</a>,
<a class="eref" href="alleg046.html#exupdate" title="Supporting different screen update methods in a single program.">exupdate</a>,
<a class="eref" href="alleg046.html#exzbuf" title="Z-buffered polygons demo.">exzbuf</a>.</blockquote>
<div class="al-api"><b>void <a name="remove_int">remove_int</a>(void (*proc)());</b></div><br>
Removes a function from the list of user interrupt routines. At program
termination, allegro_exit() does this automatically.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#install_int" title="Installs a user timer handler.">install_int</a>,
<a class="xref" href="#install_int_ex" title="Adds or modifies a timer.">install_int_ex</a>,
<a class="xref" href="#remove_param_int" title="Removes a timer with a customizable parameter.">remove_param_int</a>.</blockquote>
<div class="al-api"><b>int <a name="install_param_int">install_param_int</a>(void (*proc)(void *), void *param, int speed);</b></div><br>
Like install_int(), but the callback routine will be passed a copy of the
specified void pointer parameter. To disable the handler, use
remove_param_int() instead of remove_int().
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#install_timer" title="Installs the Allegro timer interrupt handler.">install_timer</a>,
<a class="xref" href="#remove_param_int" title="Removes a timer with a customizable parameter.">remove_param_int</a>,
<a class="xref" href="#install_param_int_ex" title="Adds or modifies a timer with a customizable parameter.">install_param_int_ex</a>,
<a class="xref" href="#install_int" title="Installs a user timer handler.">install_int</a>.</blockquote>
<div class="al-api"><b>int <a name="install_param_int_ex">install_param_int_ex</a>(void (*proc)(void *), void *param, int speed);</b></div><br>
Like install_int_ex(), but the callback routine will be passed a copy of
the specified void pointer parameter. To disable the handler, use
remove_param_int() instead of remove_int().
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#install_timer" title="Installs the Allegro timer interrupt handler.">install_timer</a>,
<a class="xref" href="#remove_param_int" title="Removes a timer with a customizable parameter.">remove_param_int</a>,
<a class="xref" href="#install_param_int" title="Installs a timer routine with a customizable parameter.">install_param_int</a>,
<a class="xref" href="#install_int_ex" title="Adds or modifies a timer.">install_int_ex</a>.</blockquote>
<div class="al-api"><b>void <a name="remove_param_int">remove_param_int</a>(void (*proc)(void *), void *param);</b></div><br>
Like remove_int(), but for use with timer callbacks that have parameter
values. If there is more than one copy of the same callback active at a
time, it identifies which one to remove by checking the parameter value
(so you can't have more than one copy of a handler using an identical
parameter).
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#install_param_int" title="Installs a timer routine with a customizable parameter.">install_param_int</a>,
<a class="xref" href="#install_param_int_ex" title="Adds or modifies a timer with a customizable parameter.">install_param_int_ex</a>,
<a class="xref" href="#remove_int" title="Removes a timers.">remove_int</a>.</blockquote>
<div class="al-api"><b>extern volatile int <a name="retrace_count">retrace_count</a>;</b></div><br>
If the retrace simulator is installed, this count is incremented on each
vertical retrace; otherwise, if the refresh rate is known, the count is
incremented at the same rate (ignoring retraces); otherwise, it is
incremented 70 times a second. This provides a way of controlling
the speed of your program without installing user timer functions.
<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg046.html#ex3d" title="3d 'bouncy cubes' demo.">ex3d</a>,
<a class="eref" href="alleg046.html#exblend" title="Using translucency in truecolor modes.">exblend</a>,
<a class="eref" href="alleg046.html#exdbuf" title="How to use double buffering to avoid flicker.">exdbuf</a>,
<a class="eref" href="alleg046.html#exflip" title="Comparison of double buffering and page flipping.">exflip</a>,
<a class="eref" href="alleg046.html#exlights" title="One way to do colored lighting effects in a hicolor video mode.">exlights</a>.</blockquote>
<div class="al-api"><b>void <a name="rest">rest</a>(unsigned int time);</b></div><br>
This function waits for the specified number of milliseconds.
<p>
Passing 0 as parameter will not wait, but just yield. This can be useful
in order to "play nice" with other processes. Other values will cause
CPU time to be dropped on most platforms. This will look better to
users, and also does things like saving battery power and making fans
less noisy.
<p>
Note that calling this inside your active game loop is a bad idea, as
you never know when the OS will give you the CPU back, so you could end
up missing the vertical retrace and skipping frames. On the other hand,
on multitasking operating systems it is good form to give up the CPU for
a while if you will not be using it.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#install_timer" title="Installs the Allegro timer interrupt handler.">install_timer</a>,
<a class="xref" href="#rest_callback" title="Like rest(), but calls the callback during the wait.">rest_callback</a>,
<a class="xref" href="alleg008.html#vsync" title="Waits for a vertical retrace to begin.">vsync</a>,
<a class="xref" href="alleg035.html#d_yield_proc" title="Invisible dialog procedure that yields CPU time slices.">d_yield_proc</a>.</blockquote>
<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg046.html#exkeys" title="How to get input from the keyboard in different ways.">exkeys</a>,
<a class="eref" href="alleg046.html#exmidi" title="Playing MIDI music.">exmidi</a>,
<a class="eref" href="alleg046.html#exquat" title="A comparison between Euler angles and quaternions.">exquat</a>,
<a class="eref" href="alleg046.html#exsample" title="Playing digital samples.">exsample</a>,
<a class="eref" href="alleg046.html#exsprite" title="Datafiles access and sprite animation.">exsprite</a>,
<a class="eref" href="alleg046.html#extimer" title="Using the timer (delays and interrupts).">extimer</a>,
<a class="eref" href="alleg046.html#extrans" title="Lighting and translucency effects.">extrans</a>,
<a class="eref" href="alleg046.html#exunicod" title="Using Unicode string functions.">exunicod</a>.</blockquote>
<div class="al-api"><b>void <a name="rest_callback">rest_callback</a>(long time, void (*callback)())</b></div><br>
Like rest(), but for non-zero values continually calls the specified
function while it is waiting for the required time to elapse. If the
provided <tt>`callback'</tt> parameter is NULL, this function does exactly the
same thing as calling rest().
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#install_timer" title="Installs the Allegro timer interrupt handler.">install_timer</a>,
<a class="xref" href="#rest" title="Waits a specified number of milliseconds or yields CPU.">rest</a>.</blockquote>
<hr><div class="al-back-to-contents"><a href="allegro.html">Back to contents</a></div>
</body>
</html>
