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. See
              "_dist" worldspawn key.

       -range n
              Scales the brightness range  of  all  lights  without  affecting
              their fade discance.  See "_range" worldspawn key.

       -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 Globally enables dirtmapping (ambient occlusion), overriding the
              "_dirt" worldspawn key. See "_dirt" for more details.

       -dirtdebug
              Implies  "-dirty",  and 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.


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


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


       "_sunlight_mangle" "x y z" | "_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_penumbra" "n"
              Specifies the penumbra width, in degrees, of  sunlight.   Useful
              values  are  3-4 for a gentle soft edge, or 10-20+ for more dif-
              fuse sunlight. Default is 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").


       "_sunlight2" "n"
              Set  the  brightness of a large dome of lights positioned around
              the map (16K unit radius). Useful for simulating higly  diffused
              light (e.g. cloudy skies) in outdoor areas. Default 0.


       "_sunlight_color2" "r g b" | "_sunlight2_color" "r g b"
              Specifies  the  colour  of  _sunlight2,  same  format  as "_sun-
              light_color". Default is white light ("255 255 255").


       "_dirt" "n"
              1 enables dirtmapping (ambient occlusion) on  all  lights,  bor-
              rowed  from  q3map2.  This adds shadows to corners and crevices.
              You can override the global setting for specific lights with the
              "_dirt"   light   entitiy   key   or   "_sunlight_dirt",  "_sun-
              light2_dirt", and "_minlight_dirt" worldspawn keys.  Default  is
              no dirtmapping (-1).


       "_sunlight_dirt" "n"
              1  enables  dirtmapping  (ambient  occlusion) on sunlight, -1 to
              disable (making it illuminate the dirtmapping shadows).  Default
              is to use the value of "_dirt".


       "_sunlight2_dirt" "n"
              1  enables  dirtmapping  (ambient occlusion) on sunlight2, -1 to
              disable. Default is to use the value of "_dirt".


       "_minlight_dirt" "n"
              1 enables dirtmapping (ambient occlusion)  on  minlight,  -1  to
              disable. Default is to use the value of "_dirt".


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


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


       "_dirt" "n"
              For  brush  models,  -1 prevents dirtmapping on the brush model.
              Useful it the bmodel touches or sticks into the world,  and  you
              want to those ares from turning black. 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.


       "_dirt" "n"
              Overrides the worldspawn setting of "_dirt" for this  particular
              light.  -1  to  disable dirtmapping (ambient occlusion) for this
              light, making it illuminate the dirtmapping shadows. 1 to enable
              ambient  occlusion  for  this  light. Default is to defer to the
              worldspawn setting.


       "_deviance" "n"
              Convert the light into a sphere of  randomly  positioned  lights
              with  radius "n" (in world units). Useful to shadows cast by the
              light a wider penumbra. "_samples" must also be set to a  number
              greater than 1. Default is 0.


       "_samples" "n"
              Number  of  lights  to use for "_deviance". Use 16 as a starting
              point, more for higher quality. Default 1.


       "_surface" "texturename"
              Makes surfaces with the given texture name emit light, by  using
              this  light as a template which is copied across those surfaces.
              Lights are spaced about 128 units (though possibly closer due to
              bsp  splitting) apart and positioned 2 units above the surfaces.


       "_surface_offset" "texturename"
              Controls the offset lights are placed above surfaces for  "_sur-
              face". Default 2.


AUTHOR
       Written by Kevin Shanahan (aka Tyrann)
       Modifications by Eric Wasylishen (aka ericw); many changes are based on
       code from q3map2.
       Based on source provided by id Software
       http://disenchant.net


REPORTING BUGS
       Please  send  bug   reports   for   this   modified   build   to   ewa-
       sylishen@gmail.com.
       Original message: 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-04-27 v0.15-31-g05bddc6                 LIGHT(1)
