java.lang.Object
- com.google.android.filament.LightManager

```
public class LightManager
extends java.lang.Object
```
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 Material.Shading.UNLIT is used).

Creation and destruction

A Light component is created using the LightManager.Builder and destroyed by calling destroy(int).
```
  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 LightManager.Type.DIRECTIONAL or LightManager.Type.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. LightManager.Builder.falloff(float) 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 LightManager.Builder.spotLightCone(float, float) 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 LightManager.Type.FOCUSED_SPOT (physically correct) and LightManager.Type.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.

Nested Class Summary

Nested Classes
Modifier and Type	Class	Description
`static class`	`LightManager.Builder`	Use Builder to construct a Light object instance
`static class`	`LightManager.ShadowCascades`
`static class`	`LightManager.ShadowOptions`	Control the quality / performance of the shadow map associated to this light
`static class`	`LightManager.Type`	Denotes the type of the light being created.

Field Summary

Fields
Modifier and Type	Field	Description
`static float`	`EFFICIENCY_FLUORESCENT`	Typical efficiency of a fluorescent light bulb (8.7%)
`static float`	`EFFICIENCY_HALOGEN`	Typical efficiency of an halogen light bulb (7.0%)
`static float`	`EFFICIENCY_INCANDESCENT`	Typical efficiency of an incandescent light bulb (2.2%)
`static float`	`EFFICIENCY_LED`	Typical efficiency of a LED light bulb (11.7%)

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method	Description
`void`	`destroy(int entity)`	Destroys this component from the given entity
`float[]`	`getColor(int i, float[] out)`	Returns the light color
`int`	`getComponentCount()`	Returns the number of components in the LightManager, note that components are not guaranteed to be active.
`float[]`	`getDirection(int i, float[] out)`	returns the light's direction in world space
`float`	`getFalloff(int i)`	returns the falloff distance of this light.
`float`	`getInnerConeAngle(int i)`
`int`	`getInstance(int entity)`	Gets an Instance representing the Light component associated with the given Entity.
`float`	`getIntensity(int i)`	returns the light's luminous intensity in lumens.
`boolean`	`getLightChannel(int i, int channel)`	Returns whether a light channel is enabled on a specified renderable.
`long`	`getNativeObject()`
`float`	`getOuterConeAngle(int i)`
`float[]`	`getPosition(int i, float[] out)`	returns the light's position in world space
`float`	`getSunAngularRadius(int i)`	returns the angular radius if the sun in degrees.
`float`	`getSunHaloFalloff(int i)`	returns the halo falloff of a Type.SUN light as a dimensionless value.
`float`	`getSunHaloSize(int i)`	returns the halo size of a Type.SUN light as a multiplier of the sun angular radius.
`LightManager.Type`	`getType(int i)`
`boolean`	`hasComponent(int entity)`	Returns whether a particular Entity is associated with a component of this LightManager
`boolean`	`isShadowCaster(int i)`	returns whether this light casts shadows.
`void`	`setColor(int i, float linearR, float linearG, float linearB)`	Dynamically updates the light's hue as linear sRGB
`void`	`setDirection(int i, float x, float y, float z)`	Dynamically updates the light's direction
`void`	`setFalloff(int i, float falloff)`	Set the falloff distance for point lights and spot lights.
`void`	`setIntensity(int i, float intensity)`	Dynamically updates the light's intensity.
`void`	`setIntensity(int i, float watts, float efficiency)`	Dynamically updates the light's intensity.
`void`	`setIntensityCandela(int i, float intensity)`	Dynamically updates the light's intensity in candela.
`void`	`setLightChannel(int i, int channel, boolean enable)`	Enables or disables a light channel.
`void`	`setPosition(int i, float x, float y, float z)`	Dynamically updates the light's position.
`void`	`setShadowCaster(int i, boolean shadowCaster)`	Whether this Light casts shadows (disabled by default)
`void`	`setSpotLightCone(int i, float inner, float outer)`	Dynamically updates a spot light's cone as angles
`void`	`setSunAngularRadius(int i, float angularRadius)`	Dynamically updates the angular radius of a Type.SUN light The Sun as seen from Earth has an angular size of 0.526° to 0.545°
`void`	`setSunHaloFalloff(int i, float haloFalloff)`	Dynamically updates the halo falloff of a Type.SUN light.
`void`	`setSunHaloSize(int i, float haloSize)`	Dynamically updates the halo radius of a Type.SUN light.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - EFFICIENCY_INCANDESCENT
```
public static final float EFFICIENCY_INCANDESCENT
```
    Typical efficiency of an incandescent light bulb (2.2%)
    
    See Also:
    
    Constant Field Values
  - EFFICIENCY_HALOGEN
```
public static final float EFFICIENCY_HALOGEN
```
    Typical efficiency of an halogen light bulb (7.0%)
    
    See Also:
    
    Constant Field Values
  - EFFICIENCY_FLUORESCENT
```
public static final float EFFICIENCY_FLUORESCENT
```
    Typical efficiency of a fluorescent light bulb (8.7%)
    
    See Also:
    
    Constant Field Values
  - EFFICIENCY_LED
```
public static final float EFFICIENCY_LED
```
    Typical efficiency of a LED light bulb (11.7%)
    
    See Also:
    
    Constant Field Values
- Method Detail
  - getComponentCount
```
public int getComponentCount()
```
    Returns the number of components in the LightManager, note that components are not guaranteed to be active. Use the EntityManager.isAlive(int) before use if needed.
    
    Returns:
    
    number of component in the LightManager
  - hasComponent
```
public boolean hasComponent(int entity)
```
    Returns whether a particular Entity is associated with a component of this LightManager
    
    Parameters:
    
    entity - An Entity.
    
    Returns:
    
    true if this Entity has a component associated with this manager.
  - getInstance
```
public int getInstance(int entity)
```
    Gets an Instance representing the Light component associated with the given Entity.
    
    Parameters:
    
    entity - An Entity.
    
    Returns:
    
    An Instance object, which represents the Light component associated with the Entity entity. The instance is 0 if the component doesn't exist.
    
    See Also:
    
    hasComponent(int)
  - destroy
```
public void destroy(int entity)
```
    Destroys this component from the given entity
    
    Parameters:
    
    entity - An Entity.
  - getType
```
@NonNull
public LightManager.Type getType(int i)
```
  - setLightChannel
```
public void setLightChannel(int i,
                            @IntRange(from=0L,to=7L)
                            int channel,
                            boolean enable)
