Allegro can set up several virtual timer functions, all going at different speeds.
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.
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.)
Return value: 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).
See also: remove_timer, install_int.
Examples using this: Available Allegro examples.
See also: install_timer, allegro_exit.
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, remove_int, install_int_ex, install_param_int.
Examples using this: exscn3d, exswitch, extimer, exzbuf.
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.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
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:
and in your initialisation code you should lock the memory:volatile int counter; void my_timer_handler() { counter++; } END_OF_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.LOCK_VARIABLE(counter); LOCK_FUNCTION(my_timer_handler);
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, remove_int, install_int, install_param_int_ex.
Examples using this: excamera, exsprite, extimer, exunicod, exupdate.
See also: install_int, install_int_ex.
Examples using this: exscn3d, exsprite, exswitch, extimer, exupdate, exzbuf.
See also: install_int, install_int_ex.
Examples using this: exkeys, exscn3d, exsprite, exswitch, extimer, exupdate, exzbuf.
See also: install_int, install_int_ex.
Examples using this: exkeys, exscn3d, exsprite, exswitch, extimer, exupdate, exzbuf.
See also: install_int, install_int_ex, remove_param_int.
See also: install_timer, remove_param_int, install_param_int_ex, install_int.
See also: install_timer, remove_param_int, install_param_int, install_int_ex.
See also: install_param_int, install_param_int_ex, remove_int.
Examples using this: ex3d, exblend, exdbuf, exflip, exlights.
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.
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.
See also: install_timer, rest_callback, vsync, d_yield_proc.
Examples using this: Available Allegro examples.
See also: install_timer, rest.