<HTML> <HEAD> <TITLE> README</TITLE> </HEAD> <BODY BGCOLOR="#000044" TEXT="WHITE" VLINK="WHITE"> <H2> Introduction</H2> bsp-renderer is an open source application for displaying levels stored in the quake3 bsp map format. It allows the user to move around in the levels using a first person camera and rudimentary collision detection. It is released under the GNU General Public License version 3 (<a href="http://www.gnu.org">www.gnu.org</a>) The purpose of this document is to give an overview of the bsp-renderer application, including how to use it, which third party libraries and third party code it uses and other technical information. This distribution of the program contains the source code and prebuilt executables. It also contains the libraries necessary to build the source, and a level called "The Forlorn Hope", which can be found at <a href="http://www.users.on.net/justonefix/">http://www.users.on.net/justonefix/</a>. bsp-renderer is currently in version 0.7 and is hosted at <a href="http://code.google.com/p/bsp-renderer">code.google.com/p/bsp-renderer</a> <p> bsp-renderer is intended as a starting point for implementing first person shooters, or similar games. The reason I created it is that I wanted to porgram an FPS-like game from scratch (well almost anyway, the map format was created by Id Software). Of course, there is a long way to go before bsp-renderer can be called an FPS, hence the name. It's about 4000 lines of code, and the GPL notices at the beginning of each file account for 500 of these. </p> <H3> How to run the application</H3> The project contains two configurations, debug and release. The prebuilt executable is a release build, which has the flag RELEASE_BUILD set. This flag adjusts were the application looks for the default map. If the application finds a bsp.cfg file in its running directory, it will parse this file to set which map to load. The bsp.cfg file in this distribution contains an explanation of the syntax. If no file is present, or no file or map is set in the file, the default map will be loaded (found in the 'media' folder). The application will exit if it cannot find the map or data file bsp.cfg specifies. Alos, the runtime library zlib1.dll needs to be in the run directory, if it does not exist in the default Windows dll directories. <H4> Keys</H4> Use WASD and mouse to move around.<BR> F1: disable collision detection.<BR> F2: enable collision detection without gravity<BR> F3: enable collision detection with gravity<BR> F8: toggle full screen mode<BR> <H3> Building bsp-renderer </H3> You will need a DirectX SDK, probably version 9.0c, it is not tested with earlier versions. You will also need MS Visual 2008 (the free express version will do). To build bsp-renderer Visual studio needs to have the paths of the DirectX libraries and include files in the VC++ directories settings (click 'options' in the 'tools' menu). Zziplib.lib, the external library used by bsp-renderer is included in the distribution and will be linked automatically when building. The usage of hardware vertex processing can't be adjusted dynamically in the current state of bsp-renderer. Use the NO_HW_VERTEXPROCESSING preprocessor definition to toggle this. Originally, bsp-renderer always used HW vertex processing, but I had to work on a laptop which didn't support it, hence this option. <H3> Technical overview </H3> <p> The levels are rendered using the visibility algorithm briefly described here. For a more in depth description see reference <a href=#ref>[1]</a> (where I received this information). </p> <p>The BSP tree for the level is traversed using the camera position to find a cluster index. This index is used to test the potentially visible clusters from the current one. The cluster visibility information is in the map data. To find the visible faces we interate over the leafs in the BSP tree (the leafs contain face indices). First, the cluster of each leaf is tested against the camera cluster. If this test is positive, its bounding box is then culled against the camera's view frustum. If the leaf is not completely outside the frustum, the faces in the leaf are added to the list of faces to render while avoiding to add the same face twice. The list of faces are then sent to the drawing routines.</p> <p>The sky is a cube mapped texture which was created using <a href=http://www.planetside.co.uk/terragen> Terragen</a>. The same sky is always used, not the ones defined in the .bsp files.</p> <H3> Limitations</H3> <p> Quake III uses "shader files" for the moving and animated parts of the map, these files are not used by bsp-renderer in its present state. </p> <p> The collision detection does not seem to work well for all curved surfaces. </p> <p> The "physics" (i.e. the gravity) is only rudimentary and quite rough </p> <p> Although it is quite fast, it could be faster. The drawing of the bezier patches is most likely not optimal. It seems they were designed for the OpenGL command glMultiDrawElementsEXT() In DirectX, I had to replace this with a loop and multiple calls to DrawIndexedPrimitive(). </p> <p> The check for the capabilities of the graphics card is a bit limited. The use of hardware vertex processing is not dynamic, meaning that if you run the executable using it on a graphics card where it is not supported, the program will exit. </p> <p> See also <a href=http://code.google.com/p/bsp-renderer/issues/list>http://code.google.com/p/bsp-renderer/issues/list</a> </p> <H2><a name="ref"> References </H2> The information on following web sites were used during the development.<BR> <BR> <span style="font-weight: bold; text-decoration: underline;"></span> <span style="font-weight: bold;">[1] Rendering Quake 3 Maps<br> </span> <table style="text-align: left; width: 100%;" border="0" cellpadding="0" cellspacing="0"> <tbody> <tr> <td style="width: 20%;">Author:</td> <td>Morgan McGuire</td> </tr> <tr> <td>Website:</td> <td><a href=http://graphics.cs.brown.edu/games/quake/quake3.html>http://graphics.cs.brown.edu/games/quake/quake3.html</a></td> </tr> </tbody> </table> <BR> <span style="font-weight: bold; text-decoration: underline;"></span> <span style="font-weight: bold;">[2] Unofficial Quake 3 Map Specs<br> </span> <table style="text-align: left; width: 100%;" border="0" cellpadding="0" cellspacing="0"> <tbody> <tr> <td style="width: 20%;">Author:</td> <td>Kekoa Proudfoot</td> </tr> <tr> <td>Website:</td> <td><a href=http://graphics.stanford.edu/~kekoa/q3/>http://graphics.stanford.edu/~kekoa/q3</a></td> </tr> </tbody> </table> <BR> <span style="font-weight: bold; text-decoration: underline;"></span> <span style="font-weight: bold;">[3] Quake 3 BSP Collision Detection<br> </span> <table style="text-align: left; width: 100%;" border="0" cellpadding="0" cellspacing="0"> <tbody> <tr> <td style="width: 20%;">Author:</td> <td>Nathan Ostgard</td> </tr> <tr> <td>Website:</td> <td><a href=http://www.devmaster.net/articles/quake3collision/>http://www.devmaster.net/articles/quake3collision</a></td> </tr> </tbody> </table> <p>For the DirectX specific parts the book <a href="http://www.moon-labs.com">Introduction to 3D Game Programming with DirectX 9.0c: A Shader Approach</a> by Frank Luna, and the DirectX SDK documentation were useful.</p> <H2> Licensing </H2> bsp-renderer is released under GPL version 3. However, it relies on third party libraries, as well as pieces of source code from other open source programs. An overview of these libraries and source code is given here. The licenses mentioned can be found in the 'licenses' folder. <H3> Source code licenses</H3> Two parts of the source code are based on algorithms originally from other open source applications. <p>- The source for the collision detection (but not the collision response) is based on code from reference [3] above, which in turn comes from the Quake III source. </p> <p>- The tessellation of the Bezier patches is based on code from reference [1]. The code originally comes from the Octagon Engine.</p> <span style="font-weight: bold; text-decoration: underline;"></span> <span style="font-weight: bold;">Quake III<br> </span> <table style="text-align: left; width: 100%;" border="0" cellpadding="0" cellspacing="0"> <tbody> <tr> <td style="width: 20%;">Original Author:</td> <td>Id Software, Inc.</td> </tr> <tr> <td>Website:</td> <td><a href=http://www.idsoftware.com/>http://www.idsoftware.com</a></td> </tr> <tr> <td>Licensed Under:</td> <td>GNU General Public License, version 2</td> </tr> </tbody> </table> <BR> <span style="font-weight: bold; text-decoration: underline;"></span> <span style="font-weight: bold;">Octagon Engine<br> </span> <table style="text-align: left; width: 100%;" border="0" cellpadding="0" cellspacing="0"> <tbody> <tr> <td style="width: 20%;">Original Author:</td> <td>Paul Baker</td> </tr> <tr> <td>Website:</td> <td><a href=http://www.paulsprojects.net/opengl/octagon/octagon.html>http://www.paulsprojects.net/opengl/octagon/octagon.html</a></td> </tr> <tr> <td>Licensed Under:</td> <td>New BSD License </td> </tr> </tbody> </table> <H3> Third party libraries </H3> <span style="font-weight: bold; text-decoration: underline;"></span> <span style="font-weight: bold;">Zziplib<br> </span> <table style="text-align: left; width: 100%;" border="0" cellpadding="0" cellspacing="0"> <tbody> <tr> <td style="width: 20%;">Original Author:</td> <td>Guido Draheim</td> </tr> <tr> <td>Website:</td> <td><a href=http://zziplib.sourceforge.net>http://zziplib.sourceforge.net</a></td> </tr> <tr> <td>Licensed Under:</td> <td>Lesser GNU Lesser Public License (called the GNU Library Public License in the 'licenses' folder)</td> </tr> </tbody> </table> <BR> <span style="font-weight: bold; text-decoration: underline;"></span> <span style="font-weight: bold;">Zlib<br> </span> <table style="text-align: left; width: 100%;" border="0" cellpadding="0" cellspacing="0"> <tbody> <tr> <td style="width: 20%;">Original Authors:</td> <td>Jean-loup Gailly and Mark Adler</td> </tr> <tr> <td>Website:</td> <td><a href=http://www.zlib.net>http://www.zlib.net</a></td> </tr> <tr> <td>Licensed Under:</td> <td>Zlib License </td> </tr> </tbody> </table> Zlib is used as a runtime library by Zziplib and not by bsp-renderer directly. <H3> Media content </H3> <span style="font-weight: bold; text-decoration: underline;"></span> <span style="font-weight: bold;">The Forlorn Hope (a Quake III level)<br> </span> <table style="text-align: left; width: 100%;" border="0" cellpadding="0" cellspacing="0"> <tbody> <tr> <td style="width: 20%;">Original Author:</td> <td>JustOneFiX</td> </tr> <tr> <td>Website:</td> <td><a href=http://www.users.on.net/justonefix/>http://www.users.on.net/justonefix/</a></td> </tr> </tbody> </table> <BR> <BR> <p>Copyright © 2008 Daniel Örstadius, daniel.orstadius@gmail.com</p> </BODY> </HTML>