Skip to main content
Filament provides a physically-based lighting system with support for multiple light types. At least one light must be added to a scene to see anything (unless using unlit materials).

​
Light Types

Filament supports three main light types, each serving different purposes in scene illumination.

​
Directional Lights

Directional lights have a direction but no position. All light rays are parallel and come from infinitely far away, making them ideal for simulating sunlight. 
utils::Entity sun = utils::EntityManager::get().create();

LightManager::Builder(LightManager::Type::SUN)
    .color({1.0f, 1.0f, 1.0f})
    .intensity(100000.0f)  // In lux
    .direction({0.548f, -0.474f, -0.689f})
    .castShadows(true)
    .build(*engine, sun);

scene->addEntity(sun);
Key characteristics:
  • No falloff over distance
  • Can cast shadows
  • Intensity specified in lux (lumen/m²)
  • Type::SUN also draws a sun disk in the sky
  • Only one directional light is fully supported per scene

​
Point Lights

Point lights emit light from a position in all directions. The intensity diminishes with the inverse square of the distance. 
utils::Entity light = utils::EntityManager::get().create();

LightManager::Builder(LightManager::Type::POINT)
    .color({1.0f, 0.8f, 0.6f})
    .intensity(100000.0f)  // In lumens
    .position({5.0f, 2.0f, 0.0f})
    .falloff(10.0f)  // Influence radius in meters
    .build(*engine, light);

scene->addEntity(light);
Key characteristics:
  • Have a position but emit in all directions
  • Intensity specified in lumens (luminous power)
  • Falloff distance defines sphere of influence
  • Cannot cast shadows
  • Multiple point lights supported

​
Spot Lights

Spot lights are similar to point lights but emit light in a cone defined by inner and outer angles. 
utils::Entity spot = utils::EntityManager::get().create();

LightManager::Builder(LightManager::Type::SPOT)
    .color({1.0f, 1.0f, 1.0f})
    .intensity(100000.0f)
    .position({0.0f, 3.0f, 0.0f})
    .direction({0.0f, -1.0f, 0.0f})
    .falloff(10.0f)
    .spotLightCone(0.174f, 0.524f)  // Inner and outer cone angles in radians
    .build(*engine, spot);

scene->addEntity(spot);
Key characteristics:
  • Have both position and direction
  • Defined by inner and outer cone angles
  • Can cast shadows (Type::SPOT and Type::FOCUSED_SPOT)
  • Type::FOCUSED_SPOT: physically correct
  • Type::SPOT: decouples illumination from cone angle for artistic control

​
Light Intensity

Filament uses physically-based units for light intensity:

​
Directional Lights

  • Measured in lux (lumen/m²)
  • Sun illuminance: ~100,000 lux
  • Overcast day: ~1,000 lux
  • Indoor office: ~300-500 lux

​
Point and Spot Lights

  • Measured in lumens (total luminous power)
  • Can also use candela (luminous intensity)
  • Set from wattage with efficiency:
// 60W incandescent bulb at 2.2% efficiency
builder.intensity(60.0f, LightManager::EFFICIENCY_INCANDESCENT);

// 10W LED bulb at 11.7% efficiency  
builder.intensity(10.0f, LightManager::EFFICIENCY_LED);
Bulb efficiency constants:
  • EFFICIENCY_INCANDESCENT: 2.2%
  • EFFICIENCY_HALOGEN: 7.0%
  • EFFICIENCY_FLUORESCENT: 8.7%
  • EFFICIENCY_LED: 11.7%

​
Light Color

Light color is specified in linear sRGB space: 
// White light
builder.color({1.0f, 1.0f, 1.0f});

// Warm tungsten light
builder.color({1.0f, 0.8f, 0.6f});

// Cool daylight
builder.color({0.9f, 0.95f, 1.0f});

​
Light Channels

Lights can be assigned to channels (0-7) for selective rendering: 
LightManager::Builder(LightManager::Type::POINT)
    .lightChannel(0, true)   // Enable channel 0
    .lightChannel(1, true)   // Enable channel 1
    .build(*engine, light);

// Renderables can filter which light channels affect them
// via RenderableManager::setLayerMask()

​
Updating Lights

Light properties can be modified at runtime: 
auto& lcm = engine->getLightManager();
auto instance = lcm.getInstance(lightEntity);

// Update position
lcm.setPosition(instance, {x, y, z});

// Update intensity
lcm.setIntensity(instance, 50000.0f);

// Update color
lcm.setColor(instance, {r, g, b});

// Update direction
lcm.setDirection(instance, {dx, dy, dz});

​
Performance Considerations

​
General Guidelines

  1. Prefer spot lights to point lights when possible
  2. Use smallest feasible outer cone angle for spot lights
  3. Minimize falloff distance for point and spot lights
  4. Avoid overlapping light influence spheres
  5. Hundreds of non-overlapping lights can be handled efficiently
  6. Overlapping lights significantly impact performance

​
Shadow Casting

  • Only directional and spot lights can cast shadows
  • Shadow casting has significant performance cost
  • Limit number of shadow-casting lights
  • See Shadows documentation for optimization

​
Sun Configuration

For Type::SUN lights, additional parameters control the sun’s appearance: 
LightManager::Builder(LightManager::Type::SUN)
    .sunAngularRadius(0.545f)    // In degrees (Earth: 0.526-0.545°)
    .sunHaloSize(10.0f)           // Halo radius multiplier
    .sunHaloFalloff(80.0f)        // Halo falloff exponent
    .build(*engine, sun);

​
Destroying Lights

Lights must be explicitly destroyed: 
engine->getLightManager().destroy(lightEntity);
EntityManager::get().destroy(lightEntity);
The maximum number of lights per scene depends on GPU capabilities, but Filament supports up to 2048 lights per Engine instance.

​
Next Steps

Shadows

Configure shadow mapping for realistic lighting

IBL

Set up image-based lighting for environment illumination

Build docs developers (and LLMs) love

Get started for freeTalk to us