Light Properties

Introduction

For Doom 3 (and subsequently, The Dark Mod), there are 4 different types of lights at our disposal. Each has their own advantages and drawbacks, and hopefully this article will help to familiarize The Dark Mod hopefuls with their use. For information on creating lights and a lot of other useful information, see A - Z Beginner Full Guide Start Here!

Light Volume Properties

Point Light

A point light is the default light (also the default for fog). No option must be checked to make a light a point light. A point light casts light, and subsequently shadows in all directions evenly, falling off after a distance defined by the light texture. This works best for most small indoor and outdoor lighting, like lamps, candles, fireplaces etc. For this reason, it is going to be the most used type.

• Note, a misconception about Point Light is that they project spherically. The box shaped bounding volume in Dark Radiant is no mere simplification, it is the literal area affected by the light for calculation purposes. Point Light volumes should be perceived as cylindrical prisms that on one axis are shaped by the silhouette of the projection texture (think of a stack of cheese cut with a cookie cutter) and the other axis (z-axis) traditionally determines the distance from origin brightness (usually vertical... or how tall you make your cheese stack) with the LightFalloffImage.

• Note 2, as of TDM 2.05 cubicLight lights offer true spherical falloff.

Projected Light

Projected light is just as the name suggests. It is probably more intuitive and easier to use than a parallel light and is better for things like projecting a window-shaped light on the floor of a room or a spotlight on a wall. To make one, select projected instead of the default omni option at the top of the light inspector.

This creates a triangular prism as the bounding box for the light (instead of a rectangular prism like a regular light), with the point ending right at the entity itself. This can be rotated using any of the XYZ rotation buttons or manually using DarkRadiant’s rotation tool (shortcut R).

You can also manipulate the projected light via the vertices (shortcut V to enable vertices dragging). By dragging the vertices in the center of the projected square, you can lengthen and change the angle of the projection while keeping the projected square the same size. To resize the projection, use the two side vertices in the correct XYZ grid view. Making the bounding box flat against a surface (like a floor) is usually unnecessary (for example, making a moonlight window light on a floor or wall), because with shadows enabled and making the projection long enough to intersect the plane on which the shadow is to be cast, the full shadow will be cast (its simple geometry and just requires minor toying).

As with all the lights, projected lights have a full range of color and texture options to let the mapper find just the effect they need, allowing you to create a great atmosphere for your map.

• As of TDM 2.06, cubicLight entities do not work properly with Projected lights. Please only use cubicLight with Point lights.

Parallel Light

A light is said to be parallel when the parallel checkbox is checked in the light inspector. It is subject to all the same options as a point light, but it has a few distinct differences. A parallel light tends to not care exactly where the entity itself is placed. The most important thing is where the light_center vertex is placed and where the light entities bounding box intersects with elements in your map.

The light_center vertex starts right in the middle of the entity. The main difference between the parallel and point lights is that a parallel light does not radiate from the origin around the entity itself. What controls the direction that shadows are cast is the placement of the light_center vertex. Shadows will run parallel (hence the name) to a line between this vertex and the light entity itself. This makes it an excellent choice for sunlight or moonlight. As such, it has some of the elements of a point light and a projected light, it can seem to radiate in a circle (if you use the appropriate texture) whilst casting a shadow in any direction preferred.

Switch to Vertex mode in DarkRadiant to drag the light_center vertex of your selected light entity.

Posted by Greebo: Also, note that a parallel light will only light surfaces "matching" the direction of the "light vector"
(origin minus light_center). All other surfaces will stay completely unlit, therefore it should be combined with an ambient light to
achieve good lighting effects. [1]

Parallel-sky light

The main problem with parallel light is that: while it does not radiate light rays from the light origin, the origin still matters when engine flows light rays through visportals. An ordinary parallel light always works properly in the visleaf where its origin is located. In addition to that, it takes effect in all the other visleafs which can be reached from the starting visleaf through visportals by travelling along the direction of the light. So in order to create a global moon/sun light which will light many outdoor areas, one has to create a separate visleaf above the outdoor areas, which would contain the light and have portals leading down to every outdoor area below. It is quite complicated.

In TDM 2.08, a new spawnarg parallelSky was added. If you add it to a parallel light (see visual example below) and set value "1", then the light will emanate from every visleaf containing surfaces with textures/smf/portal_sky material. This usually includes all outdoors area automatically. Note that other (i.e. indoors) areas are also included if they can be reached from outdoors areas through open visportals, so the light should work correctly indoors if someone opens a door.

Troubleshooting Parallel Lights

I added a parallel light but I can’t see any light at all!

