353 lines
14 KiB
Plaintext
353 lines
14 KiB
Plaintext
Updated: 2007-09-23
|
|
=====================================================================
|
|
|
|
Title : TyrLight
|
|
Filename : light.exe
|
|
Version : 0.99d
|
|
|
|
Author : Kevin Shanahan
|
|
Net Nick : Tyrann
|
|
Web Site : http://disenchant.net
|
|
Email Address : tyrann@disenchant.net
|
|
|
|
Description : Enhanced version of id software's "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.92] * .lit support
|
|
[new in 0.93] * support for QuArK style texture alignment
|
|
|
|
Requirements : Compiles and works for me on Windows & Linux (x86)
|
|
|
|
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.
|
|
|
|
TyrLight'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.
|
|
TyrLight 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
|
|
----------------
|
|
Tyrlight 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 TyrLight, you will need to add to the
|
|
command line one of "-bsp30", "-lit" or "-colored". If this is omitted,
|
|
tyrlight 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:\>tyr-light.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 : GCC / MinGW / MSYS
|
|
Known Issues : None
|
|
|
|
=====================================================================
|
|
|
|
===========
|
|
Changelog:
|
|
===========
|
|
v0.99d
|
|
- Fix memory allocation for "-lit" style colored lighting
|
|
|
|
v0.99c
|
|
- No changes to light; source code re-packaged with other tyr-utils.
|
|
|
|
v0.99b
|
|
- Fix .lit support, broken in v0.99
|
|
|
|
v0.99
|
|
- allocate more bsp memory dynamically, allowing larger bsp's to compile
|
|
properly.
|
|
|
|
v0.98
|
|
- Downgraded "not 3 values for color" to a warning for compatability
|
|
with some QC mods (Again - problem was re-introduced in 0.95)
|
|
|
|
v0.97
|
|
- Improve accuracy of lighting on the edges of odd-shaped polygons by using
|
|
the centroid as the face midpoint when adjusting the sample points.
|
|
|
|
v0.96 (source only - no binary changes)
|
|
- Compile fix for newer GCCs
|
|
- Don't ship with -Werror in the Makefile
|
|
|
|
v0.95
|
|
- Whitespace cleanups
|
|
- Raised limits for miptex, lightmap data
|
|
- Experimental fix for "sunlight parallel to surface" case (compiled out)
|
|
|
|
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 *
|
|
|
|
TyrLight is licensed under the GNU GPL. See the file COPYING for details.
|
|
|
|
|
|
* Disclaimer *
|
|
|
|
Usage of TyrLight 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. :)
|