     -----------------------------------------------------------
		       Library Reference Guide
		   Blade PSX Programming Libraries
			  (c) Blade, 2001/2
     -----------------------------------------------------------

For further information and to get the latest version, visit:
http://www.blade.ip3.com/
Or e-mail blade@ip3.com

--------
CONTENTS
--------
INTRODUCTION
GRAPHICS ROUTINES
   Initialisation
   Display Buffer Handling
   Image Handling
   Ordering Tables
   Adding Primitives to the OT
      Polygon Primitives
      Text Handling
PAD ROUTINES
SOUND ROUTINES
   Control
   MOD File Playing
   Playing Sounds
OTHER ROUTINES
3D ROUTINES

------------
INTRODUCTION
------------
This file is the Library Reference document for version 1.2 of
the Blade Libraries.

Remember to let me know of any bugs or suggestions at:
blade@ip3.com

The routines are listed in sections relating to their function.

The sample source code that comes with the libraries has examples
of most of the routines here.

-----------------
GRAPHICS ROUTINES
-----------------

--------------------------------------------------------
Initialisation
--------------------------------------------------------
SetVideoMode()
 Set the video mode for graphics processing to PAL or NTSC.

Format
 long SetVideoMode (long mode)

Arguments
 mode - new video mode (0:MODE_NTSC, 1:MODE_PAL, 2:MODE_AUTO)

Return Value
 Previous video mode (0:MODE_NTSC or 1:MODE_PAL)

Notes
 The video mode should be set before any other graphics routines
 are used.
 The default video mode at PSX power on is NTSC.
 MODE_AUTO reads an undocumented area of the PSX BIOS to determine
 the mode - so it may not be 100% correct.
 GsInitGraphQuick (see below) can also be used to set the video mode.
--------------------------------------------------------
GetVideoMode()
 Returns the current video mode.

Format
 long GetVideoMode (void)

Arguments
 none

Return Value
 Current video mode (0:MODE_NTSC or 1:MODE_PAL)
--------------------------------------------------------
ResetGraph()
 Reset the Graphics Processing Unit (GPU).

Format
 void ResetGraph (int mode)

Arguments
 mode - type of reset (0:full reset or 1:warm reset)

Return Value
 none

Notes
 It is not normally necessary to call this routine.
--------------------------------------------------------
void GsInitGraph()
 Initialise the graphics system.

Format
 void GsInitGraph (int x, int y, int intl, int dither, int vram)

Arguments
 x - x screen resolution (256/320/384/512/640)
 y - y screen resolution (240/256)
 intl - sets interlace mode (0:off, 1:on)
 dither - sets dither mode (0:off, 1:on)
 vram - not used (exists for compatibility)

Return Value
 none

Notes
 The 'normal' screen resolution is 320 x 240.
 In most cases it's easier to use GsInitGraphQuick (see below).
 Interlacing should normally be set to 0.
 Dithering shades pixel colours to 'smooth' the display.
--------------------------------------------------------
GsInitGraphQuick()
 Initialise the graphics system automatically.

Format
 void GsInitGraphQuick (int x, int y)

Arguments
 x - x screen resolution (256/320/384/512/640)
 y - y screen resolution (240/256)

Return Value
 none

Notes
 This command replaces the following 3 commands:
 SetVideoMode (MODE_AUTO);
 GsInitGraph (x_res, y_res, 0, 1, 0);
 GsDefDispBuff (0, 0, 0, y_res);
--------------------------------------------------------

--------------------------------------------------------
Display Buffer Handling
--------------------------------------------------------
GsDefDispBuff()
 Defines the Display Buffers used for double buffering.

Format
 void GsDefDispBuff (int x0, int y0, int x1, int y1)

Arguments
 x0, y0 - top left Frame Buffer co-ordinates of buffer 0
 x1, y1 - top left Frame Buffer co-ordinates of buffer 1

Return Value
 none

Notes
 The Display Buffers will have the same width and height as
 the screen (defined by GsInitGraph).
