install_int_ex(3)

1install_int_ex(3)               Allegro manual               install_int_ex(3)
2
3
4

NAME

6       install_int_ex  -  Adds  or  modifies a timer. Allegro game programming
7       library.
8

SYNOPSIS

10       #include <allegro.h>
11
12
13       int install_int_ex(void (*proc)(), int speed);
14

DESCRIPTION

16       Adds a function to the list of user timer handlers or, if it is already
17       installed,  retroactively  adjusts  its  speed (i.e makes as though the
18       speed change occurred precisely at the last tick). The speed  is  given
19       in  hardware  clock ticks, of which there are 1193181 a second. You can
20       convert from other time  formats  to  hardware  clock  ticks  with  the
21       macros:
22
23          SECS_TO_TIMER(secs)  - give the number of seconds between
24                                 each tick
25          MSEC_TO_TIMER(msec)  - give the number of milliseconds
26                                 between ticks
27          BPS_TO_TIMER(bps)    - give the number of ticks each second
28          BPM_TO_TIMER(bpm)    - give the number of ticks per minute
29
30       There can only be sixteen timers in use at a time, and some other parts
31       of Allegro (the GUI code, the mouse pointer display  routines,  rest(),
32       the  FLI player, and the MIDI player) need to install handlers of their
33       own, so you should avoid using too many at the same time. If  you  call
34       this   routine   without  having  first  installed  the  timer  module,
35       install_timer() will be called automatically.
36
37       Your function will be called by the Allegro interrupt handler  and  not
38       directly  by  the  processor, so it can be a normal C function and does
39       not need a special wrapper. You should be aware, however, that it  will
40       be  called in an interrupt context, which imposes a lot of restrictions
41       on what you can do in it. It should not use large amounts of stack,  it
42       must  not  make  any calls to the operating system, use C library func‐
43       tions, or contain any floating point code, and  it  must  execute  very
44       quickly.  Don't  try to do lots of complicated code in a timer handler:
45       as a general rule you should just set some flags and respond  to  these
46       later in your main control loop.
47
48       In  a  DOS protected mode environment like DJGPP, memory is virtualised
49       and can be swapped to disk. Due to the non-reentrancy of DOS, if a disk
50       swap  occurs  inside an interrupt handler the system will die a painful
51       death, so you need to make sure you lock all the memory (both code  and
52       data)  that  is touched inside timer routines. Allegro will lock every‐
53       thing it uses, but you are responsible for locking your  handler  func‐
54       tions.  The  macros  LOCK_VARIABLE  (variable),  END_OF_FUNCTION (func‐
55       tion_name), END_OF_STATIC_FUNCTION (function_name),  and  LOCK_FUNCTION
56       (function_name)  can be used to simplify this task. For example, if you
57       want an interrupt handler  that  increments  a  counter  variable,  you
58       should write:
59
60          volatile int counter;
61
62          void my_timer_handler()
63          {
64             counter++;
65          }
66
67          END_OF_FUNCTION(my_timer_handler)
68
69       and in your initialisation code you should lock the memory:
70
71          LOCK_VARIABLE(counter);
72          LOCK_FUNCTION(my_timer_handler);
73
74       Obviously  this  can get awkward if you use complicated data structures
75       and call other functions from within your handler, so you should try to
76       keep your interrupt routines as simple as possible.
77

RETURN VALUE

79       Returns  zero  on  success, or a negative number if there is no room to
80       add a new user timer.
81
82

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUE

SEE ALSO