Transparent Water QBSP with Hipnitual Extensions
Version 1.65

by Ken Alverson (KenA@TSO.Cin.IX.Net)
based on original code by John Carmack (JohnC@idsoftware.com)

Description:
        This verison of QBSP was designed to enable level makers to create
        maps that take full advantage of the 3dfx boards (or any future
        OpenGL compatible boards) by allowing translucent water in a level.
        It has since grown to be a fairly all purpose QBSP that should be
        able to replace pretty much any other QBSP out there.  For a full
        list of features, skip down the the "Features" section of this text
        file.

        It should be noted (I get a *ton* of mail on this subject) that this
        program can only compile MAP files, not BSP files.  And no, there
        is no known BSP->MAP converter that will create a usable map (there
        is a converter but the MAP files cannot be recompiled).  Therefore
        this is not for the GLQuake user who wants his maps to have
        translucent water, it is for level designers who want to distribute
        levels with translucent water.

Installation:
        There are several ways to use this file.  If you are using
        Worldcraft, or a similar editor which calls an external QBSP to
        compile a level, simply put this QBSP in place of your current QBSP
        and you are set.  There are a few bugs in the id source which my
        QBSP is based on (I am working to eliminate these, there are still
        a few rare ones left), so you may want to back up your old QBSP in
        case you run into a problem.  If you are compiling by hand, simply
        place this QBSP in your MAP directory, or somewhere in your path,
        and run it as usual.  If you are using a level editor that doesn't
        automatically compile levels, and you have never compiled a level
        by hand, read on, else skip to the next section.

Compiling a level by hand:
        Place this QBSP.exe in the same directory as your MAP file.  You will
        also need LIGHT.exe and VIS.exe, available elsewhere on the net
        (I recommend checking "The Forge" at
        http://www.planetquake.com/worldcraft)  When you are ready to
        compile, type the following (replacing <map name> with the filename
        of your map, sans the ".map" extension):

        QBSP <map name>
        LIGHT <map name>
        VIS -fast <map name>

        This will give you a fast compile so you can test your level.  When
        you are fairly sure you are ready to distribute your level, compile
        it with the following commands:

        QBSP <map name>
        LIGHT -extra <map name>
        VIS -level 4 <map name>

        This will give you much better performance and lighting, but it will
        more than 4 times as long to compile.  Also use these settings if
        you need to find out how well your level will run, the
        "vis -level 4" option will greatly speed up the level in Quake.

Technical details:
        You're probably wondering how I got translucent water to work,
        without even modifying the "VIS" program which does the actual
        viewable leaves calculations.  If you weren't wondering this, you
        can probably skip ahead. =)

        Basically, when QBSP compiles a level, it creates a BSP file
        (obviously) and a portal (.PRT) file.  When VIS goes to determine
        which leaves can see which other leaves, it uses the portal file
        to determine this.  Basically, the portal is a planar polygon
        that defines the edge between two leaves (the basic block that
        a level is divided into by QBSP, there are about 1,500 leaves in
        E1M1).  After QBSP determines all the portals, it strips away the
        portals that cannot bee seen through (ie the ones that go from
        open-air or water leaves to solid (wall) leaves, and portals between
        water and air).  I modified this check so that air->water and
        water->air portals are not stripped away, and are written to the
        portal file.  Basically this means VIS will interperet the
        connection between the air and water as non-visibility-blocking,
        allowing GLQuake to render the water as translucent and see what is
        below (above) the water, which would otherwise be ruled as invisible,
        due to the visibility information VIS stores in the BSP file.
        You can also force GLQuake to ignore this VIS information, by using
        the "R_NOVIS 1" console command, however since the VIS information
        optimizes the drawing of the level, this will be very slow.  There
        is also a program that takes current BSP files and makes them
        have translucent water, but it does not work in an optimized manner.
        It takes all water leaves and makes them visible from all air
        leaves, and all air leaves visible from all water leaves, giving you
        about twice the performance of "R_NOVIS 1", but not optimized
        performance, as my QBSP.  The benefit of this program
        ("WATER102.ZIP", available http://www.allgames.com/quake/) is that
        it can work on compiled levels, making it better for the gamer
        who wants their existing Quake levels to have transparent water.
        My QBSP only works on MAP source files, which means the level
        designer is responsible for using it if he wants transparent water
        in his level.  

Features:
        - Transparent water, duh...
        - Support for Hipnitual Extenstions
        - INI file support for commonly used or non-editor supported options
        - Supports brushes with up to 256 sides
        - Supports multiple wad files, up to 32.  This is done by including
          all the wad filenames in your wad property seperated by semicolons
          (ie "wad1.wad;wad2.wad;wad3.wad").  If you are using Worldcraft
          this is handled automatically.
        - Many internal constants are raised, allowing for more complex
          levels.
        - Supports "-leakspace #" option, which allows you to control
          the spacing of the leak trail particles.  2 is the default,
          if you want to make the close together you would put in a small
          number, say 0.5, if you want them more spread out you would put in
          a larger number, say 4.  Do not put in negative numbers or 0!
          This will be idiot proofed in the next version =)
        - Supports "-nowatervis" for those people who think transparent
          water is unfair.  That way I can have an all purpose QBSP.
        - Supports "-alternateaxis" which allows you to choose between
          which axis to use in natural texture mapping.  Default will look
          as it does in Worldcraft.
        - Supports "-ignorecase" which ignores case during texture lookups.
        - Interface is cleaner, and will be moreso in the next version.
        - None of the directory requirements of the original id utils.
        - Many of the map constants increased.