```
    Enables or disables a light channel. Light channel 0 is enabled by default.
    
    Parameters:
    
    i - Instance of the component obtained from getInstance().
    
    channel - Light channel to set
    
    enable - true to enable, false to disable
    
    See Also:
    
    LightManager.Builder.lightChannel(int, boolean)
  - getLightChannel
```
public boolean getLightChannel(int i,
                               @IntRange(from=0L,to=7L)
                               int channel)
```
    Returns whether a light channel is enabled on a specified renderable.
    
    Parameters:
    
    i - Instance of the component obtained from getInstance().
    
    channel - Light channel to query
    
    Returns:
    
    true if the light channel is enabled, false otherwise
  - setPosition
```
public void setPosition(int i,
                        float x,
                        float y,
                        float z)
```
    Dynamically updates the light's position.
    note: The Light's position is ignored for directional lights (LightManager.Type.DIRECTIONAL or LightManager.Type.SUN)
    
    Parameters:
    
    i - Instance of the component obtained from getInstance().
    
    x - Light's position x coordinate in world space. The default is 0.
    
    y - Light's position y coordinate in world space. The default is 0.
    
    z - Light's position z coordinate in world space. The default is 0.
    
    See Also:
    
    LightManager.Builder.position(float, float, float)
  - getPosition
```
@NonNull
public float[] getPosition(int i,
                           @Nullable @Size(min=3L)
                           float[] out)
```
    returns the light's position in world space
    
    Parameters:
    
    i - Instance of the component obtained from getInstance().
    
    out - An array of 3 float to receive the result or null.
    
    Returns:
    
    An array of 3 float containing the light's position coordinates.
  - setDirection
```
public void setDirection(int i,
                         float x,
                         float y,
                         float z)
