wyvern.lib.properties
Class SimpleLightSource

java.lang.Object
  wyvern.lib.properties.SimpleLightSource

All Implemented Interfaces:

LightingConstants, LightSource

Direct Known Subclasses:

MovableLightSource

public class SimpleLightSource

extends java.lang.Object

implements LightSource, LightingConstants

This class provides a simple light that you can place in a map. It's not as sophisticated as the MovableLightSource, which keeps track of its owner/carrier as it moves around.

If you want to implement a custom light source, you'd be wise to subclass SimpleLightSource or MovableLightSource to leverage its existing behavior.

Version:

1.0, Jun 24, 2003

Author:

Steve Yegge

Field Summary

protected wyvern.kernel.lighting.RayShadowCaster	caster_
static int	DEFAULT_LIGHT_SOURCE_INTENSITY The default intensity to use for light sources.
protected int	intensity_
protected int[][]	localIntensity_
protected Point	location_
protected GameMap	map_
protected int[][]	matrix_

Fields inherited from interface wyvern.lib.properties.LightingConstants

DARKNESS, DAYLIGHT, DIM, DUSK, GLOOM, NUM_SHADES, SHADED, TWILIGHT

Constructor Summary

SimpleLightSource()
Constructs a new SimpleLightSource with the default intensity.

SimpleLightSource(int intensity)
Constructs a new SimpleLightSource

Method Summary

void	computeLocalIntensity() This method fills the local light array.
void	computeMatrix() Recomputes the intensity matrix by invoking the raycaster.
static int	getAlphaForLightLevel(int level) Returns the percent opacity for a shading tile, given the lighting level.
static int	getDistance(int x, int y) Returns the integer distance from (0, 0) to the passed point.
int	getIntensity() Returns the current intensity of this light source.
int[][]	getLightMatrix() Returns the location list for the light source.
Point	getLocation() Returns the location at the center of our lighting array.
GameMap	getMap() Returns the map we're currently illuminating, if any.
Point	getMatrixLocation() Returns the (x,y) location of the upper-left corner of the LightSource's local light matrix returned by calling getLightMatrix().
static int	getShadingTile(int intensity) Returns the database tile number of the tile to use for the passed lighting level.
static void	main(java.lang.String[] args) Used for testing only.
void	recompute() Tells the light source to recompute its intensity matrix.
void	remove() Removes this light from its current map, if any.
void	setIntensity(int intensity) Sets the intensity of the light source.
void	setLocation(Point loc) Sets the location at the center of the area we should be illuminating.
void	setMap(GameMap map) Tells us which map we're illuminating.
void	setMap(GameMap map, int x, int y) Tells the light which map to illuminate.
java.lang.String	toString() Returns a String representation of the object for debugging.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_LIGHT_SOURCE_INTENSITY

public static final int DEFAULT_LIGHT_SOURCE_INTENSITY

The default intensity to use for light sources.

See Also:

Constant Field Values

localIntensity_

protected int[][] localIntensity_

matrix_

protected int[][] matrix_

intensity_

protected int intensity_

map_

protected GameMap map_

location_

protected Point location_

caster_

protected wyvern.kernel.lighting.RayShadowCaster caster_

Constructor Detail

SimpleLightSource

public SimpleLightSource(int intensity)

Constructs a new SimpleLightSource

SimpleLightSource

public SimpleLightSource()

Constructs a new SimpleLightSource with the default intensity.

Method Detail

getAlphaForLightLevel

public static int getAlphaForLightLevel(int level)

Returns the percent opacity for a shading tile, given the lighting level.

Parameters:

level - the lighting level at some point in the map

Returns:

the alpha value to apply to the solid-black shade tile, to achieve the appropriate shadowing. A return value of 0 means you shouldn't draw any shading tile there.

getShadingTile

public static int getShadingTile(int intensity)

Returns the database tile number of the tile to use for the passed lighting level. This is pretty much the place where we map intensities to actual dither patterns, which has a huge effect on what the lighting model looks like.

This method really ought to be in a LightManager class or something; right now it's living here because this is the only class that has any light-related code in it.

Parameters:

intensity - the total lighting level in the map at the desired location

Returns:

the database tile number of the dither pattern to use for that light level. -1 means DON'T USE A TILE (i.e. the square is completely lit, daylight).

