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. By default it affects
              all lights including sunlight and minlight; you  can  make  spe-
              cific   lights  illuminate  the  dirtmapping  shadows  with  the
              "_nodirt"  key  or  for  sunlight  with  the  "_sunlight_nodirt"
              worldspawn key.

       -dirtdebug
              When  used with -dirty, renders just the dirtmap against a full-
              bright background, ignoring all lights in the  map.  Useful  for
              previewing and turning the dirt settings.

       -dirtmode n | -dirtdepth n | -dirtscale n | -dirtgain n
              Fine-tune   the   dirtmapping,   overriding   the  corresponding
              worldspawn keys. See the worldspawn keys below.


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
              (between 0 and 1 is also accepted). Default is white light ("255
              255 255").


       "_sunlight_nodirt" "n"
              If  set to 1, sunlight is not affected by dirtmapping (making it
              illuminate the dirtmapping shadows). Default 0.


       "_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
       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.


       "_minlight_color" "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
              (between 0 and 1 is also accepted). 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
              (between 0 and 1 is also accepted). 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.


       "_dirtscale" "n" | "_dirtgain" "n"
              Override the global  "_dirtscale"  or  "_dirtgain"  settings  to
              change how this light is affected by dirtmapping (ambient occlu-
              sion). See descriptions of these keys in the worldspawn section.


       "_nodirt" "n"
              If  set  to 1, this light is not affected by dirtmapping (making
              it illuminate the dirtmapping shadows). Default 0.



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                 2015-01-30 v0.15-15-gde90fc8                 LIGHT(1)
