Creating Light Sources

Matrix transform

The matrix transform determines the translation, rotation and scaling of the light in the world space of the scene. Different types of light sources interpret these values differently. For instance, point lights emit light equally in all directions, so their orientation does not have any effect. Similarly, directional lights are intended to be so distant from a scene that their translation is not taken into account, only their orientation. Scaling values are used by area lights and window lights to set the rectangular dimensions, and are used by point lights and spot lights to set up the size of a color ramp.

This value is mandatory for all light sources; it is set when you create the light source. You can change it at any time by calling ILBSetLightTransform().

Color intensity

Each light source has an RGB color value, which determines the color of the light rays it emits. This value is mandatory for all light sources; it is set when you create the light source. You can change it at any time by calling ILBSetLightColor().

Each light source also has an intensity value, which scales the amount of light the light source emits. You can change it at any time by calling ILBSetLightIntensity().

Shadow-casting properties

All lights can cast shadows. By default, shadow casting is disabled for all lights. You can toggle shadow casting on and off by calling ILBSetCastShadows(). Different types of light sources may also offer additional controls over the way they generate shadows; for details, see Creating Light Sources below.

Direct and indirect intensity scales

Each light offers separate scale controls for its direct light and its indirect light. You can use these scales to control the contribution of each type of light relative to each other, or relative to the other light sources in your scene. Both of these scale values are set through a call to ILBSetIntensityScale().

For example, a common use of these scales is to create lightmaps that contain only the indirect light contribution from the light source, while all direct lighting is calculated at runtime instead. This allows the game to combine the benefits of real-time dynamic shadowing with the benefits of baked indirect lighting: color bleeding, high performance, etc.

Falloff

Some types of lights (including point lights, area lights, spot lights and window lights) cast light rays that get weaker with distance. The relationship between the attenuation of the light and the distance from the source is called the falloff. Beast offers three types of falloff:

• Exponent calculates falloff based purely on the distance from the source, and clips any contributions at a distance greater than a maximum range cutoff. You can set up this kind of falloff through a call to ILBSetLightExponentFalloff().
• Max Range calculates falloff based on a maximum range setting so that the light diminishes gracefully as it approaches the range cutoff. You can set up this kind of falloff through a call to ILBSetLightMaxRangeFalloff().
• Polynomial allows you to specify three coefficients (a constant, a linear, and a quadratic) that are used to calculate the falloff. The equation used is as follows, where r represents the distance to the light source:

  falloff = ( 1 / (Constant + Linear * r + Quadratic * r 2 ))

  You can set up this kind of falloff through a call to ILBSetLightPolynomialFalloff().

Light stats

Light stats determine whether or not a light source is taken into account during different types of rendering and lighting calculations. For example, you can specify for each light source whether or not it should be visible in reflections and refractions, etc. The full set of controls are listed in the ILBLightStats enumeration.

To customize the light stats for a light source, call the ILBSetLightStats() function. You provide this function with:

• A bitmask composed from the ILBLightStats enumeration that specifies the render stats that you want to modify.
• A value from the ILBLightStatOperation enumeration that indicates whether you want to enable the light stats you have identified. May be ILB_LSOP_DISABLE to disable the specified light stats, or ILB_LSOP_ENABLE to enable them.

For example:

ILBSetLightStats(lightSource, 
                         ILB_LS_VISIBLE_FOR_REFLECTIONS | ILB_LS_VISIBLE_FOR_GI, 
                         ILB_LSOP_DISABLE);

Point lights

A point light, sometimes called an omni light, is a point in 3D space that emits light equally in all directions.

To create a point light, use the ILBCreatePointLight() function.

In addition to the controls described under Creating Light Sources above, you can set the following properties for point lights:

• You can control the softness of the shadows cast by the point light by setting the effective radius of the light in world space.The default value is 0, which treats the light as a zero-dimensional point that casts the sharpest possible shadows. Larger values will cast softer, more gentle shadows. You can set the radius through a call to ILBSetShadowRadius().
• You can set up a ramp of colors that will be applied to the rays emitted from the point light as they propagate through space. You set up this color ramp by calling ILBSetLightRampEntry() one or more times to set the color value used at different positions along the ramp. See the function description for details.

Spot lights

A spot light is a point in 3D space that emits light only within a defined cone.

By default, spot lights are oriented to point in the negative direction of the Y axis; you can control this by setting a rotation in the matrix transform you apply to the light. See also The Beast Coordinate System.

To create a spot light, use the ILBCreateSpotLight() function.

In addition to the controls described under Creating Light Sources above, you can set the following properties for spot lights:

