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

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

--------
CONTENTS
--------
OVERVIEW
SYSTEM REQUIREMENTS
BSTART
COMPILE
BIN2O
BIN2H
WAV2VAG

--------
OVERVIEW
--------
The tools described in this document have been created to
simplify the process of creating homebrew Playstation games
with the Blade PSX Programming Libraries.

-------------------
SYSTEM REQUIREMENTS
-------------------
The utilities are 32-bit Windows console applications,
so you must be running Microsoft Windows 95 or above.

-------------
BSTART (v1.0)
-------------
The MIPSGCC compiler requires several environment variables to be
correctly set, and that the BIN directory is in your path.
BSTART automates this process.

BSTART should be run only once, after extracting the libraries.
It should only ever require to be run again if you re-install, or
if you move the libraries to a new directory.
To ensure the variables get set correctly, it must be run from the
directory it extracted to, ie. the base directory of the libraries.

When run, BSTART produces a batch file called MIPS.BAT.
This is a regular batch file which can be viewed, edited and
customized as required.

MIPS.BAT must be run every time you drop to the command line to
use the Blade Libraries, so it should be copied to a directory in
your existing path (C:\WINDOWS is usually there).
It can be set to run automatically in Windows 95/8 like this:
Right click the MS-DOS desktop icon, select Properties, click the
Program tab and enter the full path and filename of MIPS.BAT in the
Batch File box.
You can check your environment settings at any time by typing SET
from the command line.

The C compiler, MIPSGCC, will not work if there is a space anywhere
in your path names. If this is the case, BSTART will issue a warning.
Re-name the directory and re-run BSTART.

--------------
COMPILE (v1.0)
--------------
The syntax of the MIPSGCC command to compile a C program is fairly complex.
COMPILE simplifies the compilation process by filling in the most common
options for you.

e.g. if you have a source code file called 'game.c' that  you want to
compile, the MIPSGCC command looks like this:
MIPSGCC -I..\include -O2 -Xlinker -mpsx -o game.psx game.c ..\lib\bladeps.a

The COMPILE syntax to do the same thing looks like this:
COMPILE game.c

To include object files, for example sound/graphics data, the syntax is:
COMPILE game.c sound.o graphics.o

The PSX executable name is taken from the source file, changing the
extension from '.C' to '.PSX'.

COMPILE runs MIPSGCC behind the scenes, so you'll get error messages
if any of the required environment variables are not set correctly.
When the compilation process begins, any further messages are from
MIPSGCC, NOT from COMPILE.
Compiler messages will appear between a pair of dashed lines 
(---------------).

Of course, if you find COMPILE too limiting, you can still manually run
the compile process and have full access to all MIPSGCC options.

------------
BIN2O (v1.0)
------------
There are several ways of including binary data files (sound/graphics)
in your programs.
BIN2O converts binary data into an C object file which can be compiled
into your file PSX exe.

e.g. to use a sound file NOISE.WAV, first convert it to the PSX (VAG)
format using WAV2VAG (see below), to give you the file NOISE.VAG

From the command line, type:
BIN2O NOISE.VAG

You will have a file called NOISE.O

The data in this object file is referenced from your source code with
the label NOISE, in the following way:
extern u_char NOISE[];

The example program DEMO4 shows an example of this.

The object and label names are taken from the original data file name.

Remember C labels can't start with a number, so you'll get an error
if you run BIN2O against a data file whose name begins with a number.

------------
BIN2H (v1.0)
------------
BIN2O is similar to BIN2H, and provides an alternative method of
including binary data in your program.
BIN2H converts a binary file into a C header file (.H) which can be
included from your C source code.

Using the same example as BIN2O, for a sound file NOISE.VAG, run the
following from the command line:
BIN2H NOISE.VAG

You will now have a file called NOISE.H

The data in NOISE.H is referenced from your source code like this:
u_char NOISE[];

The example program DEMO3 shows an example of this.

As with BIN2O, the header file and label names are taken from the
original binary file name, it'll error if your data file name starts
with a number.

I would recommend using BIN2O rather than BIN2H simply because
header files created with BIN2H can get quite large, even for a
small binary file.

--------------
WAV2VAG (v1.0)
--------------
This utility converts standard PC WAV sound files into the Playstation
VAG format.

WAV files must be in the correct format before conversion:
PCM, 16-bit, MONO.
If they are different, use Windows Sound Recorder to convert them.

The syntax to convert SOUND.WAV into SOUND.VAG is:
WAV2VAG SOUND.WAV