Parallel lights can have some quirks. The light seems to fail and do nothing when intersecting multiple walls that are parallel to the face the light is actually casting on. It seems the light will work as long as it doesn’t intersect a face parallel to the one it is casting light on.

I have a parallel light but it casts a jagged light on my floor!

Similar to above, a parallel light can sometimes have anomalies when intersecting multiple walls and a floor. Since having the light intersect multiple walls when it can only cast on one of them, having a massive bounding box is pointless anyways so pay attention to what the light is touching and you should be fine.

Light Interaction Properties

Normal Light

This is the default light type. It performs all the surface interaction stages and shadow calculations. It has the heaviest performance impact.

cubicLight

New as of TDM 2.05, it is similar to Normal Light but accepts a cubemap as the projection image and uses a spherical z-falloff pattern rather than a falloff image.

The shader was originally developed by Sikkpin the author of the soft shadows mod for Doom 3 "Sikkmod". Duzenko ported portions of it to GLSL.

CubicLight projection is used in many 3D engines with the most common parlance being "Cookie Lights". Unity "Cookie Lights" can be used as a reference.
(For comparison, I am not aware of any 3D engine other than id Tech 4 that used the 1D + 2D projection images.)

As of TDM 2.06, GLSL versions of this shader will only perform Point light (omni) operations. Projected is broken.

Ambient Light

Ambient light is really just a lighting texture, but it is also a specific item that is needed in practically every map, so for those purposes it will be treated as if it were its own subset of lights.

Properties: No shadows, No specular, Bumpmapping or Directionality (Note: The "Enhance Ambient" does add Bumpmapping )

Use the ambientLight keyword.

An ambient light can be any form: it can be a point, parallel or even projected (though projected would probably be useless).

The only requirement of an ambient light is to use one of the available ambient light textures, accessible by opening the light inspector (with the shortcut L in DarkRadiant, and get used to using it), and selecting ambientlightnfo from the list.

• Ambient Light is covered in more detail in Ambient Light: Gloom not Doom

• To understand The Dark Mod's unique ambient light detection system see: Virtual Darkness

• Ambient Light can be set to automatically adjust color and brightness per "location" see: Location Settings and Dynamic ambient light

lightAmbientDiffuse and lightAmbientSpecular ( Previously ambientCubicLight )

New as of TDM 2.05. This is intended to provide an effect similar to Valve's "Precomputed Radiance Transfer" lighting in Half Life 2. It was originally developed by Sikkpin the author of the soft shadows mod for Doom 3 "Sikkmod".

In TDM 2.06, the new GLSL version of the shader (developed by Duzenko) accepts (industry standard) irradiance cubemap images.

• A new image program "makeIrradiance" was also created to use existing skybox cubemap images.

In 2.11 ambientCubicLight was replaced by two material global keywords

• lightAmbientDiffuse - meant for the standard diffuse response

• lightAmbientSpecular - incorporates cubemap reflections into the specular response

Both keywords are mean to be used with either 3rd party irradiance cubemaps or the "bakeAmbientDiffuse" and "bakeAmbientSpecular" keywords.

Example material:

lights/ambientCube/cubeSky
{
    ambientLight
    lightAmbientDiffuse bakeAmbientDiffuse(cameraLayout(env/lights/cubesky))
    lightAmbientSpecular bakeAmbientSpecular(cameraLayout(env/lights/cubesky))
    {
        map lights/squarelight_amb.tga
        colored
        zeroClamp
    }
} 

See also:

https://forums.thedarkmod.com/index.php?/topic/19803-tutorial-image-based-lighting-workflows-for-tdm/

Fog Light

This applies Doom 3's style distance fog to a light volume. The texture applied will become more opaque with distance away from the viewer. There is a variant called No Portal Fog which will not apply opaque fog to Portal areas in view. ( Beginner Tutorial: Fog )

In rare cases, you may wish for some surface inside a fog-volume to be fog-free. You can use the "noFog" keyword in the material definition for the texture applied to this surface to keep it from being "fogged".

Very thin fog (or BlendLight ) can also be used to soften the apparent light interactions near surfaces in a similar manner to the Post Process shader effect but with more mapper control. You can fake certain radiosity effects simply by amplifying small ambient light with small thin fog volumes.

Use the fogLight keyword.

noFogBoundary

Fog lights don't actually paint mist in the air, which would slow down performance quite a bit. They achieve their effect by fogging out the colour of the surfaces that they hit, proportionate to the depth of fog that lies between the player and the surface. In addition, if there is no surface between the player and the edge of the fog volume, they paint fog on the invisible walls of their own bounding volume. That's needed for a large open scene, for example, where there might be no surface between the player and the edge of the fog volume. If you're in a misty forest, and there happened to be no tree visible in a certain direction, you'd expect to see grey fog rather than clear space between the fogged trees.

