Class Light

java.lang.Object
com.codename1.gpu.Light
public final class Light extends Object
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).

  • Constructor Summary

    Constructors
    Constructor
    Description
    Light()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    computeCascadeMatrix(int cascade, float[] out)
    For a backend: the matrix of one cascade.
    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.
    int
    getAmbientColor()
    Returns the ambient color as a packed ARGB integer.
    int
    getColor()
    Returns the light color as a packed ARGB integer.
    float
    getDirectionX()
    Returns the x component of the light direction.
    float
    getDirectionY()
    Returns the y component of the light direction.
    float
    getDirectionZ()
    Returns the z component of the light direction.
    float
    getShadowBias()
    Returns the shadow depth bias.
    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.
    int
    getShadowCascades()
    Returns the number of shadow cascades, 1 or 2.
    float
    getShadowCenterX()
    Returns the x of the point the shadow map is centred on.
    float
    getShadowCenterZ()
    Returns the z of the point the shadow map is centred on.
    float
    getShadowExtent()
    Returns the half width of the area the shadow map covers.
    float
    getShadowFarExtent()
    Returns the half width of the far cascade, or the shadow extent with a single cascade.
    int
    getShadowMapSize()
    Returns the shadow map's width and height in texels.
    float
    getShadowSoftness()
    Returns the shadow softness set with setShadowSoftness.
    float
    getShadowStrength()
    Returns how dark a shadow is, from 0 to 1.
    boolean
    isShadows()
    Returns true if the light casts shadows.
    Light
    setAmbientColor(int argb)
    Sets the ambient color as a packed ARGB integer.
    Light
    setColor(int argb)
    Sets the light color as a packed ARGB integer.
    Light
    setDirection(float x, float y, float z)
    Sets the world space direction the light travels.
    Light
    setShadowCascades(int count, float farExtent)
    Splits the shadow map into cascades.
    Light
    setShadowCenter(float x, float y, float z)
    Centres the shadow map on a world point, normally the one the camera looks at.
    Light
    setShadowMap(int size, float extent)
    Sets the area and resolution of the shadow map.
    Light
    setShadows(boolean shadows)
    Turns shadow casting on or off.
    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.
    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.

    Methods inherited from class Object

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

  • 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: the x component

      • y: the y component

      • z: 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: 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: 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: 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: the width and height of the map in texels; clamped to 256 to 4096

      • extent: 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: the x coordinate

      • y: the y coordinate

      • z: 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: 0 for no darkening, 1 for no direct light at all

      • bias: 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: 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: 1 for a single map, 2 for a near and a far cascade

      • farExtent: 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: 0 or 1

      • out: 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: a 16 element array that receives the column-major matrix