Updated: 2002-05-07
=====================================================================

Title                   : TyrLite
Filename                : tyrlite.exe
Version                 : 0.94

Author                  : Kevin Shanahan
Net Nick                : Tyrann
Web Site                : http://www.planetquake.com/tyrann
Email Address           : tyrann@planetquake.com

Description             : New enhanced version of "light":
                          * Scale fade distances of individual lights
                            (without changing brightness)
                          * Choice of four different attenuation
                            formulas for individual lights
                          * Progress indicator
        [new in 0.2beta]  * Set a global minimum light level
                            (eliminate those totally dark spots)
        [new in 0.3beta]  * Supports Ritual's 'Scourge of Armagon'
                            map extensions
        [new in 0.4beta]  * Lights can cast darkness ('Anti-lights')
        [new in 0.4beta]  * Set spotlight direction by yaw and pitch
        [new in 0.5beta]  * Set a sun angle and brightness so that your
                            outdoor areas can be lit by your skybrushes
	[new in 0.6beta]  * Coloured lights !!
        [new in 0.7beta]  * Added option '-nominlimit'
        [new in 0.8beta]  * Some extra output for tracking down "too many
                            light styles on a face" warnings.
                          * Now licensed under the GNU GPL
	[new in 0.92]	  * .lit support
	[new in 0.93]     * support for QuArK style texture alignment

Requirements            : Pentium compatible processor, A Win32 operating
                          system (e.g. WinNT, Win95/98)

Additional Credits to   : id Software & Ritual Entertainment for
                          their source code,
                          Tim 'Argh!' Wright for "ArghLite",
                          Iikka 'fingers' Keranen for "IKLite"

=====================================================================

* Usage *

If you have ever used ArghLite (by Tim Wright) or IKLite (by Iikka
Keranen) before then most of this will seem very straight forward.

TyrLite's fade distance feature behaves identically to Arghlite's,
so any map that you can compile with ArghLite, you can compile
identically with this.

The attenuation formulae feature behaves identically to the one
provided in IKLite, provided that you make the appropriate key/value
substituions. IKLite uses the "angle" key to set the attenuation
formulae, but this means your use of spotlights is restricted.
TyrLite uses the "delay" key to avoid this. Also note that the number
values correspond to different formulae (I thought it was more
intuitive this way). Read the sections below for specifics.

--------------
Fade distance
--------------
To modify the fade distance of a light, add a new key of the form
"wait" "n", where n is the number to scale the distance.  N>1 will
make the light fade faster, n<1 will make it fade slower (just like
the -dist command line parameter).  

For example, n=2 would make the
light fade out at twice the normal distance and similarly n=0.5
would make the light fade out at half the normal distance.

---------------------
Attenuation Formulae
---------------------
You can select from four different attenuation formulae for a light.
To do this, add a new key of the form "delay" "n", where n is an
integer from 0-3, described below:

n=0 (default)  - Linear falloff, identical to id's original light
                 program.
n=1            - Uses the 1/x attenuation formula.
n=2            - Uses the 1/(x^2) attenuation formula.
n=3            - No attenuation. (light stays same brightness at
                 any distance).

----------------
Coloured Lights
----------------
Tyrlite now supports coloured lighting.

*** IMPORTANT ***

The original quake engine does not have the necessary features to support
coloured lighting, so to use maps with coloured lighting, you need to
download a suitable quake engine. A good place to start looking is:
  http://www.quakesrc.org

To enable coloured lighting in TyrLite, you will need to add to the
command line one of "-bsp30", "-lit" or "-colored". If this is omitted,
tyrlite will ignore the coloured lighting information in the map file
and produce a standard BSP.

Because of the way things evolved, there are two file formats used for
colored lighting. One is the "bsp30" format, which stores the lighting
information inside the bsp file, but makes the map incompatible with
older engines. The other format is ".lit" which stores the lighting info
in an external file "mapname.lit", leaving the bsp file compatible with
older engines.

You can select the output format you want to use on the command line by
adding either "-bsp30" or "-lit" ("-colored" defaults to bsp30 format
for backwards compatability).

Note that when using the bsp30 format, compiling a map with colored
lighting changes the BSP's version number from 29 to 30. Because of
this, you should always make lighting the _last_ stage of your
compilation process (when using color). If you don't, your other
programs (e.g. vis.exe) will most likely refuse to compile the map.

*** Ok, now the fun stuff =) ***

You can set an RGB (Red/Green/Blue) colour field in each light entity
in the map. To do this simply add to the light, a key of the form:

   "_color" "# # #"

Here, the "# # #" are three integers between 0 and 255, representing
the amount of red, green and blue light repectively. Try to keep the
values as high as you can while still maintaining the ratio of the
three colours. For example if you want a glaring green light, dont use
"0 1 0", because it will be VERY dark. Use "0 255 0" instead.
As a general rule, give the dominant colour the value 255 and just
change the other two colours until it looks right.

You can also set the colour of the sunlight and the 'minlight' - these
are described properly in their respective sections. For a few other
'nifty' tricks with coloured lights, read the antilight section below.

-----------
Antilights
-----------
Lights can now cast darkness!  Just set the brightness to a negative
number.  These "antilights" will only darken lights of the same
style.  For instance, a normal antilight will darken other normal
lights, but wouldn't affect a flickering light.

Coloured antilights? Sure! If you give a coloured light a negative
light value, it will "soak up" light of that colour. If you want to
be even more clever, you can give the "_color" key some negative
values too. For example, if you set "_color" "255 -255 0", with a
positive light value, the light will cast red light, and at the same
time, soak up green light. If you give the same colour values, but
a negative light value, the light will cast green, and soak up red.
Experiment and see what else you can do.

