Released: April 8, 1998
======================================================================
Title                   : ArghRad
Filename                : arghrad.exe
Version                 : 1.0

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

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
                          * More misc. options

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

Additional Credits to   : id Software for original source.

Acknowledgments        : Geoffrey DeWan for ideas from gddqrad3
                          (usage syntax unchanged for compatibility).
                          Rich Toleration, Janis Jagars, for ideas
                          from their code used in Quake ArghLite.

Other Works by Author   : ArghLite - enhanced Quake bsp lighting util
                          Q2toWad  - Q2 pak to wad texture extractor

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

Brief listing of new 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

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

   -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

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 for up to 4 suns)
    "_sun_ambient" "#"     - set sun ambient brightness, only one
    "_sun_ambient" "# # #" - alternate 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.  The path must end in a
   slash.
-moddir path
   You can specify an extra mod dir to find textures with this option
   ("-moddir d:\games\quake2\ctf\" for example).  The path must end in
   a slash.

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.

-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)


Patch Subdivision
-----------------
Sometimes surface lighting can appear "blotchy".  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 may only work on the smallest maps.

-choplight #
   This subdivides only surfaces that emit light (except sky and
   warping textures).  This can give much smoother light, with less
   slowdown.  Default is same size as -chop.
-chopsky #
   Works similarly, 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 #
   Also works similarly, 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. -ambient 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.


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 the light
value must be high enough to register as a light (play it safe and use
a value > 20, the specific value isn't 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 averaged from the color and
   brightness of all of the suns.
"_sun_ambient" "# # #"
   This alternate form explicitly specifies the red, green, and blue
   brightness of the ambient light.

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.  See that entry for more
   details.
"_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 right up against a non-sky surface that is on
the same exact plane.  This can make sunlight work improperly there.
These surfaces CAN be on the same exact plane if they are blocked from
each other's view.  Surfaces can always be placed right up against the
sky if they are at different angles.


Negative Light
--------------
Lights can cast darkness.  Just use a negative value for the "light"
key.

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 a used to colorize the
   mottled _minlighta pattern.

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

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

Version 1.0:  April 7, 1998
   * first release

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

Base                    : * "Qrad3" source code from id Software.
                          * ArghLite
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)
