LIGHT(1)                    General Commands Manual                   LIGHT(1)



NAME
       light - Caclulate lightmap data for a Quake BSP file


SYNOPSIS
       light [OPTION]... BSPFILE


DESCRIPTION
       light  reads a Quake .bsp file and calculates light and shadow informa-
       tion based on the entity definitions contained in the .bsp.   The  .bsp
       file  is  updated  with the new light data upon completion, overwriting
       any existing lighting data.


OPTIONS
       -threads n
              Set number of threads explicitly. By default light will  attempt
              to detect the number of CPUs/cores available.

       -extra Calculate  extra  samples  (2x2)  and  average  the  results for
              smoother shadows.

       -extra4
              Calculate even more samples (4x4) and average  the  results  for
              smoother shadows.

       -light n
              Set   a  global  minimum  light  level  for  style  0  (default)
              lightmaps. Overrides default light level set in worldspawn.

       -addmin
              Changes the behaviour of minlight.  Instead  of  increasing  low
              light levels to the global minimum, add the global minimum light
              level to all style 0 lightmaps.   This  may  help  reducing  the
              sometimes uniform minlight effect.

       -dist n
              Scales the fade distance of all lights by a factor of n.  If n >
              1 lights fade more quickly with distance and if n  <  1,  lights
              fade more slowly with distance and light reaches further.

       -range n
              Scales  the  brightness  range  of  all lights without affecting
              their fade discance.  Values of n > 0.5  makes  lights  brighter
              and  n  <  0.5 makes lights less bright.  The same effect can be
              achieved on individual lights by adjusting both the "light"  and
              "wait" attributes.

       -gate n
              Set  a  minimum  light level, below which can be considered zero
              brightness.  This can  dramatically  speed  up  processing  when
              there are large numbers of lights with inverse or inverse square
              falloff. In most cases, values less than 1.0 will cause no  dis-
              cernable visual differences.  Default 0.001.

       -soft [n]
              Perform  post-processing on the lightmap which averages adjacent
              samples to smooth shadow edges.  If n is  specified,  the  algo-
              rithm will take 'n' samples on each side of the sample point and
              replace the original value with the average. e.g. a value  of  1
              results  in  averaging a 3x3 square centred on the original sam-
              ple. 2 implies a 5x5 square and so on.  If -soft  is  specified,
              but  n  is  omitted,  a  value will be the level of oversampling
              requested. If no oversampling, then  the  implied  value  is  1.
              -extra  implies  a  value of 2 and -extra4 implies 3.  Default 0
              (off).

       -anglescale | -anglesense
              Set the scaling of sunlight brightness due to the angle of inci-
              dence   with   a  surface  (more  detailed  explanation  in  the
              "_anglescale" key below).

       -lit   Force generation of a .lit file, even if your map does not  have
              any coloured lights. By default, light will automatically gener-
              ate the .lit file when needed.


MODEL ENTITY KEYS
   Worldspawn Keys
       The following keys can be added to the worldspawn entity:


       "light" "n"
              Set a global minimum light level of "n" across  the  whole  map.
              This  is  an  easy way to eliminate completely dark areas of the
              level, however you may lose some contrast as a  result,  so  use
              with care. Default 0.


       "_sunlight" "n"
              Set  the brightness of the sunlight coming from an unseen sun in
              the sky.  Sky brushes (or more accurately  bsp  leafs  with  sky
              contents)  will  emit  sunlight  at  an  angle  specified by the
              "_sun_mangle" key.  Default 0.


       "_sun_mangle" "x y z"
              Specifies the direction of sunlight using yaw(x),  pitch(y)  and
              roll(z)  in  degrees.  Yaw specifies the angle around the Z-axis
              from 0 to 359 degrees and pitch  specifies  the  angle  from  90
              (straight up) to -90 (straight down). Roll has no effect, so use
              any value (e.g. 0).  Default is straight down ("0 -90 0").


       "_sunlight_color" "r g b"
              Specify red(r), green(g) and blue(b) components for  the  colour
              of  the  sunlight.  RGB  component values are between 0 and 255.
              Default is white light ("255 255 255").


   Model Entity Keys
       The following keys can be used on any entity with a brush model:


       "_minlight" "n"
              Set the minimum light level for any surface of the brush  model.
              Default 0.


       "_mincolor" "r g b"
              Specify  red(r),  green(g) and blue(b) components for the colour
              of the minlight. RGB component values are  between  0  and  255.
              Default is white light ("255 255 255").


       "_shadow" "n"
              If  n  is  1,  this  model will cast shadows on other models and
              itself (i.e. "_shadow" implies "_shadowself").  Note  that  this
              doesn't  magically  give  Quake  dynamic lighting powers, so the
              shadows will not move if the model moves. Default 0.


       "_shadowself" "n"
              If n is 1, this model will cast shadows on itself if one part of
              the  model blocks the light from another model surface. This can
              be a better compromise for moving models  than  full  shadowing.
              Default 0.


