Class LightingManager

java.lang.Object
com.github.yellowstonegames.grid.LightingManager
All Implemented Interfaces:
com.github.yellowstonegames.core.ISerializersNeeded
Direct Known Subclasses:
LightingManagerRgb
public class LightingManager extends Object implements com.github.yellowstonegames.core.ISerializersNeeded
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 LightingManager per level, where a level corresponds to a char[][]. After constructing a LightingManager with the resistances for a level, you should add all light sources with their positions, such as by using addLight(int, int, Radiance) to create a LightSource with a specific Radiance at a position, 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 light sources, 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(int[][]) to change a 2D int array that holds packed int colors (such as the backgrounds in a GlyphMap). To place user-interface lighting effects that don't affect the in-game-world lights, you can use updateUI(Coord, Radiance), which is called after update() but before draw(int[][]).
This class uses the same Oklab color space that DescriptiveColor uses for almost every place it deals with color. The exception here is draw(int[][]), which uses Oklab internally but converts the colors to RGBA8888 when it outputs them. You can use the alternative class LightingManagerRgb if you want to use RGBA colors throughout the lighting code.
Honestly, this class is quite complex, and you should really take a look at a demo that uses it to see how the different parts fit together. If you have the SquidSquad test sources, LightingTest in squidglyph provides a relatively simple example using many colors of light. VisionFramework also can be used to handle much of the boilerplate associated with vision and lighting.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    protected static interface 
    LightingManager.FovFunction
    A functional interface that is really only meant to be one of two functions: FOV.reuseFOV(float[][], float[][], int, int, float, Radius) or FOV.reuseFOVSymmetrical(float[][], float[][], int, int, float, Radius).
    static enum 
    LightingManager.SymmetryMode
    Used to choose whether FOV calculations should be done as quickly as possible (without symmetry guarantees) or more precisely (and more slowly, but with a symmetry guarantee).

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    int
    backgroundColor
    The packed Oklab int 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.
    int[][]
    colorLighting
    A 2D array that stores the color of light in each cell, as a packed Oklab int color.
    int[][]
    fovLightColors
    Represents the Oklab int colors associated with lights in lightFromFOV.
    float[][]
    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.
    float[][]
    lightFromFOV
    Used for calculations involving fovResult, generally with each colored light individually updating this 2D array and then having this array wiped clean.
    float[][]
    lightingStrength
    Used to determine the lighting power, but not colors, of all lights in the scene.
    com.github.tommyettinger.ds.ObjectDeque<LightSource>
    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.
    float[][]
    losResult
    A 2D array of floats that are either 0.0f if a cell has an obstruction between it and the viewer, or greater than 0.0f otherwise.
    Region
    noticeable
    A Region 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.
    float[][]
    resistances
    The 2D array of light-resistance values from 0.0f to 1.0f for each cell on the map, as produced by FOV.generateResistances(char[][]) or FOV.generateSimpleResistances(char[][]).
    LightingManager.SymmetryMode
    symmetry
     
    float
    viewerRange
    How far the viewer can see without light; defaults to 4.0f 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
    LightingManager()
    Unlikely to be used except during serialization; makes a LightingManager for a 20x20 fully visible level.
    LightingManager(float[][] resistance)
    Given a resistance array as produced by FOV.generateResistances(char[][]) or FOV.generateSimpleResistances(char[][]), makes a LightingManager that can have Radiance objects added to it in various locations.
    LightingManager(float[][] resistance, int backgroundColor, Radius radiusStrategy, float viewerVisionRange)
    Given a resistance array as produced by FOV.generateResistances(char[][]) or FOV.generateSimpleResistances(char[][]), makes a LightingManager that can have Radiance objects added to it in various locations.
    LightingManager(float[][] resistance, int backgroundColor, Radius radiusStrategy, float viewerVisionRange, LightingManager.SymmetryMode symmetry)
    Given a resistance array as produced by FOV.generateResistances(char[][]) or FOV.generateSimpleResistances(char[][]), makes a LightingManager that can have Radiance objects added to it in various locations.
    LightingManager(float[][] resistance, String backgroundColor, Radius radiusStrategy, float viewerVisionRange)
    Given a resistance array as produced by FOV.generateResistances(char[][]) or FOV.generateSimpleResistances(char[][]), makes a LightingManager that can have Radiance objects added to it in various locations.

  • Method Summary

    Modifier and Type
    Method
    Description
    LightingManager
    addLight(int x, int y, Radiance light)
    Adds a Radiance as a LightSource at the given position.
    LightingManager
    addLight(Coord position, Radiance light)
    Adds a Radiance as a LightSource at the given position.
    LightingManager
    addLight(Coord position, Radiance light, float spanTurns, float angleTurns)
    Adds a LightSource using the given Radiance at the given position.
    LightingManager
    addLight(LightSource light)
    Adds a LightSource to the collection this has for lights.
    float[][]
    calculateFOV(int viewerX, int viewerY)
    Used to calculate what cells are visible as if any flicker or strobe effects were simply constant light sources.
    float[][]
    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.
    float[][]
    calculateFOV(com.github.tommyettinger.ds.ObjectFloatMap<Coord> viewers, 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.
    float[][]
    calculateFOV(Coord viewer)
    Used to calculate what cells are visible as if any flicker or strobe effects were simply constant light sources.
    void
    draw(int[][] backgrounds)
    Given a 2D array that should hold RGBA int colors, fills the 2D array with different RGBA 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
    drawOklab(int[][] backgrounds)
    Given a 2D array that will hold Oklab int colors, fills the 2D array with different Oklab 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.
    boolean
    equals(Object o)
     
    protected static float[][]
    generateDefaultFloatArray()
     
    LightSource
    get(int index)
    Gets the nth LightSource at any position, where n is index.
    LightSource
    get(int x, int y)
    Gets the first LightSource at the given position, if present, or null if there is no LightSource there.
    LightSource
    get(int x, int y, int index)
    Gets the nth LightSource at the given position, where n is index, or null if there is no LightSource there.
    LightSource
    get(Coord position)
    Gets the first LightSource at the given position, if present, or null if there is no LightSource there.
    LightSource
    get(Coord position, int index)
    Gets the nth LightSource at the given position, where n is index, or null if there is no LightSource there.
    int
    getNeutralColor()
    An extension point for subclasses that don't use the Oklab color space; this defaults to returning DescriptiveColor.WHITE.
    List<Class<?>>
    getSerializersNeeded()
     
    LightingManager.SymmetryMode
    getSymmetry()
     
    int
    hashCode()
     
    int
    lightCount(Coord position)
    Returns how many LightSources are at the given position.
    com.github.tommyettinger.ds.ObjectList<LightSource>
    lightsAt(Coord position)
    Finds all LightSources this has with the given position and adds them to a newly-allocated ObjectList, which this returns.
    Collection<LightSource>
    lightsAt(Collection<LightSource> buffer, Coord position)
    Finds all LightSources this has with the given position and appends them to buffer.
    void
    mixColoredLighting(float flare)
    Edits colorLighting by adding in and mixing the colors in fovLightColors, with the strength of light in fovLightColors 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, int color)
    Edits colorLighting by adding in and mixing the given color where the light strength in lightFromFOV 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).
    boolean
    moveLight(int oldX, int oldY, int newX, int newY)
    If at least one LightSource is present at oldX,oldY, this will move the first LightSource to newX,newY.
    boolean
    moveLight(int oldX, int oldY, int newX, int newY, int index)
    If at least one LightSource is present at oldX,oldY, this will move the nth LightSource at oldX,oldY, where n is index, to newX,newY.
    boolean
    moveLight(Coord oldPosition, Coord newPosition)
    If at least one LightSource is present at oldPosition, this will move the first LightSource to newPosition.
    boolean
    moveLight(Coord oldPosition, Coord newPosition, int index)
    If at least one LightSource is present at oldPosition, this will move the nth LightSource at oldPosition, where n is index, to newPosition.
    boolean
    removeLight(int x, int y)
    Removes the first encountered LightSource with the given position, if any is present.
    boolean
    removeLight(int x, int y, int index)
    Removes the nth encountered LightSource with the given position, where n is index, if any is present.
    boolean
    removeLight(Coord position)
    Removes the first encountered LightSource with the given position, if any is present.
    boolean
    removeLight(Coord position, int index)
    Removes the nth encountered LightSource with the given position, where n is index, if any is present.
    void
    setSymmetry(LightingManager.SymmetryMode symmetry)
     
    String
    toString()
     
    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 LightingManager.
    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 LightingManager.
    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 Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait

  • Field Details

    • radiusStrategy

      public Radius radiusStrategy
      How light should spread; usually Radius.CIRCLE unless gameplay reasons need it to be SQUARE or DIAMOND.

    • resistances

      public float[][] resistances
      The 2D array of light-resistance values from 0.0f to 1.0f for each cell on the map, as produced by FOV.generateResistances(char[][]) or FOV.generateSimpleResistances(char[][]).

    • fovResult

      public float[][] 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. Edited by calculateFOV(Coord) and update(), but not updateUI(Coord, Radiance) (which is meant for effects that are purely user-interface).

    • losResult

      public float[][] losResult
      A 2D array of floats that are either 0.0f if a cell has an obstruction between it and the viewer, or greater than 0.0f otherwise.

    • lightFromFOV

      public float[][] lightFromFOV
      Used for calculations involving fovResult, generally with each colored light individually updating this 2D array and then having this array wiped clean. This serves as an intermediate storage step between the update methods and mixColoredLighting(float, int); the latter depends on this to be set by an update method or by calculateFOV(Coord).

    • lightingStrength

      public float[][] lightingStrength
      Used to determine the lighting power, but not colors, of all lights in the scene. This is set in the update methods and used in mixColoredLighting(float) and draw(int[][]).

    • colorLighting

      public int[][] colorLighting
      A 2D array that stores the color of light in each cell, as a packed Oklab int color. This 2D array is the size of the map, as defined by resistances initially and later available in width and height.

    • fovLightColors

      public int[][] fovLightColors
      Represents the Oklab int colors associated with lights in lightFromFOV. To make effective use of this field, you will probably need to be reading the source for LightingManager.

    • width

      public int width
      Width of the 2D arrays used in this, as obtained from resistances.

    • height

      public int height
      Height of the 2D arrays used in this, as obtained from resistances.

    • backgroundColor

      public int backgroundColor
      The packed Oklab int 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 defaults to the (RGBA or Oklab int) 0, which is always transparent.

    • viewerRange

      public float viewerRange
      How far the viewer can see without light; defaults to 4.0f cells, and you are encouraged to change this member field if the vision range changes after construction.

    • lights

      public com.github.tommyettinger.ds.ObjectDeque<LightSource> 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. You can edit this manually or by using moveLight(int, int, int, int), addLight(int, int, Radiance), and removeLight(int, int).

    • noticeable

      public Region noticeable
      A Region 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. Depends on the highest Radiance.range in lights.

    • symmetry

      public LightingManager.SymmetryMode symmetry

  • Constructor Details

    • LightingManager

      public LightingManager()
      Unlikely to be used except during serialization; makes a LightingManager for a 20x20 fully visible level. The viewer vision range will be 4.0f, and lights will use a circular shape.

    • LightingManager

      public LightingManager(float[][] resistance)
      Given a resistance array as produced by FOV.generateResistances(char[][]) or FOV.generateSimpleResistances(char[][]), makes a LightingManager that can have Radiance objects added to it in various locations. This will use a solid black background when it casts light on cells without existing lighting. The viewer vision range will be 4.0f, and lights will use a circular shape.
      Parameters:
      resistance - a resistance array as produced by DungeonUtility

    • LightingManager

      public LightingManager(float[][] resistance, String backgroundColor, Radius radiusStrategy, float viewerVisionRange)
      Given a resistance array as produced by FOV.generateResistances(char[][]) or FOV.generateSimpleResistances(char[][]), makes a LightingManager that can have Radiance objects added to it in various locations.
      Parameters:
      resistance - a resistance array as produced by DungeonUtility
      backgroundColor - the background color to use, as a color description
      radiusStrategy - the shape lights should take, typically Radius.CIRCLE for "realistic" lights or one of Radius.DIAMOND or Radius.SQUARE to match game rules for distance
      viewerVisionRange - how far the player can see without light, in cells

    • LightingManager

      public LightingManager(float[][] resistance, int backgroundColor, Radius radiusStrategy, float viewerVisionRange)
      Given a resistance array as produced by FOV.generateResistances(char[][]) or FOV.generateSimpleResistances(char[][]), makes a LightingManager that can have Radiance objects added to it in various locations.
      Parameters:
      resistance - a resistance array as produced by DungeonUtility
      backgroundColor - the background color to use, as a packed Oklab int
      radiusStrategy - the shape lights should take, typically Radius.CIRCLE for "realistic" lights or one of Radius.DIAMOND or Radius.SQUARE to match game rules for distance
      viewerVisionRange - how far the player can see without light, in cells

    • LightingManager

      public LightingManager(float[][] resistance, int backgroundColor, Radius radiusStrategy, float viewerVisionRange, LightingManager.SymmetryMode symmetry)
      Given a resistance array as produced by FOV.generateResistances(char[][]) or FOV.generateSimpleResistances(char[][]), makes a LightingManager that can have Radiance objects added to it in various locations.
      Parameters:
      resistance - a resistance array as produced by DungeonUtility
      backgroundColor - the background color to use, as a packed Oklab int
      radiusStrategy - the shape lights should take, typically Radius.CIRCLE for "realistic" lights or one of Radius.DIAMOND or Radius.SQUARE to match game rules for distance
      viewerVisionRange - how far the player can see without light, in cells

  • Method Details

    • generateDefaultFloatArray

      protected static float[][] generateDefaultFloatArray()

    • getSymmetry

      public LightingManager.SymmetryMode getSymmetry()

    • setSymmetry

      public void setSymmetry(LightingManager.SymmetryMode symmetry)

    • getNeutralColor

      public int getNeutralColor()
      An extension point for subclasses that don't use the Oklab color space; this defaults to returning DescriptiveColor.WHITE. There is no setter or field for the neutral color.
      Returns:
      if not overridden, DescriptiveColor.WHITE

    • lightCount

      public int lightCount(Coord position)
      Returns how many LightSources are at the given position.
      Parameters:
      position - the position to count at
      Returns:
      a non-negative int, at least 0 and less than lights.size

    • addLight

      public LightingManager addLight(int x, int y, Radiance light)
      Adds a Radiance as a LightSource at the given position. The LightSource will spread light in all directions.
      Parameters:
      x - the x-position to add the LightSource at
      y - the y-position to add the LightSource at
      light - a Radiance object that can have a changing radius, color, and various other effects on lighting
      Returns:
      this for chaining

    • addLight

      public LightingManager addLight(Coord position, Radiance light)
      Adds a Radiance as a LightSource at the given position. The LightSource will spread light in all directions.
      Parameters:
      position - the position to add the LightSource at
      light - a Radiance object that can have a changing radius, color, and various other effects on lighting
      Returns:
      this for chaining

    • addLight

      public LightingManager addLight(Coord position, Radiance light, float spanTurns, float angleTurns)
      Adds a LightSource using the given Radiance at the given position. This also restricts the lit span to spanTurns (between 0 and 1) and sets the initial direction of the light to angleTurns (also between 0 and 1).
      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
      spanTurns - how wide of an arc the LightSource will cover, measured in turns
      angleTurns - what direction the LightSource will point towards, measured in turns
      Returns:
      this for chaining

    • addLight

      public LightingManager addLight(LightSource light)
      Adds a LightSource to the collection this has for lights. This is largely irrelevant, since you can just call ObjectDeque.add(Object) on lights.
      Parameters:
      light - an existing LightSource, with a position and Radiance, to add
      Returns:
      this for chaining

    • removeLight

      public boolean removeLight(int x, int y)
      Removes the first encountered LightSource with the given position, if any is present.
      Parameters:
      x - the x-position to remove the LightSource from
      y - the y-position to remove the LightSource from
      Returns:
      true if any light was removed, false otherwise

    • removeLight

      public boolean removeLight(int x, int y, int index)
      Removes the nth encountered LightSource with the given position, where n is index, if any is present.
      Parameters:
      x - the x-position to remove the LightSource from
      y - the y-position to remove the LightSource from
      index - which of the possible lights at x,y to remove
      Returns:
      true if any light was removed, false otherwise

    • removeLight

      public boolean removeLight(Coord position)
      Removes the first encountered LightSource with the given position, if any is present.
      Parameters:
      position - the position to remove the LightSource from
      Returns:
      true if any light was removed, false otherwise

    • removeLight

      public boolean removeLight(Coord position, int index)
      Removes the nth encountered LightSource with the given position, where n is index, if any is present.
      Parameters:
      position - the position to remove the LightSource from
      index - which of the possible lights at position to remove
      Returns:
      true if any light was removed, false otherwise

    • moveLight

      public boolean moveLight(int oldX, int oldY, int newX, int newY)
      If at least one LightSource is present at oldX,oldY, this will move the first LightSource to newX,newY. If no LightSource is present at oldX,oldY, this does nothing. This will not remove any LightSource already present at newX,newY.
      Parameters:
      oldX - the x-position to move a LightSource from
      oldY - the y-position to move a LightSource from
      newX - the x-position to move a LightSource to
      newY - the y-position to move a LightSource to
      Returns:
      true if any light was moved, or false otherwise

    • moveLight

      public boolean moveLight(int oldX, int oldY, int newX, int newY, int index)
      If at least one LightSource is present at oldX,oldY, this will move the nth LightSource at oldX,oldY, where n is index, to newX,newY. If no LightSource is present at oldX,oldY, this does nothing. This also does nothing if index is greater than or equal to the number of lights at oldX,oldY. This will not remove any LightSource already present at newX,newY.
      Parameters:
      oldX - the x-position to move a LightSource from
      oldY - the y-position to move a LightSource from
      newX - the x-position to move a LightSource to
      newY - the y-position to move a LightSource to
      index - which of the possible lights at oldPosition to move
      Returns:
      true if any light was moved, or false otherwise

    • moveLight

      public boolean moveLight(Coord oldPosition, Coord newPosition)
      If at least one LightSource is present at oldPosition, this will move the first LightSource to newPosition. If no LightSource is present at oldPosition, this does nothing. This will not remove any LightSource already present at newPosition.
      Parameters:
      oldPosition - the Coord to move a LightSource from
      newPosition - the Coord to move a LightSource to
      Returns:
      true if any light was moved, or false otherwise

    • moveLight

      public boolean moveLight(Coord oldPosition, Coord newPosition, int index)
      If at least one LightSource is present at oldPosition, this will move the nth LightSource at oldPosition, where n is index, to newPosition. If no LightSource is present at oldPosition, this does nothing. This also does nothing if index is greater than or equal to the number of lights at oldPosition. This will not remove any LightSource already present at newPosition.
      Parameters:
      oldPosition - the Coord to move a LightSource from
      newPosition - the Coord to move a LightSource to
      index - which of the possible lights at oldPosition to move
      Returns:
      true if any light was moved, or false otherwise

    • get

      public LightSource get(int index)
      Gets the nth LightSource at any position, where n is index. This is largely unnecessary because you can call ObjectDeque.get(int) on lights. The only difference here is that this method returns null if index is out-of-bounds, while ObjectQueue.get(int) throws an Exception then.
      Parameters:
      index - which LightSource index to get
      Returns:
      the LightSource with the given index across all positions, or null if index if out of bounds.

    • get

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

    • get

      public LightSource get(int x, int y, int index)
      Gets the nth LightSource at the given position, where n is index, or null if there is no LightSource there.
      Parameters:
      x - the x-position to look up
      y - the y-position to look up
      index - which LightSource to get from the given position
      Returns:
      the nth LightSource at the given position, or null if none is present there

    • get

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

    • get

      public LightSource get(Coord position, int index)
      Gets the nth LightSource at the given position, where n is index, or null if there is no LightSource there.
      Parameters:
      position - the position to look up
      index - which LightSource to get from the given position
      Returns:
      the nth LightSource at the given position, or null if none is present there

    • lightsAt

      public com.github.tommyettinger.ds.ObjectList<LightSource> lightsAt(Coord position)
      Finds all LightSources this has with the given position and adds them to a newly-allocated ObjectList, which this returns.
      Parameters:
      position - the position to look up LightSources at
      Returns:
      a newly-allocated ObjectList that may have LightSource items which were found at position

    • lightsAt

      public Collection<LightSource> lightsAt(Collection<LightSource> buffer, Coord position)
      Finds all LightSources this has with the given position and appends them to buffer.
      Parameters:
      buffer - any modifiable Collection of LightSource items; may be modified
      position - the position to look up LightSources at
      Returns:
      buffer, potentially after modification

    • mixColoredLighting

      public void mixColoredLighting(float flare)
      Edits colorLighting by adding in and mixing the colors in fovLightColors, with the strength of light in fovLightColors boosted by flare (which can be any finite float greater than -1f, but is usually from 0f to 1f when increasing strength). The strengths of each colored light is determined by lightFromFOV and the colors of lights are determined by fovLightColors. If a color of light is fully transparent, this skips that light.
      This is very limited-use; the related method mixColoredLighting(float, int) is used as part of update(), but this method is meant for when multiple colors of FOV light need to be mixed at once.
      Parameters:
      flare - boosts the effective strength of lighting in fovLightColors; usually from 0 to 1

    • mixColoredLighting

      public void mixColoredLighting(float flare, int color)
      Edits colorLighting by adding in and mixing the given color where the light strength in lightFromFOV 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). This draws its existing lighting strength from lightingStrength and its existing light colors from colorLighting; it modifies both of these.
      This has limited use outside this class, unless you are reimplementing part of update() or something like it.
      Parameters:
      flare - boosts the effective strength of lighting in lightFromFOV; usually from 0 to 1
      color - the Oklab color to mix in where the light strength in lightFromFOV is greater than 0

    • 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 LightingManager. 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(int[][]), 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 LightingManager. This method is usually called before each call to draw(int[][]), 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(int[][]), 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(int[][]), 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(int[][] backgrounds)
      Given a 2D array that should hold RGBA int colors, fills the 2D array with different RGBA 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). A common use for this in text-based games uses a GlyphMap's backgrounds field as the parameter. This always mixes the calculated lights in colorLighting with the backgroundColor, using lightingStrength to determine how much the lights should affect the background color.
      If this class is extended, this method should be considered as one to override.
      Parameters:
      backgrounds - a 2D int array, which will be modified in-place; visible cells will receive RGBA8888 colors

    • drawOklab

      public void drawOklab(int[][] backgrounds)
      Given a 2D array that will hold Oklab int colors, fills the 2D array with different Oklab 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 drawOklab(), 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). A common use for this in text-based games uses a GlyphMap's backgrounds field as the parameter. This always mixes the calculated lights in colorLighting with the backgroundColor, using lightingStrength to determine how much the lights should affect the background color.
      If this class is extended, this method should be considered as one to override.
      Parameters:
      backgrounds - a 2D int array, which will be modified in-place; visible cells will receive Oklab colors

    • calculateFOV

      public float[][] 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 float[][] 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 float[][] 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

    • calculateFOV

      public float[][] calculateFOV(com.github.tommyettinger.ds.ObjectFloatMap<Coord> viewers, 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:
      viewers - an ObjectFloatMap with Coord keys representing viewer positions and float values for their vision ranges; often a CoordFloatOrderedMap
      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

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • getSerializersNeeded

      public List<Class<?>> getSerializersNeeded()
      Specified by:
      getSerializersNeeded in interface com.github.yellowstonegames.core.ISerializersNeeded