Enhanced TreeQBSP
=================

Main features are :

* Very low memory requirements, typically 10-20% of most other compilers.
* Fast processing, partly due to the low memory requirements.
* Large map capacity; most limits are beyond the Quake engine capacity.
* High precision in floating point calculations.
* MultiWAD (WorldCraft-style) and wildcard support.
* Support for default wad file if no other wads found.
* Support for Valve WAD3 format.
* Support for Hipnotic/Ritual entity rotation.
* Support for enhanced texture positioning in QuArK.
* Support for Valve 220 map format, e.g. from Hammer.
* Support for Q2/Q3 map format, e.g. from GtkRadiant.
* Support for floating point coordinates in map files (e.g. from QuArK).
* Enhanced warning/error messages.
* Enhanced leak handling.
* Progress feedback that works in any console and does not cause performance loss.
* Transparent water support.
* Cleanup of texture names.
* No hull files.
* Log file.
* INI file.

Note : TreeQBSP behaves slightly different than other QBSP variants. To make it behave more like
       the others, the following command line can be used :
      
       qbsp -oldaxis -oldleak [mapname]

       In most cases, the new style leak line (default) is considerably easier to follow in Quake,
       but if it doesn't seem correct (e.g. the line goes right through solid brushes) you might
       want to try the old style line. You can always use the "-leakdist #" option to reduce the
       amount of dots in pointfiles. If Quake cannot load the entire pointfile, use the Quake
       command line option "-particles #" to increase the capacity.

       Also, transparent water is not default (like in TxQBSP), but can be enabled via the
       "-transwater" option. Beware of the performance hit in some maps.

       Some lighting problems might occur when using most light tools together with a compiler
       that supports enhanced texture positioning (e.g. QuArK ETP or Valve 220 Hammer). Light 1.27
       and TyrLite 0.94 (see Tyrann's site below) or later versions support ETP.


Enhanced RVis/Light/BspInfo utilities
=====================================

Main features are :

* Progress feedback that works in any console and does not cause performance loss.
* Large map capacity; most limits are beyond the Quake engine capacity.
* RVis: AutoSave feature for securing long vis runs.
* Light: High quality 4x4 oversampling is available.
* Light: Fast processing using new options.
* Light: Soft anti-aliased shadows using new option.
* Light: Support for Hipnotic/Ritual entity rotation.
* Light: Support for min/maxlight, enhanced sunlight and wait/delay/mangle/antilight keys.
* Light: Emulation of TyrLite/IKLite/ArghLite/LightDLX lighting using new options.
* Light: Enhanced control of light distribution via new options and keys.
* Light: Support for QuArK/Hammer ETP (Enhanced Texture Positioning) using new option.
* BspInfo: Portal (prt) file generation available.
* BspInfo: Statistical light data printout available.
* Enhanced warning/error messages.
* Log file.

Details regarding progress feedback
-----------------------------------

One of the major enhancements is the ability to display progress while running.
This is especially important in the RVis process, since it may require a long time to finish.
There are other variants available (e.g. RVis+, HVis) that can also display progress, but they :

1. Increase total process time significantly.
2. Output a large amount of text and this is bad when running in the console of e.g. QuArK or WC.
3. Do not make any serious attempt to estimate how long time left until the process is finished.
   It is definitely not enough in the Vis process to display the # objects (or percentage thereof)
   that is finished, since the process is non-linear. It is quite normal to have 60% objects done
   but 80% processing time left.

Progress is normally displayed in the form (example from RVis) :

Base:  68.3%, Elapsed:   13:09, Left:    6:43, Total:   19:52,  68%

The "Left" time is a filtered, dynamically calculated linear estimate. It is NOT a 100% reliable
figure, but it _will_ indicate the overall progress. The first percent number displays processed
objects and the last displays estimated time completed.

A new linear coefficient estimation is calculated normally when the integer part of the object
percent value changes, e.g. when 12.9% becomes 13.0%. In some cases, estimations will be done more
often. Intermittent updates will use the previously estimated coefficient.

The progress feedback is always printed between the processing of two portals. In large maps, one
portal can be very slow to process and to avoid complete absence of feedback for a long time, an
extra progress bar has been added. It has the form "----+----+" and is activated when more than 12
times the SecRate (see "-rate" option below) has passed inside processing one portal. The default
time is then 12 * 10 = 120 seconds.

Usually, the bar is not updated in a very linear fashion but it may offer some indication of
progress. Using the "-rate" option with a PercRate value of >= 0.1 will disable the extra progress
bar. When using option "-verbose", the extra progress bar is always displayed for each portal.

With the verbose mode it's also possible to track down the origin of slow portals. Just read the
portal number it's currently working on, divide by 2, add 3 and the resulting value is now a line
number in the portal file (prt). Open this file in an editor, go to the line number and read the
first coordinate on that line. This is one of the vertices of the portal.

The portal translation formula is because there are two memory portals (front and back) for each
file portal and there are three header lines in the prt file before the long list of portals.
Example: if portal number is 12345, then the prt file line number is (12345/2 + 3) = 6175.

There is an option that controls the normal progress feedback, "-rate sec,perc,line,tot".

Explanation :

sec	SecRate, minimum # seconds between screen updates, default 10
perc	PercRate, minimum # percent between screen updates, default 1.0
line	NewLine, new linefeed for each screen update, default 1 (TRUE)
tot	Total, display total estimated time, default 1 (TRUE)

The default setting has been tweaked to suit most situations.

Simplified progress is displayed in one of the following forms (example from RVis) :

Base
----+--

Base
73%

The first is enabled by the "-barpercent" option and the second by "-numpercent". For Light and
RVis Base, the percentage values are here just the object percentage value. For RVis Full, the
values are derived from the object percentage value, but weighted. The weighting is an attempt to
make the progress info more linear and a simple third degree equation curve is used to balance the
percentage values.

The following translation table can be used to obtain the actual object percentage value.

Displayed    Objects	   
   0%	        0%
  25%	       63%
  50%	       79%
  75%	       91%
 100%	      100%

The net result is that the progress is slowed down in the beginning and then sped up to counteract
the typical RVis behaviour.

Details regarding sunlight features in Light
--------------------------------------------

Sunlight is enabled via command line options "-sunlight #" and "-sunmangle #,#" or via
"_sunlight"/"_sun_mangle" keys in worldspawn. _sun_mangle uses the format "# #" (or "# # 0"),
where the first value is the yaw angle (0 to 360 degrees around the Z-axis, negative values are
also OK) and the second value is the pitch angle (90 degrees up to -90 down). Default values are
"0 -90" and the command line overrides worldspawn settings. Note that sunlight is normally not
affected by the "-range" option.

A good start combination is "_sunlight" "250" and "_sun_mangle" "45 -75" and then experiment
for best results. Note that the important thing is normally not to create light, but interesting
shadows.

You can also control how the sunlight is attenuated by its incoming angle for each face by using
the "_anglesense" key in worldspawn. Higher values means more attenuation (darker). Valid float
values are 0-1 with 0.5 as default.

The 2nd sunlight is enabled via command line option "-sunlight2 #" or via "_sunlight2" key in
worldspawn. This 2nd sun is actually many suns automatically positioned in an arrangement with
different yaw/pitch to eliminate bad shadows. When option "-extra" or "-extra4" is enabled, more
suns are used.

This 2nd sunlight value can be used to soften the shadows in outdoor areas from the normal
sunlight without using minlight, which in turn then may be reserved for indoor areas. A value of
60 is a good starting point for the 2nd sunlight if the normal sunlight is 250.

You can also add the "-shadowsense #" option which sets the angle (shadow) sensitivity for 2nd
sunlight (default 0.0). This can reduce the sometimes uniform look of sunlight. Recommended value
is 0.4 together with an increased 2nd sunlight level of about 10. For convenience, you can also
use option "-sunlight3 #" or "_sunlight3" key which just enables 2nd sunlight and at the same time
sets shadow sensitivity to 0.4.

Details regarding wait/delay/mangle/antilight/angle/_softangle/_anglesense features in Light
--------------------------------------------------------------------------------------------

Several keys can be added to a light entity to better control its behaviour. The "wait" key
controls the fade distance and the default value is 1.0. Using a higher value will make the light
fade faster thus making it darker, e.g. "wait" "1.5".

The "delay" key sets the attenuation formulae, possible values are:

0 (default)  - Linear falloff, identical to id's original light program.
1            - Use the 1/x attenuation formula, has wider range than default.
2            - Use the 1/(x*x) attenuation formula, faster falloff than delay 1.
3            - No attenuation (light stays same brightness at any distance).
4            - Local minlight (no attenuation, non-additive and minlight override).
5            - Similar to 2 but with more attenuation and never brighter than "light" value.

Local minlight can be used to have different minlight levels in different areas. Just add these
lights until all corners of an area are lit. Local minlight will never add more light to a face if
it's already sufficiently lit. Just remember that its range is only limited by solid architecture
or using spotlight cone.

Local minlight also override each other (brighter wins) and normal minlight with any level. This
means that they can be used both to brighten or darken (similar to antilights below) areas that
are otherwise controlled by minlight. However, local minlight cannot darken areas that are lit by
normal lights or sunlight. Local minlights open for many possibilities, some experimentation is
recommended here.

The "mangle" key controls the direction of a light, i.e. a spotlight. It has the form "# #" (or
"# # 0"), where the first value is the yaw angle (0 to 360 degrees around the Z-axis, negative
values are also OK) and the second value is the pitch angle (90 degrees up to -90 down), e.g.
"mangle" "45 -75". Also, similar to targeted lights, you can change the width of the spotlight
cone with the "angle" key (default 40 degrees).

For spotlights, you can also specify an inner cone using the "_softangle" key. This creates a
softer transition between full spotlight effect within the inner cone and then gradually lower
effect until reaching the outer cone. This key must be smaller than the angle key and its default
value is 0, which means disabled.

The "_anglesense" key controls how a light is attenuated by its incoming angle for each face.
Higher values means more attenuation (darker). Valid float values are 0-1 with 0.5 as default.
Local minlight can't use this feature and is always 0. Angle sensitivity can also be globally set
from command line but will not override the entity values. See also "-shadowsense #" option above.

Using antilight (lights with negative value) will "cast darkness" with the same rules (wait, delay
etc) as for positive lights. Note that light styles are important here; antilights will only
darken lights with matching light style. Also note that with antilights, you can go below the
ambient (min/sunlight etc) limit. You can't use antilight as ambient lights.

Using the "-oldlight" or "-iklite" options will disable the wait/delay/mangle/antilight features,
using the "-dlx" option will disable the wait/delay/mangle features and using the "-noanti" option
will disable antilights.

Details regarding the softening feature in Light
------------------------------------------------

Adding the "-soft" option can reduce the jagged edges of shadows by slightly softening (blurring)
the lighting. This is especially useful in bright maps with high-contrast shadows.

The option can be used with ("-soft #") or without a value ("-soft"). If used without a value, an
automatic mode is set where the softening value follows the level of oversampling (the "-extra*"
options). If no oversampling is enabled, a value of 1 is used. Together with "-extra" or
"-extra4", a value of 2 or 3 respectively will be used.

Setting the value manually will override the auto mode and is normally not recommended. A higher
value means a softer lighting for the same level of oversampling. Keeping the value in the range
1-5 is recommended, since otherwise visible distortions might appear near face edges. This is due
to the softening being performed separately for each texture face. If distortions appear, either
lower the softening value or manipulate the lighting slightly (yaw/pitch etc) in that particular
area.

Some experimentation might be required here for best results.

The "-soft" option also enables higher tolerance for the directional relationship between each
face and the light sources that cast light on it. Traditionally, a light source is disregarded if
it's on the same plane or behind a face. This may cause some faces to be strangely dark even if a
visible light source is nearby. Enabling the "-soft" option will consider a light source visible
even if it's slightly behind the face.

The distance behind the face is default 3, but can be set using the "-softdist #" option.

Tip : For a very fast but somewhat sketchy lighting, use "-fast -soft". For a very high quality
      but still not too slow lighting, use "-fast -soft -extra4".

Details regarding Light emulation capabilities
----------------------------------------------

Original Light features are supported by default. Use the "-oldlight" option for closer emulation
and to prevent detection of newer features. Setting "-light 0" from the command line can also help
avoiding undesired effects.

Most TyrLite 0.94 features are also supported by default, main exceptions are coloured lighting
and some antilight features. Use the "-tyrlite" or "-tyrlite95" options for closer emulation.
These options enable global range and disable lights in non-light entities (i.e. with a classname
that doesn't begin with "light"). Automatic detection and conversion of the older TyrLite
_sun_mangle format (x y z) is always enabled. Should it fail, override with the "-sunmangle"
option. Light distribution may differ compared to older TyrLite versions.

Use the "-etp" option for maps that are created in QuArK/Hammer using the ETP or Valve 220 format
and built with an ETP capable compiler (e.g. Tx/TreeQBSP). It's probably valid for any editor that
can generate these formats. TyrLite 0.94 and later use this mode for any map.

IKLite emulation is enabled by the "-iklite" option. All features are supported. Emulation is done
by translating the angle keys into corresponding delay keys, adjusting distance attenuation and
setting angle sensitivity for delay 3 lights to 1 and the default range to 1. The range can be
overridden by command line or worldspawn if necessary. As above, setting "-light 0" from the
command line is sometimes required.

ArghLite emulation is enabled by the "-arghlite" option. All features are supported. Emulation is
done by disabling the entity delay feature and enabling additive minlight and global range.

Partial LightDLX emulation is enabled by the "-dlx" option. Only antilights and the "message"
"max #" feature are supported.

Using any of the emulation modes and not having "-extra4" enabled will enforce maximum
compatibility. Enabling "-extra4" will favour quality over compatibility.

Detection of unsupported keys varies with the currently enabled options and should only be
considered a hint. Since several of the entity keys are the same for different light tools, it's
very difficult to always correctly identify the proper emulation. Use the "-unsup" option to
display unsupported key details. Use the "-detect" option to display a summary of detected keys.

Details regarding AutoSave feature in RVis
------------------------------------------

The AutoSave feature makes vis save its state at certain intervals while it's running. If it gets
interrupted for various reasons, you can just restart and it will proceed from the last valid
state. This is very convenient in long vis runs and you e.g. need to shut down the computer or in
case of a power failure.

The default save time is 60 seconds but this can be changed using option "-savetime #". Note that
using a too short interval may prolong the total vis time significantly and may also cause intense
disk activity. Also, the state can only be saved between the processing of two portals. This means
that if vis gets interrupted while processing one slow portal, the time spent in that portal will
be lost.

AutoSave uses a new file "map.vis" (if the map name is "map.bsp") for saving the state. In case of
disrupted state save, there might also be a "map.vi0" file that will automatically be removed when
restarting. For successful restart from a saved state, vis requires the state file (vis/vi0),
the portal file (prt) and the bsp file itself.

Note that if the portal file gets updated (new file date/time stamp), the state file will be
considered out of date and hence not loaded. It will be overwritten at the next state save time.

The same state file is used for both Base ("-fast") and Full ("-level #") sessions, which means
that after a partial or completed Base session, you can start a Full and vis will take advantage
of what's been done already. Conversely, after a partial or completed Full session, you can start
a Base and it will complete immediately. However, you cannot change fullvis level afterwards and
starting with version 2.20, this will be enforced.

There is a "-nosave" option to disable the AutoSave feature altogether.


Tip : When you leave your computer for processing a lengthy operation (e.g. RVis), make sure
      you're using a very simple screen saver (e.g. the one that just makes the screen black).
      Modern CPU intensive screen savers can _easily_ add 50-100% processing time.

