Byte Engine Docs

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:

LightBest intensity unitTypical use
DirectionalLightIlluminance in luxSunlight or another source that's effectively infinitely far away
PointLightLuminous intensity in candela or total flux in lumensBare bulbs and other omnidirectional sources
ConeLightLuminous intensity in candela or total flux in lumensSpotlights, 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:

VariantFieldsDirectional lightPoint and cone lights
Illuminancelux, measurement_distance_mE = luxI = E × d², where d is the measurement distance
LuminousIntensitycandela, reference_distance_mE = I / d², where d is the reference distanceI = candela
LuminousFluxlumens, directional_beam_area_m2E = Φ / A, where A is the beam areaPoint: I = Φ / 4π. Cone: I = Φ / Ω, where Ω = π × (2 − cos(inner) − cos(outer))
Luminancenits, projected_area_m2, reference_distance_mE = 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 +Z is the emission axis.
  • Local +X is the IES C0 plane.
  • Local +Y is 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.

Rust API

On this page