Lighting
Look up the light shapes, their physical units and conversions, how far a light reaches, and the shadow and light limits.
Byte Engine lights a scene in physical units, so a light responds predictably to distance and material properties. This page defines the light shapes, the units they take and how they convert, and the limits on reach, count, and shadows. To create lights and set up exposure, environment, and fog, follow Light a scene.
Light shapes
Byte Engine provides three analytic light shapes. Point and cone lights can also use a baked IES profile when you need a measured angular intensity distribution:
| Light | Best intensity unit | Typical use |
|---|---|---|
DirectionalLight | Illuminance in lux | Sunlight or another source that's effectively infinitely far away |
PointLight | Luminous intensity in candela or total flux in lumens | Bare bulbs and other omnidirectional sources |
ConeLight | Luminous intensity in candela or total flux in lumens | Spotlights, flashlights, and focused fixtures |
One world-space distance unit is one meter. Keep your scene at that scale so inverse-square attenuation and distance-based conversions remain meaningful.
Color
LightColor::TemperatureKelvin names a blackbody-style illuminant, which Byte
Engine converts through CIE chromaticity to linear sRGB. A Kelvin value must be
from 1,000 K through 40,000 K. LightColor::LinearSrgb names an authored
color. Its RGB values describe chromaticity, not brightness: Byte Engine
normalizes the color to unit photopic luminance, so only PhotometricIntensity
sets brightness. RGB components must be nonnegative and the color must have
nonzero luminance.
Intensity conversions
Every PhotometricIntensity variant works with every light shape. Byte Engine
resolves the authored quantity on the CPU into illuminance in lux for a
directional light and luminous intensity in candela for a point or cone light:
| Variant | Fields | Directional light | Point and cone lights |
|---|---|---|---|
Illuminance | lux, measurement_distance_m | E = lux | I = E × d², where d is the measurement distance |
LuminousIntensity | candela, reference_distance_m | E = I / d², where d is the reference distance | I = candela |
LuminousFlux | lumens, directional_beam_area_m2 | E = Φ / A, where A is the beam area | Point: I = Φ / 4π. Cone: I = Φ / Ω, where Ω = π × (2 − cos(inner) − cos(outer)) |
Luminance | nits, projected_area_m2, reference_distance_m | E = L × A / d² | I = L × A |
Every field is validated for every shape, even when that shape's conversion
doesn't use it. A cone light's angular falloff is
clamp((cosine − cos(outer)) / (cos(inner) − cos(outer)), 0, 1) on both the CPU
and the GPU, and cone angles are half angles measured from the light direction.
Analytic lights don't retain the physical emitter shape after the conversion.
Light constructors return PhotometricError when a color, magnitude, distance,
or area is zero, negative, or not finite.
IES profiles
A baked IES profile supplies a point or cone light's peak candela and its
relative intensity in every direction. LightColor only tints it, and dimmer
scales it linearly from 0.0 for off through 1.0 for the measured output. An
Orientation places the profile:
- Local
+Zis the emission axis. - Local
+Xis the IES C0 plane. - Local
+Yis the IES C90 plane.
Light reach and limits
A point or cone light reaches as far as its exposed illuminance stays above 1/1024 lux. On a white surface, that much light shows as about one step of an 8-bit display, so lights keep their inverse-square falloff without a visible edge. A brighter light, or a brighter camera exposure, reaches farther. Directional lights reach everything.
A scene can hold up to 1,024 lights. If it holds more, the renderer logs a warning and leaves out the lights past that limit.
Shadow maps
A point light casts shadows through one cube map and a cone light through one perspective shadow map. A cone with an outer half angle of 90° or more remains a valid light but can't use one perspective shadow map.
A local light's shadow reaches from 0.1 m to where its exposure-weighted peak illuminance falls below 0.125 lux.
The visibility pipeline specifies which lights get shadow maps, how large they are, and how often they're drawn, under shadow maps.
Sky and calibration
If you install the atmosphere sky with setup_atmosphere_sky_render_pass, the newest directional
light is also the sky's sun. Its lux and color set how bright and what color the sky is, so a
brighter sun brightens the sky too. Without a directional light, the sky is black. The sky includes
light that scatters more than once in the air, and sunlight the ground reflects back up, so a
100,000 lux sun gives a clear sky of about 2,000 to 8,000 nits, brightest near the horizon. The sky is drawn after opaque surfaces
and before transparent ones, so glass and other blended surfaces show the sky behind them.
Physical calibration limits
Emissive materials don't have a unified physical calibration with analytic lights. Radiometric units such as watts and watts per square meter aren't supported.