Lights reference

Back to Lambent

Every type here is in com.raiiiden.lambent.api. All positions are camera-relative, and all colors are linear RGB that already include the light’s brightness (see the conventions).

Lights: the limits

Constant	Value	Meaning
`MAX_LAMPS`	4	Spot lights per frame. A pair counts as one. Each gets one tile of the shadow atlas.
`MAX_GLOWS`	48	Glows per frame.
`MAX_LENSES`	16	Lens blooms per frame.
`MAX_POINTS`	6	Point lights per frame.
`NEAR`	0.1	The shadow maps’ near plane (m).
`MOST_TURN`	8°	How far one lamp of a pair may point off the pair’s line.
`BACK`	2	How far behind a pair (m) its shadow map may look from, so both beams fit in its view.

Beam

A kind of beam: Beam(range, edge, dip, intensity) for a plain lamp, or Beam(range, edge, dip, intensity, hot, corona, spill, rings) for a reflector.

Field	Unit	Meaning
`range`	m	How far it reaches. It fades out before this.
`edge`	rad	Half angle of the beam’s edge.
`dip`	rad	How far the beam is aimed below level. Headlights point a little down at the road.
`intensity`		How bright it is close up. Multiply your color by it.
`hot`	rad	A reflector’s hot spot width. 0 for a plain lamp.
`corona`	rad	The corona round the hot spot.
`spill`		How bright the flat spill out to the edge is.
`rings`		How strongly the corona rings.

Presets:

Preset	Range	Edge	Use
`Beam.LOW`	32 m	30°	Low beam headlights, aimed 2.5° down.
`Beam.HIGH`	56 m	20°	High beams, nearly level.
`Beam.REVERSE`	12 m	55°	Reverse lamps: a short, wide wash behind.
`Beam.FLASHLIGHT`	46 m	34°	A flashlight: a tight 12° hot spot, a corona, and a dim spill.

fov() and far() give the shadow map’s field of view and far plane; spreading() how fast the light spreads with distance. You only need these when building a Lamp by hand.

Spot lights

pair

boolean pair(int key, Beam beam, Entity holder,
             Vector3f first, Vector3f last, Vector3f direction, Vector3f up,
             Vector3f aimFirst, float shineFirst, Vector3f aimLast, float shineLast,
             Vector3f color, Vector3f ambient)

Two beams that share one shadow map, the way a car’s headlights do.

first, last: the two lamps, the outermost of them if a vehicle has more.
direction: the pair’s line (forward). up: the shadow map’s up, usually the vehicle’s up.
aimFirst, aimLast: where each lamp points. Each may be up to MOST_TURN off direction, for a lamp a dent has knocked askew.
shineFirst, shineLast: how bright each lamp is now, 0 to 1. A broken lamp is 0.
color: one lamp’s light. ambient: the lightmap color round them.
holder: the entity carrying them. It, and whatever it rides or carries, casts no shadow in its own beams.

spot

boolean spot(int key, Beam beam, Entity holder, Vector3f position, Vector3f direction,
             float shining, Vector3f color, Vector3f ambient, float glare, boolean handheld)

One beam, such as a flashlight.

glare: how much it glares at the eye when it points at the camera. Use 0 for the viewer’s own light.
handheld: it swings about with a look. Its shadow blocks are gathered all round it rather than in a cone ahead, and its dust is thinner and kept off the lens.

Lamp

frame.lamp(Lamp) takes a spot light worked out by hand, for when pair and spot cannot express it. pair and spot build a Lamp too; read Frame.pair in the source for how each field is filled in. The record carries the key, beam, holder, middle position, half spread, direction, the two lamps’ aims and brightness (sides), color, ambient, the air’s dustiness along the beam (air), the shadow map’s view and projection, glare and handheld.

Point

new Point(Vector3f position, Vector3f color, float reach, Vector3f ambient, float near,
          Vector3f min, Vector3f max)

Light all round a point.

reach (m): how far it lights at most. Lambent skips every pixel past it, so keep it tight.
near (m²): how far the light holds up before it falls away. The light at distance d is color / (1 + d² / near). Small values give a small, sharp pool; Veltorque’s flares use 2500 so one high in the sky still lights the ground.
min, max: the box its light stays in. Use frame.room(id, at), which finds the hollow the light is shut in (a cave, a room, a hole) by filling the air round it, and returns null in the open. In the open, use -1e5 and 1e5.

Point lights have no shadow map. With pointShadows on (the default), light still stops at whatever stands between it and a surface: on screen it marches through the scene’s depth, and off screen it checks the blocks round the eye, kept in a 3D texture (Solids) and a height map of what the sky sees (Skyline).

Glow

new Glow(Vector3f position, Vector3f facing, Vector3f color, float size, float streak, float tilt)

A lit lens seen from in front: a tail lamp, a reverse lamp’s lens, a flare’s flame.

facing: which way the lens faces. It shows fully from in front and fades out side-on.
size (m): the lens’s half size.
streak: how bright a streak of glare it draws across the screen; 0 for none. tilt (rad): the streak’s angle.

Lens

new Lens(Vector3f[] corners, Vector3f color)

Bloom round a lit lamp’s box: 8 corners, where corner i takes x from bit 0, y from bit 1 and z from bit 2 of i. Lambent draws the box at half size wherever the scene shows it, then blurs it twice: a tight glow over the lens and a wide halo round it.