Ubuntu Manpage: install_int_ex - Adds or modifies a timer. Allegro game programming library.

name
synopsis
description
return value
see also

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.

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUE

SEE ALSO