Overview
Lights come in different types:- Directional lights - Parallel light rays from infinity (e.g., sun)
- Point lights - Emit light from a position in all directions
- Spot lights - Emit light from a position in a cone
Creation and Destruction
A Light component is created using the LightManager::Builder and destroyed by callingLightManager::destroy(utils::Entity).
Light Types
Directional light that also draws a sun’s disk in the sky. All light rays are parallel and come from infinitely far away. Used to simulate the sun
Directional light that emits light in a given direction. Similar to SUN but without the sun disk visualization
Point light that emits light from a position in all directions. Intensity diminishes with inverse square of distance
Physically correct spot light. Changing the outer cone angle affects illumination levels
Spot light with coupling of outer cone and illumination disabled. Allows independent control of cone angle and brightness
Builder Methods
Constructor
Creates a light builder and sets the light’s Type.Type of Light object to create
lightChannel
Enables or disables a light channel. Light channel 0 is enabled by default.Light channel to enable or disable, between 0 and 7
Whether to enable or disable the light channel
This Builder, for chaining calls
castShadows
Whether this Light casts shadows (disabled by default).Enables or disables casting shadows from this Light
This Builder, for chaining calls
shadowOptions
Sets the shadow-map options for this light.Shadow configuration options
This Builder, for chaining calls
castLight
Whether this light casts light (enabled by default).Enables or disables lighting from this Light
This Builder, for chaining calls
position
Sets the initial position of the light in world space.Light’s position in world space. Default is at the origin
This Builder, for chaining calls
The Light’s position is ignored for directional lights (Type::DIRECTIONAL or Type::SUN).
direction
Sets the initial direction of a light in world space.Light’s direction in world space. Should be a unit vector. Default is
This Builder, for chaining calls
The Light’s direction is ignored for Type::POINT lights.
color
Sets the initial color of a light.Color of the light specified in the linear sRGB color-space. Default is white
This Builder, for chaining calls
intensity
Sets the initial intensity of a light.For directional lights: illuminance in lux (lumen/m²). For point/spot lights: luminous power in lumen
This Builder, for chaining calls
intensity (Watts)
Sets the initial intensity of a light in watts.Energy consumed by a lightbulb. Related to brightness by the efficiency parameter
Efficiency as a decimal (not percentage). See efficiency constants below
This Builder, for chaining calls
Efficiency Constants
| Lightbulb Type | Constant | Efficiency |
|---|---|---|
| Incandescent | EFFICIENCY_INCANDESCENT | 2.2% |
| Halogen | EFFICIENCY_HALOGEN | 7.0% |
| Fluorescent | EFFICIENCY_FLUORESCENT | 8.7% |
| LED | EFFICIENCY_LED | 11.7% |
intensityCandela
Sets the initial intensity of a spot or point light in candela.Luminous intensity in candela
This Builder, for chaining calls
falloff
Set the falloff distance for point lights and spot lights.Falloff distance in world units. Default is 1 meter
This Builder, for chaining calls
The Light’s falloff is ignored for directional lights (Type::DIRECTIONAL or Type::SUN).
spotLightCone
Defines a spot light’s angular falloff attenuation.Inner cone angle in radians, between 0.00873 (0.5°) and outer
Outer cone angle in radians, between 0.00873 (0.5°) and π/2
This Builder, for chaining calls
The spot light cone is ignored for directional and point lights.
sunAngularRadius
Defines the angular radius of the sun, in degrees.Sun’s radius in degrees, between 0.25° and 20.0°. Default is 0.545°
This Builder, for chaining calls
sunHaloSize
Defines the halo radius of the sun.Radius multiplier of the sun angular radius. Default is 10.0
This Builder, for chaining calls
sunHaloFalloff
Defines the halo falloff of the sun.Dimensionless number used as an exponent. Default is 80.0
This Builder, for chaining calls
build
Adds the Light component to an entity.Reference to the filament::Engine to associate this light with
Entity to add the light component to
Success if the component was created successfully, Error otherwise
ShadowOptions
Control the quality and performance of the shadow map associated with a light.Size of the shadow map in texels. Must be a power-of-two and >= 8
Number of shadow cascades (1-4). Only applicable to Type::SUN or Type::DIRECTIONAL lights. Values > 1 enable cascaded shadow mapping (CSM)
Split positions for shadow cascades. Values represent camera frustum split planes from near (0.0) to far (1.0)
Constant bias in world units (e.g., meters). Default is 1mm. Ignored when View’s ShadowType is VSM
Scale factor for maximum sampling error. Should be 1.0. Ignored when View’s ShadowType is VSM
Distance from camera after which shadows are clipped. Use 0.0 for camera far distance. Only affects directional lights
Optimize shadow quality from this distance (meters). Default 1m works well for many scenes
Optimize shadow quality in front of this distance (meters)
When true, optimizes for stability over resolution. Disables LiSPSM and resolution enhancements
Enable Light-space Perspective Shadow Mapping for better shadow resolution
Constant depth bias in depth-resolution units. Generally should be small and positive
Slope-based depth bias. Default works well with PCF_LOW. Essential for LiSPSM
Whether to use screen-space contact shadows
Number of ray-marching steps for screen-space contact shadows
Maximum shadow-occluder distance for screen-space contact shadows (world units)
Light bulb radius for soft shadows (2cm default). Used with DPCF or PCSS
Transforms the shadow direction. Must be a unit quaternion. Ignored for non-directional lights
ShadowCascades Utilities
computeUniformSplits
Compute cascadeSplitPositions according to a uniform split scheme.Float array of at least size (cascades - 1) to write split positions into
Number of shadow cascades, at most 4
computeLogSplits
Compute cascadeSplitPositions according to a logarithmic split scheme.Float array of at least size (cascades - 1)
Number of shadow cascades, at most 4
Camera near plane distance
Camera far plane distance
computePracticalSplits
Compute cascadeSplitPositions according to a practical split scheme.Float array of at least size (cascades - 1)
Number of shadow cascades, at most 4
Camera near plane distance
Camera far plane distance
Value in [0, 1] that interpolates between log and uniform split schemes. Start with 0.5
Instance Methods
getType
Returns the type of the light.Instance of the component obtained from getInstance()
The light type
isDirectional
Helper function that returns if a light is a directional light.Instance of the component
True if this light is Type::DIRECTIONAL or Type::SUN
isPointLight
Helper function that returns if a light is a point light.Instance of the component
True if this light is Type::POINT
isSpotLight
Helper function that returns if a light is a spot light.Instance of the component
True if this light is Type::SPOT or Type::FOCUSED_SPOT
setPosition
Dynamically updates the light’s position.Instance of the component
Light’s position in world space
getPosition
Returns the light’s position in world space.Instance of the component
Light position
setDirection
Dynamically updates the light’s direction.Instance of the component
Light’s direction in world space. Should be a unit vector
getDirection
Returns the light’s direction in world space.Instance of the component
Light direction
setColor
Dynamically updates the light’s hue as linear sRGB.Instance of the component
Color of the light in linear sRGB color-space
getColor
Returns the light’s color in linear sRGB.Instance of the component
Light color
setIntensity
Dynamically updates the light’s intensity. The intensity can be negative.Instance of the component
For directional lights: illuminance in lux. For point/spot lights: luminous power in lumen
getIntensity
Returns the light’s luminous intensity in candela.Instance of the component
Luminous intensity in candela. For Type::FOCUSED_SPOT lights, depends on outer cone angle
setShadowCaster
Enables or disables shadow casting for this light.Instance of the component
Enables or disables casting shadows
isShadowCaster
Returns whether this light casts shadows.Instance of the component
True if shadow casting is enabled
Complete Example
Performance Tips
- Prefer spot lights to point lights and use the smallest outer cone angle possible
- Use the smallest possible falloff distance for point and spot lights
- Minimize overlapping lights - Performance is very sensitive to light overlap
- Hundreds of non-overlapping lights can be handled without significant overhead
- Only one directional light is currently supported - if multiple are added, the dominant one will be used