Class Environment

java.lang.Object
com.codename1.gpu.Environment
public final class Environment extends Object

The atmosphere every draw is shaded in: fog, the sky and ground colours that light a surface from above and below, and how the result is exposed and tone mapped to the display.

A default environment changes nothing: no fog, the light's own ambient colour and no tone mapping, so a scene that never sets one renders exactly as before. Set it with GraphicsDevice.setEnvironment, or GameView.getEnvironment() in a game.

GameView view = new GameView() {
    protected void update(double deltaSeconds) {
    }
};
view.getEnvironment()
        .setFog(0xffa9b3ba, 0.035f, 0.08f)
        .setHemisphere(0xff9fb4c8, 0xff4a4036)
        .setToneMapping(true)
        .setExposure(1.1f);

Fog is exponential squared in distance from the eye, thinned with height by heightFalloff, so a valley fills with haze while a rooftop stays clear. It applies to every material type except Material.Type.SKYBOX.

  • Constructor Summary

    Constructors
    Constructor
    Description
    Environment()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    Environment
    clearHemisphere()
    Goes back to the light's own flat ambient colour.
    Environment
    clearSky()
    Goes back to drawing Material.Type.SKYBOX surfaces in their own colour and texture.
    float
    getCloudCover()
    Returns how much of the sky is cloud, from 0 to 1.
    float
    getExposure()
    Returns the exposure multiplier.
    float
    getFogBaseHeight()
    Returns the height at which fog is at its full density.
    int
    getFogColor()
    Returns the fog colour as ARGB.
    float
    getFogDensity()
    Returns the fog density per world unit, 0 when there is no fog.
    float
    getFogHeightFalloff()
    Returns how quickly fog thins with height, per world unit.
    int
    getGroundColor()
    Returns the ground colour as ARGB.
    int
    getHorizonColor()
    Returns the sky colour at the horizon, as ARGB.
    String
    getShaderKey()
    Returns the part of the shader variant key that depends on this environment: whether fog, hemisphere lighting, tone mapping and the open sky are on.
    int
    getSkyColor()
    Returns the sky colour as ARGB.
    int
    getSunColor()
    Returns the colour of the sun in the sky, as ARGB.
    int
    getVersion()
    Returns a number that changes whenever a setting does, so a backend can tell that a shader variant or a uniform it cached is stale.
    int
    getZenithColor()
    Returns the sky colour straight up, as ARGB.
    boolean
    isFog()
    Returns true if fog is on.
    boolean
    isHemisphere()
    Returns true if surfaces are lit by the sky and ground colours.
    boolean
    isSky()
    Returns true if skybox surfaces are painted as an open sky.
    boolean
    isToneMapping()
    Returns true if shaded colours are tone mapped.
    Environment
    setExposure(float exposure)
    Scales the light reaching the camera before it is tone mapped.
    Environment
    setFog(int color, float density, float heightFalloff)
    Turns fog on.
    Environment
    setFogBaseHeight(float y)
    Sets the height at which fog is at its full density; it thins above it.
    Environment
    setHemisphere(int sky, int ground)
    Lights surfaces with a sky colour from above and a ground colour from below, blended by the surface normal, in place of the light's flat ambient colour.
    Environment
    setSky(int zenith, int horizon, int sun, float clouds)
    Paints Material.Type.SKYBOX surfaces as an open sky: a gradient from the horizon to the zenith, the sun where the light comes from with a glow around it, and soft clouds.
    Environment
    setToneMapping(boolean toneMapping)
    Maps shaded colours through a filmic (ACES) curve, so bright light rolls off instead of clipping to white.

    Methods inherited from class Object

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

  • Constructor Details

    • Environment

      public Environment()

  • Method Details

    • setFog

      public Environment setFog(int color, float density, float heightFalloff)

      Turns fog on. A density of 0 turns it off.

      Parameters

      • color: the colour of the fog, as ARGB

      • density: how thick it is, per world unit; a surface 1 / density units away is about 63% fog

      • heightFalloff: how quickly it thins with height above setFogBaseHeight, per world unit; 0 is the same thickness everywhere

      Returns

      this environment for chaining

    • setFogBaseHeight

      public Environment setFogBaseHeight(float y)

      Sets the height at which fog is at its full density; it thins above it.

      Parameters
      • y: the world height
      Returns

      this environment for chaining

    • setHemisphere

      public Environment setHemisphere(int sky, int ground)

      Lights surfaces with a sky colour from above and a ground colour from below, blended by the surface normal, in place of the light's flat ambient colour. It is what gives an outdoor scene its shape in shadow.

      Parameters

      • sky: the colour that lights upward facing surfaces, as ARGB

      • ground: the colour that lights downward facing surfaces, as ARGB

      Returns

      this environment for chaining

    • clearHemisphere

      public Environment clearHemisphere()

      Goes back to the light's own flat ambient colour.

      Returns

      this environment for chaining

    • setToneMapping

      public Environment setToneMapping(boolean toneMapping)

      Maps shaded colours through a filmic (ACES) curve, so bright light rolls off instead of clipping to white. Lit and physically based materials are affected; unlit ones, sprites and the sky are not.

      Parameters
      • toneMapping: true to tone map
      Returns

      this environment for chaining

    • setExposure

      public Environment setExposure(float exposure)

      Scales the light reaching the camera before it is tone mapped.

      Parameters
      • exposure: the multiplier, 1 for none
      Returns

      this environment for chaining

    • setSky

      public Environment setSky(int zenith, int horizon, int sun, float clouds)

      Paints Material.Type.SKYBOX surfaces as an open sky: a gradient from the horizon to the zenith, the sun where the light comes from with a glow around it, and soft clouds. Draw it on a large sphere around the camera, seen from inside; it is computed per pixel from the view direction, so it needs no texture and has no seams.

      Parameters

      • zenith: the colour straight up, as ARGB

      • horizon: the colour at the horizon, as ARGB; match it to the fog colour so distant geometry melts into the sky

      • sun: the colour of the sun disc and its glow, as ARGB; black for none

      • clouds: how much of the sky is cloud, from 0 to 1

      Returns

      this environment for chaining

    • clearSky

      public Environment clearSky()

      Goes back to drawing Material.Type.SKYBOX surfaces in their own colour and texture.

      Returns

      this environment for chaining

    • isSky

      public boolean isSky()
      Returns true if skybox surfaces are painted as an open sky.

    • getZenithColor

      public int getZenithColor()
      Returns the sky colour straight up, as ARGB.

    • getHorizonColor

      public int getHorizonColor()
      Returns the sky colour at the horizon, as ARGB.

    • getSunColor

      public int getSunColor()
      Returns the colour of the sun in the sky, as ARGB.

    • getCloudCover

      public float getCloudCover()
      Returns how much of the sky is cloud, from 0 to 1.

    • getFogColor

      public int getFogColor()
      Returns the fog colour as ARGB.

    • getFogDensity

      public float getFogDensity()
      Returns the fog density per world unit, 0 when there is no fog.

    • getFogHeightFalloff

      public float getFogHeightFalloff()
      Returns how quickly fog thins with height, per world unit.

    • getFogBaseHeight

      public float getFogBaseHeight()
      Returns the height at which fog is at its full density.

    • isFog

      public boolean isFog()
      Returns true if fog is on.

    • isHemisphere

      public boolean isHemisphere()
      Returns true if surfaces are lit by the sky and ground colours.

    • getSkyColor

      public int getSkyColor()
      Returns the sky colour as ARGB.

    • getGroundColor

      public int getGroundColor()
      Returns the ground colour as ARGB.

    • isToneMapping

      public boolean isToneMapping()
      Returns true if shaded colours are tone mapped.

    • getExposure

      public float getExposure()
      Returns the exposure multiplier.

    • getVersion

      public int getVersion()
      Returns a number that changes whenever a setting does, so a backend can tell that a shader variant or a uniform it cached is stale.

    • getShaderKey

      public String getShaderKey()
      Returns the part of the shader variant key that depends on this environment: whether fog, hemisphere lighting, tone mapping and the open sky are on. Values such as the fog colour are uniforms and are not part of it.