@c -*-texinfo-*-
@node HOWTO Pseudo DynLight, , Lighting, Lighting System
@subsection Pseudo-dynamic Lights
@cindex pseudo-dynamic lights
@cindex dynamic lights
@cindex static lights
@cindex @code{iLight}

One little known feature in CS is the ability to have pseudo-dynamic
lights. Pseudo-dynamic lights are somewhere between static lights and
dynamic lights. Static lights cannot move but they generate high quality
lightmaps. Dynamic lights can move but the quality of lighting is much
less. Pseudo-dynamic lights are a variant of static lights. They cannot
move either but they can change intensity and color dynamically. Since
they also use lightmaps the quality is very good and they have correct
shadows. Pseudo-dynamic lights are ideal for lights that can be switched
on/off or possibly even for outside light that you want to turn off (at
night). Note that the usage of pseudo-dynamic lights adds an additional
shadow map to every polygon that is touched by that light. So memory
usage can go up quickly.

@subsubheading Creating a Pseudo-Dynamic Light

To specify a pseudo-dynamic light in a map file you use the following
syntax:

@example
<light name="DynLight">
  <center x="23" y="1" z="5"/>
  <radius>10</radius>
  <color red="1" green="0" blue="0"/>
  <dynamic />
<light>
@end example

In other words, the syntax is the same as for a normal light except for
the @samp{dynamic} keyword. Note that lights usually don't have a name
but for a pseudo-dynamic light it is convenient to have one since you can
use that name to find the light later (which is essential if you want to
change the color/intensity).

To create a pseudo-dynamic light from within an application you can
use the following code:

@example
csRef<iLight> light = engine->CreateLight ("DynLight",
  csVector3 (23, 1, 5), 10, csColor (1, 0, 0), true);
sector->GetLights ()->AddLight (light);
@end example

This will create exactly the same light as the one specified above.

At some point you may want to change the color of the light. You can
do this with the following code:

@example
light->SetColor (csColor (0, 0, 1));
@end example

This will change the color of the light from red to blue.

@subsubheading Include Files

The include files useful for this section are:

@example
#include <iengine/light.h>
#include <iengine/sector.h>
#include <iengine/engine.h>
@end example
