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

For further information, or to get the latest versions, visit:
http://www.blade.ip3.com/
Or e-mail me at:
blade@ip3.com

--------
CONTENTS
--------
INTRODUCTION
PROCESS OVERVIEW
PSX HARDWARE OVERVIEW
IMAGES
ORDERING TABLES
DOUBLE BUFFERING
FILE FORMATS
EXAMPLES
ACKNOWLEDGEMENTS

------------
INTRODUCTION
------------
If you've ever wanted to write your own Playstation (PSX) game
then you've come to the right place, and downloaded the right
software!

Sony started the ball rolling when they launched the 'Net
Yaroze' - a black, programmable PSX.
It was expensive, sold in limited numbers, and a condition
of membership was that you wouldn't share any information
with non members. Nevertheless it proved popular.

Around the same time, some innovative hackers managed to
create their own homebrew Yaroze, using a standard PSX
with a Datel Action Replay (AR) and PC Comms Card.
By re-flashing the AR ROM, and writing some PC utilities,
they were able to compile and run their own code on the PSX.
This is the method still used.
More info on the required hardware and software, where to
get it and how to set it up can be found at:
http://www.psxdev.ip3.com

The problem with the homebrew set up was getting hold of
any C libraries.
The Yaroze (and professional PsyQ) libraries can be found on
various internet sites, but their legality is dubious.

The 'Rob Withey/James Higgs' libraries were released a couple of
years ago, and they inspired me to have a go at writing my own.
I began writing the Blade Libraries in assembler, as Rob had, but
it proved hard to keep on top of things, so I re-wrote some
sections in C.
The re-written code turned out to be just as fast and more compact
than the assembler - perhaps not a good reflection on my asm skills!
As expected, the source was easier to update and maintain, too.
Until then I had just been messing around to see what I could learn
without really thinking about releasing them.
As things progressed, I decided that other people might find them
useful.

Several months later, here they are...
They work with the free MIPS GCC cross-compiler created by 'co' from
Japan. The compiler is included in the Blade Libraries download.
I've also written a few utilities to simplify set-up, compilation
and coding.

----------------
PROCESS OVERVIEW
----------------
The PSX doesn't have a keyboard or hard disk, so programming directly
is difficult, therefore a PC is used to edit and compile the
source code, and to create any graphics and sound data.
The compiled PSX executable is sent to the PSX to be run.

The Blade Libraries are an extension to standard C, so any experience
of C will help a lot.
Having said that, with a good book on C, there's no reason why you
can't learn C while writing a Playstation game.
There are source code examples with the Blade Libraries, which
should provide a good learning path.

---------------------
PSX HARDWARE OVERVIEW
---------------------
There are some Playstation specific concepts which are worth taking
some time to understand before jumping in and coding.
The main CPU is a MIPS R3000 with 2Mb of memory, normally referenced
through addresses 0x80000000 - 0x801fffff.
As well as the main CPU, the PSX has several co-processors to handle
graphics and sound processing functions:

GPU - Graphics Processing Unit
------------------------------
The GPU handles graphics processing, including on-screen display.
It has it's own separate 1Mb memory, known as the Frame Buffer or
video RAM.
This is best thought of as a 1024x512 '2-dimensional' memory space.

Within the Frame Buffer you define an area to be the Display Buffer.
This area is where the GPU prepares the display before sending it to
the television.
The Display Buffer can be located anywhere in the Frame Buffer, but it
makes sense to locate in the top left of the Frame Buffer (0,0).
The width and height of the Display Buffer should be set to the screen
resolution you require, commonly 320x240.

This diagram illustrates the Frame Buffer and Display Buffer:

                         Frame Buffer
(0,0)  +--------------+------------------------------+
       |      320     |                              |
       |              |                              |
       |   Display 240|                              |
       |   Buffer     |                              |
       |              |                              |
       +--------------+                              |
       |                                             |
       |                                             |
       |                                             |
       |                                             |
       |                                             |
       |                                             |
       +---------------------------------------------+(1023,511)

