réorg doc

lib/examples/lights/README.md

@@ -0,0 +1,124 @@
+# 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).
+
+```sh
+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.
+
+```sh
+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).
+
+```sh
+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.
+
+```sh
+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).