• You can set the angular width of the spot light cone in a call to ILBSetSpotlightCone().
• You can set the angular width of the penumbra: the shadowy region at the edge of the spot cone. You can also set an exponent that controls how rapidly the light fades away in the penumbra as you move from the center of the spot to the outside of the cone. These values are also set in a call to ILBSetSpotlightCone().
• You can control the softness of the shadows cast by the spot light by setting the effective radius of the light in world space. The default value is 0, which treats the light as a zero-dimensional point that casts the sharpest possible shadows. Larger values will cast softer, more gentle shadows. You can set the radius through a call to ILBSetShadowRadius().
• You can set up a ramp of colors that will be applied to the rays emitted from the spot light as they propagate through space. You set up this color ramp by calling ILBSetLightRampEntry() one or more times to set the color value used at different positions along the ramp. See the function description for details.
• You can set near and far clipping planes by calling ILBSetClippingPlanes(). This restricts the effects of the light to objects that lie between the near plane and the far plane.
• You can make the spot light project a texture, or a gobo, by calling ILBSetLightProjectedTexture(). The U and V axes of the texture are always mapped to the local X and Z axes of the light source respectively.

Directional lights

A directional light, or sun light, is a distant light source whose rays light the scene at a constant angle with no falloff.

By default, directional lights are oriented to point in the negative direction of the Y axis; you can control this by setting a rotation in the matrix transform you apply to the light. See also The Beast Coordinate System.

To create a directional light, use the ILBCreateDirectionalLight() function.

In addition to the controls described under Creating Light Sources above, you can set the following properties for directional lights:

• You can control the softness of the shadows cast by the directional light by setting the angle of sky occupied by the light source. The default value is 0, which treats the light as a zero-dimensional point that casts the sharpest possible shadows. Larger values will cast softer, more gentle shadows. You can set the radius through a call to ILBSetShadowAngle().

Directional lights have no falloff; therefore, their rays do not diminish in brightness as they propagate through space.

Area lights

An area light is a planar rectangle that emits light from one face.

By default, area lights are oriented to point in the negative direction of the Y axis; you can control this by setting a rotation in the matrix transform you apply to the light. See also The Beast Coordinate System.

To create an area light, use the ILBCreateAreaLight() function. The size of the rectangle is set by the scaling values you set in the transform matrix you provide to this function. By default, it extends from (-1, -1) to (1, 1).

Window lights

A window light simulates a beam of directional light coming through a rectangular window.

By default, window lights are oriented to point in the negative direction of the Y axis; you can control this by setting a rotation in the matrix transform you apply to the light. See also The Beast Coordinate System.

To create a window light, use the ILBCreateWindowLight() function. The size of the rectangle is set by the scaling values you set in the transform matrix you provide to this function. By default, it extends from (-1, -1) to (1, 1).

In addition to the controls described under Creating Light Sources above, you can set the following properties for window lights:

• You can control the softness of the shadows cast by the window by setting the angle of sky occupied by the light source. The default value is 0, which treats the light as a zero-dimensional point that casts the sharpest possible shadows. Larger values will cast softer, more gentle shadows. You can set the radius through a call to ILBSetShadowAngle().

Sky lights

A sky light is a light source that can surround the entire scene or a defined volume within the scene. It can light the scene with a constant color, or colors derived from a texture.

To create a sky light, use the ILBCreateSkyLight() function.

In addition to the controls described under Creating Light Sources above, you can set the following properties for sky lights:

• You can set a texture for the sky light by calling ILBSetSkyLightTexture(). If you set a texture, the light emitted by the sky is colored according to the pixels in the texture. The rotation of the transform matrix controls the orientation of the texture relative to the scene.
• When using a texture, you can reduce noise in global illumination by blurring the texture a little through a call to ILBSetSkyLightTextureFilter().
• You can control the volume affected by the sky light by calling ILBSetLightVolumeType(). You pass an element of the ILBLightVolumeType enumeration to indicate the type of volume you want the sky light to occupy: an infinite volume that surrounds the whole scene, a sphere, or a cube. The position and size of the latter two volume types are defined by the translation and scaling values you set in the transform matrix.

Sky lights have no falloff; therefore, their rays do not diminish in brightness as they propagate through space.

Ambient lights

An ambient light is a light source that applies equally to all surfaces in the scene, regardless of their orientation or occlusion.

To create an ambient light, use the ILBCreateAmbientLight() function.

In addition to the controls described under Creating Light Sources above, you can set the following properties for ambient lights:

• You can control the volume affected by the ambient light by calling ILBSetLightVolumeType(). You pass an element of the ILBLightVolumeType enumeration to indicate the type of volume you want the ambient light to occupy: an infinite volume that surrounds the whole scene, a sphere, or a cube. The position and size of the latter two volume types are defined by the translation and scaling values you set in the transform matrix.

Ambient lights have no falloff; therefore, their rays do not diminish in brightness as they propagate through space.