==
3D
==

SPIN3D
  Description   : Rotates a 3D object.
  Calling format: ROTATE[YAW,PITCH]
                      YAW   = degrees to rotate around Y-axis.    Y Z
                      PITCH = degrees to rotate around X-axis.    |/
                                                                  +-X
  Return value  : None.
  Special notes : The included procedure SETUP sets up the object.  Read
                      its documentation for more information.
                  This is more of a demonstration program than a procedure,
                      but I've included it anyway because of its usefulness.
  Author        : Scott Southurst
                  maverick@deakin.edu.au


====
AMAL
====

_AMAL_BOUNCING_BALLS
  Description   : Creates bouncing balls with AMAL.  This only sets up the
                      AMAL programs; you need to write the main loop
                      yourself.
  Calling format: _AMAL_BOUNCING_BALLS[NUM,GROUND,XLEFT,XRIGHT]
                      NUM    = number of balls to create
                      GROUND = Y-coordinate of "ground"
                      XLEFT  = X-coordinate of left "wall"
                      XRIGHT = X-coordinate of right "wall"
  Return value  : None.
  Special notes : The boundaries for the balls are not set in stone; they
                      can be changed with the Amreg() function, as follows:
                          GROUND = Amreg(2)
                          XLEFT  = Amreg(0)
                          XRIGHT = Amreg(1)
                      So, if you use other AMAL routines in the same
                      program, be sure not to use these three registers.
  Author        : Mark Baker
                  ukrbake@prl.philips.co.uk

_AMAL_FIREWORKS
  Description   : Creates fireworks in AMAL.  The procedure includes the
                      running loop; you can change or remove it if you need
                      to.
  Calling format: _AMAL_FIREWORKS[NUM]
                      NUM = number of particles for explosion
  Return value  : None.
  Special notes : 8 particles are always created, even if you specify a
                      number less than 8 in the procedure call.
  Author        : Mark Baker
                  ukrbake@prl.philips.co.uk


====
Data
====

CAPS_NAME
  Description   : Capitalises a name correctly; e.g. "jean-luc picard" ->
                      "Jean-Luc Picard".
  Calling format: CAPS_NAME[NAME$]
                      NAME$ = Name to capitalise.
  Return value  : A string containing the name, correctly capitalised.
  Author        : Gavin Segal
                  cs922044@red.ariel.cs.yorku.ca

QUICKSORT
  Description   : Performs a "Quick Sort" on an array.
  Calling format: QUICKSORT[NO,ST]
                      NO = Number of array elements.
                      ST = First array element (0 or 1).
  Return value  : None.
  Special notes : The procedure needs to be modified somewhat to fit your
                      specific program.  Places that need to be changed are
                      so marked in the procedure.
  Author        : ???

REF_ASCII
  Description   : Converts a number into a 3-character ASCII representation.
                      Numbers in the range 0 to 16,581,374 can be converted.
  Calling format: REF_ASCII[N]
                      N = the number to be converted
  Return value  : A string containing the 3-character representation of N.
  Author        : Gavin Segal
                  cs922044@red.ariel.cs.yorku.ca

REF_NUMBER
  Description   : Converts a 3-character ASCII representation of a number
                      (see REF_ASCII) back to the original number.
  Calling format: REF_NUMBER[N$]
                      N$ = the 3-character string representing the number
  Return value  : An integer, the number represented by N$.
  Author        : Gavin Segal
                  cs922044@red.ariel.cs.yorku.ca


========
Graphics
========

_FAST_ELLIPSE
  Description   : Draws an ellipse using only fixed-point math.
  Calling format: _FAST_ELLIPSE[XC,YC,RX,RY,_FILLED]
                      XC,YC - center of ellipse
                      RX,RY - X and Y radii (for a circle, RX=RY)
                      _FILLED - whether ellipse should be filled or not
  Return value  : None.
  Special notes : Requires procedure _4WS (included in file).
  Author        : Michael Sikorsky
                  sikorsky@bode.ee.ualberta.ca