The remainder of the Frame Buffer is used to store sprite and texture
data (in the PSX's TIM graphics format).

The main system CPU cannot see the Frame Buffer, and it can only be
accessed via the GPU.
To display a sprite on the screen, the texture data must first be loaded
from main memory into the Frame Buffer, from where the GPU can display it.
Don't worry if this sounds confusing - working through some
of the practical examples will clarify things.

GTE - Geometry Transfer Engine
------------------------------
The Geometry Transfer Engine carries out matrix and vector calculations
that are essential for 3D graphics programming.
You won't normally be programming it directly, so you don't have to
know much about its innards.

SPU - Sound Processing Unit
---------------------------
The SPU handles the sound processing of the PSX's 24 voices.
In a similar way to the GPU it has it's own independent 512k memory,
known as the Sound Buffer.
Again, because the main CPU cannot see the Sound Buffer memory,
you must upload sample data from main memory to the Sound Buffer
before it can be played.

PAD
---
The Blade Libraries currently support only digital reading of pads.
There is currently no facility to read analogue values, or vibrate.
The values of the pad readings are only updated during VSync.
You must remember this if, for example, you include a pause routine in
your game.

This is a simplified overview of the Playstation hardware, but it
should be enough to get you started writing a game with the Blade
Libraries.

------
IMAGES
------
The PSX stores images in the TIM format.

TIM images can have different colour depths, depending on the
number of colours required:
4-bit (16 colours)
8-bit (256 colours)
16-bit (32768 colours - the top bit is used for transparency)
24-bit - used for static display only, not supported

For 16-bit images, each pixel holds it's own colour data, and
the data is stored 'uncompressed' in the Frame Buffer, i.e. the
width and height of the image stored in the Frame Buffer is the
same as the width and height of the image when it's displayed.

For 4/8-bit images, the colour and pixel data is separate, with
the pixel data being stored in a 'compressed' format.
The height of the pixel data is the same as the displayed image.
For 8-bit images, the pixel data is half the width of the displayed
image, and for 4-bit images the pixel data is a quarter the width.
Decompression is handled on the fly by the GPU.

As mentioned, the colour data is stored separately from the pixel
data, in Color Look Up Tables (CLUTs), which are basically palettes.
4-bit CLUTs are 16x1 in the Frame Buffer, and 8-bit CLUTs are 256x1
in the Frame Buffer.

Again, don't worry too much about all this - normally you just
convert your image to a TIM, load it to the Frame Buffer, then
display it as required.
This is just background information which you may, or may not,
find useful.
The main point, maybe, is that 16-bit images are simpler, but use
more space in the Frame Buffer.

---------------
ORDERING TABLES
---------------
Ordering Tables (OTs) are an important concept in PSX programming.

Rather than the grid of pixels you may be used to on the PC, graphics
on the PSX are dealt with as primitives: a primitive being any
individual graphic unit, such as a dot, a line, a sprite, a polygon etc.

To display graphics, you add primitives to a queue (the OT), using
various 'GsSort..' commands (see libref.txt for details).
At the end of the main game loop you issue a 'GsDrawOT' command to
tell the GPU to process the data in the OT and create the on-screen
display.

For example, to clear the screen to black we add a 'clear screen'
primitive to the OT using:
GsSortClear (0, 0, 0);
This command does not actually clear the screen, it just adds the
appropriate commands to the OT.
The screen will clear when the GPU processes this command in the OT.

OTs are implemented slightly differently in the Blade Libraries than
in the Yaroze/PsyQ libraries.

Yaroze and PsyQ allow primitives to be inserted at any point in the
OT queue, making the order of the 'GsSort..' commands in your code
unimportant.
The 'depth' of the primitive in the queue is specified in each
'GsSort..' command.

The Blade Libraries work on a first-in-first-out basis.
Primitives from 'GsSort..' commands are placed at the end of the OT.
This means you must issue 'GsSort..' commands in the order you want
the graphics to be displayed from back to front.

When using the Blade libraries just remember that the graphics you
add to the OT queue first will be displayed first.
In a normal game loop, you would first add a 'clear screen' primitive,
then work forwards, adding backgrounds, sprites, text etc.

3D functions operate slightly differently...
The objects are sorted automatically based on their projected Z value.
This ensures the furthest away objects are correctly printed first.

A common problem is the sizing of the OTs.
There must be enough space in the OT to store the required information
for every primitive you'll have on the screen.
A dot requires 8 bytes, some of the more complex polygon primitives
need 32 bytes each.
Other things like text, clear screens and the commands to switch
Display Buffers (see below) all require space, too.
A good rule of thumb for 2D graphics, is to take the maximum number of
objects that will ever be on screen at one time and multiply by 24.
3D graphics require much larger OTs.
You should always err on the side of caution when sizing the OT.
If it's too small, GsSort commands will start overwriting code in
memory and cause a crash.
If your program crashes and needs a hard reset of the PSX, the culprit
could well be an overflowing OT.

----------------
DOUBLE BUFFERING
----------------
As the GPU processes the OT, it converts the primitive commands into
displayable data, which it copies to the Display Buffer area.
The Display Buffer is then copied to the television.
As the game loops, it's possible that the GPU could be updating the
Display Buffer as it's being displayed, resulting in flickering.
To eliminate this, we use a process called double buffering.
Instead of one, we define two Display Buffer areas and two OTs.

The GPU renders the graphics to one area while the other is being
displayed. When the television raster beam jumps to the top to begin
drawing the next frame (Vertical Synchronisation), the OT and Display
Buffer that the GPU is using are switched.
This results in an efficient flicker-free display.

This diagram illustrates the two Display Buffers:

                         Frame Buffer
(0,0)  +--------------+------------------------------+           
       |      320     |                              |
       |              |                              |
       |   Display 240|                              |
       |   Buffer 0   |                              |
       |              |                              |
(0,240)+--------------+                              |
       |      320     |                              |
       |              |                              |
       |   Display 240|                              |
       |   Buffer 1   |                              |
       |              |                              |
       +--------------+                              |
       +---------------------------------------------+(1023,511)

------------
FILE FORMATS
------------
The PSX uses some unique file formats you should be aware of.
There are tools to convert common PC formats to these formats.

TIM files
---------
TIM files hold 2D texture and sprite data, including the Frame Buffer
co-ordinates for upload.
TIM images can have a colour depth of 4, 8 or 16-bit.
Image data is held in two parts - pixel data and CLUT (palette) data,
although having said that, 16-bit TIM images do not have a CLUT - each
pixel colour is described within the pixel data.
The utility TimSet can import BMP files, and allows on-screen positioning
of CLUT and pixel data in the Frame Buffer before saving as a TIM.
There is a plug-in for Photoshop/Paint Shop Pro which allows loading and
saving of TIMs.

VAG files
---------
These are the PSX files that hold sound sample data.
The utility 'WAV2VAG' is used to convert from WAV format.
WAV files must be in the correct format before conversion:
PCM, 16-bit, MONO.
Use Windows Sound Recorder to save them in the correct format.
The sampling rate is commonly 44100Hz or lower.

HIT files
---------
HIT files are the PSX version of MODtracker music files.
The Blade Libraries use a slightly modified version of James Higgs'
version of the Hitmen's PSX MOD player, which plays HIT files.
'MODCONV' converts standard MOD files to HIT files.

TMD files
---------
These are 3D image files.
The file conversion process is as follows:
Most 3D packages can output files in DXF format.
This is converted to the intermediate RSD format.
These are converted into the TMD format required by the libraries.
The tools used are as follows:
'DXF2RSD' converts standard DXF files into RSD format.
The RSD format 'splits' the DXF file into 4 ASCII (hand editable)
files - .RSD, .PLY, .MAT and .GRP.
'RSDFORM' converts the RSD files into a TMD file.
In summary, the 3D file conversion process has two steps and uses
two utilities as follows:
DXF2RSD then RSDFORM

--------
EXAMPLES
--------
There are short source code examples included with the Blade
Libraries, in the DEMOS folder.
They are fairly well documented and should be easy to follow.

----------------
ACKNOWLEDGEMENTS
----------------
Many thanks to everyone involved in the PSXDEV scene.
You've ALL contributed to my knowledge of the PSX which
made it possible to write these libraries.

Special thanks to the following (in no particular order):
Sony, Datel, Yums, co, The Hitmen, Padua, Napalm, Rob Withey,
Jum Higgs, Loser, Cozza and of course T.