Sometimes you don't want that to happen, for example if you're using a very large but very light fog to simulate atmospheric perspective in a town. You want the colour and detail of buildings to fade with distance, but you don't want heavy fog blocking the view of the sky in the gaps between buildings where you see to the very edge of the big fog light. You can use spawnarg "noFogBoundary" for that. It lets fog paint on solid surfaces, while leaving empty space and caulk sky free of fog effects.

noPortalFog

This is a Doom 3 Global Material keyword that disables the optimization that auto-closes portals that are past the fully fogged
radius. It can be used to prevent lights and emissive surfaces from turning off suddenly producing a jarring and unnatural effect.

In TDM 2.12 (alpha) development builds, this is now an entity spawnarg as well so authors do not need to create override materials to use this feature.

noFog ( new 2.07 )

As of TDM 2.07, you can apply a noFog global material flag to the material def or the noFog entity spawnarg to the entity def and this will prevent fogging on these surfaces or entities.
Most visual fog issues are in cases where fog is "not" applied somewhere. Therefore, this is mostly a performance related argument or can be used as a special effects.

fogAlpha ( new 2.08 )

As of TDM 2.08, you can apply a fogAlpha keyword to alpha textures to determine whether they receive fog. The value is a floating point number between 0 and 1
which determines how intensely the fog affects the alpha texture.

Blend Light

Blend lights can be considered to be like volumetric decals. They do not perform most of the interaction shader operations and merely apply a texture to a volume using an OpenGL Blend Mode. Blend lights have the least performance impact. Blend lights can also be used to create "negative light".

Example negative light shader:

lights/bdog_testBlendLight2
{
 blendLight
 lightFalloffImage makeintensity( textures/blackdog/blendlight_falloff_inverse.tga )
 {
 blend gl_zero, gl_one_minus_src_color
 map textures/blackdog/blackdog_icon_inverse.tga
 zeroclamp
 //alphazeroclamp
 colored
 } 
}

Use the blendLight keyword.

Volumetric light ( new 2.10 )

Volumetric light makes the whole light volume slightly visible to the player (added in TDM 2.10). The related spawnargs are:

• volumetric_light = 0: Set to 1 to enable volumetric light.
• volumetric_dust = 0.002: How strong the volumetric effect is (reduce it if too bright).
• volumetric_noshadows: How volumetric light handles shadows (see below).

The spawnarg volumetric_noshadows only affects the volumetric effect, and has three different values (default value is taken from noshadows spawnarg):

• = 0: Shadows must be respected. If that's not possible, then the whole volumetric effect must be disabled.
• = 1: Shadows must be ignored.
• = -1: Shadows should be respected. But if that's not possible, then shadows can be ignored as well. --- useless in TDM 2.11

There are several reasons why engine can fail to support shadows in volumetric light:

1. Player uses stencil shadows (r_shadows 1) or (fixed in TDM 2.11) disabled volumetric light sampling (r_volumetricSamples 0).
2. Shadow maps are not yet supported for the particular light. This happens for large lights, for instance.
3. Shadows were disabled on the light itself (noshadows).

Light Settings

There are several settings with which to customize your lights. These settings allow the mapper to customize the look of a light (or a combination of lights) into a near infinity of looks. All are accessed through the light inspector (shortcut of L in DarkRadiant)

Color

The color palette allows the mapper to pick the color of the light emitted, arguably one of the most useful controls the mapper has over a light. To access it, click the button under the “Colour” heading. From there, adjust the settings until you find a correct color (can take some trial and error). In a game like The Dark Mod or Doom 3, where darkness is often more prevalent than light, the color picked often needs to be darker than expected. Without a direct brightness option, the color takes on this task. For a low level ambient light, the color picked would be almost pitch black. A pitch black light would not cast any light, but anything less than pitch black will cast a faint light. As such, it can take some trial and error to find the correct light for a situation, as initially, one is likely to pick a seemingly correct color only to find it is far too bright.

Remember: changing light settings or adding lights (and models) does not require re-compiling the map!

Radius

The 'radius' of your light can be changed by dragging its corners around in the 2d windows. Doom 3 lights do not have an actual radius, they are actually square lights and will light up everything they touch inside their bounding box in the editor. They will evenly light everything to their edges. While square lights might seem fairly odd there are options to make them more believable and have a nice fade, namely the 'texture' applied.

