//filament-android/com.google.android.filament/LightManager

LightManager

[main]
open class LightManager

LightManager allows you to create a light source in the scene, such as a sun or street lights.

At least one light must be added to a scene in order to see anything (unless the UNLIT is used).

Creation and destruction

A Light component is created using the LightManager.Builder and destroyed by calling destroy.

 Engine engine = Engine.create();
 int sun = EntityManager.get().create();

 LightManager.Builder(Type.SUN)
             .castShadows(true)
             .build(engine, sun);

 engine.getLightManager().destroy(sun);

Light types

Lights come in three flavors:

• directional lights
• point lights
• spot lights

Directional lights

Directional lights have a direction, but don't have a position. All light rays are parallel and come from infinitely far away and from everywhere. Typically a directional light is used to simulate the sun.

Directional lights and spot lights are able to cast shadows.

To create a directional light use DIRECTIONAL or SUN, both are similar, but the later also draws a sun's disk in the sky and its reflection on glossy objects.

warning: Currently, only a single directional light is supported. If several directional lights are added to the scene, the dominant one will be used.

Point lights

Unlike directional lights, point lights have a position but emit light in all directions. The intensity of the light diminishes with the inverse square of the distance to the light. falloff controls the distance beyond which the light has no more influence.

A scene can have multiple point lights.

Spot lights

Spot lights are similar to point lights but the light they emit is limited to a cone defined by spotLightCone and the light's direction.

A spot light is therefore defined by a position, a direction and inner and outer cones. The spot light's influence is limited to inside the outer cone. The inner cone defines the light's falloff attenuation.

A physically correct spot light is a little difficult to use because changing the outer angle of the cone changes the illumination levels, as the same amount of light is spread over a changing volume. The coupling of illumination and the outer cone means that an artist cannot tweak the influence cone of a spot light without also changing the perceived illumination. It therefore makes sense to provide artists with a parameter to disable this coupling. This is the difference between FOCUSED_SPOT (physically correct) and SPOT (decoupled).

Performance considerations

Generally, adding lights to the scene hurts performance, however filament is designed to be able to handle hundreds of lights in a scene under certain conditions. Here are some tips to keep good performance.

• 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. Performance is very sensitive to overlapping lights. The falloff distance essentially defines a sphere of influence for the light, so try to position point and spot lights such that they don't overlap too much.
• On the other hand, a scene can contain hundreds of non overlapping lights without incurring a significant overhead.

Types

Properties

Functions