```
    Dynamically updates the light's direction
    The light direction is specified in world space and should be a unit vector.
    
    note: The Light's direction is ignored for LightManager.Type.POINT lights.
    
    Parameters:
    
    i - Instance of the component obtained from getInstance().
    
    x - light's direction x coordinate (default is 0)
    
    y - light's direction y coordinate (default is -1)
    
    z - light's direction z coordinate (default is 0)
    
    See Also:
    
    LightManager.Builder.direction(float, float, float)
  - getDirection
```
@NonNull
public float[] getDirection(int i,
                            @Nullable @Size(min=3L)
                            float[] out)
```
    returns the light's direction in world space
    
    Parameters:
    
    i - Instance of the component obtained from getInstance().
    
    out - An array of 3 float to receive the result or null.
    
    Returns:
    
    An array of 3 float containing the light's direction.
  - setColor
```
public void setColor(int i,
                     float linearR,
                     float linearG,
                     float linearB)
```
    Dynamically updates the light's hue as linear sRGB
    
    Parameters:
    
    i - Instance of the component obtained from getInstance().
    
    linearR - red component of the color (default is 1)
    
    linearG - green component of the color (default is 1)
    
    linearB - blue component of the color (default is 1)
    
    See Also:
    
    LightManager.Builder.color(float, float, float), getInstance(int)
  - getColor
```
@NonNull
public float[] getColor(int i,
                        @Nullable @Size(min=3L)
                        float[] out)
```
    Returns the light color
    
    Parameters:
    
    i - Instance of the component obtained from getInstance().
    
    Returns:
    
    An array of 3 float containing the light's color in linear sRGB
  - setIntensity
```
public void setIntensity(int i,
                         float intensity)
```
    Dynamically updates the light's intensity. The intensity can be negative.
    
    Parameters:
    
    i - Instance of the component obtained from getInstance().
    
    intensity - This parameter depends on the LightManager.Type, for directional lights, it specifies the illuminance in lux (or lumen/m^2). For point lights and spot lights, it specifies the luminous power in lumen. For example, the sun's illuminance is about 100,000 lux.
    
    See Also:
    
    LightManager.Builder.intensity(float)
  - setIntensityCandela
```
public void setIntensityCandela(int i,
                                float intensity)
```
    Dynamically updates the light's intensity in candela. The intensity can be negative. This method is equivalent to calling setIntensity for directional lights (Type.DIRECTIONAL or Type.SUN).
    
    Parameters:
    
    i - Instance of the component obtained from getInstance().
    
    intensity - Luminous intensity in candela.
    
    See Also:
    
    LightManager.Builder.intensityCandela(float)
  - setIntensity
```
public void setIntensity(int i,
                         float watts,
                         float efficiency)
```
    Dynamically updates the light's intensity. The intensity can be negative.
    Lightbulb type | Efficiency -----------------+------------ Incandescent | 2.2% Halogen | 7.0% LED | 8.7% Fluorescent | 10.7%
    This call is equivalent to:
    Builder.intensity(efficiency * 683 * watts);
    Parameters:
    
    i - Instance of the component obtained from getInstance().
    
    watts - Energy consumed by a lightbulb. It is related to the energy produced and ultimately the brightness by the efficiency parameter. This value is often available on the packaging of commercial lightbulbs.
    
    efficiency - Efficiency in percent. This depends on the type of lightbulb used.
  - getIntensity
```
public float getIntensity(int i)
```
    returns the light's luminous intensity in lumens.
    note: for LightManager.Type.FOCUSED_SPOT lights, the returned value depends on the outer cone angle.
    
    Parameters:
    
    i - Instance of the component obtained from getInstance().
    
    Returns:
    
    luminous intensity in lumen.
  - setFalloff
```
public void setFalloff(int i,
                       float falloff)
```
    Set the falloff distance for point lights and spot lights.
    
    Parameters:
    
    i - Instance of the component obtained from getInstance().
    
    falloff - falloff distance in world units. Default is 1 meter.
    
    See Also:
    
    LightManager.Builder.falloff(float)
  - getFalloff
```
public float getFalloff(int i)
```
    returns the falloff distance of this light.
    
    Parameters:
    
    i - Instance of the component obtained from getInstance().
    
    Returns:
    
    the falloff distance of this light.
  - setSpotLightCone
```
public void setSpotLightCone(int i,
                             float inner,
                             float outer)