--------------------------------------------------------
GsGetActiveBuff()
 Returns the currently active Display Buffer (0 or 1).

Format
 int GsGetActiveBuff (void)

Arguments
 none

Return Value
 Active Display Buffer number (0 or 1).
--------------------------------------------------------
GsSwapDispBuff()
 Switches the active Display Buffers between 0 and 1.

Format
 void GsSwapDispBuff (void)

Arguments
 none

Return Value
 none

Notes
 If buffer 0 is currently active, buffer 1 will now become
 active (and vice versa).
 To avoid switching buffers as they are being drawn to the
 television, you should run this command after a WaitVSync.
--------------------------------------------------------
 
--------------------------------------------------------
Image Handling
--------------------------------------------------------
LoadImage()
 Send image data from main memory to the Frame Buffer.

Format
 void LoadImage (RECT *rect, u_long *p)

Arguments
 *rect - pointer to destination rectangular area in Frame Buffer
 *p - pointer to address of data in main memory

Return Value
 none

Notes
The data to be sent is raw pixel or CLUT data.
--------------------------------------------------------
LoadTim()
 Send a PSX graphics (TIM) file from main memory to the Frame
 Buffer.

Format
 long LoadTim (TIMHEADER *tim)

Arguments
 *tim - pointer to TIM image data

Return Value
 -1 if not a valid TIM, otherwise 0

Notes
 The TIM image format holds information about where the image
 should be placed in the Frame Buffer, and may contain pixel
 and CLUT data.
--------------------------------------------------------
GetTPage()
 Return the Texture Page (TPage) number of an image.

Format
 u_short GetTPage (int tp, int abr, int x, int y)

Arguments
 tp - image colour depth (0:4-bit, 1:8-bit, 2:15-bit)
 abr - not implemented
 x, y - co-ordinates in the Frame Buffer

Return Value
 Texture Page number (1 - 32)

Notes
 The Frame Buffer is split into 32 virtual areas, or TPages, each
 64 x 256, which are used internally by the GPU.
 GsGetTimInfo can be used to get this information for a TIM image.
--------------------------------------------------------
GetClut()
 Calculates the ID of a Colour Look Up Table (CLUT).

Format
 u_short GetClut (int x, int y)

Arguments
 x, y - co-ordinates of the CLUT in the Frame Buffer

Return Value
 The ID of the CLUT.

Notes
 The GPU refers to CLUT data by an ID number.
 GsGetTimInfo can be used to get this information for a TIM image.
--------------------------------------------------------
GsGetTimInfo()
 Gather information from a TIM file.

Format
 void GsGetTimInfo (TIMHEADER *tim, GsIMAGE *img)

Arguments
 *tim - pointer to TIM image data
 *img - pointer to GsImage variable to hold the information

Return Value
 none

Notes
 The TIM image format contains more information than just
 the pixel and colour data.
 GsGetTimInfo retrieves the following 'extra' information:
 tpage - the texture page number
 px, py - offset of the data within the TPage
 pmode - image colour depth (0:4-bit, 1:8-bit, 2:15-bit)
 clutid - clut position
 w, h - width and height of the data
--------------------------------------------------------

--------------------------------------------------------
Ordering Tables
--------------------------------------------------------
GsDrawOT()
 Tells the GPU to start processing the Ordering Table.

Format
 void GsDrawOT (u_long *pOT)

Arguments
 *pOT - pointer to the start of the Ordering Table

Return Value
 none

Notes
 The Ordering Table is basically an array of unsigned chars
 (or PACKETs) which contains GPU primitive information.
--------------------------------------------------------
GsSetWorkBase()
 Indicate the location of the OT for GsSort... commands.

Format
 void GsSetWorkBase (u_char *pOT)

Arguments
 *pOT - pointer to the start of the Ordering Table

Return Value
 none

Notes
 When using double buffering you define two OTs and
 use GsSetWorkBase to point to the currently active one.
 Although the Ordering Tables are defined as u_char arrays,
 the packets are written as words, so the number of entries
 in the array should be divisible by 4.
