# 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).