Package com.google.android.filament

Class LightManager.Builder

java.lang.Object

com.google.android.filament.LightManager.Builder

Enclosing class:

LightManager

public static class LightManager.Builder
extends java.lang.Object

Use Builder to construct a Light object instance

Constructor Summary

Constructors

Constructor	Description
Builder(LightManager.Type type)	Creates a light builder and set the light's LightManager.Type.

Method Summary

Modifier and Type	Method	Description
void	build(Engine engine, int entity)	Adds the Light component to an entity.
LightManager.Builder	castLight(boolean enabled)	Whether this light casts light (enabled by default)
LightManager.Builder	castShadows(boolean enable)	Whether this Light casts shadows (disabled by default)
LightManager.Builder	color(float linearR, float linearG, float linearB)	Sets the initial color of a light.
LightManager.Builder	direction(float x, float y, float z)	Sets the initial direction of a light in world space.
LightManager.Builder	falloff(float radius)	Set the falloff distance for point lights and spot lights.
LightManager.Builder	intensity(float intensity)	Sets the initial intensity of a light.
LightManager.Builder	intensity(float watts, float efficiency)	Sets the initial intensity of a light in watts.
LightManager.Builder	intensityCandela(float intensity)	Sets the initial intensity of a spot or point light in candela.
LightManager.Builder	lightChannel(int channel, boolean enable)	Enables or disables a light channel.
LightManager.Builder	position(float x, float y, float z)	Sets the initial position of the light in world space.
LightManager.Builder	shadowOptions(LightManager.ShadowOptions options)	Sets the shadow map options for this light.
LightManager.Builder	spotLightCone(float inner, float outer)	Defines a spot light's angular falloff attenuation.
LightManager.Builder	sunAngularRadius(float angularRadius)	Defines the angular radius of the sun, in degrees, between 0.25° and 20.0° The Sun as seen from Earth has an angular size of 0.526° to 0.545°
LightManager.Builder	sunHaloFalloff(float haloFalloff)	Defines the halo falloff of the sun.
LightManager.Builder	sunHaloSize(float haloSize)	Defines the halo radius of the sun.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Builder

public Builder(@NonNull
               LightManager.Type type)

Creates a light builder and set the light's LightManager.Type.

Parameters:

type - LightManager.Type of Light object to create.

Method Detail

lightChannel

@NonNull
public LightManager.Builder lightChannel(@IntRange(from=0L,to=7L)
                                         int channel,
                                         boolean enable)

Enables or disables a light channel. Light channel 0 is enabled by default.

Parameters:

channel - Light channel to enable or disable, between 0 and 7.

enable - Whether to enable or disable the light channel.

castShadows

@NonNull
public LightManager.Builder castShadows(boolean enable)

Whether this Light casts shadows (disabled by default)

warning: LightManager.Type.POINT lights cannot cast shadows.

Parameters:

enable - Enables or disables casting shadows from this Light.

Returns:

This Builder, for chaining calls.

shadowOptions

@NonNull
public LightManager.Builder shadowOptions(@NonNull
                                          LightManager.ShadowOptions options)

Sets the shadow map options for this light.

Parameters:

options - A LightManager.ShadowOptions instance

Returns:

This Builder, for chaining calls.

See Also:

LightManager.ShadowOptions

castLight

@NonNull
public LightManager.Builder castLight(boolean enabled)

Whether this light casts light (enabled by default)

In some situations it can be useful to have a light in the scene that doesn't actually emit light, but does cast shadows.

Parameters:

enabled - Enables or disables lighting from this Light.

Returns:

This Builder, for chaining calls.

position

@NonNull
public LightManager.Builder position(float x,
                                     float y,
                                     float z)

Sets the initial position of the light in world space.

note: The Light's position is ignored for directional lights (LightManager.Type.DIRECTIONAL or LightManager.Type.SUN)

Parameters:

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.

Returns:

This Builder, for chaining calls.

direction

@NonNull
public LightManager.Builder direction(float x,
                                      float y,
                                      float z)

Sets the initial direction of a light in world space.

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:

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)

