Timer Unit

---

{=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
=-=-=-=-=-=-                                                     -=-=-=-=-=-=
-=-=-=              System Timer Low Level Interface Unit              =-=-=-
=-=-                                                                     -=-=
-=-=-=                     Coded by: Chris Lattner                     -=-=-=
=-=-=-=-=-=-                        1995                         -=-=-=-=-=-=
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=}
UNIT Timer;

INTERFACE
TYPE
  TimerHandlerProc = PROCEDURE;

PROCEDURE StartTimer(TimesASecond : INTEGER);
(*  StartTimer - Sets the system timer to run at the specified frequency,
  measured in hertz.  It installs an interrupt handler that regulates the
  time of day functions, and makes sure  that the system clock - the time
  kept by the "GetTime" function - is not sped up.  At every clock cycle,
  the procedure pointed  to by "TimerProc" is executed, and the interrupt
  returns.  TimesASecond is the desired interrupt rate of the clock.  The
  default rate is 18.2 rounded to 19. For high performance games, this is
  obviously way too slow.  TimesASecond is  automatically clipped to make
  sure that it is above 18.  Example:

  StartTimer(100);       { Produces an clock that operates at 100 hz }

  Make sure that you call "EndTimer" whenever your program exits - It has
  to free all of the  system resources it allocates  and revert the timer
  to it's normal state.  Not calling "EndTimer" WILL result in the user's
  computer locking up after the program is finished executing.         *)

PROCEDURE EndTimer;
(*  EndTimer - Frees all of the system resources allocated by StartTimer,
  deinitializes the interrupt handler, and restores the computer timer to
  it's default state.  It must be called before  the executing program is
  finished.   Calling this procedure multiple  times is OK, as extraneous
  calls are ignored.  Example:

  EndTimer;              { Frees system resources and restores timer }

  That is all there is to it!                                          *)

PROCEDURE SetTimerHandler(TimerHandler : TimerHandlerProc);
(*  SetTimerHandler - Installes  a user handler for the  timer interrupt.
  The specified  procedure is  called once every  iteration of  the clock
  cycle.  I recommend that you keep this proceedure as short as possible,
  to improve the response time of  other events, and to provide your main
  loop with as  much of the CPU time as  possible.  The handler  that you
  pass to  this procedure is  just a normal  procedure with  no arguments
  that is declared as "FAR".  Example:  (The default timer procedure)

  PROCEDURE DefaultTimerProc; FAR;      { Make sure you include the FAR }
  BEGIN
    INC(Time);                          { Do whatever you need to here! }
  END;

  SetTimerHandler(DefaultTimerProc);    { Example of installing it.     }

  Your timer handler is called however many times a second that you
  specify, but the system timer is still normalized.                   *)

VAR
  Time           : LONGINT;
(*  Time - Incremented every tick of the default timer tick handler.
  Used as an example.  Example:

  BEGIN
    StartTimer(100);
    Time := 0;
    WHILE Time < 100 DO ;         { Wait one second }

    Time := 0;
    WHILE Time < 50 DO ;          { Wait .5 seconds }

    OldTime := Time;
    WHILE OldTime+10 > Time DO ;  { Wait .1 seconds }

    EndTimer;
  END;                                                                 *)