Ordinarily antilights won't fade the light level any lower that the
level's minimum lighting level. Sometimes you may want this to happen
though, so you can enable this with the command line switch -nominlimit

-------------------
Spotlight Yaw/Pitch
-------------------
Spotlights can be optionally aimed by specifying yaw and pitch
values, instead of targeting an info_null entity.  Add a new key in
the form "mangle" "# # 0".  The first # is the yaw angle, 0 to 360
degrees around the Z-axis.  The second # is the pitch angle, 90 to
-90 degrees up to down.  The 0 is just a required placeholder.

Example:
   {
   "classname" "light"
   "origin"    "100 50 150"
   "light"     "200"
   "mangle"    "45 -20 0"
   }

-----------------
Minimum lighting
-----------------
Setting a minimum light level allows you to eliminate any spots in
your map that you feel are too dark, without affecting the brightness
of any of the lights in the level.

There are two ways to set the minimum light level.  The first is by
adding a new key in the form "light" "n" to the map's "worldspawn"
entity, where n is the minimum light value.  Example:
   {
   "classname" "worldspawn"
   "wad"       "quake101.wad"
   "light"     "20"
   }

The second method is by using the command line parameter -light n,
where n is the minimum light value.  The command line option
overrides any value set in "worldspawn". For example:

   C:\>TyrLite.exe -light 10 example.bsp

You can also set the colour of the "minlight". This is an option
that you will want to only use with care, otherwise your map will be the
same colour everywhere. To enable this feature, add a key to the worldspawn
of the form: "_minlight_color" "# # #", where "# # #" is the RGB value as
usual. Colours close to white are likely to be best here.

---------
Sunlight
---------
You can set the brightness of the sun, as well as the direction of
the incoming light and any sky brush will cast light in that direction.

To set the brightness of the sunlight, add a new key in the worldspawn
of the form: "_sunlight" "#", where # is an integer value the same as for
any other light. To set the direction of the incoming sunlight, add a key
of the form: "_sun_mangle" "# # 0".  As with spotlights above, the first
# is the yaw angle, 0 to 360 degrees around the Z-axis. The second # is
the pitch angle, 90 to -90 degrees up to down.  The 0 is just a required
placeholder.

You can also specify a colour for the sunlight. Add to the worldspawn, a
key of the form "_sunlight_color" "# # #", with "# # #" as the RGB values
for the desired colour. As with minlight, a subtle effect is probably best
here. For example you might just add a tint of blue to the sunlight colour
to give a feeling of early dusk...

-----
Other
-----
Note that the above features can be used in any combination.
For example, you could have a light with fields like this:
   {
   "classname" "light"
   "origin"    "100 50 150"
   "light"     "200"
   "wait"      "3"
   "delay"     "2"
   }
Which would give an attenuation formula: 1/((3x)^2)


There are two other command line options:
-nocount  - Disables the progress indicator. Use this if you want
            to run the program from inside Worldcraft.
-compress - If you don't understand this, don't worry. It's only
            useful in rare circumstances.
            Basically, after lighting the map, it removes all
            key/value pairs from the light entities in the bsp
            (no, it won't affect the map file) except for
            'classname' and 'origin'. Try using this if you start
            getting 'entity text too long' errors.


The original command line options still work:
-extra    - Turns on extra sampling for smoother lighting/shadows.
-dist n   - Scales the fade distance of ALL lights.  N>1 fades 
            faster, n<1 fades slower.  A light with a "wait" will be
            scaled once for that, then scaled again by -dist.
-range n  - Scales the brightness range of ALL lights without
            affecting their fade distance.  N>.5 makes them brighter,
            n<.5 makes them darker.  Can achieve the same affect on
            individual lights by increasing or decreasing both the
            brightness and "wait" factors.

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

Base                    : Quake light source code from id
                          Software and Ritual Entertainment.
                          Features were inspired by "Arghlite" by
                          Tim Wright and "IKLite" by Iikka Keranen,
                          however modifications are completely
                          original.
                          (Some of the explanation in this text file
                           is however, only slightly modified from Tim
                           Wright's arghlite explanations).

Compiler used           : Microsoft VC++ 5.0
Known Issues            : None

=====================================================================

===========
Changelog:
===========
v0.94
 - small speed improvement on previous texture alignment stuff
 - added check for tracestack overflow
 - some cleanups, local functions made static, more const stuff

v0.93
 - Correctly calculate sample points for surfaces using non-standard
    texture alignment (e.g. Different texture alignment possible using
    QuArK).

v0.92
 - Added .lit support
 - Added some checks for entity key/value lengths
 - Added check for too many switching lights

v0.91
 - Fixed bug with "-nominlimit" option when not using colored lights.
 - Had to change project settings optimisation to "minimize size",
    since "maximise speed" was causing corruption of facenormals in my
    test map.

v0.90
 - Downgraded "not 3 values for color" to a warning for compatability
    with some QC mods.

=====================================================================

* Copyright / Permissions *

TyrLite is licensed under the GNU GPL. See the file COPYING for details.
The source code used to build this executable is available from:
http://www.fileplanet.com/dl/dl.asp?tyrann/utils/tyrlite-0.92-src-GPL.zip

* Disclaimer *

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

(Okay, with that officially stated... I can say you probably have
nothing to worry about.  This is as stable as id's or Ritual's
versions.  If those didn't do anything nasty to ya, this isn't likely
to either. :)
