
USING glBSP
===========

by Andrew Apted.  24th September 2001.


Running glBSP
-------------

There are now two versions of glBSP: normal `glbsp' (the text
version), and `glbspX' (offering a graphical interface).  This
documentation applies to the text version only.  Under Windows, the
text version must be run from the DOS box.

There are two main ways of using glBSP:

  1. Create the GL nodes and store them in a separate file with the
     GWA extension.  This is called "GWA mode".
  
  2. Create the GL nodes and store them in the WAD file itself, just
     like how a normal node builder works.

These ways are described in more detail below.


1. GWA Mode
-----------

For general use, when you just want to use some wad (e.g. FOO.WAD)
with a compliant OpenGL DOOM port, then this method is the recommended
way.  It is also the simplest method, just type:

   glbsp foo.wad

and then glBSP will create the file "foo.gwa".  A compliant OpenGL
DOOM port (such as EDGE) will notice the GWA file automatically and
load it appropriately.  Nothing more needs to be done.

Note !  You should not specify these GWA files on the command line
(i.e. with the -file option), doing so will likely confuse the
compliant OpenGL DOOM port and it may crash.

Note 2: when using GWA mode, the output file does not contain any
information for things, linedefs, sidedefs, sectors, reject, or
blockmap, all it contains is the GL node information.  This is where
the name "GWA" comes from, it is short for "GL WAD" (in case you were
wondering).


2. Non-GWA Mode
---------------

This method is intended for WAD authors, so they can create a single
WAD file for distribution that contains all the needed information.
Using this method looks like this:

   glbsp foo1.wad -o foo2.wad

and then glBSP will build the GL nodes and output the new file
"foo2.wad" containing them.  It will also build the normal node
information if it is absent.


Option Descriptions
-------------------

The following options are recognised:

  -factor <num> 
               Changes the cost assigned to seg splits.  Factor can
               be any number greater than 0, larger values make seg
               splits more costly (and thus glBSP tries harder to
               avoid them), but smaller values produce better BSP
               trees.  See the section below for more info.  The
               default value is known to be a good compromise.

  -noreject    Normally glBSP will create an simple REJECT map for
               each level.  This options prevents any existing
               REJECT map from being clobbered.

  -noprog      Does not show the progress indicator.

  -warn        Shows extra warning messages, which detail various
               non-serious problems that glBSP has while analysing the
               level structure.  Often these warnings show a real
               problem in the level (e.g. a non-closed sector or
               invalid sidedef), so they are worth checking now and
               then.

  -packsides   Pack sidedefs, by detecting which sidedefs are
               identical and removing the duplicates, producing a
               smaller PWAD.  Note: this may make your level a lot
               harder to edit !  Therefore this option is most useful
               when producing a final WAD for public release.
 
  -v1          Backwards compatibility.  The current version of the
               "GL Nodes" spec (V2.0) introduces a new format for the
               GL_VERT lump designed to prevent slime trails.  Some
               engines may not support this at first, so use this
               option to produce the old (V1.0) format.

These next set of options normally don't need to be used, but they are
provided to allow complete control or for special circumstances:

  -loadall     glBSP will normally try to copy lumps from the input
               WAD file to the output file instead of loading them
               into memory.  This allows you to run glBSP on very
               large WADS (e.g. 15 MB for DOOM II) on a low memory
               machine.

               This option causes everything from the input file to be
               loaded into memory.  This allows you to run glBSP using
               the same file for both input and output, but I strongly
               recommend _against_ it: you could lose your original
               WAD if something goes wrong (and you know Murphy...).

  -nogl        Forces glBSP to not create the GL node info.

  -nonormal    Forces glBSP to not create the normal node information
               when it detects that it is absent.
 
  -forcenormal
               glBSP will normally detect if the normal node info (i.e. 
               the non-GL variety) is present, and leave it untouched
               when it is, otherwise create it.  This option forces
               glBSP to recreate the normal node info.
               
  -forcegwa    Normally glBSP will automatically use GWA mode if the
               output filename is missing (i.e. no -o option) or if
               the output filename has the ".gwa" extension.  This
               option forces glBSP into GWA mode.
 
  -keepsect    Prevents unused sectors that are found in the level
               from being removed.  This is important for anything
               that refers to sector numbers directly (e.g. certain
               EDGE RTS commands), since pruning unused sectors can
               make their numbers (as seen in an editor) different.
 
  -noprune     Disables all pruning of unused vertices, sidedefs,
               linedefs and sectors from levels.  Pruning only occurs
               when normal nodes are being built (i.e. it is
               automatically disabled when in GWA mode).
 
  -maxblock <num> 
               Sets the limit of the number of blocks the BLOCKMAP may
               contain before we truncate it.  Default is 44000.  When
               the level is too large to fit, glBSP will truncate the
               blockmap, so it covers less area on the level.  This
               means that in the parts it doesn't cover (at the outer
               edges) there is no collision detection: you can walk
               through walls and other objects and bullets/missiles
               don't hit anything.  On very large but sparse levels,
               using a larger value (e.g. 60000) may help.

               A more serious problem is when the blockmap overflows
               (glBSP will show a message about this).  The blockmap
               created is invalid, and could crash the DOOM engine
               when used.  Setting a lower limit (e.g. 20000 or less)
               may help prevent crashes -- at the expense of the
               no-collision problem popping up.  Some DOOM engines
               (e.g. BOOM and MBF) have a "-blockmap" option that
               generates their own blockmap internally, fixing these
               problems.


