Package squidpony.squidgrid.gui.gdx

Class LightingHandler

java.lang.Object
squidpony.squidgrid.gui.gdx.LightingHandler
All Implemented Interfaces:
Serializable
public class LightingHandler
extends Object
implements Serializable
A convenience class that makes dealing with multiple colored light sources easier. All fields are public and documented to encourage their use alongside the API methods. The typical usage case for this class is when a game has complex lighting needs that should be consolidated into one LightingHandler per level, where a level corresponds to a char[][]. After constructing a LightingHandler with the resistances for a level, you should add all light sources with their positions, either using addLight(int, int, Radiance) or by directly putting keys and values into lights. Then you can calculate the visible cells once lighting is considered (which may include distant lit cells with unseen but unobstructing cells between the viewer and the light) using calculateFOV(Coord), which should be called every time the viewer moves. You can update the flicker and strobe effects on all Radiance objects, which is typically done every frame, using update() or updateAll() (updateAll() is for when there is no viewer), and once that update() call has been made you can call draw(SparseLayers) to change the background colors of a SparseLayers, draw(SquidPanel) to change the colors of a SquidPanel (typically the background layer of a SquidLayers, as from SquidLayers.getBackgroundLayer()), or draw(float[][]) to change a 2D float array that holds packed float colors (which may be used in some custom setup). To place user-interface lighting effects that don't affect the actual FOV of creatures in the game, you can use updateUI(Coord, Radiance), which is called after update() but before draw(float[][]).
Created by Tommy Ettinger on 11/2/2018.
See Also:
Serialized Form

  • Field Summary

    Fields 
    Modifier and Type Field Description
    float backgroundColor
    The packed float color to mix background cells with when a cell has lighting and is within line-of-sight, but has no background color to start with (its color is 0f as a packed float, or SColor.TRANSPARENT).
    float[][][] colorLighting
    A pair of 2D float arrays with different usages; colorLighting[0] is a 2D array that stores the strength of light in each cell, and colorLighting[1] is a 2D array that stores the color of light in each cell, as a packed float color.
    double[][] fovResult
    What the "viewer" (as passed to calculateFOV(Coord)) can see either nearby without light or because an area in line-of-sight has light in it.
    int height
    Height of the 2D arrays used in this, as obtained from resistances.
    OrderedMap<Coord,​Radiance> lights
    A mapping from positions as Coord objects to Radiance objects that describe the color, lighting radius, and changes over time of any in-game lights that should be shown on the map and change FOV.
    double[][] losResult
    A 2D array of doubles that are either 0.0 if a cell has an obstruction between it and the viewer, or greater than 0.0 otherwise.
    GreasedRegion noticeable
    A GreasedRegion that stores any cells that are in line-of-sight or are close enough to a cell in line-of-sight to potentially cast light into such a cell.
    Radius radiusStrategy
    How light should spread; usually Radius.CIRCLE unless gameplay reasons need it to be SQUARE or DIAMOND.
    double[][] resistances
    The 2D array of light-resistance values from 0.0 to 1.0 for each cell on the map, as produced by DungeonUtility.generateResistances(char[][]).
    float[][][] tempColorLighting
    Temporary storage array used for calculations involving colorLighting; it sometimes may make sense for other code to use this as temporary storage as well.
    double[][] tempFOV
    Temporary storage array used for calculations involving fovResult; it sometimes may make sense for other code to use this as temporary storage as well.
    double viewerRange
    How far the viewer can see without light; defaults to 4.0 cells, and you are encouraged to change this member field if the vision range changes after construction.
    int width
    Width of the 2D arrays used in this, as obtained from resistances.

  • Constructor Summary

    Constructors 
    Constructor Description
    LightingHandler()
    Unlikely to be used except during serialization; makes a LightingHandler for a 20x20 fully visible level.
    LightingHandler​(double[][] resistance)
    Given a resistance array as produced by DungeonUtility.generateResistances(char[][]) or DungeonUtility.generateSimpleResistances(char[][]), makes a LightingHandler that can have Radiance objects added to it in various locations.
    LightingHandler​(double[][] resistance, float backgroundColor, Radius radiusStrategy, double viewerVisionRange)
    Given a resistance array as produced by DungeonUtility.generateResistances(char[][]) or DungeonUtility.generateSimpleResistances(char[][]), makes a LightingHandler that can have Radiance objects added to it in various locations.
    LightingHandler​(double[][] resistance, com.badlogic.gdx.graphics.Color backgroundColor, Radius radiusStrategy, double viewerVisionRange)
    Given a resistance array as produced by DungeonUtility.generateResistances(char[][]) or DungeonUtility.generateSimpleResistances(char[][]), makes a LightingHandler that can have Radiance objects added to it in various locations.

  • Method Summary

    Modifier and Type Method Description
    LightingHandler addLight​(int x, int y, Radiance light)
    Adds a Radiance as a light source at the given position.
    LightingHandler addLight​(Coord position, Radiance light)
    Adds a Radiance as a light source at the given position.
    double[][] calculateFOV​(int viewerX, int viewerY)
    Used to calculate what cells are visible as if any flicker or strobe effects were simply constant light sources.
    double[][] calculateFOV​(int viewerX, int viewerY, int minX, int minY, int maxX, int maxY)
    Used to calculate what cells are visible as if any flicker or strobe effects were simply constant light sources.
    double[][] calculateFOV​(Coord viewer)
    Used to calculate what cells are visible as if any flicker or strobe effects were simply constant light sources.
    void draw​(float[][] backgrounds)
    Given a 2D array of packed float colors, fills the 2D array with different colors based on what lights are present in line of sight of the viewer and the various flicker or strobe effects that Radiance light sources can do.
    void draw​(SparseLayers layers)
    Given a SparseLayers, fills the SparseLayers with different colors based on what lights are present in line of sight of the viewer and the various flicker or strobe effects that Radiance light sources can do.
    void draw​(SquidPanel background)
    Given a SquidPanel that should be only solid blocks (such as the background of a SquidLayers) and a position for the viewer (typically the player), fills the SquidPanel with different colors based on what lights are present in line of sight of the viewer and the various flickering or pulsing effects that Radiance light sources can do.
    Radiance get​(int x, int y)
    Gets the Radiance at the given position, if present, or null if there is no light source there.
    Radiance get​(Coord position)
    Gets the Radiance at the given position, if present, or null if there is no light source there.
    void mixColoredLighting​(float flare)
    Edits colorLighting by adding in and mixing the colors in tempColorLighting, with the strength of light in tempColorLighting boosted by flare (which can be any finite float greater than -1f, but is usually from 0f to 1f when increasing strength).
    void mixColoredLighting​(float flare, float color)
    Edits colorLighting by adding in and mixing the given color where the light strength in tempFOV is greater than 0, with that strength boosted by flare (which can be any finite float greater than -1f, but is usually from 0f to 1f when increasing strength).
    LightingHandler moveLight​(int oldX, int oldY, int newX, int newY)
    If a Radiance is present at oldX,oldY, this will move it to newX,newY and overwrite any existing Radiance at newX,newY.
    LightingHandler moveLight​(Coord oldPosition, Coord newPosition)
    If a Radiance is present at oldPosition, this will move it to newPosition and overwrite any existing Radiance at newPosition.
    LightingHandler removeLight​(int x, int y)
    Removes a Radiance as a light source from the given position, if any is present.
    LightingHandler removeLight​(Coord position)
    Removes a Radiance as a light source from the given position, if any is present.
    void update()
    Typically called every frame, this updates the flicker and strobe effects of Radiance objects and applies those changes in lighting color and strength to the various fields of this LightingHandler.
    void updateAll()
    Typically called every frame when there isn't a single viewer, this updates the flicker and strobe effects of Radiance objects and applies those changes in lighting color and strength to the various fields of this LightingHandler.
    void updateUI​(int lightX, int lightY, Radiance radiance)
    Updates the flicker and strobe effects of a Radiance object and applies the lighting from just that Radiance to just the colorLighting field, without changing FOV.
    void updateUI​(Coord pos, Radiance radiance)
    Updates the flicker and strobe effects of a Radiance object and applies the lighting from just that Radiance to just the colorLighting field, without changing FOV.

    Methods inherited from class java.lang.Object

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

  • Field Details

  • Constructor Details

  • Method Details

    • addLight

      public LightingHandler addLight​(int x, int y, Radiance light)
      Adds a Radiance as a light source at the given position. Overwrites any existing Radiance at the same position.
      Parameters:
      x - the x-position to add the Radiance at
      y - the y-position to add the Radiance at
      light - a Radiance object that can have a changing radius, color, and various other effects on lighting
      Returns:
      this for chaining

    • addLight

      public LightingHandler addLight​(Coord position, Radiance light)
      Adds a Radiance as a light source at the given position. Overwrites any existing Radiance at the same position.
      Parameters:
      position - the position to add the Radiance at
      light - a Radiance object that can have a changing radius, color, and various other effects on lighting
      Returns:
      this for chaining

    • removeLight

      public LightingHandler removeLight​(int x, int y)
      Removes a Radiance as a light source from the given position, if any is present.
      Parameters:
      x - the x-position to remove the Radiance from
      y - the y-position to remove the Radiance from
      Returns:
      this for chaining

    • removeLight

      public LightingHandler removeLight​(Coord position)
      Removes a Radiance as a light source from the given position, if any is present.
      Parameters:
      position - the position to remove the Radiance from
      Returns:
      this for chaining

    • moveLight

      public LightingHandler moveLight​(int oldX, int oldY, int newX, int newY)
      If a Radiance is present at oldX,oldY, this will move it to newX,newY and overwrite any existing Radiance at newX,newY. If no Radiance is present at oldX,oldY, this does nothing.
      Parameters:
      oldX - the x-position to move a Radiance from
      oldY - the y-position to move a Radiance from
      newX - the x-position to move a Radiance to
      newY - the y-position to move a Radiance to
      Returns:
      this for chaining

    • moveLight

      public LightingHandler moveLight​(Coord oldPosition, Coord newPosition)
      If a Radiance is present at oldPosition, this will move it to newPosition and overwrite any existing Radiance at newPosition. If no Radiance is present at oldPosition, this does nothing.
      Parameters:
      oldPosition - the Coord to move a Radiance from
      newPosition - the Coord to move a Radiance to
      Returns:
      this for chaining

    • get

      public Radiance get​(int x, int y)
      Gets the Radiance at the given position, if present, or null if there is no light source there.
      Parameters:
      x - the x-position to look up
      y - the y-position to look up
      Returns:
      the Radiance at the given position, or null if none is present there

    • get

      public Radiance get​(Coord position)
      Gets the Radiance at the given position, if present, or null if there is no light source there.
      Parameters:
      position - the position to look up
      Returns:
      the Radiance at the given position, or null if none is present there

    • mixColoredLighting

      public void mixColoredLighting​(float flare)
      Edits colorLighting by adding in and mixing the colors in tempColorLighting, with the strength of light in tempColorLighting boosted by flare (which can be any finite float greater than -1f, but is usually from 0f to 1f when increasing strength). Primarily used internally, but exposed so outside code can do the same things this class can.
      Parameters:
      flare - boosts the effective strength of lighting in tempColorLighting; usually from 0 to 1

    • mixColoredLighting

      public void mixColoredLighting​(float flare, float color)
      Edits colorLighting by adding in and mixing the given color where the light strength in tempFOV is greater than 0, with that strength boosted by flare (which can be any finite float greater than -1f, but is usually from 0f to 1f when increasing strength). Primarily used internally, but exposed so outside code can do the same things this class can.
      Parameters:
      flare - boosts the effective strength of lighting in tempColorLighting; usually from 0 to 1

    • update

      public void update()
      Typically called every frame, this updates the flicker and strobe effects of Radiance objects and applies those changes in lighting color and strength to the various fields of this LightingHandler. This will only have an effect if calculateFOV(Coord) or calculateFOV(int, int) was called during the last time the viewer position changed; typically calculateFOV() only needs to be called once per move, while update() needs to be called once per frame. This method is usually called before each call to draw(float[][]), but other code may be between the calls and may affect the lighting in customized ways.

    • updateAll

      public void updateAll()
      Typically called every frame when there isn't a single viewer, this updates the flicker and strobe effects of Radiance objects and applies those changes in lighting color and strength to the various fields of this LightingHandler. This method is usually called before each call to draw(float[][]), but other code may be between the calls and may affect the lighting in customized ways. This overload has no viewer, so all cells are considered visible unless they are fully obstructed (solid cells behind walls, for example). Unlike update(), this method does not need calculateFOV(Coord) to be called for it to work properly.

    • updateUI

      public void updateUI​(Coord pos, Radiance radiance)
      Updates the flicker and strobe effects of a Radiance object and applies the lighting from just that Radiance to just the colorLighting field, without changing FOV. This method is meant to be used for GUI effects that aren't representative of something a character in the game could interact with. It is usually called after update() and before each call to draw(float[][]), but other code may be between the calls and may affect the lighting in customized ways.
      Parameters:
      pos - the position of the light effect
      radiance - the Radiance to update standalone, which does not need to be already added to this

    • updateUI

      public void updateUI​(int lightX, int lightY, Radiance radiance)
      Updates the flicker and strobe effects of a Radiance object and applies the lighting from just that Radiance to just the colorLighting field, without changing FOV. This method is meant to be used for GUI effects that aren't representative of something a character in the game could interact with. It is usually called after update() and before each call to draw(float[][]), but other code may be between the calls and may affect the lighting in customized ways.
      Parameters:
      lightX - the x-position of the light effect
      lightY - the y-position of the light effect
      radiance - the Radiance to update standalone, which does not need to be already added to this

    • draw

      public void draw​(SparseLayers layers)
      Given a SparseLayers, fills the SparseLayers with different colors based on what lights are present in line of sight of the viewer and the various flicker or strobe effects that Radiance light sources can do. You should usually call update() before each call to draw(), but you may want to make custom changes to the lighting in between those two calls (that is the only place those changes will be noticed).
      Parameters:
      layers - a SparseLayers that may have existing background colors (these will be mixed in)

    • draw

      public void draw​(SquidPanel background)
      Given a SquidPanel that should be only solid blocks (such as the background of a SquidLayers) and a position for the viewer (typically the player), fills the SquidPanel with different colors based on what lights are present in line of sight of the viewer and the various flickering or pulsing effects that Radiance light sources can do. Given a SquidPanel that should be only solid blocks (such as the background of a SquidLayers), fills the SquidPanel with different colors based on what lights are present in line of sight of the viewer and the various flicker or strobe effects that Radiance light sources can do. You should usually call update() before each call to draw(), but you may want to make custom changes to the lighting in between those two calls (that is the only place those changes will be noticed).
      Parameters:
      background - a SquidPanel used as a background, such as the back Panel of a SquidLayers

    • draw

      public void draw​(float[][] backgrounds)
      Given a 2D array of packed float colors, fills the 2D array with different colors based on what lights are present in line of sight of the viewer and the various flicker or strobe effects that Radiance light sources can do. You should usually call update() before each call to draw(), but you may want to make custom changes to the lighting in between those two calls (that is the only place those changes will be noticed).
      Parameters:
      backgrounds - a 2D float array, typically obtained from SquidPanel.colors or SparseLayers.backgrounds

    • calculateFOV

      public double[][] calculateFOV​(Coord viewer)
      Used to calculate what cells are visible as if any flicker or strobe effects were simply constant light sources. Runs part of the calculations to draw lighting as if all radii are at their widest, but does no actual drawing. This should be called any time the viewer moves to a different cell, and it is critical that this is called (at least) once after a move but before update() gets called to change lighting at the new cell. This sets important information on what lights might need to be calculated during each update(Coord) call; it does not need to be called before updateAll() (with no arguments) because that doesn't need a viewer. Sets fovResult, losResult, and noticeable based on the given viewer position and any lights in lights.
      Parameters:
      viewer - the position of the player or other viewer
      Returns:
      the calculated FOV 2D array, which is also stored in fovResult

    • calculateFOV

      public double[][] calculateFOV​(int viewerX, int viewerY)
      Used to calculate what cells are visible as if any flicker or strobe effects were simply constant light sources. Runs part of the calculations to draw lighting as if all radii are at their widest, but does no actual drawing. This should be called any time the viewer moves to a different cell, and it is critical that this is called (at least) once after a move but before update() gets called to change lighting at the new cell. This sets important information on what lights might need to be calculated during each update(Coord) call; it does not need to be called before updateAll() (with no arguments) because that doesn't need a viewer. Sets fovResult, losResult, and noticeable based on the given viewer position and any lights in lights.
      Parameters:
      viewerX - the x-position of the player or other viewer
      viewerY - the y-position of the player or other viewer
      Returns:
      the calculated FOV 2D array, which is also stored in fovResult

    • calculateFOV

      public double[][] calculateFOV​(int viewerX, int viewerY, int minX, int minY, int maxX, int maxY)
      Used to calculate what cells are visible as if any flicker or strobe effects were simply constant light sources. Runs part of the calculations to draw lighting as if all radii are at their widest, but does no actual drawing. This should be called any time the viewer moves to a different cell, and it is critical that this is called (at least) once after a move but before update() gets called to change lighting at the new cell. This sets important information on what lights might need to be calculated during each update(Coord) call; it does not need to be called before updateAll() (with no arguments) because that doesn't need a viewer. This overload allows the area this processes to be restricted to a rectangle between minX and maxX and between minY and maxY, ignoring any lights outside that area (typically because they are a long way out from the map's shown area). Sets fovResult, losResult, and noticeable based on the given viewer position and any lights in lights.
      Parameters:
      viewerX - the x-position of the player or other viewer
      viewerY - the y-position of the player or other viewer
      minX - inclusive lower bound on x to calculate
      minY - inclusive lower bound on y to calculate
      maxX - exclusive upper bound on x to calculate
      maxY - exclusive upper bound on y to calculate
      Returns:
      the calculated FOV 2D array, which is also stored in fovResult