wsg/lib/examples/lights/README.md

Lights, Shadows & Emissive

Examples covering lighting: shadow mapping, isolated light types, and emissive materials.

Example	Run command	What it shows
shadow	cargo run -p wsg-lib --example shadow	Shadow mapping in isolation (directional light, 4 objects on a floor)
shadow_test	cargo run -p wsg-lib --example shadow_test	Dedicated shadow test: one directional caster, cube on a ground slab, PCF-softened
spot_test	cargo run -p wsg-lib --example spot_test	Isolated spot light: directed beam, penumbra, attenuation
emissive	cargo run -p wsg-lib --example emissive	Emissive materials (increasing intensities 0 → 4.0)

All commands run from the repo root.

---

shadow — Shadow Mapping

Four objects (cube, sphere, cone, cylinder) on a floor, lit by a directional light that casts shadows. Shadow quality is controlled by ShadowConfig (map size, anti-acne bias).

cargo run -p wsg-lib --example shadow

Keys

Key	Action
Drag (LMB)	Orbit camera
Wheel	Zoom
R	Reset camera
1	Front view
2	Side view
3	Top view (see shadow shapes clearly)
L	Change light direction (3 presets)

What to observe

• The cube rotates slowly → its shadow moves on the floor.
• The sphere has a smooth shadow/light transition (soft terminator).
• The cone produces a distinct triangular shadow.
• In top view (3), you see the exact shape of projected shadows.
• Shadow map size (1024 default) determines resolution: modify SHADOW_MAP_SIZE at the top of the file to test 256 (pixelated) or 2048 (sharp).

---

shadow_test — Dedicated Shadow Mapping Test

A single directional light is configured as the shadow caster (Scene::set_shadow_caster(Some(0))). The cube sits on a large thin ground slab, so its silhouette is projected as a crisp PCF-softened shadow. With a small ambient term the shadow is clearly visible and the light/shadow directions are easy to read:

1. the blocker (cube) casts a directional shadow that stretches along the ground opposite the light direction — the light sits at the camera's front-right and low-ish, so the shadow runs clearly across the ground to the left of the cube,
2. the shadow edge is softened by 3×3 PCF (no hard jagged border),
3. the lit faces are bright while the shadowed ground stays near-ambient, proving the depth comparison is applied per-pixel.

cargo run -p wsg-lib --example shadow_test

---

spot_test — Isolated Spot Light

Only a spot light is on (the default directional light is removed via clear_lights()) and the ambient is deliberately very low. The rotating cube therefore appears nearly black except where the spot's cone reaches it — you clearly see:

1. a directed beam (not an omni halo like the point light),
2. a smoothed edge (penumbra) at the cone's limit,
3. the lighting that follows the cube as it rotates (the cone is fixed in world space).

cargo run -p wsg-lib --example spot_test

---

emissive — Emissive Materials

Five spheres in a row with increasing emissive intensities:

Sphere	Color	Intensity	Effect
1	Gray	0.0	No glow (reference)
2	Orange	0.5	Slight glow
3	Yellow	1.0	Visible glow
4	Green	2.0	HDR glow (beyond 1.0)
5	Blue	4.0	Intense glow (saturation)

With HDR, intensities > 1.0 produce a true "glow" (values exceed [0,1] in linear space). Without HDR, they would be clamped to white.

cargo run -p wsg-lib --example emissive

Keys

Key	Action
Drag (LMB)	Orbit camera
Wheel	Zoom
R	Reset camera
E / Q	Exposure ×1.3 / ÷1.3
0	Reset exposure
C	Cycle emissive multiplier (1× → 2× → 0.5× → …)

What to observe

• Sphere 1 (intensity 0) is simply lit by the directional light.
• Spheres 2-5 glow with their own light, independent of scene lighting.
• C doubles or halves all intensities simultaneously (to see the HDR effect).