Tip: you can rotate a light so only one corner will touch a wall and make a triangular shaped light. 

Or rotate it so 2 corners touch a wall and make a line of light.

Changing Radius of Light Entity:

If you put a premade light entity into your map, the radius of the light won't be visible.

To change it, use the following syntax (and whichever value you wish):

 "set _color on flame" "0.9 0.8 0.7"
 "set light_radius on flame" "250 250 250"

With lanterns and such use 'light' and with torches and candles etc use 'flame'.

 "set _color on light" "0.9 0.8 0.7"
 "set light_radius on light" "250 250 250"

(Copied from Baddcog's old "Lighting A to Z" article)

Parallel

Selecting this option turns the light into a parallel light (as opposed to a point or projected light). See Parallel Light

Do not cast shadows (fast)

As the name suggests, this setting causes the light to not cast shadows on any object. This can cause the light itself to not be confined by walls, which can sometimes be beneficial and sometimes not. The main purpose of enabling this option is performance. Shadows are processor intensive and are not needed in some cases, so removing them wherever not beneficial to gameplay can vastly improve performance. Note that ambient lights never cast any shadows. Another way to improve performance similarly is to set the entity property on a model or func_static (this doesn’t work on worldspawn) noshadows to 1.

• Further details: Turning Shadows Off , Noselfshadows

Skip Specular Lighting

Specular Lighting refers to a texture's specular map, wherein a flat surface (such as a wall) is painted with a texture that has a specular component. This causes a surface to have shinier and duller parts on a flat surface based on the darkness of the corresponding location on the specular map. Not all textures have specular maps. Checking this option could improve performance or remove the effect if it is not wanted. [2]

Spectrum

You may use the "spectrum" keyword to isolate specific lights to specific materials which have the same spectrum value in their material definition. Spectrum Keyword at Modwiki

In TDM 2.07 spectrum was added as an entity spawnarg

lightspectrum (new 2.08 )

As of 2.08 there is a new spectrum keyword "lightspectrum" that only affects standard lights and allows ambient lights to render as expected. This makes it much more useful to control where lights are allowed to illuminate

nospectrum ( new 2.08 )

As of 2.08 there is a new spectrum keywork "nospectrum" that will bypass spectrum behavior for all spectrum lights except the one whose spectrum number you specify. This will force all spectrum lights to illuminate this entity.

Other light settings

AI sight ( new 2.04 )

Spawnarg ai_see controls whether the light is visible to AI. It defaults to "1", i.e. the light does help AI to see. You can set this spawnarg to "0" to make accent lights that will (1) not affect the player's lightgem, and (2) won't make suspicious objects like rope arrows more visible to AI.

AreaLock ( new 2.08 )

Forces the light to stop rendering when the visleaf that contains its origin is closed.

Chandeliers

Typically chandeliers are setup with multiple particle flames, but just one light entity (for better performance). Bind the candles to the chandelier, then if one is doused, all will extinguish. (See the prefab for an example.)

Lighting Textures

Rich_is_Bored's Example

The lighting textures are also accessed in the light inspector.

Lights can be modified by two different texture types:

• Projection Image - This is the texture that is projected on the surface
• LightFalloffImage - This texture varies the intensity of the light through the volume along the Z Axis
• (Notes: While the Falloff Image is a 2D texture it is rendered as 1D (one dimensional). You will notice that almost all Falloff Images are thin strips with perpendicular stripes. Traditionally, Falloff will be used to diminish the light with distance to the source but you can violate the physics of real lights and have the intensity increase with distance or vary intensity from bright to dim to bright... etc. )

These textures allow the mapper to change the intensity and falloff of a light.

Light textures with the addition of material keywords like scroll,rotate, etc. will grant lights the ability to animate and produce special effects such as;

• A moving light for a fireplace
• A candle or torch
• A light flickering along with sound volume.

One can also apply a fog texture to the light (the only way built into Doom 3 to create fog). Color is of a similar concern when creating fog, as noted in Color

• A typical "Light Shader" material definition

lights/My_Custom_Light1
{

  lightFalloffImage makeIntensity( textures/My_Custom_Light1_Z ) // Falloff Image

  { 
  forceHighQuality
  map textures/My_Custom_Light1_XY // Z-Projection Image
  zeroClamp
  }

}

(For advanced detail and techniques see Light Textures and Falloff Images )

Further reading

• Lighting Performance Options
• Relighting Lights
• A great tutorial on outdoor lighting can be found here: Dynamic outdoor lighting techniques
• Modwiki's summarized Doom 3 lighting article: Light