--------------------------------------------------------

--------------------------------------------------------
Adding Primitives to the OT
--------------------------------------------------------
Primitives are added to the OT using GsSort... commands.
The syntax of these commands is similar, but the primitive
information passed to them is different.
--------------------------------------------------------
void GsSortClear (int r, int g, int b)
 Adds a 'clear screen' primitive.
 r, g, b - colour to clear screen to
--------------------------------------------------------
void GsSortLine (GsLINE* line)
 Adds a line primitive.

GsLINE attributes
 r, g, b - colour of the line
 x0, y0 - start co-ordinate of the line
 x1, y1 - end co-ordinate of the line
--------------------------------------------------------
void GsSortGLine (GsGLINE* line)
 Adds a gradient shaded line primitive - the colour of the
 line is shaded from a start to an end colour.

GsLINE attributes
 r0, g0, b0 - start colour of the line
 r1, g1, b1 - end colour of the line
 x0, y0 - start co-ordinate of the line
 x1, y1 - end co-ordinate of the line
--------------------------------------------------------
void GsSortDot (GsDOT* dot)
 Adds a single pixel primitive.

GsDot attributes
 r, g, b - colour of the pixel
 x, y - co-ordinates of the pixel
--------------------------------------------------------
void GsSortSprite (GsSPRITE* sprite)
 Adds a sprite primitive.

GsSPRITE attributes
 r, g, b - brightness of sprite colours (0 - 255)
 x, y - top left co-ordinates of the sprite
 w, h - width and height of the sprite
 u, v - offset of the sprite within tpage
 clutid - clutid of sprite
 tpage - tpage of the sprite
 rotate - angle of rotation
 scalex, scaley - scaling factors in x and y directions

Notes
 Sprites are normally made from TIM images, so GsGetTimInfo
 should be used to set most of the attributes of GsSprite.
 
 Rotation & Scaling Notes
  Rotation and scaling is a relatively slow process, so
  if you do not intend to use these functions, initialise
  rotate/scalex/scaley values of the sprite to 4096 (or ONE).
  4096 (or ONE) is the 'unit' value for scaling and rotation.
  For rotation, 360 degrees = ONE, 180 degrees = (ONE/2) etc.
  For scaling, normal size = ONE, double size = (ONE*2) etc.
  If you intend to use either scaling or rotation, you MUST
  intialise all three values (scalex/scaley/rotate) to ONE.
  Rotation and Scaling always takes place around the centre
  of the sprite.
  Remember the sprite's x/y coordinates are the coordinates
  of the top left corner BEFORE scaling and rotation.
  If the scaling of a sprite is too small, or too large, it
  will disappear from the display.
--------------------------------------------------------
void GsSortTile (GsTILE* tile)
 Adds a 'tile' or solid box primitive.

GsTILE attributes
 r, g, b - colour of tile
 x, y - co-ordinates of the tile
 w, h - width and height of the tile
 trans - semi transparency rate (see below)

Notes
 There are 4 different semi transparency rates, and 0 for 'off'. 
 When printing a semi transparent pixel, the colour of the pixel
 and the colour of the pixel beneath it are used in the following
 way:
 B = background colour behind pixel to be printed
 F = foreground colour of pixel
 0 - off
 1 - ( x B) + ( x F)
 2 - (1 x B) + (1 x F)
 3 - (1 x B) - (1 x F)
 4 - (1 x B) + ( x F)
 It's hard to describe how each mode looks - the best way is to run
 a demo - there is one included with the libraries

 The best way to see how the different modes look is to run a demo!

 The semi transparency for a 

 When semi transparency is set for a pixel, the GPU first reads the pixel it
 wants to write to, and then calculates the colour it will write from the 2
 pixels according to the semitransparency mode selected. Processing speed is
 lower in this mode because additional reading and calculating are
 necessary. There are 4 semitransparency modes in the GPU.

 B=  the pixel read from the image in the frame buffer, F = the
 halftransparent pixel

 1 * 0.5 x B + 0.5 x F
 2 * 1.0 x B + 1.0 x F
 3 * 1.0 x B - 1.0 x F
 4 * 1.0 x B +0.25 x F

