Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
install_int_ex(3)		Allegro	manual		     install_int_ex(3)

NAME
       install_int_ex -	Adds or	modifies a timer. Allegro game programming li-
       brary.

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, in-
       stall_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 func-
       tions, 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	every-
       thing it	uses, but you are responsible for locking your	handler	 func-
       tions.  The  macros  LOCK_VARIABLE  (variable),	END_OF_FUNCTION	(func-
       tion_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(3),       remove_int(3),	    install_int(3),	   in-
       stall_param_int_ex(3),  excamera(3),  exsprite(3),  extimer(3),	exuni-
       cod(3), exupdate(3)

Allegro				 version 4.4.2		     install_int_ex(3)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=install_int_ex&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help