Lights control the rendering of the nearby Renderable objects, by attempting to simulate how a real light would affect them. They are represented by the Light component.

Creating a light

Light is created as any component, and requires no additional parameters.

HSceneObject lightSO = SceneObject::create("Light");
HLight light = lightSO->addComponent<CLight>();

Once created light can be positioned and oriented normally using its SceneObject.

Light types

Lights have three variants that determine how light affects surrounding objects: radial, spot and directional. You can change between light variants with CLight::setType().

// Make a radial light

Radial light

Radial light affects everything within a certain radius from the light (i.e. its sphere of influence). It is the most basic type of light.


Spot light

Spot lights only illuminate a certain direction (i.e. like a flash-light). The user can specify the angle of illumination.


Directional light

Directional lights are a special type of light primarily used for simulating sun-light, or otherwise far-away objects. Unlike radial or spot lights they cannot be positioned. Only their orientation matters and they equally affect every object in the scene.


Light properties

Each light has a set of properties you can adjust (aside from position/orientation, which are handled by the SceneObject). Most of the properties are common for all light types but some are only relevant for specific types. We'll go over all of the properties below.


As the name implies, this controls what color light is being emitted from the source. It can be set by calling CLight::setColor() and it is valid for all light types.

Attenuation radius

Attenuation radius determines how far away does the light's influence reach. For radial lights this is the radius of the sphere of influence, and for spot lights this is the distance from the origin in the direction of the light. This property is not relevant for directional lights as their range is infinite. Use CLight::setAttenuationRadius() to set the range.

Note that the manually set range will only be used if automatic attenuation is disabled. You can toggle this by calling CLight::setUseAutoAttenuation(). When automatic attenuation is enabled the maximum range is calculated automatically based on the light intensity (described below). This automatic attenuation will smoothly cut off the light influence when it reaches roughly 10% of its intensity. Sometimes this is not wanted in which case you can turn this off and increase the range manually. Reducing the range manually will result in a non-physically realistic light attenuation.


This controls how strong is the light. Although you could technically control light intensity using the color property (by using a lighter or darker color), using the intensity allows the engine to simulate high-dynamic range.

In nature the range of light intensities varies highly - standing outside at a sunlit day may be hundreds or thousands of times brighter than standing indoors illuminated by a lightbulb. We won't perceive such a large difference because our eyes are able to adjust to different intensities.

Banshee uses a HDR algorithm to try to approximate this adjustment, which results in more realistic and higher quality lighting. Therefore it can be important for realism to set up the light intensities similar to what they would be in nature.

Use CLight::setIntensity() to change the light intensity.

The specific units used for intensity (in case you want to look them up for actual light sources) are luminous flux for radial/spot lights, and luminance for directional lights.

Source radius

By default all lights are considered point (punctual) lights, meaning they have no surface area. In case you want to make an area light set the source radius of the light by calling CLight::setSourceRadius(). The value of this property is interpreted differently depending on light type:

  • Radial - Light represents a spherical area light and source radius is the sphere's radius
  • Spot - Light represents a disc area light (oriented toward spot direction) and the source radius in the disc radius
  • Directional - Light represents a disc area light projected on the sky, and the source radius represents the angular radius (in degrees) of the light. For example, Sun's angular radius is roughly 0.5° (varies slighly).

Area light types are particulary important for physically based rendering, as they can produce realistic looking specular reflections, which is not the case for point lights.


Lights may or may not cast shadows. For realism all lights should cast shadows, but that is not feasible due to the high performance costs of using shadows. Therefore you should enable shadows only for one, or a few important lights. Use CLight::setCastsShadow() to enable or disable shadow casting.

Spot angles

Spot light have a property that defines at how wide an angle do they cast light in. Narrower angle means a more focused light beam, while wider angle means a weaker light covering a larger area.

You can set the spot light angle (also knows as total angle) with CLight::setSpotAngle. Note that light intensity will be spread out over the range, so when increasing the angle, you might also want to increase the intensity to keep the perceived brightness the same.

You can also call CLight::setSpotFalloffAngle to set an angle that allows a smooth falloff at the edge of the lights radius. This must be an angle smaller than the total spot angle. Within this angle the light intensity will be uniform, but as the angle increases past the falloff angle and towards the total angle and intensity will slowly reduce, resulting in a smooth falloff curve. If you don't want the smooth falloff, set this angle to the same value as the total angle.