--------------------------------------------------------

Polygon Primitives
--------------------------------------------------------
Polygons are 3 or 4-sided primitives which are normally for
use by the libraries 3D functions.
You can, of course, use them directly in your own code, too.
They can be Gouraud shaded (or gradated), where each corner
of the polygon has it's own colour, and the GPU shades
the body of the polygon appropriately between the colours.
They can also be textured, where the body of the polygon is
filled with a TIM texture image from the Frame Buffer.
A sprite is basically a textured 4-sided polygon.
For a 3-sided polygon, the corners are numbered like this:
  0
 1 2
For a 3-sided polygon, the corners are numbered like this:
 0 1
 2 3
--------------------------------------------------------
void GsSortPoly3 (GsPOLY3* poly)
 Adds a 3-sided polygon primitive to the OT.

GsPOLY3 attributes
  r, g, b - colour of the polygon
  x0, y0 - co-ordinates of corner 0
  x1, y1 - co-ordinates of corner 1
  x2, y2 - co-ordinates of corner 2
--------------------------------------------------------
void GsSortGPoly3 (GsGPOLY3* poly)
 Adds a 3-sided gradated polygon primitive to the OT.

GsGPOLY3 attributes
 r0, g0, b0 - colour of corner 0
 r1, g1, b1 - colour of corner 1
 r2, g2, b2 - colour of corner 2
 x0, y0 - co-ordinates of corner 0
 x1, y1 - co-ordinates of corner 1
 x2, y2 - co-ordinates of corner 2
--------------------------------------------------------
void GsSortTPoly3 (GsTPOLY3* poly)
 Adds a 3-sided textured polygon primitive to the OT.

GsTPOLY3 attributes
 r, g, b - colour of the polygon
 x0, y0 - co-ordinates of corner 0
 x1, y1 - co-ordinates of corner 1
 x2, y2 - co-ordinates of corner 2
 u0, v0 - offset of texture data corner 0
 u1, v1 - offset of texture data corner 1
 u2, v2 - offset of texture data corner 2
 clutid - clut id of texture data
 tpage - texture page number of texture data
--------------------------------------------------------
void GsSortGTPoly3 (GsGTPOLY3* poly)
 Adds a 3-sided gradated textured polygon primitive to the OT.

GsGTPOLY3 attributes
 r0, g0, b0 - colour of corner 0
 r1, g1, b1 - colour of corner 1
 r2, g2, b2 - colour of corner 2
 x0, y0 - co-ordinates of corner 0
 x1, y1 - co-ordinates of corner 1
 x2, y2 - co-ordinates of corner 2
 u0, v0 - offset of texture data corner 0
 u1, v1 - offset of texture data corner 1
 u2, v2 - offset of texture data corner 2
 clutid - clut id of texture data
 tpage - texture page number of texture data
--------------------------------------------------------
void GsSortPoly4 (GsPOLY4* poly)
 Adds a 4-sided polygon primitive to the OT.

GsPOLY4 attributes
 r, g, b - colour of the polygon
 x0, y0 - co-ordinates of corner 0
 x1, y1 - co-ordinates of corner 1
 x2, y2 - co-ordinates of corner 2
 x3, y3 - co-ordinates of corner 3
--------------------------------------------------------
void GsSortGPoly4 (GsGPOLY4* poly)
 Adds a 4-sided gradated polygon primitive to the OT.

GsGPOLY4 attributes
 r0, g0, b0 - colour of corner 0
 r1, g1, b1 - colour of corner 1
 r2, g2, b2 - colour of corner 2
 r3, g3, b3 - colour of corner 3
 x0, y0 - co-ordinates of corner 0
 x1, y1 - co-ordinates of corner 1
 x2, y2 - co-ordinates of corner 2
 x3, y3 - co-ordinates of corner 3
--------------------------------------------------------
void GsSortTPoly4 (GsTPOLY4* poly)
 Adds a 4-sided textured polygon primitive to the OT.

