# DRAFT — Étape 14 : Shadows (Phase 4.2, optionnel)

> **Objectif** : ajouter les **ombres portées** (shadow mapping) à `wsg-lib`, sur une **lumière
> unique** (directionnelle ou spot) choisie par la scène. C'est le dernier item optionnel restant
> de la Phase 4.2 (hémisphérique ✅, multi-lumières ✅ Étape 12, spot ✅ Étape 13, **shadows →
> ici**).
>
> **État de départ** : l'éclairage est entièrement CPU-packé dans `FrameUniforms` (liste
> `lights[8]`, caméra `view/proj`, `options[0]` = unlit). Le `Renderer` possède déjà une depth
> texture de scène (`_depth_texture`/`depth_view`) et un cache d'object bind groups
> (`object_cache`, par entité, modèle réécrit chaque frame). Le shader `standard_shader.wgsl` a
> un layout unique de 3 bind groups partagé par **toutes** les pipelines (Étapes 3 + 10) : frame
> @0, object @1, texture diffuse @2.
>
> **Définition de done** : un objet éclairé par la lumière ombreuse projette une ombre visible
> sur une surface adjacente (un sol), et l'ombre bouge quand le cube tourne. Vérifié au runtime
> via un exemple dédié (`shadow_test`). Aucune régression sur les exemples existants (`simple`,
> `cube`, `manual`, `spot_test`) — les ombres sont **éteintes par défaut**.

---

## 1. Modèle retenu : shadow mapping mono-lumière

Le shadow mapping classique se fait en **deux passes** :

1. **Pass ombre (depth-only)** : on rend la scène depuis le point de vue de la lumière dans une
   texture de profondeur dédiée (la **shadow map**). Seule la profondeur compte — pas de couleur,
   pas d'éclairage.
2. **Pass principale** : dans le fragment shader, on reprojette chaque fragment dans l'espace
   lumière (`light_view_proj`), on compare sa profondeur à la shadow map. Si le fragment est plus
   loin que l'occulteur enregistré, il est **à l'ombre** ; sinon il multiplie l'éclairage par 1.