Returns:

This Builder, for chaining calls.

color

@NonNull
public LightManager.Builder color(float linearR,
                                  float linearG,
                                  float linearB)

Sets the initial color of a light.

The light color is specified in the linear sRGB color-space. The default is white.

Parameters:

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)

Returns:

This Builder, for chaining calls.

See Also:

LightManager.setColor(int, float, float, float)

intensity

@NonNull
public LightManager.Builder intensity(float intensity)

Sets the initial intensity of a light. This method overrides any prior calls to #intensity or #intensityCandela.

Parameters:

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.

Returns:

This Builder, for chaining calls.

See Also:

LightManager.setIntensity(int, float)

intensity

@NonNull
public LightManager.Builder intensity(float watts,
                                      float efficiency)

Sets the initial intensity of a light in watts.

  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);

This method overrides any prior calls to #intensity or #intensityCandela.

Parameters:

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.

Returns:

This Builder, for chaining calls.

intensityCandela

@NonNull
public LightManager.Builder intensityCandela(float intensity)

Sets the initial intensity of a spot or point light in candela.

Parameters:

intensity - Luminous intensity in candela. This method is equivalent to calling the plain intensity method for directional lights (Type.DIRECTIONAL or Type.SUN). This method overrides any prior calls to #intensity or #intensityCandela.

Returns:

This Builder, for chaining calls.

falloff

@NonNull
public LightManager.Builder falloff(float radius)

Set the falloff distance for point lights and spot lights.

At the falloff distance, the light has no more effect on objects.

The falloff distance essentially defines a sphere of influence around the light, and therefore has an impact on performance. Larger falloffs might reduce performance significantly, especially when many lights are used.

Try to avoid having a large number of light's spheres of influence overlap.

The Light's falloff is ignored for directional lights (LightManager.Type.DIRECTIONAL or LightManager.Type.SUN)

Parameters:

radius - Falloff distance in world units. Default is 1 meter.

Returns:

This Builder, for chaining calls.

spotLightCone

@NonNull
public LightManager.Builder spotLightCone(float inner,
                                          float outer)

Defines a spot light's angular falloff attenuation.

A spot light is defined by a position, a direction and two cones, inner and outer. These two cones are used to define the angular falloff attenuation of the spot light and are defined by the angle from the center axis to where the falloff begins (i.e. cones are defined by their half-angle).

note: The spot light cone is ignored for directional and point lights.

Parameters:

inner - inner cone angle in radian between 0 and pi/2

outer - outer cone angle in radian between inner and pi/2

Returns:

This Builder, for chaining calls.

See Also:

LightManager.Type.SPOT, LightManager.Type.FOCUSED_SPOT

sunAngularRadius

@NonNull
public LightManager.Builder sunAngularRadius(float angularRadius)

Defines the angular radius of the sun, in degrees, between 0.25° and 20.0° The Sun as seen from Earth has an angular size of 0.526° to 0.545°

Parameters:

angularRadius - sun's radius in degree. Default is 0.545°.

Returns:

This Builder, for chaining calls.

sunHaloSize

@NonNull
public LightManager.Builder sunHaloSize(float haloSize)

Defines the halo radius of the sun. The radius of the halo is defined as a multiplier of the sun angular radius.

Parameters:

haloSize - radius multiplier. Default is 10.0.

Returns:

This Builder, for chaining calls.

sunHaloFalloff

@NonNull
public LightManager.Builder sunHaloFalloff(float haloFalloff)

Defines the halo falloff of the sun. The falloff is a dimensionless number used as an exponent.

Parameters:

haloFalloff - halo falloff. Default is 80.0.

Returns:

This Builder, for chaining calls.

build

public void build(@NonNull
                  Engine engine,
                  int entity)

Adds the Light component to an entity.

If this component already exists on the given entity, it is first destroyed as if LightManager.destroy(int) was called.

warning: Currently, only 2048 lights can be created on a given Engine.

Parameters:

engine - Reference to the Engine to associate this light with.

entity - Entity to add the light component to.