==========================================================================
       ::  RESERVOIR GODS :: ASSEMBLY LIBRARY :: CODED BY MRPINK ::      
==========================================================================

The libraries are based on the use of Constructors and Deconstructors
as in object oriented programming.

Each section of the library is initialised with a constructor, and
at the end is de-initialised with a deconstructor.

To use the assembly library, you must included the main header
file:

	include	reservor.lib

This code initialises memory with an Mshrink(), turns off the mouse
and puts the computer into supervisor mode.

It then initialises all other library modules by calling their
constructor routines.

After this has been done, it jumps to a label called 'start_rg'
- this is equivalent to the Main() function in C.

Place a routine in your code called 'start_rg' this will be 
the first routine called after all the libraries are
initialised. Don't use a Pterm() to quit, just exit this
routine with an rts which will pass control back to
the 'reservor.lib'. All modules will be de-initialised
and the program will quit.

==========================================================================
 BSSDEBUG.LIB
==========================================================================

This is a library for users of BSS Debug.

It patches into the screen handling functions of this debugger
which read Vsetmode() to ascertain the screen mode. Instead
it sets the screen mode currently specified in the screen.lib
library.

==========================================================================
 DISK.LIB
==========================================================================

This library gives you a full suite of disk functions.

There are the standard gemdos functions for opening, reading, writing
and closing files, as well as the seek and FsFirst()/FsNext() calls.

There are also compound routines which allow you to easily save or
load complete files with one call.

==========================================================================
 DSP.LIB
==========================================================================

This library gives you a range of functions for acessing the DSP.

The main Xbios calls are defined here, including locking and unlocking
the DSP and requesting a unique ability. There are functions for
checking and reserving DSP memory, converting LODs to binary and
executing them.

There are functions for transferring packets of data to and from
the DSP in bytes, words and k-words.

==========================================================================
 GEMDOS.LIB
==========================================================================

This defines some useful gemdos routines.

A number of macros are set up for Mshrink(), Super(), Pterm() and
some well used line-a calls.

There are memory allocation routines and the standard gemdos
keyboard input and printing routines.

==========================================================================
 GRAPHICS.LIB
==========================================================================

Has some very basic graphics primitives.

This library includes routines to draw lines, draw shaded lines
and draw lines behind objects. There is also a line calculation
routine based on a modified bresenham algorithm

All the stuff in this library is pretty old and not really worth
using! This is just including for completeness.

==========================================================================
 KEYBOARD.LIB
==========================================================================

Possibly the most useful library here!

This library contains a complete replacement keyboard function that
takes over the system $118 routine and provides all its functionality.

There are functions for checking keys, waiting for a key, full reading
of both joysticks and mouse and also routines to read the jaguar
powerpads.

NOTE:
In the main keyboard handler, in the routine 'rlkb_store_key'
this routine jumps to an absolute address in the operating system
($1132) where the default o/s keyboard handler resides. This is
done to ensure the keyboard is still functional through debuggers
and is for debugging purposes only! This section of code should
be removed when releasing finished programs for distribution as
I cannot be sure that the o/s keyboard handler is at this exact
location on all versions of TOS.

==========================================================================
 MATHS.LIB
==========================================================================

Some geometric routines included here.

This library has functions for 2D and 3D rotations and also the
production of (fully clipped) polygons.

Again most of this code is quite old but it should be of use
to someone!

==========================================================================
 NEMESIS.LIB
==========================================================================

This library contains routines to control the nemesis accelerator.

Even if you don't have a nemesis, this library is useful to ensure
that your productions are compatible with people who own nemesis machines.

There are routines for detecting the nemesis and setting its mode
(off/lo/hi). There are also routines for ensuring that RGB monitors
use the correct dot clock setting to ensure proper screen display
on Nemesis high mode.

==========================================================================
 POLYGON.LIB
==========================================================================

Some very basic polygon routines here!

==========================================================================
 SCREEN.LIB
==========================================================================

A very important library giving you total control over the Videl chip!

The libraries have routines for saving and restoring the current
videl state.

The main functionality of this library is a complete set of screen
setting routines that totally replace the system VsetMode routine
and give you a much wider range of screen modes for all monitors.

The screen setter is very easy to use, you simply pass the X size,
Y size and colour mode of your desired screen mode to the 
'rlsc_set_screen_mode' function and it does the rest!

There are also routines for setting the physical address of the
screen.

==========================================================================
 SOUND.LIB
==========================================================================

This library gives you some basic access to the sound system.

As well as saving and restoring the current sound status, the library
also has functions for toggling the internal speaker on and off,
and setting the output volume (both left and right channels).

==========================================================================
 SPRITE.LIB
==========================================================================

This library has some simple sprite routines.

There are some saving/restoring functions for sprites, the creation
of sprite masks and some blitter based sprite plotting routines.

==========================================================================
 TRACKER.LIB
==========================================================================

This library gives you a full DSP protracker replay with 2 sample chanels.

The replay code was coded by Tat of Avena and this library gives you
a simple interface to his code. There is full protracker replay and
also sample functions. There is a sample queue function which allows
will process a stack of samples in a FIFO manner.

==========================================================================
 VECTOR.LIB
==========================================================================

Contains essential vector saving/restoring functions!

This has routines for saving all the system interrupts and vectors
and restoring them at the end of your program.

There is also a VBL queue handler for routines to be executed every VBL.
There are functions for installing and removing vbl routs and waiting
for vertical blanks.

==========================================================================

These libraries are programmed and maintained by MrPink of ReservoirGods.
Tracker replay coding by Tat of Avena.

If you have any questions about these libraries, do not hesitate to
contact me and I will be glad to help you out:

 mrpink.rg@zetnet.co.uk

 Leon O'Reilly. Cwm Isaf. Abermule. Montgomery. Welshpool. Powys. SY15 6JL

 http://rg.atari.org

==========================================================================
                                                 [c] 1998 Reservoir Gods
==========================================================================