GsTPOLY4 attributes
 r, g, b - colour of the polygon
 x0, y0 - co-ordinates of corner 0
 x1, y1 - co-ordinates of corner 1
 x2, y2 - co-ordinates of corner 2
 x3, y3 - co-ordinates of corner 3
 u0, v0 - offset of texture data corner 0
 u1, v1 - offset of texture data corner 1
 u2, v2 - offset of texture data corner 2
 u3, v3 - offset of texture data corner 3
 clutid - clut id of texture data
 tpage - texture page number of texture data
--------------------------------------------------------
void GsSortGTPoly4 (GsGTPOLY4* poly)
 Adds a 4-sided gradated textured polygon primitive to the OT.

GsGTPOLY4 attributes
 r0, g0, b0 - colour of corner 0
 r1, g1, b1 - colour of corner 1
 r2, g2, b2 - colour of corner 2
 r3, g3, b3 - colour of corner 3
 x0, y0 - co-ordinates of corner 0
 x1, y1 - co-ordinates of corner 1
 x2, y2 - co-ordinates of corner 2
 x3, y3 - co-ordinates of corner 3
 u0, v0 - offset of texture data corner 0
 u1, v1 - offset of texture data corner 1
 u2, v2 - offset of texture data corner 2
 u3, v3 - offset of texture data corner 3
 clutid - clut id of texture data
 tpage - texture page number of texture data
--------------------------------------------------------

Text Handling
--------------------------------------------------------
FntLoad()
 Load a font to use for printing text on the PSX screen.

Format
 void FntLoad (u_char num, TIMHEADER *font)

Arguments
 num - font number to load (0 - 9)
 *font - pointer to the font's TIM image data

Return Value
 none

Notes
 10 fonts can be loaded at any one time (numbered 0 - 9).
 The built-in font uses 0, but this can be overwritten.
 The TIM image for a new font must be in a certain format:
 Each character in the font must be 8 x 8 pixels.
 The font TIM should be 32 chars wide and 3 chars high (for
 a font with upper and lower case), or 2 chars high (for an
 an upper case only font).
 The characters must be in the correct order - load one of
 the sample fonts into a paint program to see how.
--------------------------------------------------------
FntColor ()
 Sets the colour of a font.

Format
 void FntColor (u_char num, u_char r, u_char g, u_char b)

Arguments
 num - font number (0 - 9)
 r, g, b - colour of font

Return Value
 none

Notes
 This is best used on fonts which are plain white.
--------------------------------------------------------
FntPrint ()
 Print some text on the PSX screen (via the Ordering Table).

Format
void FntPrint (u_char num, int x, int y, char *fmt, ...)

Arguments
 num - number of font to use (0 - 4)
 x, y - where to place it on the screen
 *fmt - pointer to data to print

Return Value
 none

Notes
 This function is basically a standard 'C' printf.
 When printing variables, only these formatting codes are
 allowed: %x (hexadecimal), %d (decimal), %c (character)
 and %s (string).
 Escape sequences like newline (\n) should not be used.
 If you attempt to print any lower-case characters using
 an upper-case only font, the text will be automatically
 converted to upper-case.
--------------------------------------------------------

------------
PAD ROUTINES
------------

--------------------------------------------------------
PadInit ()
 Initialises the pad for use.

Format
 void PadInit (void)

Arguments
 none

Return Value
 none

Notes
 This must be run before you can read the pad.
--------------------------------------------------------
u_long PadRead ()
 Returns the value of data on pad 1.

Format
 u_long PadRead (void)

Arguments
 none

Return Value
 Value of data on pad 1.

Notes
 Only reads digital values.
 Testing for button presses is done with the following defines:
 PAD_SELECT,   PAD_START,
 PAD_UP,       PAD_DOWN,   PAD_LEFT,  PAD_RIGHT,
 PAD_TRIANGLE, PAD_CIRCLE, PAD_CROSS, PAD_SQUARE
 PAD_L1,       PAD_R1,     PAD_L2,    PAD_R2,
 To read pad 2, use PadRead2 (below).
 The value on the pad port is updated every VSync, so
 to read the pad, WaitVSync must called.
 This is normally done anyway in a main game loop.