### Portée (D1)
Une **seule** lumière ombreuse par frame, désignée par **son index dans le tableau packé**
(directionnelles d'abord, puis points, puis spots — même convention que `Lights::into_frame_array`).
Un index sentinelle `MAX_LIGHTS` (= 8) signifie « aucune ombre » → **éteint par défaut**
(non-régression). Les ombres **point** (cube map, 6 faces) sont **hors périmètre** (D6) — on couvre
les deux projections utiles :
- **directionnelle** → projection **orthographique** (soleil lointain) ;
- **spot** → projection **perspective** depuis le sommet du cône.

### Pourquoi ce choix ?
- Coût, lisibilité et validation simples : une texture, une passe, un VP lumière, un échantillon PCF.
- S'aligne sur l'architecture existante (matrices par frame, object bind group réutilisé).
- Le multi-shadow et les ombres point seront des extensions incrémentales (voir §6 « Évolutions »),
  pas une réécriture.

---

## 2. Décisions (D1..D8)

| # | Décision |
|---|----------|
| **D1** | **Une seule lumière ombreuse** par frame, sélectionnée par index (tuple `(enable, index)`). Desactivée par défaut (index = `MAX_LIGHTS`). API : `Scene::set_shadow_caster(index)`. |
| **D2** | **Shadow map** : `DEPTH_FORMAT` (Depth32Float), résolution **1024×1024** par défaut, `usage = RENDER_ATTACHMENT | TEXTURE_BINDING`, 1 mip. Propriété du `Renderer` (comme la depth texture de scène). |
| **D3** | **Matrice `light_view_proj` calculée sur CPU** chaque frame par le `Renderer` (depuis `scene.shadow_caster()` + la lumière + un centre/rayon de scène). Ortho pour directionnelle, perspective pour spot. Uploadée dans `FrameUniforms` (tampon frame existant, `min_binding_size: None` → extension transparente). |
| **D4** | **Pipeline ombre dédiée** (vertex-only, `fragment: None`) : layout = [group 0 : `light_view_proj`, group 1 : `object_layout` **réutilisé**]. Elle réutilise donc directement `object_cache` (bind groups par entité déjà réécrits chaque frame). |
| **D5** | **PCF (Percentage Closer Filtering)** : échantillon comparateur (`sampler_comparison` + `texture_depth_2d`) + petit kernel 3×3 dans le shader, **slope-scaled depth bias** sur la pipeline ombre (`DepthBiasState { constant, slope_scale, clamp }`) + un petit bias constant dans la comparaison pour supprimer l'acné. |
| **D6** | **Ombre ponctuelle (cube map) hors périmètre** : documentée en §6, PAS implémentée à l'Étape 14. |
| **D7** | **Non-régression** : ombres éteintes par défaut → exemples `simple`/`cube`/`manual`/`spot_test` inchangés (pas de changement de leur rendu). Le groupe 3 (shadow) reste lié sur toutes les pipelines mais l'échantillonnage est porté par `options[1]`/index. |
| **D8** | **Résolution shadow** configurable plus tard ; constante `SHADOW_MAP_SIZE = 1024` maintenant (setter + recréation de texture reportés — voir §6). |

---

## 3. Plan d'implémentation

### 3.1 Étendre `FrameUniforms` (+ contrat WGSL) — uniform.rs / standard_shader.wgsl
Ajouter, après les compteurs, **avant** `options` (alignement 16 respecté par `repr(C)` comme par
WGSL) :

| Offset | Champ | Type | Sens |
|--------|-------|------|------|
| 672 | num_directional | u32 | (existant) |
| 676 | num_point | u32 | (existant) |
| 680 | num_spot | u32 | (existant) |
| 684 | **shadow_light_index** | u32 | index de la lumière ombreuse, `MAX_LIGHTS` = aucune |
| 688 | **light_view_proj** | mat4x4<f32> | VP de la lumière ombreuse |
| 752 | **shadow_params** | vec4<f32> | x = résolution (taille shadow map en pixels), y = bias, z/w = libres |
| 768 | options | vec4<u32> | (existant, `options[1]` = « ombres actives » 0/1) |

- Total : **784 octets** (au lieu de 704). `FRAME_UNIFORMS_SIZE = size_of` suit automatiquement ;
  le `min_binding_size: None` du layout frame rend l'agrandissement transparent.
- **WGSL** `struct FrameUniforms` mis à jour à l'identique (même ordre, mêmes types) ; la table
  d'offset du header du fichier est réindexée.
- **Tests** `frame_uniforms_layout_matches_wgsl` (uniform.rs) mis à jour : nouvel `offset_of`
  pour `shadow_light_index` (684), `light_view_proj` (688), `shadow_params` (752), `options`
  (768) et nouvelle taille 784.

### 3.2 Ressources shadow dans le `Renderer` — core/renderer.rs
Dans `Renderer::new`, allouer :
- `_shadow_texture: wgpu::Texture` + `shadow_view: wgpu::TextureView` (1024², Depth32Float,
  `RENDER_ATTACHMENT | TEXTURE_BINDING`) — même pattern que `create_depth_texture`, helper isolé
  `create_shadow_map(device, size)` ;
- `shadow_sampler: wgpu::Sampler` : `compare: Some(CompareFunction::GreaterEqual)` (voir D5) ,
  `mag/min_filter: Linear`, `address_mode: ClampToEdge` — comparateur requis pour
  `textureSampleCompare` ;
- `shadow_bind_group` : group 3 = [`shadow_sampler` (0), `shadow_view` (1)] ;
- `shadow_uniform_buffer` : 64 o (une `Mat4`), + `shadow_uniform_bind_group` (group 0 de la
  pipeline ombre) ;
- `shadow_pipeline` : vertex-only (voir 3.3).

Nouveaux champs privés + les exposer par getters (au minimum `shadow_texture`,
`shadow_bind_group`, `shadow_pipeline`, `shadow_uniform_bind_group`) pour `render_scene`.

### 3.3 Pipeline ombre dédiée — pipeline/pipeline_cache.rs (helper) + renderer.rs
Nouvelle **`create_shadow_pipeline_layout(device, object_layout)`** et helper `build_shadow_pipeline` :
- Layout : [`shadow_uniform_layout` (group 0, buffer uniform VERTEX), `object_layout` (group 1)].
  `object_layout` = exactement celui existant (même bind group par entité réutilisé). ✔
- `vertex` : `vs_main` d'un **nouveau shader minimal `shadow_shader.wgsl`** qui ne fait que :
  `clip = light_view_proj * object.model * vec4(position,1)`. Entrées : uniquement `position`
  (location 0). Pas de fragment (`fragment: None`).
- `depth_stencil` : `DEPTH_FORMAT`, `depth_write = true`, `compare = Less`, **`bias` slope-scaled**
  (`constant = 2` , `slope_scale = 2.0`, clamp ~0) — anti-acné (D5).

Le shader ombre est ajouté en constante embarquée (`shadow_shader.wgsl` sous
`lib/src/shaders/`) et enregistrable via `PipelineCache::register_shader` comme les autres.

### 3.4 Pass ombre : `render_shadow_map` — core/renderer.rs
Nouvelle méthode, appelée **en tête de `render_scene`** (même `CommandEncoder`) :
1. Si `scene.shadow_caster()` est `None` → ne rien faire (ombre éteinte, `options[1] = 0`).
2. Calculer `light_view_proj` (D3, helper `light_view_proj(camera_setup, scene)` — voir 3.6),
   l'écrire dans `shadow_uniform_buffer`.
3. `encoder.begin_render_pass` sur `shadow_view` (depth clear 1.0, pas de color attachment),
   `set_pipeline(shadow_pipeline)`, pour chaque entité : `set_bind_group(0, shadow_uniform)` +
   `set_bind_group(1, object_bind_group_for(label, transform))` + draw (indexed ou non).
4. Mettre `options[1] = 1` dans les frame uniforms.

`render` (bas niveau, sans scène) ne fait **pas** d'ombre — documenté (D7).

### 3.5 Échantillonnage PCF dans `standard_shader.wgsl`
- Déclarer le groupe 3 (ajouté à **toutes** les pipelines via `create_*_bind_group_layouts`) :
  ```
  @group(3) @binding(0) var shadow_sampler: sampler_comparison;
  @group(3) @binding(1) var shadow_texture: texture_depth_2d;
  ```
- Dans `fs_main`, **après** le calcul de `diffuse` et **une seule fois** (hors boucles lumière) :
  1. `let in_shadow = 1.0 - sample_shadow(in.world_pos, frame);` avec `sample_shadow()` calculant
     `light_uv` = NDC de `frame.light_view_proj * world_pos`, mappé en `[0,1]` (xy et z), puis
     un **PCF 3×3** : moyenne de 9 `textureSampleCompare(shadow_texture, shadow_sampler, uv+off,
     z-bias)` (offsets en texels / `shadow_params.x`).
  2. `let lit = base * (ambient + diffuse * shadow_factor);` — l'ombre **ne touche pas l'ambiant**
     (les ombres dures du soleil conservent une composante ambiante, look réaliste et pas de noir
     total).
- Garde : si `frame.shadow_light_index == MAX_LIGHTS` (ou `options[1] == 0`) → `shadow_factor = 1`
  (aucune ombre). Comportement identique aux exemples existants (D7).
- Le `light_view_proj` est un attribut **global** de frame (une seule lumière ombreuse, d'où la
  porte _mono-lumière_ D1).

### 3.6 Helper de calcul `light_view_proj` — core/renderer.rs (ou math/)
`fn light_view_proj(light_index, lights, scene_center, area_radius) -> Mat4` :
- lire la lumière par `lights.into_frame_array()` → type par **position** (même logique que le
  shader) ;
- **directionnelle** : `dir = normalize(position_dir.xyz)` (déjà « vers la lumière ») ;
  position légère = `scene_center + dir * D` avec D grand (ex. `area_radius * 2 + 10`) ;
  view = `look_at(light_pos, scene_center, up)` (up = Y, ou X si parallèle à Y) ;
  proj = **ortho** `(-ext, ext, -ext, ext, near, far)` centrée sur la scène ;
- **spot** : view = `look_at(position_dir.xyz, position_dir.xyz + dir_angle.xyz, up)` ;
  proj = **perspective** fov = `2 * acos(dir_angle.w)` (demi-angle stocké en cos), near = 0.1,
  far = radius ;
- `scene_center`/`area_radius` : par défaut origine / constante (ex. `SHADOW_AREA_RADIUS = 5.0`),
  surchargeables via `Scene` (optionnel à l'Étape 14 — constante en dur OK pour l'exemple).

### 3.7 API `Scene` — scene/scene.rs
- Nouveau champ `shadow_caster: Option<usize>` (+ getter `set_shadow_caster(index)`, getter
  `shadow_caster()`).
- `None` par défaut → ombres éteintes (D7).
- Optionnel : `set_shadow_area(center, radius)` si on veut un réglage fin (reporté si inutile
  pour l'exemple).

### 3.8 Exemple `shadow_test` — lib/examples/shadow_test.rs + README
- **Sol** (plan +Z ou XZ, quad gris) + **cube** posé dessus, éclairé par **une directionnelle**
  qui caste une ombre (`scene.set_shadow_caster(0)` puisque la directionnelle par défaut est
  l'index 0 après clean/setup).
- Cube qui **tourne** (réutiliser `Quat` composé de l'`spot_test`) → l'ombre sur le sol change de
  forme/position à l'écran : preuve visuelle.
- Caméra fixe oblique (ou orbitale simple) pour bien voir l'ombre sur le sol.
- Ligne café : `cargo run -p wsg-lib --example shadow_test`.
- Documenter dans `lib/examples/README.md` (tableau des exemples, convention anglophone ✔).

---

## 4. Non-régression (obligatoire)
- `cargo build --workspace`, `cargo check --workspace` : verts.
- `cargo test --workspace` : tests `uniform.rs` (nouveaux offsets) + `lights.rs` inchangés passent.
- Exemples existants (`simple`, `cube`, `manual`, `spot_test`) : rendu **identique** (ombres
  éteintes par défaut, groupe 3 lié mais non échantillonné quand `shadow_light_index == 8`).
- `cargo fmt --all` une fois le code formaté.

## 5. Vérification au runtime
1. `cargo run -p wsg-lib --example shadow_test` : un cube éclairé projette une ombre nette sur le
   sol ; l'ombre **bouge** quand le cube tourne.
2. Toggle à la main (commenter `set_shadow_caster`) : ombre disparaît → le flag porte bien
   l'activation.
3. Quelques frames : pas d'artefact type acné (PCF + bias D5). Zoom sur la jonction cube/sol.
4. (Optionnel) tenter une **spot** comme castor (`set_shadow_caster(..)` sur une spot) : ombre
   perspective visible.

## 6. Évolutions (hors périmètre Étape 14)
- **Multi-ombres** : tableau de shadow maps + dépliage de `light_view_proj` en `[Mat4; N]` /
  array de textures (array layer), PCF indexé par lumière. Change le contrat uniform → nouvelle
  étape.
- **Ombre ponctuelle** : cube map 6 faces + `textureSampleCompare` sur `texture_depth_cube_array`.
- **Résolution /  soft shadow dynamique** : `set_shadow_map_size` avec recréation de texture,
  kernel PCF variable, blister/VSM.
- **Optimisation** : limiter la pass ombre aux seules entités dans le cône/frustum de la lumière.

---

## 7. Suivi (à compléter après implémentation)
> Remplir le bilan ici une fois l'étape livrée (comme pour les Étapes 12–13) : ce qui marche, ce
> qui a été vérifié, git-log du commit, et **vider** ce DRAFT pour l'étape suivante.

## 8. Ordre des commits (plan)
1. `feat(uniform): FrameUniforms étendu (shadow_light_index, light_view_proj, shadow_params)`
2. `feat(shadow): shader ombre + pipeline depth-only + ressources Renderer`
3. `feat(shadow): pass render_shadow_map + PCF dans standard_shader.wgsl`
4. `feat(scene): Scene::set_shadow_caster`
5. `test: exemple shadow_test + README des exemples`
6. (si besoin) `fix: bias/PCF — artefacts`