NAME¶
install_int_ex - Adds or modifies a timer. Allegro game programming library.
SYNOPSIS¶
#include <allegro.h>
int install_int_ex(void (*proc)(), int speed);
DESCRIPTION¶
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:
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
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.
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.
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:
volatile int counter;
void my_timer_handler()
{
counter++;
}
END_OF_FUNCTION(my_timer_handler)
and in your initialisation code you should lock the memory:
LOCK_VARIABLE(counter);
LOCK_FUNCTION(my_timer_handler);
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.
RETURN VALUE¶
Returns zero on success, or a negative number if there is no room to add a new
user timer.
SEE ALSO¶
install_timer(3alleg4),
remove_int(3alleg4),
install_int(3alleg4),
install_param_int_ex(3alleg4),
excamera(3alleg4),
exsprite(3alleg4),
extimer(3alleg4),
exunicod(3alleg4),
exupdate(3alleg4)