{ SPX Library Version 2.0  Copyright 1993 Scott D. Ramsay }

  The SPX_TIM units is clock timer unit.  It is the same as the counters
 in the unit SPX_SND but maintains more counters.  12 clock timers to
 use for game precision.

     s_clk : array[0..5] of word;  { slow counters }
     f_clk : array[0..5] of word;  { fast counters }

  The unit takes control of the computer's clock interrupt and allows
the changing of its interrupt frequency.  From its regular 18.2 times per
second.

  The slow counters always count down at 18.2 times a second. Regardless of
the clock interrupt's rate. So, for example, the loop below will wait
for about 5 seconds:

   s_clk[0] := 5*18;
   repeat
   until s_clk[0]=0;

  Notice that there is nothing in the repeat loop.  The counters are
automatically decremented.  The counters also do not roll over. They will
decrement until they reach zero then stop.

  The fast counters count down according to the clock rate.  The clock rate
can be changed by the following procedure:

    procedure setrate(cycles:word);

  The variable cycles indicates the number of cycles(interrupts) to generate
per second.  So  setrate(18);  will restore the clock to its original rate.
Setrate(1000);  will generate an interrupt 1000 times per second.  Warning some
slow computers (8086/286) can not handle high clock rates.  Also conflicts
may occur if running under MS Windows or OS/2.

   Here's another example:

      setrate(2048);  { set the clock rate }
      f_clk[0] := 4096;
      repeat
      until f_clk[0]=0;

   The above example will loop for 2 seconds.

   A nice thing about the counters is that you can use them to
regulate the speed of your program/game.  Lets make a VERY rough
example.  Lets suppose you wrote a game that you want each 'frame'
or pass to take 1 second.  Your game loop would look something
like this:

     repeat
       s_clk[0] := 18;
       { grab user inputs }
       { do game calcuations }
       { setup objects for display }
       { update visual screen }
       while s_clk[0]<>0 do;
     until game_over;

   If one pass of the loop is faster than one second, then the game
will wait in the while loop until a second is up. Now depending on the
speed of the computer, the number of calcuations, speed of displaying the
sprites, the wait time may vary.  But the above loop will always wait
at MOST one second.  Now if one pass takes longer than a second then the
counter is already reached zero so there is no delay.  So the loop is
running at maximum speed.

   Now for event loops in games we WANT it to run alot faster than 1 sec.
So we would use a fast clock counter.

     setrate(3000);
     repeat
       f_clk[0] := 80;
       { grab user inputs }
       { do game calcuations }
       { setup objects for display }
       { update visual screen }
       while f_clk[0]<>0 do;
     until game_over;

   Now were all set.  We can even get fancy.  We can even automatically
adjust the rate according to the cabilities of the machine;

     var
       crate    : word;

     setrate(3000);
     crate := 80;
     repeat
       f_clk[0] := crate;
       { grab user inputs }
       { do game calcuations }
       { setup objects for display }
       { update visual screen }
       if (crate>0) and (f_clk[0]<10)
         then dec(crate);
       while f_clk[0]<>0 do;
     until game_over;

   Now if the computer can't keep up with the rate (The clock comes
close to timing out).  The rate is speeded up.

NOTES:
      This unit will not work in protected mode because of changing the clock
rate.  As a result the the f_clk counters will act as s_clk counters.  Such
in a Windows DOS box. etc.
ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
GLOBAL VARIABLES:

      f_clk:     Fast clock counters
      s_clk:     Slow clock counters
      rate:      Current fast clock rate
      cntime:    Reserved counter, Do not modify
  --------------------------------------------------------
      f_userclk,
      s_userclk   : userproc;

    F_USERCLK and S_USERCLK allows you to add your own custom routines
  at each clock interrupt.  Since these procedures are called at every
  interrupt you have to avoid a few things:

      1.  You routine should be fast as possible. Since it will be called
         many times.  if it does to many calculations, it will slow the
         program down.

      2. Do not call any interupts.  You are already in one.

      3. Avoid disk access.  It may or may not work.  Don't try it!

      4. Your routine must be declared as a far procedure with no
         parameters.

  Example:

    Uses spx_tim;

    var
      l,s : longint;

    procedure MyUserClk;  far;
    begin
      inc(l);
    end;


    begin
      l := 0;
      s_userclk := MyUserClk;
      readln; s := l;
      writeln('My function was called ',s,' times while waiting');
    end.

ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
procedure setrate(cycles:word);

  Changes the clock rate of the computer.

  CYCLES:  Number of interrupts to generate per second

ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
procedure wait(seconds,which:integer);

  Wait for a specified number of seconds.

  SECONDS:  Number of seconds to wait;
  WHICH:    Index number of slow clock counter to use.  (0..3)

ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