```
    Dynamically updates a spot light's cone as angles
    
    Parameters:
    
    i - Instance of the component obtained from getInstance().
    
    inner - inner cone angle in *radians* between 0 and pi/2
    
    outer - outer cone angle in *radians* between inner and pi/2
    
    See Also:
    
    LightManager.Builder.spotLightCone(float, float)
  - setSunAngularRadius
```
public void setSunAngularRadius(int i,
                                float angularRadius)
```
    Dynamically updates the angular radius of a Type.SUN light The Sun as seen from Earth has an angular size of 0.526° to 0.545°
    
    Parameters:
    
    i - Instance of the component obtained from getInstance().
    
    angularRadius - sun's radius in degrees. Default is 0.545°.
  - getSunAngularRadius
```
public float getSunAngularRadius(int i)
```
    returns the angular radius if the sun in degrees.
    
    Parameters:
    
    i - Instance of the component obtained from getInstance().
    
    Returns:
    
    the angular radius if the sun in degrees.
  - setSunHaloSize
```
public void setSunHaloSize(int i,
                           float haloSize)
```
    Dynamically updates the halo radius of a Type.SUN light. The radius of the halo is defined as a multiplier of the sun angular radius.
    
    Parameters:
    
    i - Instance of the component obtained from getInstance().
    
    haloSize - radius multiplier. Default is 10.0.
  - getSunHaloSize
```
public float getSunHaloSize(int i)
```
    returns the halo size of a Type.SUN light as a multiplier of the sun angular radius.
    
    Parameters:
    
    i - Instance of the component obtained from getInstance().
    
    Returns:
    
    the halo size
  - setSunHaloFalloff
```
public void setSunHaloFalloff(int i,
                              float haloFalloff)
```
    Dynamically updates the halo falloff of a Type.SUN light. The falloff is a dimensionless number used as an exponent.
    
    Parameters:
    
    i - Instance of the component obtained from getInstance().
    
    haloFalloff - halo falloff. Default is 80.0.
  - getSunHaloFalloff
```
public float getSunHaloFalloff(int i)
```
    returns the halo falloff of a Type.SUN light as a dimensionless value.
    
    Parameters:
    
    i - Instance of the component obtained from getInstance().
    
    Returns:
    
    the halo falloff
  - setShadowCaster
```
public void setShadowCaster(int i,
                            boolean shadowCaster)
```
    Whether this Light casts shadows (disabled by default)
    warning: LightManager.Type.POINT cannot cast shadows.
    
    Parameters:
    
    i - Instance of the component obtained from getInstance().
    
    shadowCaster - Enables or disables casting shadows from this Light.
  - isShadowCaster
```
public boolean isShadowCaster(int i)
```
    returns whether this light casts shadows.
    
    Parameters:
    
    i - Instance of the component obtained from getInstance().
  - getOuterConeAngle
```
public float getOuterConeAngle(int i)
```
  - getInnerConeAngle
```
public float getInnerConeAngle(int i)
```
  - getNativeObject
```
public long getNativeObject()
```

Class LightManager

Creation and destruction

Light types

Directional lights

Point lights

Spot lights

Performance considerations

Nested Class Summary

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

EFFICIENCY_INCANDESCENT

EFFICIENCY_HALOGEN

EFFICIENCY_FLUORESCENT

EFFICIENCY_LED

Method Detail

getComponentCount

hasComponent

getInstance

destroy

getType

setLightChannel

getLightChannel

setPosition

getPosition

setDirection

getDirection

setColor

getColor

setIntensity

setIntensityCandela

setIntensity

getIntensity

setFalloff

getFalloff

setSpotLightCone

setSunAngularRadius

getSunAngularRadius

setSunHaloSize

getSunHaloSize

setSunHaloFalloff

getSunHaloFalloff

setShadowCaster

isShadowCaster

getOuterConeAngle

getInnerConeAngle

getNativeObject