Light a scene
Create directional, point, and cone lights in physical units, then set the exposure, environment, and fog to match.
Use physical light units when you want lighting that responds predictably to distance and material properties.
Byte Engine has three light shapes: DirectionalLight for the sun and other
distant sources, PointLight for bulbs and other omnidirectional sources, and
ConeLight for spotlights. Point and cone lights can also use a baked IES
profile when you need a measured angular intensity distribution. The units each
shape takes, how Byte Engine converts them, and the limits on light reach and
count are in the lighting reference.
One world-space distance unit is one meter. Keep your scene at that scale so inverse-square attenuation and distance-based conversions remain meaningful.
Create a light
Choose a color, choose an intensity, and create the light. Then create it on the application's world scope,
GraphicsApplication::world, so the active rendering pipeline can use it.
use byte_engine::{
core::{Creator as _, message_bus::MessageScope},
math::Vector3,
rendering::{DirectionalLight, LightColor, PhotometricIntensity},
};
let world = MessageScope::standalone("world");
let sunlight = DirectionalLight::new(
Vector3::new(0.2, -1.0, 0.3),
LightColor::TemperatureKelvin(5_778.0),
PhotometricIntensity::Illuminance {
lux: 100_000.0,
measurement_distance_m: 1.0,
},
)?;
world.create(sunlight);
# Ok::<(), byte_engine::rendering::PhotometricError>(())Light constructors return PhotometricError when a color, magnitude, distance, or area is zero,
negative, or not finite. A Kelvin value must be from 1,000 K through 40,000 K.
Choose a color
Use LightColor::TemperatureKelvin for a blackbody-style illuminant such as daylight, a tungsten
lamp, or a warm practical light. Byte Engine converts the temperature through CIE chromaticity to
linear sRGB.
Use LightColor::LinearSrgb for an authored color:
let color = LightColor::LinearSrgb(Vector3::new(1.0, 0.15, 0.02));The RGB values describe chromaticity, not brightness. Byte Engine normalizes the color to unit
photopic luminance. Set brightness with PhotometricIntensity; increasing the RGB values alone
doesn't make the light brighter. RGB components must be nonnegative and the color must have
nonzero luminance.
Choose an intensity
You can use every PhotometricIntensity variant with every light shape. Include the reference
distance or area carried by the variant so Byte Engine can make a deterministic conversion.
Lux
Lux measures illuminance arriving at a surface. It's the most direct choice for a directional
light. For a point or cone light, measurement_distance_m says where the requested illuminance
must be reached.
let intensity = PhotometricIntensity::Illuminance {
lux: 500.0,
measurement_distance_m: 2.0,
};For local lights, Byte Engine converts lux to candela with I = E × d². A light that produces
500 lux at 2 meters therefore has an intensity of 2,000 candela. The measurement distance is
validated but doesn't change an already directional illuminance field.
Candela
Candela measures luminous intensity in one direction. It maps directly to point and cone lights.
For a directional light, reference_distance_m defines the plane where the equivalent
illuminance is measured.
let intensity = PhotometricIntensity::LuminousIntensity {
candela: 1_200.0,
reference_distance_m: 1.0,
};A directional light converts this value with E = I / d². Local lights keep the candela value;
their reference distance is validated but doesn't change it.
Lumens
Lumens measure total luminous flux. A point light distributes its lumens uniformly over 4π
steradians, so Byte Engine uses I = Φ / 4π.
A cone light distributes its lumens through its inner-to-outer soft cone. Byte Engine uses the same linear angular falloff on the CPU and GPU:
cone factor = clamp((cosine − cos(outer)) / (cos(inner) − cos(outer)), 0, 1)Its effective solid angle is:
Ω = π × (2 − cos(inner half-angle) − cos(outer half-angle))
I = Φ / ΩFor a directional light, supply the beam area at the reference plane and Byte Engine uses
E = Φ / A.
let intensity = PhotometricIntensity::LuminousFlux {
lumens: 1_600.0,
directional_beam_area_m2: 4.0,
};directional_beam_area_m2 is required and validated for every light. Point and cone lights don't
use it because their emission shape already defines how the flux is distributed.
Nits
Nits, or candela per square meter, measure luminance. Use this option when you know the luminance and projected area of the emitting surface.
let intensity = PhotometricIntensity::Luminance {
nits: 300.0,
projected_area_m2: 0.02,
reference_distance_m: 2.0,
};Point and cone lights use the uniform-emitter approximation I = L × A. Directional lights use
E = L × A / d². Analytic lights don't retain the physical emitter shape after this conversion.
Create point and cone lights
The following point light emits 800 lumens uniformly:
use byte_engine::rendering::{LightColor, PhotometricIntensity, PointLight};
let bulb = PointLight::new(
Vector3::new(0.0, 2.4, 0.0),
LightColor::TemperatureKelvin(2_700.0),
PhotometricIntensity::LuminousFlux {
lumens: 800.0,
directional_beam_area_m2: 1.0,
},
)?;The following cone light emits 1,600 lumens through a soft 20° to 30° half-angle range:
use byte_engine::rendering::{ConeLight, LightColor, PhotometricIntensity};
let spotlight = ConeLight::new(
Vector3::new(0.0, 3.0, 0.0),
Vector3::new(0.0, -1.0, 0.0),
LightColor::TemperatureKelvin(3_200.0),
PhotometricIntensity::LuminousFlux {
lumens: 1_600.0,
directional_beam_area_m2: 1.0,
},
20.0_f32.to_radians(),
30.0_f32.to_radians(),
)?;Cone angles are half angles measured from the light direction. The renderer
automatically uses a 0.1 m near plane and a neutral exposure scale of 1. It
extends the far plane until peak exposure-weighted illumination falls below
0.125 lux. These values control only the cone shadow view. They don't limit
lighting attenuation. Override either endpoint with with_shadow_near or
with_shadow_far, or override both with with_shadow_range.
A cone with an outer half angle of 90° or more remains a valid light but can't use one perspective
shadow map.
Use an IES profile
Use an IES profile when you have a fixture's measured .ies file and want its real angular intensity
pattern. Bake the source into your resource database, then pass its resource ID to PointLight::new_ies
or ConeLight::new_ies.
The IES file supplies the peak candela and the relative intensity in every direction. LightColor
only tints that measured light. Don't pass a separate PhotometricIntensity value. Set dimmer to a
linear fraction from 0.0 for off through 1.0 for the profile's measured output. For example, 0.01
runs the measured fixture at 1% output. The renderer applies the same dimmed intensity to shading,
automatic shadow coverage, and shadow priority.
The renderer uses a dimmed unit-luminance fallback while the profile uploads asynchronously. If the resource is missing or isn't a usable baked IES image, the visibility pipeline logs an error and the fallback remains active.
Use an Orientation to place the profile:
- Local
+Zis the emission axis. - Local
+Xis the IES C0 plane. - Local
+Yis the IES C90 plane.
Keep the orientation when you animate a fixture, because its C0 plane defines the rotation of an
asymmetric profile. Use orientation_from_direction only when a canonical zero-roll frame is enough.
use byte_engine::{
math::{Orientation, Point},
rendering::{LightColor, PointLight},
};
let office_fixture = PointLight::new_ies(
Point::new(0.0, 2.4, 0.0),
Orientation::identity(),
LightColor::Kelvin(4_000.0),
0.5,
"lights/office.ies",
)?;For a cone fixture, use ConeLight::new_ies with the same position, orientation, color, dimmer, and
resource ID, followed by its inner and outer half angles. After the profile reaches the GPU, its dimmed
calibrated peak candela also controls automatic shadow coverage and local-shadow priority.
Control local-light shadows
Point lights use a cube shadow map, so each selected point light renders six 90-degree shadow
views. The renderer uses a 0.1 m near plane and extends the automatic far plane until the peak
exposure-weighted illumination falls below 0.125 lux. This range controls shadow coverage only. It
doesn't limit inverse-square lighting. Use with_shadow_near, with_shadow_far, or
with_shadow_range on PointLight when your scene needs explicit coverage.
Every shadow-casting light shares one memory budget, 128 MiB by default. Set
render.shadow-maps.budget-mb at application startup to change it. The sun
takes its share first, then local lights in order of how much of the screen
they cover, and the lights that don't fit stay lit without shadows. The
shadow map reference gives the costs and
the order.
Set camera exposure
Real-world light values are far brighter than a display can show, so pair them with a matching
camera exposure. Exposure is measured in stops, and each stop halves or doubles the light that the
camera shows. To use a photographic exposure value, convert it with -(EV100 + log2(1.2)):
use byte_engine::rendering::Camera;
// A sunny day at EV100 15, the sunny-16 rule.
let camera = Camera::new().with_exposure(-(15.0 + 1.2_f32.log2()));Typical EV100 values are 15 for a sunny day, 12 to 13 for an overcast one, and 5 to 7 for a lit
room at night. An exposure of 0.0 shows scene values unchanged.
The physically based (PBR) visibility pipeline and the atmosphere sky apply the exposure as they write scene light,
so a 100,000 lux sun on a glossy surface stays within the range of the scene image, whose
floating-point channels reach about 65,000.
Later passes, such as bloom and tone mapping, receive exposed light. Scenes drawn with other
pipelines ignore exposure. The camera's aperture field doesn't change it.
Calibrate the environment map
Environment maps store light in arbitrary units. Give the environment the illuminance it should deliver to an upward-facing surface, so it lights the scene in the same units as your lights:
use byte_engine::rendering::Environment;
// Clear-sky light on the ground, next to a 100,000 lux sun.
let environment = Environment::new("sky.environment.bead").with_illuminance(15_000.0);A clear daytime sky delivers about 10,000 to 25,000 lux and an overcast one about 1,000 to
10,000. Without with_illuminance, the map's own values are used unchanged.
Add height fog
Height fog fills the scene with mist that's thickest near the ground and thins out with altitude, like rain mist, an overcast day, or haze in a valley. Install the fog pass after the scene pipeline and particles, and before antialiasing, lens flare, bloom, and tone mapping, so bright light glows through the mist. Then create a fog in a tick after the one that creates the window:
use byte_engine::rendering::{ExponentialHeightFog, FogLayer};
byte_engine::application::graphics::setup_exponential_height_fog_render_pass(&mut app);
// Later, once the window exists: rain mist that hides about 40 % of a surface 10 m away.
app.world().factory::<ExponentialHeightFog>().create(
ExponentialHeightFog::new(FogLayer::new(0.06).with_height_falloff(0.1))
.with_ambient_illuminance(15_000.0),
);A FogLayer sets how much fog there is at each height. Its density is the fraction of light it
blocks per meter at its base height. Light rain mist is about 0.01 to 0.06, and thick fog is
0.1 or more. The height falloff sets how quickly it thins: the density halves every
ln(2) / falloff meters above the base height.
To add mist that pools near the ground, such as spray from rain splashes, stack a second, dense layer with a steep falloff. Its fog adds to the first layer's:
ExponentialHeightFog::new(FogLayer::new(0.06).with_height_falloff(0.1))
// Spray that halves every 0.23 m, so it stays below the knees.
.with_second_layer(FogLayer::new(0.3).with_height_falloff(3.0))
.with_ambient_illuminance(15_000.0)A layer covers the whole scene at its height. To keep mist in one area, such as the courtyard where rain splashes, confine the layer to a world-space box:
use byte_engine::math::{AABB, Point};
let courtyard = AABB::new(Point::new(-7.5, -1.0, -1.0), Point::new(7.0, 2.5, 2.0));
let splash_mist = FogLayer::new(0.3).with_height_falloff(3.0).with_bounds(courtyard);The fog stops sharply at the box's faces, so line them up with walls, pillars, or the ground where geometry hides them. Put the top where the layer has already thinned out.
Two light sources light the fog, in the same units as the rest of the scene:
- The sky, given in lux with
with_ambient_illuminance. Use the same value as the environment'swith_illuminance, so fully fogged views match the brightness of an even overcast sky. - The newest directional light, scattered mostly forward by water droplets. Looking toward the sun,
the fog glows, and
with_anisotropysets how tight that glow is.
Fog also covers the sky: the horizon disappears into it, while the sky straight up stays mostly
clear. Use with_max_opacity to keep a trace of distant surfaces visible through the thickest fog.
Height fog limits
The fog doesn't cast or receive shadows, so it glows evenly in shaded areas too. Transparent surfaces and particles take the fog of the opaque surface behind them.
Rust API
DirectionalLightPointLightConeLightIesProfileCameraEnvironmentExponentialHeightFogFogLayerLightColorPhotometricIntensity
After you create a light, create it on the world scope with
Creator::create.