=========================================
   MATH.KCL
   MATH LIBRARY FOR KAMASOFT C'
=========================================

The library is loaded in the compilation
phase (ExT, G) to the upper part of
memory. A function is used by declaring
the library once with extern "math.kcl";
and each function with extern NAME();
then it is called like an ordinary
function.

FUNCTION LIST
-------------------------

name     bytes  input  output
-------  -----  -----  ------
ABS         10      1       1
COS        114      1       1
FCOS        50      1       1
FSIN        48      1       1
GCD         95      2       1
LCM        143      2       1
MAX         43      2       1
MIN         42      2       1
POW         47      2       1
RND         27      0       1
SGN         13      1       1
SIN        112      1       1
SQRT        29      1       1
UMAX        33      2       1
UMIN        32      2       1

Note: SIN, COS, FSIN and FCOS take the
angle as a byte 0-255 for a full turn (64
= 90 deg, 128 = 180 deg) and return a
fixed-point value where 256 = 1.0, so the
range is -256 to +256.

PARAMETER PASSING
--------------------------
- the last (or only) argument is in
register HL
- all arguments are also in the parameter
block
  pointed to by the system variable 5CB0h
 Each argument takes 2 bytes:
     arg1 = ((5CB0))+0 and +1
     arg2 = ((5CB0))+2 and +3   etc.
- the return value (for functions that
return
  one) is in register HL (the high byte H
  is
  zero for byte results)

=========================================
 ABS - absolute value
=========================================

INPUT : 1 - arg1 n
OUTPUT: 1 - |n|

Returns the absolute value of the signed
16-bit number n (so -5 gives 5). The most
negative value -32768 has no positive
16-bit form and is returned unchanged.

USAGE:
  declare int d;
  extern "math.kcl";
  d=abs(x2-x1);

=========================================
 COS - cosine
=========================================

INPUT : 1 - arg1 angle (0-255)
OUTPUT: 1 - cosine, 256 = 1.0

Returns the cosine of the angle, on the
256 = 1.0 fixed-point scale (range -256
to +256). The angle is a byte: 0-255 is a
full turn, so 0 = 0 deg, 64 = 90 deg, 128
= 180 deg. It is the sine of angle+64
with a small polynomial, so it is fairly
accurate.

USAGE:
  declare int c;
  extern "math.kcl";
  c=cos(0);     /* 256 = 1.0 */
  c=cos(64);    /* 0 */

=========================================
 FCOS - fast cosine
=========================================

INPUT : 1 - arg1 angle (0-255)
OUTPUT: 1 - cosine, 256 = 1.0

A smaller and faster cosine on the same
256 = 1.0 scale and the same 0-255 angle
as COS, but it uses a simpler curve, so
values can be off the true cosine by a
few percent. Use it when speed and size
matter more than precision.

USAGE:
  declare int c;
  extern "math.kcl";
  c=fcos(a);

=========================================
 FSIN - fast sine
=========================================

INPUT : 1 - arg1 angle (0-255)
OUTPUT: 1 - sine, 256 = 1.0

A smaller and faster sine on the same 256
= 1.0 scale and the same 0-255 angle as
SIN, but with a simpler curve, so values
can differ from the true sine by a few
percent. Good for animation where speed
beats accuracy.

USAGE:
  declare int s;
  extern "math.kcl";
  s=fsin(a);

=========================================
 GCD - greatest common divisor
=========================================

INPUT : 2 - arg1 a, arg2 b
OUTPUT: 1 - gcd(a,b)

Returns the greatest common divisor of
the two unsigned numbers a and b, using
the fast binary (Stein) method. gcd(x,0)
is x and gcd(0,0) is 0. Useful to reduce
a fraction or as a step of LCM.

USAGE:
  declare int g;
  extern "math.kcl";
  g=gcd(12,18);   /* 6 */

=========================================
 LCM - least common multiple
=========================================

INPUT : 2 - arg1 a, arg2 b
OUTPUT: 1 - lcm(a,b) (low 16 bits)

Returns the least common multiple of a
and b, worked out as a/gcd(a,b)*b. The
result is kept modulo 65536, so a
multiple that does not fit in 16 bits
wraps. lcm(x,0) is 0.