_FAST_LINE
  Description   : Draws a line using only fixed-point math.
  Calling format: _FAST_LINE[X1,Y1,X2,Y2]
                      X1,Y1 - coordinates of the first point
                      X2,Y2 - coordinates of the second point
  Return value  : None.
  Author        : Michael Sikorsky
                  sikorsky@bode.ee.ualberta.ca

MULTI_LINE
  Description   : Draws a multi-colour line.
  Calling format: MULTI_LINE[X1,Y1,X2,Y2,NUM,LIM]
                      X1,Y1 - starting coordinates
                      X2,Y2 - ending coordinates
                      NUM   - starting colour
                      LIM   - ending colour
  Return value  : None.
  Special notes : When the colour number reaches LIM, it returns to 1.
  Author        : Mark Baker
                  ukrbake@prl.philips.co.uk

PALETTE_PROCS
  Description   : Five procedures to store, set, and fade the colours of a
                      screen.
  Calling format: _PUTPAL[N,_START,_END] - store screen colours in palette
                      N      = Palette number
                      _START = First colour to store
                      _END   = Last colour to store
                  _GETPAL[N,_START,_END] - set screen colours from palette
                      N      = Palette number
                      _START = First colour to set
                      _END   = Last colour to set
                  _FADEPALxx[T,N] - fade first 8, 16, or 32 colours to
                                    palette N (xx=8, 16, or 32)
                      T = VBLs between colour changes
                      N = Palette number
  Return value  : None for all procedures.
  Special notes : The procedures require that your program set up an array
                      PAL() at the beginning of the program; read the file
                      for details.
  Author        : Seumas McNally
                  sfmcnally@BIX.com

_PALETTE_TO_ANTIQUE
  Description   : Converts palette to "antique photograph".  Hard to
                      describe; you'll have to see it yourself.
  Calling format: _PALETTE_TO_ANTIQUE[_SCREEN]
                      _SCREEN - the screen number to affect.
  Return value  : None.
  Author        : Michael Sikorsky
                  sikorsky@bode.ee.ualberta.ca

_PALETTE_TO_BW
  Description   : Converts palette to black and white.
  Calling format: _PALETTE_TO_BW[_SCREEN]
                      _SCREEN - the screen number to affect.
  Return value  : None.
  Author        : Michael Sikorsky
                  sikorsky@bode.ee.ualberta.ca

_PALETTE_TO_NEGATIVE
  Description   : Converts palette to "negative" colours (e.g. black<->white)
  Calling format: _PALETTE_TO_NEGATIVE[_SCREEN]
                      _SCREEN - the screen number to affect.
  Return value  : None.
  Author        : Michael Sikorsky
                  sikorsky@bode.ee.ualberta.ca

PICKCOLOURS
  Description   : This procedure returns the numbers of the darkest, the mid
                      brightest and brightest colour of the current screen.
  Calling format: PICKCOLOURS
  Return value  : A string. The string contains the numbers mentioned
                      above, separated by colons (i.e. "1:21:10").
  Special notes : The file contains a procedure called Brightness that this
                      procedure needs, so do not remove.
                      There's a test programme included.
                      There's a guide included.
  Author        : Branko Collin
                  u249026@vm.uci.kun.nl

SBOX
  Description   : Draws a 3D-looking box with rounded corners and a dark
                      outline.  Good for drawing gadgets, particularly in
                      conjunction with TBOX.
  Calling format: SBOX[X1,Y1,X2,Y2,IN]
                      (X1,Y1),(X2,Y2) = coordinates for the box
                      IN = True if the box should be "depressed", False
                               otherwise.
  Return value  : None.
  Special notes : To achieve the 3D-effect, the procedure uses colours 0 and
                      N-1 (for an N-colour screen).  It assumes that colour
                      0 will be dark and colour N-1 will be bright.  Also,
                      the procedure draws a dotted line for the "inner
                      outline"; you need to set the background ink colour
                      to some colour different from 0 and N-1 in intensity.
  Author        : Paul Hickman
                  ph@doc.ic.ac.uk

