                          Jaluit BSP Tree Compiler
                  Andrea Marchini, University of Parma, Italy

Requirements   : 386+387, 486DX recommended for higher polygon's number,
                 537 Kb RAM, 4Kbytes of hard disk free space :)
Features       : max 2048 polygons, max 10 sides per polygon
Usage          : jaluit <filename.ext>
Output file    : <filename.bsp>
Special switch : jaluit <filename.ext> s  : where s is the max number of sides
                                            in input and output files

The special switch s could slow down the whole processing, but could also 
optimize the final number of polygons. Try different s values...

Input file structure:
1 word      : polygons number
then for each polygon...
1 byte      : polygon's side number = n
3 bytes     : color, or everything about the polygon you want to preserve
n*3 dword   : polygon's vertices, 3 32bit IEEE floats (x,y,z) per vertex

Output file structure:
1 word      : polygons number
then for each polygon...
1 byte      : polygon's side number = n
3 bytes     : color, or everything about the polygon you want to preserve
n*3 dword   : polygon's vertices, 3 32bit IEEE floats (x,y,z) per vertex
1 word      : index to the front child (0 means no front child)
1 word      : index to the back child (0 means no back child)

Error messages:
1) Cannot find adequate root polygon
   Jaluit can't find a proper root polygon to split other polygons in less
   than 10 sides: try using polygons with less sides.
2) Too many polygons                 
   Jaluit have splitted the input polygons and has reached its limit (2048):
   try using less polygons with more sides.
3) Too many polygons in input file   
   The input file contains more than 2048 polygons. Use less polygons (see
   error #2)
4) Error opening input file          
   Jaluit can't open the input file: check for the correct name.
5) Not enough memory to run          
   Jaluit needs 537Kb of main memory anyway.
6) Error creating output file
   Jaluit can't create the output file: check for free space available, or,
   if you are using diskette, for write-protection switch.
7) Too many sides used in input file
   A polygon in the input file has more than 10 sides. Try using more polygons
   with less sides.

The use of the compiler presumes the use of flat convex polygons. The normal 
vector of the polygons is calculated as follows:
 - the vertices close the outline counterclockwise : the normal vector come 
   out from the screen.                   
   
                   <-----^    ^----->
                   |     |    |     |
                   |  .  |    |  x  |
                   |     |    |     |
                   ----->|    <-----|


                           Quick DOCS on BSP tree

1) What is a BSP tree?
BSP (Binary Space Partitioning) trees are precompiled structures that allows 
fast visibility determination of a polygon and simplify shadow calculation, 
collision detection and other related stuff. In order to use BSP trees 
in your program, you need a BSP tree compiler to generate the tree before 
reading and using it. 

2) What's the structure of a BSP tree?
Suppose there are some flat convex polygons in the three-dimensional space. 
One of these polygons will be chosen to be the first root polygon in the tree. 
This polygon, that has a front and back faces, defines a plane. The space is 
divided in two partitions by such a plane. One of these, includes the polygons 
lying in front of the root, the other contains the polygons lying behind the 
root. Repeating in a recursive way the choice of the root polygon in every 
subspace generated you will obtain the BSP tree. The root chosen in the 
front-subspace will be the front-child, the other one will be the back-child.

                             POLYGON 1
                            /          \
                     front /            \ back
                          /              \
                 POLYGON 3               POLYGON 2
                 /        \             /         \
         front  /      back\           /front      \ back
               /            \         /             \
      POLYGON 5              -       -             POLYGON 4

3) How can I use BSP trees?
In the space has been defined a view point. BSP tree can be used to order the 
polygons from the farthest to the nearest from such a view point. This process
starts from the first root polygon stored in the tree. If the view point faces
forward, you will have to consider the back-polygons tree, else you will 
traverse the front-polygons tree. Once you get the correct child (front or 
back), you will have to apply the same procedure as before, until you reach the
first root polygon without childs. This will be the farthest polygon from the
view point. You could want to use this algorithm for correct polygon drawing.
This is a pseudo code for a job such this:

Walk_Tree(Root_Polygon)

{
if(Root_Polygon.Facing(View_Point)=Forward)
        {
        Walk_Tree(Root_Polygon.Back_Child)
        Draw(Root_Polygon)
        Walk_Tree(Root_Polygon.Front_Child)
        }
else
        {
        Walk_Tree(Root_Polygon.Front_Child)
        Walk_Tree(Root_Polygon.Back_Child)
        }
}


If you want to have more information on BSP tree, have a look here:
http://www.qualia.com/bspfaq/

Another good place on BSP trees is
http://www.io.com/~paulhart/game/FAQ/BSP_FAQ.html 

You can also look at Paul's game programming page: 
http://www.io.com/~paulhart/game/

This is the home page of the Dr.Dobb's Journal:
http://www.ddj.com/

This is the page of the first DDJ's article on BSP trees: 
http://www.ddj.com/ddj/1995/1995.07/dwyer.htm

Here is another interesting place:
file://x2ftp.oulu.fi/pub/msdos/programming/theory/bsp_tree.zip

Thanks to Nathan Dwyer and Michael Abrash for their DDJ articles. Thanks to 
everybody using this little, modest, pocket program. How did I build up this 
"thing"?! I've used only Assembly language! Are you interested in source code? 
Have you anything to suggest (for the README file sintax and grammar too ;-)? 
Did you have any trouble with the program? 
Please contact me:
marchini@ulisse.cedi.unipr.it

NB: Please don't modify the contents of this file, the name and the code of 
    the executable file. THANKS!! ;-)

                                                Andrea Marchini


