Client API. The Codename One framework your app is built on: this runs on the device, not in a backend.

public final class Light

  1. Object
  2. Light
A single directional light plus a global ambient term, consumed by lit materials (Material.Type.LAMBERT and Material.Type.PHONG). The direction is the direction the light travels, in world space. Set the active light on the device with GraphicsDevice.setLight(Light).

Constructors

public Light()

Methods

public Light setDirection(float x, float y, float z)Sets the world space direction the light travels.
public float getDirectionX()Returns the x component of the light direction.
public float getDirectionY()Returns the y component of the light direction.
public float getDirectionZ()Returns the z component of the light direction.
public int getColor()Returns the light color as a packed ARGB integer.
public Light setColor(int argb)Sets the light color as a packed ARGB integer.
public int getAmbientColor()Returns the ambient color as a packed ARGB integer.
public Light setAmbientColor(int argb)Sets the ambient color as a packed ARGB integer.
public Light setShadows(boolean shadows)Turns shadow casting on or off.
public boolean isShadows()Returns true if the light casts shadows.
public Light setShadowMap(int size, float extent)Sets the area and resolution of the shadow map.
public int getShadowMapSize()Returns the shadow map’s width and height in texels.
public float getShadowCenterX()Returns the x of the point the shadow map is centred on.
public float getShadowCenterZ()Returns the z of the point the shadow map is centred on.
public float getShadowExtent()Returns the half width of the area the shadow map covers.
public Light setShadowCenter(float x, float y, float z)Centres the shadow map on a world point, normally the one the camera looks at.
public Light setShadowStyle(float strength, float bias)Sets how dark a shadow is and how far a surface must be behind the shadow map before it counts as shadowed.
public float getShadowStrength()Returns how dark a shadow is, from 0 to 1.
public Light setShadowSoftness(float softness)Sets how soft shadow edges are: the spacing, in shadow map texels, of the 3 by 3 samples every shaded pixel averages.
public float getShadowSoftness()Returns the shadow softness set with setShadowSoftness.
public Light setShadowCascades(int count, float farExtent)Splits the shadow map into cascades.
public int getShadowCascades()Returns the number of shadow cascades, 1 or 2.
public float getShadowFarExtent()Returns the half width of the far cascade, or the shadow extent with a single cascade.
public float getShadowCascadeRatio()For a backend: the factor the far cascade scales the near cascade’s x and y by, the near extent over the far one; 0 with a single cascade.
public void computeCascadeMatrix(int cascade, float[] out)For a backend: the matrix of one cascade.
public float getShadowBias()Returns the shadow depth bias.
public void computeShadowMatrix(float[] out)Computes the matrix that takes a world position to the shadow map’s clip space: an orthographic view along the light’s direction, centred on the shadow centre.

Inherited methods

From Object

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

Constructor details

Light

public Light()

Method details

setDirection

public Light setDirection(float x, float y, float z)
Sets the world space direction the light travels.

Parameters

x float
the x component
y float
the y component
z float
the z component

Returns

this light for chaining

getDirectionX

public float getDirectionX()
Returns the x component of the light direction.

getDirectionY

public float getDirectionY()
Returns the y component of the light direction.

getDirectionZ

public float getDirectionZ()
Returns the z component of the light direction.

getColor

public int getColor()
Returns the light color as a packed ARGB integer.

setColor

public Light setColor(int argb)
Sets the light color as a packed ARGB integer.

Parameters

argb int
the packed ARGB color

Returns

this light for chaining

getAmbientColor

public int getAmbientColor()
Returns the ambient color as a packed ARGB integer.

setAmbientColor

public Light setAmbientColor(int argb)
Sets the ambient color as a packed ARGB integer.

Parameters

argb int
the packed ARGB color

Returns

this light for chaining

setShadows

public Light setShadows(boolean shadows)

Turns shadow casting on or off. With shadows on, a GraphicsDevice that supports them (GpuCapabilities.isShadowsSupported) renders the scene from the light into a shadow map before each frame, and lit materials that receive shadows are darkened where it is blocked.

The map covers a square extent units either side of the shadow centre, seen along the light’s direction; move the centre with the camera (setShadowCenter) and keep the extent as small as the view allows, since the map’s resolution is spread over it.

