README for glBSP ================ by Andrew Apted. 4th September 2000. Introduction ------------ glBSP is a nodes builder specially designed to be used with OpenGL ports of the DOOM game engine. It adheres to the "GL-Friendly Nodes" specification, which means it adds some new special nodes to a WAD file that makes it very easy (and fast !) for an OpenGL DOOM engine to compute the polygons needed for drawing the levels. There are many DOOM ports that understand the GL Nodes which glBSP creates, including: EDGE, the Doomsday engine (JDOOM), and Doom3D. See the links below. Status ------ The current version of glBSP is 1.91. It has been tested and known to work on numerous large wads, including DOOM I shareware, DOOM II, TeamTNT's Eternal III, and beta versions of Fanatic's QDOOM. NOTE: Version 1.91 introduces support for "V2 GL Nodes". This allows the BSP information to be stored with greater precision, preventing problems like "slime trails". It may take a while before all DOOM ports that understand GL Nodes are updated to read the new format. Until they do, use the -v1 option to generate the old format. Copyright --------- glBSP is Copyright (C) 2000 Andrew Apted. It is based on `BSP 2.3' (C) Colin Reed and Lee Killough, which was created from the basic theory stated in DEU5 (OBJECTS.C) by Raphael Quinet. All trademarks are the propriety of their owners. License ------- Thanks to Lee Killough and André Majorel (the previous and current maintainers of BSP, respectively), glBSP is now under the GNU General Public License (GPL). See the file `COPYING' in the source package (or go to http://www.gnu.org) for the full text, but to summarise: This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. Contact ------- Questions, bug reports, suggestsions, etc... about glBSP should be directed to the glBSP public forum which can be found here: http://sourceforge.net/forum/?group_id=10592 Alternatively you could join the glbsp-public mailing list. Details about doing this can be found here: http://sourceforge.net/mail/?group_id=10592 Links ----- The homepage for glBSP can be found here: http://glbsp.sourceforge.net/ The "GL Friendly Nodes" specifications can be found here: http://glbsp.sourceforge.net/glnodes.html The EDGE homepage can be found here: http://edge.sourceforge.net/ The JDOOM homepage is here: http://www.newdoom.com/jdoom The Doom3D site can be found here: http://www.redrival.com/fudgefactor/doom3d.html Acknowledgements ---------------- Andy Baker, for making binaries and stuff. Marc A. Pullen, for testing and helping with the documentation. Lee Killough and André Majorel, for giving their permission to put glBSP under the GNU GPL. Jaakko Keränen, who gave some useful feedback on the "GL Friendly Nodes" specification. Marc Rousseau (author of ZenNode 1.0), Robert Fenske Jr (author of Warm 1.6), L.M. Witek (author of Reject 1.1), and others, for releasing the source code to their WAD utilities, and giving me lots of ideas to "borrow" :), like blockmap packing. Colin Reed and Lee Killough (and others), who wrote the original BSP 2.3 which glBSP is based on. Matt Fell, for the Doom Specs v1.666. Raphael Quinet, for DEU and the original idea. id Software, for not only creating such an irresistable game, but releasing the source code for so much of their stuff. ... and everyone else who deserves it ! Using glBSP =========== by Andrew Apted. 8th September 2000. 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. 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. Option Descriptions ------------------- The following options are recognised: -factor 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 (5) is known to be a good compromise. -noreject Normally glBSP will create an empty REJECT map for each level. This options prevents any existing REJECT map from being clobbered. -noprog Does not show the twirling 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. -hexen Hexen support. Specify this option if the WAD file is for Hexen. This allows glBSP to read and write the different lump formats, and also enables some code to handle lines belonging to PolyObjects better. -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). 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.