Bugs:
        - None known.

Future plans:
        - Support reconstructing the portal file from the BSP.  BSP2PRT will
          be integrated soon.
        - Fix all the id bugs (tell me what they are!).
        - Implement all user requested features (send em to me!).

Changes from v1.61 to v1.65:
        - Fixed a nasty wad string length problem.  The wad code handled it
          fine, but it ran into a problem writing it to the BSP file
          due to a Quake engine string length limitation.  Now, the full
          wad string is used by QBSP, but only the first 128 characters
          are written to the BSP.
        - Added an option, "-ignorecase" that ignores case while searching
          for textures in the wad file.  Someone requested it...
        - Added support for options read from a file.  Simply put options
          in QBSP.INI in the working directory, and they will be read as if
          they came on the command line.  This allows people to use options
          like "-alternateaxis", "-ignorecase" or such from an editor that
          doesn't directly support them.  Options can be seperated by spaces
          or carriage returns.

Changes from v1.60 to v1.61:
        - Changed Point off Plane from error to warning
        - Actually went back and idiot proofed "-leakspace #"

Changes from v1.50 to v1.60:
        - Fixed the rotation quirk in Carmack's code.  It now defaults to
          matching what you see in Worldcraft, although the other rotation
          mode is still available by using the "-alternateaxis" option.
        - Raised the max token size from 128 to 1024.  This should fix any
          problems with Worldcraft's wad strings.
        - Raised some of the internal constants:
           * MAX_HULL_POINTS  changed from   32 to    64
           * MAX_HULL_EDGES   changed from   64 to   128
           * MAX_MAP_BRUSHES  changed from 4096 to  8192
           * MAX_MAP_ENTITIES changed from 1024 to  2048
           * MAX_MAP_PLANES   changed from 8192 to 16384
          All of these changes were requested by users - I am not entirely
          sure that the Quake engine can handle the increased values, but
          this will only affect maps that actually *use* that much, a map
          within the legal limits will not be affected, even if the constants
          are out of the legal limit.
        - Minor optimizations.
        - Added a help option, -?.  It describes most of the command line
          options.  Due the rush to release this version with the fixed
          rotation, not all of the options have been described.

Changes from v1.10 to v1.50:
        - Fixed a major slowdown issue regarding the handling of sky
          brushes.  Who would have thought people would use them correctly
          (unlike id <g>)?  Levels with large amounts of sky should show
          noticable improvement with this version.
        - Added "-leakspace #" option, see features section for details
        - Fixed the id bug where leakfiles are always 0 length and the
          leak position is incorrectly reported (thanks Yahn Bernier)

Changes from v1.00 to v1.10:
        - Added "-nowatervis", see features section for details
        - Cleaned up the interface a bit

Thanks to:
        - Andy Bay (I couldn't compile it without you <g>)
        - Yahn Bernier (you also need "hit_occupied = l->occupied")
        - autolycus and Deathdealer (umm, yeah...)
        - DJ Delorian (for DJGPP, although whenever I compile with DJGPP
          it crashes on large maps...I have to get Andy to compile it with
          Symantec C++ so that it will work right <g>)
        - Nick Pandher, Gary Tarolli, and the rest of the 3dfx gang (when
          is my Stingray going to work at full speed? =P)
        - Chris Bolin and the PainKeep team (for pointing out the sky
          problem, and putting out an awesome mod)
        - Anyone I've forgotten (how's that for a catch-all?)