Parameters

shadows boolean
true to cast shadows

Returns

this light for chaining

isShadows

public boolean isShadows()
Returns true if the light casts shadows.

setShadowMap

public Light setShadowMap(int size, float extent)
Sets the area and resolution of the shadow map.

Parameters

size int
the width and height of the map in texels; clamped to 256 to 4096
extent float
the half width of the square it covers, in world units

Returns

this light for chaining

getShadowMapSize

public int getShadowMapSize()
Returns the shadow map’s width and height in texels.

getShadowCenterX

public float getShadowCenterX()
Returns the x of the point the shadow map is centred on.

getShadowCenterZ

public float getShadowCenterZ()
Returns the z of the point the shadow map is centred on.

getShadowExtent

public float getShadowExtent()
Returns the half width of the area the shadow map covers.

setShadowCenter

public Light setShadowCenter(float x, float y, float z)
Centres the shadow map on a world point, normally the one the camera looks at.

Parameters

x float
the x coordinate
y float
the y coordinate
z float
the z coordinate

Returns

this light for chaining

setShadowStyle

public Light setShadowStyle(float strength, float bias)
Sets how dark a shadow is and how far a surface must be behind the shadow map before it counts as shadowed.

Parameters

strength float
0 for no darkening, 1 for no direct light at all
bias float
the depth offset in the map’s 0..1 range; raise it if surfaces shadow themselves in stripes (“acne”), lower it if shadows detach from the objects that cast them

Returns

this light for chaining

getShadowStrength

public float getShadowStrength()
Returns how dark a shadow is, from 0 to 1.

setShadowSoftness

public Light setShadowSoftness(float softness)
Sets how soft shadow edges are: the spacing, in shadow map texels, of the 3 by 3 samples every shaded pixel averages. 1 is a crisp edge with its stair steps smoothed; 2 to 3 is a soft outdoor penumbra. Larger values start to show the sample pattern.

Parameters

softness float
the sample spacing in texels, at least 0.5

Returns

this light for chaining

getShadowSoftness

public float getShadowSoftness()
Returns the shadow softness set with setShadowSoftness.

setShadowCascades

public Light setShadowCascades(int count, float farExtent)
Splits the shadow map into cascades. With two, the map set by setShadowMap keeps its resolution for the area near the shadow centre, and a second map of the same size covers farExtent units either side of it, so a large scene gets crisp shadows up close and coarse ones in the distance instead of coarse shadows everywhere. Each shaded pixel uses the near map when it falls inside it and the far one otherwise. Casters are drawn once per cascade.

Parameters

count int
1 for a single map, 2 for a near and a far cascade
farExtent float
the half width of the far cascade in world units; ignored with one cascade, and never less than the near extent

Returns

this light for chaining

getShadowCascades

public int getShadowCascades()
Returns the number of shadow cascades, 1 or 2.

getShadowFarExtent

public float getShadowFarExtent()
Returns the half width of the far cascade, or the shadow extent with a single cascade.

getShadowCascadeRatio

public float getShadowCascadeRatio()
For a backend: the factor the far cascade scales the near cascade’s x and y by, the near extent over the far one; 0 with a single cascade. It is the fourth component of the shadow parameters every generated shader receives.

Returns

the ratio in (0, 1], or 0 when the map is not split

computeCascadeMatrix

public void computeCascadeMatrix(int cascade, float[] out)
For a backend: the matrix of one cascade. Cascade 0 is computeShadowMatrix; cascade 1 is the same view scaled in x and y by getShadowCascadeRatio, so both share one depth range. A backend draws cascade i into the ith square of a map getShadowCascades squares wide.

Parameters

cascade int
0 or 1
out float[]
a 16 element array that receives the column-major matrix

getShadowBias

public float getShadowBias()
Returns the shadow depth bias.

computeShadowMatrix

public void computeShadowMatrix(float[] out)
Computes the matrix that takes a world position to the shadow map’s clip space: an orthographic view along the light’s direction, centred on the shadow centre. Every backend uses this one, so shadows land in the same place on each.

Parameters

out float[]
a 16 element array that receives the column-major matrix