--------------------------------------------------------
u_long PadRead2 ()
 Returns the value of data on pad 2.

Format
 u_long PadRead2 (void)

Arguments
 none

Return Value
 Value of data on pad 2.

Notes
 Works in the same way as PadRead (above), but returns
 the values of the buttons pressed on pad 2.
--------------------------------------------------------
PadStop ()
 Shut down pad reading.

Format
 void PadStop (void)

Arguments
 none

Return Value
 none

Notes
 Used to 'tidy-up' before exiting a program.
--------------------------------------------------------

--------------
SOUND ROUTINES
--------------

Control
--------------------------------------------------------
SsInit ()
 Initialise the sound system.

Format
 void SsInit (void)

Arguments
 none

Return Value
 none

Notes
 Must be run before any sound functions can be used.
--------------------------------------------------------
SsStop ()
 Shut down the sound system.

Format
 void SsStop (void)

Arguments
 none

Return Value
 none

Notes
 Used to 'tidy-up' before exiting a program.
--------------------------------------------------------
SsGetMVol ()
 Get the master volume of the sound system.

Format
 void SsGetMVol (SndVolume * m_vol)

Arguments
 *m_vol - pointer to SndVolume type variable to hold volume 
	  information.

Return Value
 none

Notes
 The information placed into m_vol is as follows:
 left - left speaker volume (0 - 127)
 right - right speaker volume (0 - 127)
--------------------------------------------------------
SsSetMVol ()
 Set the master volume of the sound system.

Format
 void SsSetMVol (u_short left, u_short right)

Arguments
 left - left speaker volume (0 - 127)
 right - right speaker volume (0 - 127)

Return Value
 none
--------------------------------------------------------
SsGetVoiceMask ()
 Indicate sound voices currently in use.

Format
 u_long SsGetVoiceMask (void)

Arguments
 none

Return Value
 An unsigned long value holding the 'voice in use' data.

Notes
 The right-hand 24 bits of the return value represent
 whether the corresponding voice is in use (1) or not (0).
--------------------------------------------------------

MOD File Playing
--------------------------------------------------------
The Blade Libraries use a (slightly) modified version of
the James Higgs' modified Hitmen PSX MOD player, so any
references to MOD files actually refer to HIT files converted
using MODCONV.

--------------------------------------------------------
InitMod ()
 Set up a MOD (or actually 'HIT') music file for playing.

Format
 void InitMod (u_char num, u_char *modaddr)

Arguments
 num - MOD number to load
 *modaddr - address of MOD file data

Return Value
 none

Notes
 Loads MOD sample data from main memory into the Sound
 Buffer and initialises the MOD.
 A maximum of 5 MODs can be loaded at a time (numbered 0 - 4).
 Remember that the Sound Buffer is only 512k in size, which
 can easily be used up with only a couple of large MODs.
--------------------------------------------------------
PollMod ()
 Play the next line of a MOD (or HIT) music file.

Format
 void PollMod (u_char num)

Arguments
 num - MOD to play

Return Value
 none

Notes
 Must be called once every loop to keep a MOD playing.
--------------------------------------------------------
void PauseMod (u_char num)
 Pauses playback of a MOD.

Format
 void PauseMod (u_char num)

Arguments
 num - MOD to pause

Return Value
 none
--------------------------------------------------------
StartMod ()
 Unpause playback of a paused MOD.

Format
 void StartMod (u_char num)

Arguments
 num - MOD to unpause

Return Value
 none
--------------------------------------------------------
ReStartMod ()
 Re-start a MOD playing from the beginning.

Format
 void ReStartMod (u_char num)

Arguments
 num - MOD number to restart

Return Value
 none
--------------------------------------------------------
GetModVol ()
 Get the current volume of a a MOD

Format
 u_char GetModVol (u_char num)