_SEPARATE_RGB
  Description   : Filters colours in picture.
  Calling format: _SEPARATE_RGB[_SCREEN,X]
                      _SCREEN - the screen number to affect.
                      X       - the "filter" colour:
                                  1 - Red
                                  2 - Green
                                  3 - Blue
                                  4 - Magenta
                                  5 - Yellow
                                  6 - Purple
  Return value  : None.
  Author        : Michael Sikorsky
                  sikorsky@bode.ee.ualberta.ca

SIMPLEARC
  Description   : This routine draws an arc, where arc is defined as part
                      of an ellipse (alas, no fancy bezier curves).
  Calling format: SIMPLEARC[X,Y,RX,RY,_START_DEG,_TOT_DEG]
                      X,Y           = centre coordinates
                      RX,RY         = radii for x and y directions
                      _START_DEG    = starting point in degrees
                      _TOT_DEG      = total length in degrees
  Return value  : None.
  Special notes : There's a test programme included.
                      Tested on an A500, .5 fast, .5 chip, 2nd drive.
                      Please, do try and improve it.
  Author        : Branko Collin
                  u249026@vm.uci.kun.nl

TBOX
  Description   : Draws a 3D-looking box.
  Calling format: TBOX[X1,Y1,X2,Y2,IN]
                      (X1,Y1),(X2,Y2) = coordinates for the box
                      IN = True if the box should be "depressed", False
                               otherwise.
  Return value  : None.
  Special notes : To achieve the 3D-effect, the procedure uses colours 0 and
                      N-1 (for an N-colour screen).  It assumes that colour
                      0 will be dark and colour N-1 will be bright.
  Author        : Paul Hickman
                  ph@doc.ic.ac.uk


=====
Icons
=====

_MAKEMASK
  Description   : Creates a mask for an icon, using a given colour as
                      "transparent".
  Calling format: _MAKEMASK[_SCREEN,_COLOUR,TEMP1,TEMP2,X1,Y1,X2,Y2,_ICON]
                      _SCREEN     - Screen that icon is displayed on
                      _COLOUR     - Colour to make transparent
                      TEMP1,TEMP2 - Two temporary (unused) screens
                      (X1,Y1)     - Upper-left corner of icon
                      (X2,Y2)     - Lower-right corner of icon
                      _ICON       - Icon number to create mask for
  Return value  : None.
  Special notes : Can be changed to work with bobs instead of icons; just
                      just change "Icon Base" to "Sprite Base".
                  Assumes that the icon exists and has a mask.  A typical
                      calling sequence would be:

                      Get Icon N,X1,Y1 To X2,Y2
                      Make Icon Mask N
                      _MAKEMASK[Screen,_COLOUR,TEMP1,TEMP2,X1,Y1,X2,Y2,N]

  Author        : Michael Sikorsky
                  sikorsky@bode.ee.ualberta.ca


=====
Other
=====

_DATECONVERT
  Description   : Converts a date in the format "YYMMDD" (e.g. "930911") into
                      a more human-readable format.
  Calling format: _DATECONVERT[DATE$,FORMAT]
                      DATE$  = the date in YYMMDD format
                      FORMAT = the format to return the date in.  See the
                                   procedure's documentation for details.
  Return value  : The date, as a string, in the specified format.
  Author        : Geoffrey Carman
                  cs922012@ariel.cs.yorku.ca

