Released: March 19, 1999
======================================================================
Title                   : ArghRad
Filename                : arghrad.exe
Version                 : 2.01

Author                  : Tim Wright
Net Nick                : Argh!
Email Address           : argh@ntplx.net
                          (comments, questions, bug reports, etc.
                          welcome... flames aren't ;)
ArghRad WWW             : http://www.planetquake.com/arghrad/

Description             : Enhanced version of Qrad3:
                          * Load textures from paks, supports optional
                             mod dir
                          * Better patch subdivision control
                          * Sunlight options
                          * Extensive light falloff control
                          * New spotlight aiming methods
                          * Negative lights/colors
                          * Entity brush models can cast light,
                             provides many more surface light options
                          * Eliminates many qrad3 lighting bugs
                          * Light unvised maps
                          * Phong shading for simulating curves
                          * More misc. options
                          (note: Heretic2 support, and plugin effects
                           have been postponed until the next major
                           version)

Requirements            : Pentium, A Win32 operating system, and
                          whatever the requirements are for
                          id's Qrad3.

Additional Credits to   : id Software for original source.
                          Ritual for FreeDirectLights() code

Acknowledgments         : Geoffrey DeWan for ideas from gddqrad3
                           (usage syntax kept for compatibility).
                          Rich Tollerton, Janis Jagars, for ideas
                           from their code used in Quake ArghLite.
                          Michael Meadows for creating the ArghRad
                           web site.
                          Mr Elusive for major help on eliminating
                           light bleeds.
                          John Fitzgibbons for help on eliminating
                           black-band & splotch sky/liquid light bugs

Other Works by Author   : ArghLite - enhanced Quake bsp lighting util
                          Q2toWad  - Q2 pak to wad texture extractor
                          Doom3D   - Q2 TC, webpage:
                                     http://www.planetquake.com/doom3d

======================================================================
* Overview *

Brief listing of options.  See manual below for full details.
Note: You may need to rename ARGHRAD.EXE to QRAD3.EXE to get it to
work with some map editors.

Command Line Options
--------------------
   -gamedir path - path to quake2\baseq2\
   -moddir path  - path to optional mod dir

   -nobmodlight  - turn off entity brush model lighting
   -nocurve      - turn off phong shading
   -nosplotchfix - turn off anti-splotch fix for normal surface light
   -nostopbleed  - turn off light-bleed checking

   -nocolor  - disable colored lighting, weighted results
   -nocoloru - disable colored lighting, unweighted results

   -chopcurve # - subdivide curve patches into size # units
   -choplight # - subdivide light patches into size # units
   -chopsky #   - subdivide sky light patches into size # units
   -chopwarp #  - subdivide warping light patches into size # units

   -ambienta #  - global ambient brightness, absolute scale
   -minlight #  - same as -ambient
   -minlighta # - same as -ambienta
   -maxlighta # - maximum light brightness, absolute scale
   -nominlimit  - let negative light darken minlight

   -radmin # - sets the radiosity minimum transfer threshold

   -onlybounce - only save bounced light

Map Entries
-----------
worldspawn:
   "light" "#"        - set ambient brightness to #
   "light" "# # #"    - alternate form, separate RGB brightness
   "_ambient" "#"     - same as "light"
   "_ambient" "# # #" - same as alternate form of "light"

   "_sun_light" "#"       - set sun brightness to #
   "_sun" "target"        - sun angle = spotlight pointing to target
   "_sun_target" "target" - same as "_sun"
   "_sun_angle" "# #"     - set sun angle by yaw/pitch
   "_sun_mangle" "# #"    - same as "_sun_angle"
   "_sun_vector" "# # #"  - set sun angle by direction vector
   "_sun_color" "# # #"   - set sun color
   "_sun_diffuse" "#"     - diffuse light brightness
   "_sun_difwait" "#"     - diffuse light attenuation
   "_sun_diffade" "#"     - same as "_sun_difwait"
     (all the ABOVE sun keys can be prefixed by either _sun, _sun2,
     _sun3, or _sun4, allowing up to 4 separate suns)
   "_sun_ambient" "#"     - set sun ambient brightness
   "_sun_ambient" "# # #" - alternate form, separate RGB brightness
   "_sun_surface" "#"     - set sun surface brightness
   "_sun_surface" "# # #" - altername form, separate RGB brightness

point lights:
   "light" "#"      - # can be negative, casting darkness
   "_color" "# # #" - any # can be negative for mixed light/darkness

   "_mangle" "# #"       - aim spots by yaw(0-360) & pitch(-90-90)
   "_spotangle" "# #"    - same as "_mangle"
   "_spotvector" "# # #" - aim spotlights by direction vector
   "_spotpoint" "# # #"  - aim spotlights at global coordinate point
   "_focus" "#"          - cone attenuation for spotlights

   "_falloff" "#" - 0=linear, 1=inverse, 2=inverse square

   "_wait" "#"    - light distance attenuation
   "_fade" "#"    - same as "_wait"
   "_angwait" "#" - light angle attenuation
   "_angfade" "#" - same as "_angwait"

bmodel lights:
   "light" "#"      - force light-emitting faces use this brightness
   "_lightmin" "#"  - minimum brightness for light-emitting faces
   "style" "#"      - light-emitting faces use this style
   "_color" "# # #" - light-emitting faces use this color
   "_focus" "#"     - similar to spotlights, in direction of face

   "_minlighta" "#"   - like "_minlight", but uses absolute scale
   "_ambient" "#"     - ambient brightness for bmodel
   "_ambient" "# # #" - alternate format, separate RGB values

======================================================================
* Manual *

Texture Handling
----------------
-gamedir path
   ArghRad can be run from anywhere by using this command line option
   to specify the path to the baseq2 dir.
-moddir path
   You can specify an extra mod dir to find textures with this option
   ("-moddir d:\games\quake2\ctf\" for example).

If textures (or the colormap.pcx) aren't unpacked, ArghRad will search
for them inside the pak files (up to 10 paks in gamedir or moddir).
Search order is: moddir unpacked, moddir pak9.pak-pak0.pak, gamedir
unpacked, gamedir pak9.pak-pak0.pak.


Lighting Behavior
-----------------
-nobmodlight
   ArghRad allows entity brush models to cast surface light (see that
   section for more details).  Use this option to disable it.
-nocurve
   By default, ArghRad will perform phong-shading on surfaces
   configured for it (see that section for more details).  Use this
   option to disable it.
-nosplotchfix
   Normally, ArghRad takes extra measures to reduce the "splotchy" 
   lighting often seen near light-emitting surfaces.  This can really 
   improve the appearance of sky/warping surface lights, but might 
   cause undesirable results with normal surface lights.  This option 
   disables these measures for normal surface lights (however, they
   are still always applied to sky/warping surfaces)
-nostopbleed
   ArghRad defaults to using special checking to stop light from
   "bleeding" through solid walls.  It can greatly improve the map's
   appearance, although it may cause occasional minor lighting
   distortions at brush edges.  This option disables the checking if
   desired. (the qbsp3 -noweld option makes the light distortions
   much more obvious and frequent, if you must use -noweld then
   -nostopbleed is recommended)

-nocolor
   Colored lighting can be disabled with this options.  The RGB values
   are weighted according to B/W TV luminance (green brighter than red
   which is brighter than blue).
-nocoloru
   Same as -nocolor, except the RGB values are unweighted (all the
   same brightness)

-radmin #
   Radmin sets the transfer threshold for bounced light.  It defaults
   to 0.  Greater values can dramatically reduce memory usage and
   rendering time at the cost of quality.  It is somewhat tricky to
   use, as it can change the lighting's appearance in unpredictable
   ways.  Low values (<0.01) generally look best.

-onlybounce
   This option tells ArghRad to only save the bounced light.  It was
   added to help ArghRad development, and probably has little
   practical use in map making.


Phong Shading
-------------
ArghRad can use phong shading to simulate curved surfaces.  This
option is assigned to individual faces.  To make ArghRad use phong
shading on a face, give it a light value, but do NOT set the light
flag.  That face will be smoothed together with all touching faces
that have the same value.  Think of this value as a "curve ID tag".
Try to use unique values for unconnected curves because that will
speed up compiling.

Note that Quake2 isn't exactly designed with curves in mind, and so
you may see occasional "breaks" in the smooth lighting.  Also, this
shading has no affect on the in-game dynamic lights (like the blaster
glow, etc).


Patch Subdivision
-----------------
Sometimes surface lighting can appear "blotchy", uneven.  All surfaces
are divided up into patches which are used to calculate light radiated
from that surface.  The default patch size is 64 units square.  This
could always be decreased with -chop for smoother lighting, but the
cost in speed is huge, and increases the chance of qrad3 bombing with
a MAX_PATCHES error.  ArghRad provides new options to only subdivide
specific types of surfaces.

-chopcurve #
   This subdivides only surfaces configured for phong shading.
   Default is 32, or the -chop size, whichever is smaller.  If your
   map has a very large number of curves, you may want to increase
   this value to speed things up and avoid the MAX_PATCHES error.
-choplight #
   This subdivides only surfaces that emit light (except sky and
   warping textures).  This can give much smoother lighting, with less
   slowdown.  Default is the same size as -chop.
-chopsky #
   Works like -choplight, but only on sky surfaces that emit light.
   This is a separate option because skies often cover large areas,
   and one might not wish to subdivide them as much.
-chopwarp #
   Works like -choplight, but only for warping surfaces like water.


Global Lighting
---------------
The old -ambient and -maxlight work a bit strange.  They require a
decimal from 0 to 2 which is multiplied by 128 to get the brightness.

-minlight #
   Just a new synonym for -ambient.
-ambienta #
-minlighta #
   These options are identical.  These work on an absolute scale to
   set ambient light value (i.e. -ambienta 15 sets the ambient to 15)
-maxlighta #
   Also works on an absolute scale to set maximum brightness.

Ambient lighting can also be specified in the "worldspawn" entity.
This adds the option of colored ambient light.

"light" "#"
"_ambient" "#"
   Sets the ambient brightness to #.
"light" "# # #"
"_ambient" "# # #"
   Alternate format, individually sets the red, green, and blue
   ambient brightness.

By default, negative lights will not go darker then the minlight
value.  You can allow it to do so with the -nominlimit command line
option.


Sunlight
--------
ArghRad provides options to create more realistic directional
sunlight.  Sunlight is cast from all light-emitting sky surfaces.
That means these surfaces must have the light flag set, and a light
value.  The specific value isn't normally used, it just lets ArghRad
know to cast sunlight from that surface.  These keys are all placed in
"worldspawn".  Missing keys are filled in with defaults.  If none of
these keys exists, ArghRad uses normal surface lighting.

"_sun_ambient" "#"
   Sets sun ambient brightness.  This value is added to every point
   that can see the sky.  The color is calculated from the colors of
   all of the suns.
"_sun_ambient" "# # #"
   This alternate form explicitly specifies the red, green, and blue
   brightness of the ambient light.

"_sun_surface" "#"
   Sets the brightness of sun surface lighting.  This allows combining
   normal surface lighting with sunlight (which often looks nicer than
   _sun_ambient).  The color is calculated from the colors of all the
   suns.  If this value is set to 1.0, then the brightness values of
   the actual surfaces will be used instead.
"_sun_surface" "# # #"
   This alternate form explicitly specifies the red, green, and blue
   brightnesses of the surface light.  If all three values are less
   than or equal to 1.0, then it will be treated like an RGB color,
   and the brightness values of the actual surfaces will be used
   instead.

The rest of the sun options can start with _sun, _sun2, _sun3, or
_sun4, allowing up to four suns at once.  The descriptions below all
use _sun.

"_sun_light" "#"
   Sets sun brightness.  Distance does not affect sunlight.  Defaults
   to 200.

"_sun" "target"
   Target is name of an info_null.  To set the angle, create a
   spotlight and target it at the same info_null.  The sun angle will
   match the direction of the spotlight.
"_sun_angle" "# #"
"_sun_mangle" "# #"
   These options are identical.  This sets the sun's angle by yaw and
   pitch, like "_spotangle" for spotlights.  It is the direction that
   the sunlight is cast, not where the sun is in the sky.
"_sun_vector" "# # #"
   This sets the sun's angle by a direction vector, like "_spotvector"
   for spotlights.  See that entry for more details.

"_sun_color" "# # #"
   This sets the color of the sun.  Defaults to the color of the sky
   surface.

"_sun_diffuse" "#"
   Sets the brightness of diffuse sunlight.  This simulates sunlight
   on a hazy day by making it appear fuzzed out around the edges.
   This can't be brighter than "_sun_light".
"_sun_difwait" "#"
"_sun_diffade" "#"
   This scales the fade distance of diffuse sunlight.  # > 1.0 makes
   it fade out faster, # < 1.0 makes it fade out slower.  Note that
   decreasing -chopsky may be necessary to get acceptable results from
   larger #s.

Do not put a sky surface on the same plane as a non-sky surface if
they have a direct line of sight to each other.  This can make
sunlight work improperly there.  As long as the direct line of
sight is blocked by other brushes, this is not a problem.


Negative Light
--------------
Lights can cast darkness.  Just use a negative value for the "light"
key.  Negative lights will only affect other lights of the same style.

The "_color" key can also accept negative numbers for any of the
values.  This can even be used to mix light/dark casting from the same
light.


Light Attenuation
-----------------
"_falloff" "#"
   This can change the falloff type of point lights.  A value of 0 is
   linear (the default).  2 is inverse square, the same as surface
   lights.  This appears much darker than linear falloff, so the
   brightness must be scaled accordingly.  1 is inverse, sort of a
   compromise between 0 and 2.

"_wait" "#"
"_fade" "#"
   These options are identical.  For linear falloff, these scale the
   fade distance of the light without changing its brightness.  # >
   1.0 makes the light fade out faster, # < 1.0 makes it fade out
   slower.

"_angwait" "#"
"_angfade" "#"
   These options are identical.  These scale the intensity of light
   based on the angle it strikes a surface.  # > 1.0 make the light
   fade faster as the angle faces away from the light.  # < 1.0 makes
   it fade slower.


Spotlights
----------
"_mangle" "# #"
"_spotangle" "# #"
   These options are identical.  They aim spotlights by yaw and pitch
   angles.  The first angle goes from 0 to 360 degrees around the z
   axis.  The second angle goes from -90 (straight down) to 90
   (straight up).
"_spotvector" "# # #"
   This aims spotlights by a direction vector (x,y,z).
"_spotpoint" "# # #"
   This aims spotlights at a global coordinate point.  It's similar to
   targeting by info_null without needing an info_null entity.

"_focus" "#"
   This works similar to "_angwait" for all point lights, but only in
   the direction of the spotlight.  This can create a smoothly fading
   cone, which can considerably cut down on the often-seen jagged
   edges.


Entity Brush Model Lights
-------------------------
Entity brush models now can emit light, opening up many new options
for surface lights.  Func_wall is probably the best entity to use for
these lights.  Be aware that these brushes still do not cast shadows,
so creative editing may be needed to achieve the proper effects.

"light" "#"
   If the "light" key is present, it will override the light value
   of the individual faces.

"_lightmin" "#"
   This sets a minimum brightness for light-emitting faces.  This
   can be used to make a surface appear to glow brighter without
   giving off as bright light.

"_color" "# # #"
   This sets all light-emitting surfaces on the brush to cast this
   color light.  If possible, select a similarly-colored texture for
   a more logical appearance.

"style" "#"
   This sets all light-emitting surfaces on the brush to cast this
   light style.

"_focus" "#"
   Similar to spotlights (see that entry for more details), this
   affects the angle fade in the direction of the light-emitting
   surface.  Because of the nature of surface lights, be aware that
   large values may cause unanticipated results.

"_minlighta" "#"
   Like -ambient, "_minlight" uses an unusual brightness scale.  This
   key works like "_minlight" but uses an absolute scale like
   -ambienta.
"_ambient" "#"
   This is similar to _minlighta, except it actually adds a solid
   ambient brightness to the whole brush.
"_ambient" "# # #"
   This alternate form specifies separate red, green, and blue
   ambient brightness.  This can even be used to colorize the
   mottled _minlighta pattern.


Lighting Unvised Maps
---------------------
ArghRad will now calculate the lighting from all direct lights in
unvised maps.  This includes maps that leak.  It essentially does a
-bounce 0 without the help of the vis data.  Note that this often
takes much longer to calculate.  This ability has been added to help
during the map creation process.  The final versions of maps should
always be leak-free and fully vised.


======================================================================
* History *

Version 2.01: March 19, 1999
   * program: added -nosplotchfix command line option
   * text: added -nosplotchfix info

Version 2.00: March 2, 1999
   * program: added phong shading
   * program: added _sun_surface feature
   * program: rewrote sunlight code to be more efficient
   * program: rewrote anti-light-bleed code to improve quality
   * program: fixed qrad3 black-band & splotchy sky/liquid light bugs
   * program: fixed qrad3 surface #0 bounced light bug
   * program: improved command-line option output
   * program: removed some now-unused qrad3 code
   * text: added new feature info, made minor tweaks elsewhere
   * text: added John Fitzgibbons to acknowledgments

Version 1.50: November 2, 1998
   * program: added direct-lighting of unvised maps
   * program: added FreeDirectLights() to reclaim memory
   * program: added light-bleed checking and -nostopbleed
   * program: tweaked speed and memory use in some areas
   * program: added -radmin cutoff
   * program: rewrote texture handling code to be more efficient
   * text: added new feature info, made minor tweaks elsewhere
   * text: added Mr Elusive to acknowledgments

Version 1.03b:  September 17, 1998
   * program: fixed -moddir to read all pak#.pak
Version 1.03:  September 17, 1998
   * program: fixed ambient & minlight bug from original qrad3
   * program: tweaked -gamedir/-moddir to not require final backslash
   * text: _sun_angle clarification

Version 1.02:  August 24, 1998
   * program: fixed spotlight _focus lighting bug
   * program: fixed bad _ambient lighting in worldspawn
   * text: added -nominlimit info
   * text: added Michael Meadows to acknowledgments, added webpage URL

Version 1.01:  April 30, 1998
   * program: eliminated crashes with multiple suns using _sun aiming
   * program: fixed -chop* and -nobmodlight settings messages
   * program: fixed the spelling of "square" in verbose mode
   * text: corrected Rich Tollerton's name in acknowledgments
   * text: negative light clarification

No version change:  April 8, 1998
   * text: -gamedir/-moddir correction
No version change:  April 7, 1998
   * text: sunlight correction

Version 1.0:  April 7, 1998
   * first release

======================================================================
* Construction *

Base                    : * "Qrad3" source code from id Software.
                          * ArghLite
                          * Ritual SiN qrad3 source (FreeDirectLights)
Compiler used           : Microsoft VC++ 4.0
Construction time       : A while ;)

======================================================================
* Copyright / Permissions *

You MAY distribute this EXE, provided you include this file, with no
modifications.  You may distribute this file in any electronic format
(BBS, Diskette, CD, etc.) as long as you include this file intact.

* Disclaimer *

Usage of ArghRad is at your own risk.  I accept NO responsibility
for any form of damage incurred through the usage of this program.

======================================================================
* Where to get this Utility *

ftp://ftp.cdrom.com/pub/quake2/utils/level_edit/bsp_builders/
 arghrad.zip (and all mirrors)
http://www.planetquake.com/arghrad/files.html
