LIGHT(1)                                                              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.

       -dirty Enables dirtmapping (ambient occlusion), borrowed  from  q3map2.
              This adds shadows to corners and crevices. For best results com-
              bine with -extra4.

       -dirtdebug
              When used with -dirty, renders just the dirtmap against a  full-
              bright background, ignoring regular lights in the map.

       -dirtmode n
              Choose  between ordered (0, default) and randomized (1) dirtmap-
              ping.

       -dirtdepth n
              Maximum depth of occlusion  checking  for  dirtmapping,  default
              128.

       -dirtscale n
              Scale  factor used in dirt calculations, default 1. Lower values
              (e.g. 0.5) make the dirt fainter, 2.0 would create  much  darker
              shadows.

       -dirtgain n
              Exponent used in dirt calculation, default 1. Lower values (e.g.
              0.5) make the shadows darker and stretch further away from  cor-
              ners.


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                          TYR_VERSION                         LIGHT(1)
