LIGHT

NAME
SYNOPSIS
DESCRIPTION
OPTIONS
MODEL ENTITY KEYS
LIGHT ENTITY KEYS
AUTHOR
REPORTING BUGS
COPYRIGHT
SEE ALSO

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 information 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 discernable 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 algorithm 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 sample. 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 incidence 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 generate the .lit file when needed.

−dirt

Globally enables dirtmapping (ambient occlusion), overriding the "_dirt" worldspawn key. See "_dirt" for more details.

−dirtdebug

Implies "-dirt", and renders just the dirtmap against a fullbright background, ignoring all lights in the map. Useful for previewing and turning the dirt settings.

−dirtmode n | −dirtdepth n | −dirtscale n | −dirtgain n | −dirtangle n

Fine-tune the dirtmapping, overriding the corresponding worldspawn keys. See the worldspawn keys below.

−gamma [n]

Adjust brightness of final lightmap. Default 1, >1 is brighter, <1 is darker. See "_gamma" worldspawn key.

−lux

Generate a .lux file storing average incoming light directions for surfaces. Usable by FTEQW with "r_deluxemapping 1"

−surflight_subdivide [n]

Configure spacing of all surface lights. Default 128 units. Minimum setting: 64 / max 2048. In the future I’d like to make this configurable per-surface-light.

−onlyents

Updates the entities lump in the bsp. You should run this after running qbsp with -onlyents, if your map uses any switchable lights. All this does is assign style numbers to each switchable light.

−sunsamples [n]

Set the number of samples to use for "_sunlight_penumbra" and "_sunlight2" (sunlight2 may use more or less because of how the suns are set up in a sphere). Default 100. The "\b" escape sequence toggles red text on/off, you can use this in any strings in the map file. e.g. "message" "Here is \bsome red text\b..."

−surflight_dump

Saves the lights generated by surfacelights to a "mapname-surflights.map" file.

−lmscale n

Equivelent to "_lightmap_scale" worldspawn key.

−bspxlit

Writes rgb data into the bsp itself.

−bspx

Writes both rgb and directions data into the bsp itself.

−novanilla

Fallback scaled lighting will be omitted. Standard grey lighting will be ommitted if there are coloured lights. Implies "-bspxlit". "-lit" will no longer be implied by the presence of coloured lights.

−bounce n

Enables 1 bounce, 0=disable even if set in worldspawn. Available as a worldspawn key.

−bouncescale n

Scales brightness of bounce lighting, default 1. Available as a worldspawn key.

−bouncecolorscale n

Weight for bounce lighting to use texture colors from the map: 0=ignore map textures (default), 1=multiply bounce light color by texture color. Available as a worldspawn key.

−phongdebug

Write normals to lit file for debugging phong shading.

−bouncedebug

Write bounced lighting only to the lightmap for debugging / previewing -bounce.

−novisapprox

Disable approximate visibility culling of lights, which has a small chance of introducing artifacts where lights cut off too soon.

−backend b

Choose a raytracing backend, currently available: embree, bsp.

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.

"_anglescale" "n" | "_anglesense" "n"

Set the scaling of sunlight brightness due to the angle of incidence with a surface (more detailed explanation in the "_anglescale" light entity key below).

"_sunlight_mangle" "yaw pitch roll" | "_sun_mangle" "yaw pitch roll"

Specifies the direction of sunlight using yaw, pitch and roll in degrees. Yaw specifies the angle around the Z-axis from 0 to 359 degrees and pitch specifies the angle from 90 (shining straight up) to -90 (shining straight down from above). 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 diffuse 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 dome of lights arranged around the upper hemisphere. (i.e. ambient light, coming from above the horizon). Default 0.

"_sunlight_color2" "r g b" | "_sunlight2_color" "r g b"

Specifies the colour of _sunlight2, same format as "_sunlight_color". Default is white light ("255 255 255").

"_sunlight3" "n"

Same as "_sunlight2", but for the bottom hemisphere (i.e. ambient light, coming from below the horizon). Combine "_sunlight2" and "_sunlight3" to have light coming equally from all directions, e.g. for levels floating in the clouds. Default 0.

"_sunlight_color3" "r g b" | "_sunlight3_color" "r g b"

Specifies the colour of "_sunlight3". Default is white light ("255 255 255").

"_dirt" "n"

1 enables dirtmapping (ambient occlusion) on all lights, borrowed 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", "_sunlight2_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/3, -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) dirtmapping.

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

"_dirtangle" "n"

Cone angle in degrees for occlusion testing, default 88. Allowed range 1-90. Lower values can avoid unwanted dirt on arches, pipe interiors, etc.

"_gamma" "n"

Adjust brightness of final lightmap. Default 1, >1 is brighter, <1 is darker.

"_lightmap_scale" "n"

Forces all surfaces+submodels to use this specific lightmap scale. Removes "LMSHIFT" field.

Model Entity Keys
The following keys can be used on any entity with a brush model. "_minlight", "_mincolor", "_dirt", "_phong", and "_phong_angle" are supported on func_detail/func_group as well, if qbsp from these tools is used.
"_minlight" "n"

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

"_minlight_exclude" "texname"

Faces with the given texture are excluded from receiving minlight on this brush model.

"_minlight_color" "r g b" | "_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.

"_phong" "n"

1 enables phong shading on this model with a default _phong_angle of 89 (softens columns etc).

"_phong_angle" "n"

Enables phong shading on faces of this model with a custom angle. Adjacent faces with normals this many degrees apart (or less) will be smoothed. Consider setting "_anglescale" to "1" on lights or worldspawn to make the effect of phong shading more visible. Use the "-phongdebug" command-line flag to save the interpolated normals to the lightmap for previewing (use "r_lightmap 1" or "gl_lightmaps 1" in your engine to preview.)

"_lightignore" "n"

1 makes a model receive minlight only, ignoring all lights / sunlight. Could be useful on rotators / trains.

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" "yaw pitch roll"

Turns the light into a spotlight and specifies the direction of light using yaw, pitch and roll 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). 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 incidence of light on a surface has on the brightness of the surface. 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 occlusion). 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"

Split up the light into a sphere of randomly positioned lights within radius "n" (in world units). Useful to give shadows a wider penumbra. "_samples" specifies the number of lights in the sphere. The "light" value is automatically scaled down for most lighting formulas (except linear and non-additive minlight) to attempt to keep the brightness equal. Default is 0, do not split up lights.

"_samples" "n"

Number of lights to use for "_deviance". Default 16 (only used if "_deviance" is set).

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

Controls the offset lights are placed above surfaces for "_surface". Default 2.

"_surface_spotlight" "n"

For a surface light template (i.e. a light with "_surface" set), setting this to "1" makes each instance into a spotlight, with the direction of light pointing along the surface normal. In other words, it automatically sets "mangle" on each of the generated lights.

"_project_texture" "texture"

Specifies that a light should project this texture. The texture must be used in the map somewhere.

"_project_mangle" "yaw pitch roll"

Specifies the yaw/pitch/roll angles for a texture projection (overriding mangle).

"_project_fov" "n"

Specifies the fov angle for a texture projection. Default 90.

AUTHOR

Written by Kevin Shanahan (aka Tyrann)
Modifications by Eric Wasylishen (aka ericw); many changes are based on code from q3map2.
Modifications by David Walton (aka spike); focusing on lux support and optimizations.
Based on source provided by id Software
http://disenchant.net

REPORTING BUGS

Please send bug reports for this modified build to ewasylishen@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)