getDistance

public static int getDistance(int x,
                              int y)

Returns the integer distance from (0, 0) to the passed point. Just does the distance formula. Faster to inline it in your code if it's performance-intensive.

Parameters:

x - local x coordinate

y - local y coordinate

getLightMatrix

public int[][] getLightMatrix()

Returns the location list for the light source. The light is typically centered in the array, although that's not required, nor are there any constraints on the array dimensions (e.g. it can be even by odd). The map will take the array and "apply" it into the global array at the (x,y) location returned by getMatrixLocation().

Specified by:

getLightMatrix in interface LightSource

Returns:

the local array of integer intensities computed by the LightSource. Each array value is added to (or subtracted from, in the case where the LightSource is removed) the map. An array value of zero thus has no effect, and LightSource implementations can make use of this to return custom-shaped illumination patterns.

getMatrixLocation

public Point getMatrixLocation()

Returns the (x,y) location of the upper-left corner of the LightSource's local light matrix returned by calling getLightMatrix().

Specified by:

getMatrixLocation in interface LightSource

Returns:

the point in the map at which to apply the local array. The LightSource has to know where it is in the map anyway, so that it can call addLight() at the appropriate location, not to mention compute its intensity array correctly using the ray-caster utilities. Since the LightSource is in complete control of where its light is displayed, it has to tell the map where to apply its local intensity array; hence this method.

recompute

public void recompute()

Tells the light source to recompute its intensity matrix.

This method is called by the map when a square becomes opaque or non-opaque within the radius illuminated by the light. The light removes itself from the map, computes its new lighting matrix, and re-adds itself at the same location.

Specified by:

recompute in interface LightSource

getMap

public GameMap getMap()

Returns the map we're currently illuminating, if any.

Returns:

the map we're in

setMap

public void setMap(GameMap map)

Tells us which map we're illuminating. Doesn't actually do anything except store the map reference. You need to manually remove and add the light to have it change the lighting level in the map.

Parameters:

map - the map to put the light in

setMap

public void setMap(GameMap map,
                   int x,
                   int y)

Tells the light which map to illuminate. This method causes the light to call recompute(), which figures out its lighting contribution and adds that contribution to the passed map.

Specified by:

setMap in interface LightSource

Parameters:

map - the map to put the light in

x - map x location

y - map y location

remove

public void remove()

Removes this light from its current map, if any.

Specified by:

remove in interface LightSource

getIntensity

public int getIntensity()

Returns the current intensity of this light source.

setIntensity

public void setIntensity(int intensity)

Sets the intensity of the light source.

Parameters:

intensity - the radius of the light source.

getLocation

public Point getLocation()

Returns the location at the center of our lighting array.

Returns:

the (x, y) location we're centered on, in map coordinates

setLocation

public void setLocation(Point loc)

Sets the location at the center of the area we should be illuminating. Doesn't do anything except store the passed location. You need to call map.addLight() and map.removeLight() manually, if the light is changing.

Parameters:

loc - the new map (x, y) location

computeLocalIntensity

public void computeLocalIntensity()

This method fills the local light array. As an example, a light source with intensity 4 would have a 7x7 local intensity array that looks like this:

 	0 0 1 1 1 0 0
 	0 1 2 2 2 1 0
 	1 2 3 3 3 2 1
 	1 2 3 4 3 2 1
 	1 2 3 3 3 2 1
 	0 1 2 2 2 1 0
 	0 0 1 1 1 0 0
 

The light source is at the center, and intensity drops off as a linear function of distance. (N^2 is too harsh.) We use the computed intensity values to index into a table to select a dither pattern to draw. Any intensity above "daylight" gets no dither pattern; any intensity below some threshold (probably zero) gets complete darkness.

computeMatrix

public void computeMatrix()

Recomputes the intensity matrix by invoking the raycaster. First copies the local intensity matrix (which is fixed for a given intensity) to the lighting matrix. Then calls the raycaster to mask out any squares in the lighting matrix that aren't reachable from the source's current location in the current map.

This method is called whenever the light is added to a map or moves within a map. It should also be called whenever any of the map's opaque squares change transparency status within reach of the light source.

main

public static void main(java.lang.String[] args)

Used for testing only. Prints out light array.

toString

public java.lang.String toString()

Returns a String representation of the object for debugging.