USAGE:
  declare int m;
  extern "math.kcl";
  m=lcm(4,6);     /* 12 */

=========================================
 MAX - larger of two (signed)
=========================================

INPUT : 2 - arg1 a, arg2 b
OUTPUT: 1 - the larger (signed)

Returns the larger of the two signed
numbers a and b (-32768 to 32767). For
values treated as unsigned (0-65535) use
UMAX.

USAGE:
  declare int m;
  extern "math.kcl";
  m=max(-3,5);    /* 5 */

=========================================
 MIN - smaller of two (signed)
=========================================

INPUT : 2 - arg1 a, arg2 b
OUTPUT: 1 - the smaller (signed)

Returns the smaller of the two signed
numbers a and b (-32768 to 32767). For
values treated as unsigned (0-65535) use
UMIN.

USAGE:
  declare int m;
  extern "math.kcl";
  m=min(-3,5);    /* -3 */

=========================================
 POW - integer power
=========================================

INPUT : 2 - arg1 base, arg2 exp
OUTPUT: 1 - base^exp (low 16 bits)

Returns base raised to the power exp by
repeated multiplication. Both are 16-bit
and only the low 16 bits of the result
are kept, so it wraps on overflow. exp =
0 gives 1.

USAGE:
  declare int p;
  extern "math.kcl";
  p=pow(2,10);    /* 1024 */

=========================================
 RND - pseudo-random number
=========================================

INPUT : 0
OUTPUT: 1 - random number (0-65535)

Returns a pseudo-random 16-bit number. It
mixes the ROM SEED (5C76h) with the
FRAMES counter (5C78h), scrambles the
result and stores it back in SEED, so
each call gives a new value. For a number
0..n-1 use rnd()%n; for 1..6 use
rnd()%6+1.

USAGE:
  declare int r;
  extern "math.kcl";
  r=rnd()%6+1;    /* a dice roll */

=========================================
 SGN - sign of a number
=========================================

INPUT : 1 - arg1 n
OUTPUT: 1 - -1, 0 or 1

Returns the sign of the signed number n:
0FFFFh (-1) when n is negative, 0 when n
is zero, and 1 when n is positive.

USAGE:
  declare int s;
  extern "math.kcl";
  s=sgn(x);       /* -1, 0 or 1 */

=========================================
 SIN - sine
=========================================

INPUT : 1 - arg1 angle (0-255)
OUTPUT: 1 - sine, 256 = 1.0

Returns the sine of the angle on the 256
= 1.0 fixed-point scale (range -256 to
+256). The angle is a byte: 0-255 is a
full turn, so 0 = 0 deg, 64 = 90 deg, 128
= 180 deg, 192 = 270 deg. A small
polynomial gives a result accurate to
about one part in 256.

USAGE:
  declare int s;
  extern "math.kcl";
  s=sin(64);    /* 256 = 1.0 */
  s=sin(192);   /* -256 = -1.0 */

=========================================
 SQRT - integer square root
=========================================

INPUT : 1 - arg1 n (0-65535)
OUTPUT: 1 - floor of the square root

Returns the integer (rounded down) square
root of the unsigned number n, a value
0-255 (sqrt(65535) = 255). For a perfect
square the result is exact.

USAGE:
  declare int r;
  extern "math.kcl";
  r=sqrt(100);    /* 10 */

=========================================
 UMAX - larger of two (unsigned)
=========================================

INPUT : 2 - arg1 a, arg2 b
OUTPUT: 1 - the larger (unsigned)

Returns the larger of a and b treated as
unsigned numbers (0-65535). For signed
values use MAX.

USAGE:
  declare int m;
  extern "math.kcl";
  m=umax(a,b);

=========================================
 UMIN - smaller of two (unsigned)
=========================================

INPUT : 2 - arg1 a, arg2 b
OUTPUT: 1 - the smaller (unsigned)

Returns the smaller of a and b treated as
unsigned numbers (0-65535). For signed
values use MIN.

USAGE:
  declare int m;
  extern "math.kcl";
  m=umin(a,b);

=========================================
 End
