/** \page file_format File formats

\section fileOverview Overview

There are two file types: level and map files. There are one or more
map files for each level file. The level file represents the data common
to a set of levels (sprites and status screen information) where as the
map file represents the data for one level ie how to draw the map and
what the bad guys are going to do.

The game searches for level files sorted by uid. So it will run level
file with uid3 equal to 1 before level file with uid3 equal to 2. It then
searchs for map files with uid3 equal to the level file number and runs
each of these in the order it finds them.

\section mapfile Map Files

Map files contain the information about:
<ul>
<li>Which background sprites to plot to form the map.</li>
<li>When to introduce bad guys.</li>
<li>The paths the bad guys will follow.</li>
<li>Which sprites to use for bullets, players ship and explosions.</li>
<li>Where the players ship starts.</li>
<li>Initial health and powerups of players ship.</li>
</ul>

\subsection mapformat Format

<ul>
<li>32bit uid 1 = application uid</li>
<li>32bit uid 2 = 2 (this is a map file)</li>
<li>32bit uid 3 = level number (which level file to load with this map)</li>
<li>32bit uid crc</li>
<li>32bit offset to map data</li>
<li>32bit offset to path data</li>
<li>32bit sprite number of players ship</li>
<li>32bit first sprite number to use for players ship explosion</li>
<li>32bit last sprite number to use for players ship explosion (inclusive)</li>
<li>32bit first sprite number to use for bad guy explosion</li>
<li>32bit last sprite number to use for bad guy explosion (inclusive)</li>
<li>32bit sprite number of first of 8 sequential sprites to use for bullets of power 1</li>
<li>32bit sprite number of first of 8 sequential sprites to use for bullets of power 2</li>

<li>32bit sprite number of first of 8 sequential sprites to use for bullets of power 3</li>
<li>32bit sprite number of first of 8 sequential sprites to use for bullets of power 4</li>
<li>32bit X position of players ship at start of level</li>
<li>32bit Y position of players ship at start of level</li>
<li>32bit health of players ship at start of level</li>
<li>32bit number of powerups for players bullets at start of level (only used if player is starting a new game on this level, other wise will use the number of powerups the player had at the end of the previous level)</li>
<li>n * 2 * 8 (N * 8 * TInt16s) of map data  (see file TMapLineType.h)</li>
<li>n * 2 * 4 (N * 4 * TInt16s) of path data (see file TPathLineType.h)</li>
</ul>

\section levelFile Level Files

These contain the background and ship sprites and the information and
sprites used to draw the status screen. 

\subsection levelFormat Format

<ul>
<li>32bit uid 1 = application uid</li>
<li>32bit uid 2 = 1 (this is a level file)</li>
<li>32bit uid 3 = level number (used to match map and level files together)</li>
<li>32bit uid crc</li>
<li>32bit map sprites offset</li>
<li>32bit ship sprites offset</li>
<li>32bit offset to status data and sprites</li>
<li>map, ship, and status data.</li>
</ul>

Offsets are given from the first non uid byte, ie the offset of the
map sprites offset is 0, the offset of the ship sprites offset is 4
the offset of the uid crc is -4 etc.


Map sprites are 64 pixels by 50 pixels, 2 pixels are stored in each
32bit word, so each sprites is 6400 bytes, see the sprite format for
more infomation

Ship sprites are 32x24 pixels, again 2 pixels in one 32bit word,
so each sprite is 1536 bytes, see the sprite format for
more infomation

Status screen data is a list of the size and where to put sprites
for the health and ships, what background sprites to plot, and where
to put the score see the RStatus class for more information.


\subsection spriteFormat Sprite data format

The sprite data is a series of 32 bit words, the words are broken down
into 8 nibbles (nibble = 1/2 byte) each of which represents mask information
and two pixels. Numbering the nibbles 87654321 where 8 is the most significant
nibble we have:

<ul>
<li> nibble 8, bits give landscape/ship/ship extension mask:
        <ul>
        <li>bit 3 = landscape</li>
        <li>bit 2 = ship extension, unused</li>
        <li>bit 1 = players ship</li>
        <li>bit 0 = unused</li>
        </ul></li>
<li> nibble 7, red component of right hand pixel</li>
<li> nibble 6, green component of right hand pixel</li>
<li> nibble 5, blue component of right hand pixel</li>
<li> nibble 4, mask for players bullets, 4 bits giving the number of the bullet. 8 bullets are currently supported.
<li> nibble 3, red component of left hand pixel</li>
<li> nibble 2, green component of left hand pixel</li>
<li> nibble 1, blue component of left hand pixel</li>
</ul>

Sprites are always a multiple of 32bit words therefore the X dimension
of sprites is always a mutiple of 2. Also the sprite routines in the game
only handle plotting sprites on 32bit boundarys so for a 640 pixel wide
screen X dimensions run from 0-319. (ie plotting a sprite at 10,20 will
put it at 20 pixels in from the left and 20 pixels down from the top).

\subsection uidFormat Generating uids

The 3 uid words and the uid crc are generated using uidcrc.exe which
takes 4 parameters. The three uids and the name of the file to create with
the 16 byte uid header.

*/