Arguments
 num - MOD number whose volume is requested

Return Value
 The volume of the MOD (0 - 63)

Notes
 The default volume of a MOD after initialisation is 23.
--------------------------------------------------------
SetModVol ()
 Set the volume of a MOD

Format
 void SetModVol(u_char num, u_char volume)

Arguments
 num - MOD number whose volume is to be set
 volume - the volume to set to (0 - 63)

Return Value
 none

Notes
 The default volume of a MOD after initialisation is 23.
--------------------------------------------------------

Playing Sounds
--------------------------------------------------------
SsVagLoad ()
 Load a PSX sound file (VAG) from main memory into the
 Sound Buffer.

Format
long SsVagLoad (VAGHEADER *vag)

Arguments
 *vag - pointer to VAG data

Return Value
 The address in the Sound Buffer of the VAG.
--------------------------------------------------------
SsPlaySound ()
 Play a sound.

Format
 char SsPlaySound (u_long addr, char voice, int lvol, int rvol)

Arguments
 addr - the Sound Buffer address of the sound data
 voice - the voice to play the sound with (0 - 23 or -1)
 lvol - left speaker volume
 rvol - right speaker volume

Return Value
 The voice used to play the sound.

Notes
 You can specify the voice to be used explicitly with a value
 of 0 - 23, or specify a value of -1, meaning the first
 available voice will be used.
--------------------------------------------------------

--------------
OTHER ROUTINES
--------------

--------------------------------------------------------
rand32 ()
 Generate a random number.

Format
 int rand32 (void)

Arguments
 none

Return Value
 A random integer value ranging from from -2,147,483,647
 to +2,147,483,647.

Notes
 For example, to get a random number between 0 and 255:
 random = (abs(rand32()) & 0x000000ff);
--------------------------------------------------------
srand32 ()
 Re-seed the random number creation process.

Format
 void srand32 (unsigned long seed)

Arguments
 seed - the new seed for random numbers

Return Value
 none
--------------------------------------------------------
WaitVSync ()
 Wait for Vertical Synchronisation to occur.

Format
 void WaitVSync (void)

Arguments
 none

Return Value
 none

Notes
 To ensure an efficient graphics display, Display Buffers
 must be switched just after a VSync occurs.
--------------------------------------------------------

-----------
3D ROUTINES
-----------

--------------------------------------------------------
GsInit3d ()
 Initialise the 3D environment.

Format
 void GsInit3d (void)

Arguments
 none

Return Value
 none

Notes
 Initialises the 3D environment.
 It must be run before any other 3D functions.
 Sets the origin of the 3D system to the centre of the screen.
--------------------------------------------------------
LoadTmd ()
 Converts raw TMD data into the correct format for processing.

Format
 void LoadTmd(TMDHEADER * tmd)

Arguments
 *tmd - pointer to TMD model data

Return Value
 none

Notes
 This function does not move the TMD data in memory - it converts
 internal offsets to the correct format for GTE processing.
--------------------------------------------------------
GsSortObject ()
 Adds 3D model primitives to the Ordering Table.

Format
void GsSortObject (GsOBJECT * object)

Arguments
 * object - pointer to a TMD model previously loaded with LoadTmd.

GsOBJECT attributes
 model - pointer to the TMD model data to use
 x, y, z - the position of the object in space
 rx, ry, rz - the rotation of the object around it's centre

Notes
 One complete revolution of an object means a rotation angle of
 ONE (4096), so to rotate an object in the 'x' direction by
 180 degrees, you would add (ONE/2) to the rx attribute.
 There is currently a limit of 1024 objects on screen.
--------------------------------------------------------
GsSetView ()
 Sets the position and angle for viewing in 3D.

Format
 void GsSetView (GsCAMERA * camera)

Arguments
 * camera - pointer to 'camera' data

GsCAMERA attributes
 x, y, z - the position of the view point in space
 ax, ay, az - the angle of viewing

Notes
 As usual, ONE (4096) represents 360 degrees of angle.
--------------------------------------------------------