LIGHT ENTITY KEYS
       Light  entity  keys can be used in any entity with a classname starting
       with the first  five  letters  "light".  E.g.  "light",  "light_globe",
       "light_flame_small_yellow", etc.


       "light" "n"
              Set  the  light  intensity. Negative values are also allowed and
              will cause the entity to subtract light cast by other  entities.
              Default 300.


       "wait" "n"
              Scale  the  fade  distance  of the light by "n". Values of n > 1
              make the light fade more quickly with distance, and values  <  1
              make  the  light  fade  more  slowly  (and  thus reach further).
              Default 1.


       "delay" "n"
              Select an attenuation formaula for the light:
                0 => Linear attenuation (default)
                1 => 1/x attenuation
                2 => 1/(x^2) attenuation
                3 => No attenuation (same brightness at any distance)
                4 => "local minlight" - No attenuation and like minlight,
                     it won't raise the lighting above it's light value.
                     Unlike minlight, it will only affect surfaces within
                     line of sight of the entity.
                5 => 1/(x^2) attenuation, but slightly more attenuated and
                     without the extra bright effect that "delay 2" has
                     near the source.


       "_color" "r g b"
              Specify red(r), green(g) and blue(b) components for  the  colour
              of  the  light.  RGB  component  values  are  between 0 and 255.
              Default is white light ("255 255 255").


       "target" "name"
              Turns the light into a spotlight, with the  direction  of  light
              being  towards  another entity with it's "targetname" key set to
              "name".


       "mangle" "x y z"
              Turns the light into a spotlight and specifies the direction  of
              light  using yaw(x), pitch(y) and roll(z) in degrees. Yaw speci-
              fies the angle around the Z-axis from 0 to 359 degrees and pitch
              specifies  the  angle  from  90  (straight  up) to -90 (straight
              down). Roll has no effect, so use any  value  (e.g.  0).   Often
              easier than the "target" method.


       "angle" "n"
              Specifies the angle in degrees for a spotlight cone. Default 40.


       "_softangle" "n"
              Specifies the angle in degrees for an inner spotlight cone (must
              be less than the  "angle"  cone.  Creates  a  softer  transition
              between the full brightness of the inner cone to the edge of the
              outer cone.  Default 0 (disabled).


       "targetname" "name"
              Turns the light into a  switchable  light,  toggled  by  another
              entity targeting it's name.


       "style" "n"
              Set the animated light style. Default 0.


       "_anglescale" "n" | "_anglesense" "n"
              Sets  a scaling factor for how much influence the angle of inci-
              dence of light on a surface has on the brightness  of  the  sur-
              face.  n  must  be between 0.0 and 1.0. Smaller values mean less
              attenuation, with zero meaning that angle of  incidence  has  no
              effect at all on the brightness. Default 0.5.


AUTHOR
       Written by Kevin Shanahan (aka Tyrann)
       Based on source provided by id Software
       http://disenchant.net


REPORTING BUGS
       Please send bug reports to tyrann@disenchant.net.
       Improvements to the documentation are welcome and encouraged.


COPYRIGHT
       Copyright (C) 2013 Kevin Shanahan
       Copyright (C) 1997 id Software
       License GPLv2+:  GNU GPL version 2 or later
       <http://gnu.org/licenses/gpl2.html>.

       This  is  free  software:  you  are free to change and redistribute it.
       There is NO WARRANTY, to the extent permitted by law.


SEE ALSO
       qbsp(1) vis(1) bspinfo(1) bsputil(1) quake(6)



TYRUTILS                       2013-04-24 v0.15                       LIGHT(1)