NEW_INPUT
  Description   : Extended input routines for strings and real numbers.
                  The routines only accept characters legal for the input
                  type and allow a limit on the length of the input.
  Calling format: S_INPUT[L,DEFAULT$]
                      L - Input field length
                      DEFAULT$ - String that is shown at the
                       start of the proc and taken as input
                       if the user just hits RETURN.
                  R_INPUT[L,DEFAULT#]
                      L - Input field length
                      DEFAULT# - Number that is shown at the
                          start of the proc and taken as input
                          if the user just hits RETURN.
  Return value  : String or real number with user input.
  Special notes : Includes a test program.
  Author        : Christian Mumenthaler
                  mumi@molbio.ethz.ch

_TO_NTSC
  Description   : Switches display to NTSC mode.
  Calling format: _TO_PAL
  Return value  : None.
  Special notes : Requires ECS or better chipset.
  Author        : Michael Sikorsky
                  sikorsky@bode.ee.ualberta.ca

_TO_PAL
  Description   : Switches display to PAL mode.
  Calling format: _TO_PAL
  Return value  : None.
  Special notes : Requires ECS or better chipset.
  Author        : Michael Sikorsky
                  sikorsky@bode.ee.ualberta.ca


============
ScreenEaters
============

[See the file ScreenEaters/SE.doc for more information.  Note that no screen]
[eaters return any values.                                                  ]

SEB_4LEAFWIPE
  Description   : Wipes the screen from the four sides inward.
  Calling format: SEB_4LEAFWIPE[SCR,C]
  Author        : Paul Hickman
                  ph@doc.ic.ac.uk

SEB_DIAGONAL_WIPE
  Description   : Wipes the screen in a circular pattern.
  Calling format: SEB_DIAGONAL_WIPE[SCR,C]
  Author        : Paul Hickman
                  ph@doc.ic.ac.uk

SEB_HSTRIPS
  Description   : Divides the screen into horizontal strips which then fold
                      in on each other.
  Calling format: SEB_HSTRIPS[SCR,C,N,D]
                      N = Number of strips; must be a factor of Screen Height
                      D = Delay in VBLs
  Author        : Paul Hickman
                  ph@doc.ic.ac.uk

SEB_PATTERN_WIPE
  Description   : Uses a pattern to clear the screen.
  Calling format: SEB_PATTERN_WIPE[SCR,C]
  Author        : Paul Hickman
                  ph@doc.ic.ac.uk

SEB_ROLL
  Description   : "Rolls" the screen up, down, left, or right.
  Calling format: SEB_ROLL[SCR,C,TMPSCR,RW,D]
                      TMPSCR = Temporary screen number
                      RW     = Width of "roll".  Should be less than 1/3 the
                                   size of the screen in the direction of
                                   the roll.  In other words, when rolling
                                   left or right, RW should be less than
                                   Screen Width/3; when rolling up or down,
                                   should be less than Screen Height/3.
                      D      = Roll direction: 0=up, 1=down, 2=left, 3=right
  Special notes : The original submission consisted of four procedures,
                      ROLLUP, ROLLDOWN, ROLLLEFT, and ROLLRIGHT.  For ease
                      of use I wrote ROLL.  If you only need one or two
                      directions of rolling, you can just copy the procedures
                      you need and call them directly.
  Author        : Paul Hickman, based on code from Seumas McNally
                  PH - ph@doc.ic.ac.uk; SM - sfmcnally@BIX.com
                  ROLL procedure by Andrew Church (95ACHURCH@vax.mbhs.edu)

SEB_TILES
  Description   : Clears the screen by removing blocks.
  Calling format: SEB_TILES[SCR,C,BS,SPEED]
                      BS    = size of blocks (multiples of 8 work best)
                      SPEED = Delay in VBLs
  Author        : Derek Waters
                  n1djwate@aelmg.adelaide.edu.au

SEB_TRICLEAR
  Description   : Clears the screen by erasing triangular sections.
  Calling format: SEB_TRICLEAR[SCR,C,N,D]
                      N = size of triangles; must be a factor of both
                              Screen Width and Screen Height
                      D = Delay in VBLs
  Author        : Paul Hickman
                  ph@doc.ic.ac.uk

SEB_VSTRIPS
  Description   : Divides the screen into vertical strips which then fold in
                      on each other.
  Calling format: SEB_VSTRIPS[SCR,C,N,D]
                      N = Number of strips; must be a factor of Screen Width
                      D = Delay in VBLs
  Author        : Paul Hickman
                  ph@doc.ic.ac.uk

SED_EATZOOM
  Description   : Divides the screen into tiles which then collapse inward
                      upon themselves.
  Calling format: SED_EATZOOM[SCR,C,TMPSCR,TX,TY,ZMODE]
                      TMPSCR = temporary screen number
                      TX,TY  = size of tiles.  TX should be a factor of
                                   Screen Width; TY, of Screen Height.
                      ZMODE  = 1: tiles cleared from top to bottom
                               2: tiles cleared randomly
                               3: tiles cleared in a circular pattern.
  Author        : Paul Hickman, based on code from Seumas McNally
                  PH - ph@doc.ic.ac.uk; SM - sfmcnally@BIX.com

SES_ANGLEWIPE
  [ The original version of this procedure had a bug that would ]
  [ consistently crash the computer.  I fixed the bug.  --AC    ]
  Description   : Wipes the screen in a quarter-circle pattern, using one
                      corner as the center of the circle.
  Calling format: SES_ANGLEWIPE[SCR,C,CORNER]
                      CORNER = corner to start from: 1=TL, 2=BL, 3=BR, 4=TR
  Author        : Derek Waters
                  n1djwate@aelmg.adelaide.edu.au

SES_EATZOOM
  Description   : Divides the screen into tiles which then collapse inward
                      upon themselves.
  Calling format: SED_EATZOOM[SCR,C,TMPSCR,TS,ZMODE]
                      TMPSCR = temporary screen number
                      TS     = size of tiles (X and Y).  Should be a factor
                                   of Screen Width and Screen Height.
                      ZMODE  = 1: tiles cleared from top to bottom
                               2: tiles cleared randomly
                               3: tiles cleared in a circular pattern.
  Author        : Paul Hickman, based on code from Seumas McNally
                  PH - ph@doc.ic.ac.uk; SM - sfmcnally@BIX.com

SES_SAND
  Description   : This one is hard to describe.  It's (apparently) supposed
                      to be a sandglass-effect, but it looks like a big
                      triangle going up the screen.
  Calling format: SES_SAND[SCR,C,SPEED]
                      SPEED = Delay in VBLs
  Author        : Derek Waters
                  n1djwate@aelmg.adelaide.edu.au


========
ScreenFX
========

MOVING_RAINBOWS
  Description   : Creates moving rainbows.  This is actually a set of four
                      procedures that set up, display, animate, and remove
                      the rainbows.
  Calling format: SET_MOVING_RAINBOWS[AMP,POS,SPC,AFFECTCOL,SPEED]
                      AMP       = amplitude of movement (_RAIN_AMP)
                      POS       = central rainbow position (_RAIN_POS)
                      SPC       = spacing between rainbows (_RAIN_SPACE)
                      AFFECTCOL = colour number to affect
                      SPEED     = speed of rainbows (_RAIN_SPEED)
                  _DISPLAY_RAINBOWS[SPEED,SPC]
                      SPEED     = speed at which the rainbows appear
                      SPC       = as above
                  _ANIMATE_RAINBOWS
                  _REMOVE_RAINBOWS[SPEED]
                      SPEED     = speed at which the rainbows disappear
  Return value  : None for all procedures.
  Special notes : Due to the unusual nature of this submission, I have
                      included an example program with the procedures.  The
                      program includes the necessary variable initialization
                      for the procedures.  Where I have listed a variable
                      name in parentheses in the "Calling format" section,
                      the variable of that name in the example program will
                      have a comment providing more information about that
                      variable.  DO NOT change the names of the variables;
                      they are needed by the rainbow procedures!
  Author        : Mark Baker
                  ukrbake@prl.philips.co.uk


=======
Screens
=======

RDZONE
  Description   : Reads the coordinates of a screen zone into global
                      variables X1,Y1,X2,Y2 without changing the current
                      screen.  If the zone does not exist, the variables
                      remain unchanged.
  Calling format: RDZONE[SCRN,Z]
                      SCRN = Screen number
                      Z    = Zone number
  Return value  : True if the zone existed, FALSE if it did not.
  Author        : Paul Hickman
                  ph@doc.ic.ac.uk

RDZONE2
  Description   : Reads the coordinates of a screen zone into global
                      variables X1,Y1,X2,Y2 without changing the current
                      screen.  If the zone does not exist, an "Illegal
                      function call" error is generated.
  Calling format: RDZONE2[SCRN,Z]
                      SCRN = Screen number
                      Z    = Zone number
  Return value  : None.
  Author        : Paul Hickman
                  ph@doc.ic.ac.uk


======
System
======

_DOSERROR
  Description   : Returns the AmigaDOS error message for an IoErr() error
                      code.
  Calling format: _DOSERROR[ERR]
                      ERR - IoErr() (Doscall(-132)) return value.
  Return value  : String that contains the error text.
  Special notes : This procedure handles all errors for AmigaDOS 2.1.  Use
                      of the AmigaDOS 2.04 Fault() function is not yet
                      implemented.
  Author        : Andrew Church
                  95ACHURCH@vax.mbhs.edu

_GET_ARGS
  Description   : Processes Command Line$ to determine CLI arguments.
  Calling format: _GET_ARGS[CMDLN$,_MAXARGC]
                      CMDLN$   = String of CLI arguments taken from
                                     Command Line$
                      _MAXARGC = Maximum number of arguments you'd expect
  Return value  : Number of arguments found.  Also, stores the arguments
                      in ARGV$() which is shared.
  Special notes : Includes a test program.
  Author        : Michael Cox
                  aj639@Cleveland.Freenet.EDU

MAKE_RAM
  Description   : Attempts to access the RAM disk.  This results in the RAM
                      disk being initialised if it was not already.
  Calling format: RAM_DISK
  Return value  : None.
  Author        : Paul Hickman
                  ph@doc.ic.ac.uk


====
Text
====

MESSAGEBOX
  Description   : Creates a colourful message box.  This is actually two
                      separate procedures, one to display the message box
                      and one to clear it.
  Calling format: M_DISP[CLR,MESSAGE$]
                      CLR      = Basic colour to use.  This should be one
                                     of $001,$010,$011,$100,$101,$110,$111.
                      MESSAGE$ = Message to display.
                  M_CLEAR
  Return value  : None for both procedures.
  Special notes : You must have a 32- or 64-colour screen opened before the
                      message box is displayed.
  Author        : Mark Baker
                  ukrbake@prl.philips.co.uk

OPENFONT
  Description   : Opens/closes a font.
  Calling format: OPENFONT[NAME$,SIZE,_REM]
                      NAME$ - Name of the font.  ".font" extension is
                                optional.
                      SIZE  - Font size.
                      _REM  - 0 to open the font, nonzero to close it.
  Return value  : Font number (to be used with Set Font).
  Author        : Andrew Church
                  95ACHURCH@vax.mbhs.edu

_SHADOW_TXT
  Description   : Writes shadowed text to the current screen.
  Calling format: _SHADOW_TXT[X,Y,_FG,_BG,_TXT$]
                      X,Y   - coordinates for text (like Text command)
                      _FG   - foreground colour
                      _BG   - background colour
                      _TXT$ - text to write
  Return value  : None.
  Author        : Michael Sikorsky
                  sikorsky@bode.ee.ualberta.ca