Notes for TC authors:
---------------------

None of the various WAD tools that exist (such as DSHRINK, CLEANWAD,
DEUTEX, etc..) are "glBSP aware", they will rearrange or even remove
some of the special GL entries.  If you are preparing your final WAD
file that is either a compilation of just multiple maps, or multiple
maps and other data (music, textures, sprites, graphics, etc..), run
the following process to properly compile everything:

  1. For your final compile of your maps (e.g. you are completely done
     making your maps), compile them using glbsp and use the -nogl
     option to *not* build the GL nodes.
  
     e.g.:
          glbsp -nogl map.wad -o map1.wad
  
  2) Run rmb (reject map building) at this point on your WAD files.
  
     e.g.:
          rmb map1.wad map2.wad -perfect -nomap
  
  3) Merge all your WAD files into your main WAD using NWT or
     Wintex/DEUSF.
  
  4) Run cleanwad on your main WAD
  
     e.g.:
          cleanwad main.wad main1.wad +rr +al +tw +rp +pp +is +rb +pb
  
  5) Recompile the maps in your main WAD with the GL nodes.  Be sure
     to use the -noreject option, which prevents the reject entries
     created by rmb from being overwritten.
  
     e.g.:
          glbsp -noreject main1.wad -o main2.wad

 
Your final output, main2.wad, will be a clean and compact WAD, with no
wasted space, and all the GL nodes in the proper order. All of your
data will be in this WAD file as well, as glbsp can compile the maps
in a WAD without destroying non-map data.
  
*** DO NOT: ***
  
  + Run dshrink on your map WADs at any time!

  + Run cleanwad on your map WADs *after* you have compiled your GL
    friendly nodes!  (The GL nodes will be removed).

  + Use Wintex/DEUSF to merge map WADs with GL friendly nodes in them!
    (The GL node entries will be rearranged, causing problems).


Problems under DOS ?
--------------------

If you find that glBSP consistently runs out of memory and/or crashes
at a certain point within a particular WAD, it could well be your DPMI
settings.  This happened to me just recently, after much checking of
the code the problem seemed inexplicable.  It turned out that CWSDPMI
was the culprit.  The solution was to increase CWSDPMI's "internal
heap" size using the companion CWSPARAM program, bumping it up from
128 to 1024 (see the CWSPARAM.DOC file for the details).  If you have
a different one (e.g. QDPMI), then check its documentation.


How glBSP works and stuff
-------------------------

A node builder works like this: say you are looking at your level in
the automap or in the level editor.  The node builder needs to pick a
line (stretching to infinity) that divides the whole map in two halves
(can be rough).  Now cover up one half with your hand, and repeat the
process on the remaining half.  The nodes builder keeps doing this
until the areas that remain are convex (i.e. none of the walls can
block the view of any other walls when you are inside that area).

Those infinite lines are called "partition lines", and when they cross
a linedef, the linedef has to be split.  Each split piece is called a
"seg", and every split causes more segs to be created.  Having fewer
segs is good: less to draw & smaller files, so partition lines are
chosen so that they minimise splits.  The "-factor" value controls how
costly these splits are.  Higher values cause the node builder to try
harder to avoid splits.

So, each "partition" line splits an area (or "space") of the level
into *two* smaller spaces.  This is where the term "Binary Space
Partition" (BSP) comes from.

Another thing: having a good BSP tree is also important, and helps for
faster rendering & smaller files.  Thus the node builder also tries to
make the BSP tree good (by making it balanced, and keeping it small).
If the "-factor" value is too high, it will care too much about the
splits, and probably make a bad BSP tree.  How good the BSP tree is
can be gauged by the output line that reads:

   Heights of left and right subtrees = (12,24)

Lower values are better (the BSP tree is smaller), and values that are
closer together are also better (the BSP is more balanced).


Differences to BSP 2.3
----------------------

As mentioned in the readme file, glBSP is based on BSP 2.3.  Most of
the code has been rewritten, however, and some features of BSP were
changed or abandoned.  Features that are different:

  +  When the output file is not specified (i.e. no -o option), then
     the default output file will be a GWA file with the same name.
     Under BSP 2.3, the default output file would be "tmp.wad".

  +  All code for doing visplane checks has been removed.  It was very
     complex stuff, and for OpenGL DOOM ports this checking is not
     needed.  Thus glBSP does not accept the following options that
     BSP 2.3 supports: -thold, -vp, -vpmark, -vpwarn.

  +  glBSP should work on big-endian platforms (like the Mac).  The
     code was rewritten with this in mind, though it has not been
     tested yet (a report on this would be appreciated).
  
  +  The "just for a grin" special feature where a linedef with tag
     999 would cause an angle adjustment was removed.
 
  +  glBSP has Hexen support.
 
  +  glBSP packs the blockmap, and can merge identical sidedefs.

  +  glBSP has a much more modular architecture.

  +  The GUI version, glbspX, is completely new.
 


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

