LOD GPU

docs/DRAFT.md

@@ -1,190 +1,320 @@
-# DRAFT — Étape 18 : Batching par Material (ROADMAP 4.3)
+# Étape 19 — LOD (Level of Detail) par entité
 
-> **Statut** : brouillon de conception (à valider avant implémentation).
-> Couvre le 1er item de la Phase 4.3 de `docs/ROADMAP.md` :
-> « Batching par Material (réduction des state changes GPU) ».
->
-> **Archive** : le draft Étape 17 (rendu GPU-driven) a été vidé après validation (2026-09-22).
-> Référence durable : `docs/tech/ARCHI_CPU_GPU.md` (écarts D1/D4/D5/D12 + piège D14) ;
-> texte intégral : git `3a424af` (`git show 3a424af:docs/DRAFT.md`).
+## Contexte
 
-## Contexte — où on en est
+Le culling (Étape 17) supprime les objets **hors écran**. Le LOD supprime le travail **invisible**
+sur les objets qui sont sur l'écran : un maillage de 3840 indices qui n'occupe que 20×20 pixels
+à l'écran gaspille du GPU — presque tous ses triangles ne produisent aucun pixel.
 
-Le rendu est 100 % indirect (Étape 17) : un draw indirect **par slot**, dans l'ordre d'insertion
-des entités. À chaque draw, la passe principale met à jour (`Renderer::render_scene`,
-`renderer.rs` §7) :
+Principe : chaque mesh peut porter **plusieurs niveaux de géométrie** (L0 = détaillée, L1, L2 =
+de plus en plus simplifiée, silhouettes proches). Chaque frame, on mesure la **taille perçue**
+de chaque entité (rayon de sa bounding sphere projeté en pixels) et on choisit le niveau le plus
+grossier **suffisant**. La transition est protégée par une **hystérésis** (bande morte) pour
+éviter le scintillement d'un objet oscillant autour d'un seuil.
 
-| Appel | Coût |
-|---|---|
-| `set_pipeline(material.pipeline)` | **changement d'état** (swap de pipeline côté driver) |
-| `set_bind_group(0, frame)` | constant dans la passe (re-set inutile mais pas cher) |
-| `set_bind_group(1, object, [offset dynamique])` | paramètre de draw — **pas** un changement d'état |
-| `set_bind_group(2, material.texture_bind_group)` | **changement d'état** (un bind group par `Material`) |
-| `set_bind_group(3, shadow)` | constant |
-| `set_vertex_buffer` / `set_index_buffer` | par mesh, pas cher |
-| `draw_*_indirect` | le draw lui-même |
+ROADMAP : item 4.3 « Level of Detail (LOD) ». Le DRAFT de l'Étape 18 (batching par material) est
+remplacé par ce draft — il est validé et son contenu est dans `ARCHI_CPU_GPU.md` + git history.
 
-→ Le nombre de changements d'état (pipeline + bind group @2) est proportionnel au **nombre
-d'entités**, même quand des dizaines d'entités partagent le même `Material`. La doc du module
-promet déjà « Entity sorting ... minimizes pipeline switches (batching by material) » — c'est ce
-que fait cette étape.
+## La contrainte d'architecture qui tout détermine
 
-Le pass d'ombre n'a qu'**un** pipeline et l'appelle **une seule fois** avant la boucle
-(`renderer.rs` §5) → déjà « batché » sur l'état : rien à y faire.
-
-## Objectif
-
-Réduire les changements d'état de la passe principale de **O(entités)** à **O(matériaux
-distincts)**, sans changer le rendu, sans changer l'API publique, et sans toucher au chemin
-GPU-driven (compute, culling, buffers, indirect) ni au pass d'ombre.
-
-## Contraintes & principes
-
-- **Aucune rupture d'API** : optimisation interne du `Renderer` ; aucun type/méthode publique
-  nouveau ; les exemples ne sont pas modifiés.
-- **Aucune régression visuelle** : tous les pipelines de l'engine sont **opaques**
-  (`BlendState::REPLACE`, `pipeline_cache.rs`) → le depth buffer résout l'ordre → réordonner
-  les draws est visuellement neutre (D4).
-- **Culling/indirect intacts** : les verdicts GPU (args = 0 → no-op) et les buffers ne changent
-  pas ; seul l'**ordre d'émission** des draws change.
-- **Déterminisme** : l'ordre des draws doit rester reproductible frame après frame (slots
-  append-only stables, Étape 17 D9).
-- Capacité ≤ 256 slots → le groupage (O(N), `HashMap` ≤ 256 entrées) est du bruit ; on le
-  refait **chaque frame** (toujours correct, aucun cache à invalider).
+`set_vertex_buffer` est un **état de passe posé par le CPU** — le GPU ne peut pas choisir entre
+deux buffers par draw indirect. Donc **plusieurs buffers par niveau est exclu** : tous les
+niveaux d'un mesh vivent dans **un seul buffer de vertices** (et un seul buffer d'indices), et
+le GPU sélectionne le niveau en écrivant l'**offset** (`baseVertex` / `firstVertex`) et le
+`count` dans les indirect draw args — des champs que le draw indirect lit déjà. C'est ce qui
+rend le LOD compatible avec l'architecture GPU-driven existante sans aucun nouveau mécanisme de
+rendu : le pass `cull` écrit déjà les draw args, il écrit juste les bonnes valeurs.
 
 ## Décisions
 
-### D1 — Clé de groupage : l'identité du `Material` (pointeur `Arc`), pas le shader_id
-- Le vrai « état » qui change entre deux draws partageant un pipeline est le **bind group @2**
-  (texture/sampler) : chaque `Material` en possède un propre (`Material::build`). Deux
-  materials qui partagent le même `shader_id` partagent le pipeline (Arc, `PipelineCache`)
-  mais **pas** le bind group @2 → grouper au niveau pipeline ferait alterner le @2.
-- Clé retenue : `Arc::as_ptr(&material)` — même pointeur ⟺ même objet `Material` ⟺ même
-  pipeline **et** même bind group @2 → les deux changements d'état sont figés dans le groupe.
-- Le fallback `scene.default_material()` est un `Arc` unique en cache (`RefCell`) → toutes les
-  entités sans material forment un groupe.
-- **Subtilité de durée de vie** : le groupage matérialise d'abord les `Arc<Material>` dans un
-  `Vec` (un par slot actif) ; les pointeurs-clés ne sont dérivés qu'ensuite. Les `Arc` restent
-  donc vivants pendant toute la passe → aucun pointeur ne pend (le `Arc` retourné par
-  `default_material()` est un clone : sans le `Vec`, il serait libéré en fin de closure).
+### D1 — Le CPU décide du niveau, le GPU mappe niveau → draw args
 
-### D2 — Ordre des groupes : première apparition en ordre de slots ; intra-groupe : ordre de slots
-- On parcourt les slots dans leur ordre stable (insertion, Étape 17 D9) ; le groupe d'un slot
-  est créé à la **première** apparition de sa clé. `HashMap<clé, index>` + `Vec<groupe>` :
-  O(N), sans tri, **déterministe** et stable frame à frame (scène inchangée → ordre inchangé).
-- En pratique, le premier draw de chaque groupe est le même que l'ancien premier draw du slot
-  → l'impression visuelle est préservée ; seuls les draws de matériaux *différents*
-  s'intercalent moins.
+Le CPU calcule chaque frame le niveau par entité (rayon projeté + hystérésis) et l'uploade dans
+un petit buffer par slot ; le pass `cull` existe déjà et lit ce niveau pour choisir la ligne du
+tableau par mesh (count + offset).
 
-### D3 — Les slots cullés (no-op) restent émis dans leur groupe
-- Le CPU ne connaît pas le verdict GPU du culling (un readback par frame stallerait la boucle
-  — cf. `debug_dump`) : le draw d'un slot cullé est un indirect **zéro count ≈ gratuit** ; on
-  l'émet quand même, dans son groupe.
-- Le nombre de **draw calls** est donc inchangé (1 par slot actif) ; seul le nombre de
-  **changements d'état** baisse. Réduire aussi les draw calls = multi-instancing (exclu —
-  Périmètre).
+Raisonnement :
+- **Testabilité** : la décision est une fonction pure Rust `lod_level(radius_px, last, max,
+  thresholds)` → testable sans GPU, comme `batch_slots` (maison).
+- Le CPU **réécrit déjà** les transform slots chaque frame — un niveau de plus dans la même
+  passe coûte ~1 flop multipli par entité.
+- Aucune extension de `CullUniforms` (pas de view-projection à ajouter) — le CPU a déjà
+  caméra + viewport.
+- L'alternative (décision GPU : viewProj + hauteur dans les cull uniforms, état hystérésis GPU)
+  est documentée comme **extension future** — elle n'apporte qu'un gain marginal (1 KB de
+  upload/frame) au prix d'un test par readback.
 
-### D4 — Réordonnancement sûr : pipelines 100 % opaques
-- `pipeline_cache.rs` crée toutes les pipelines avec `blend: Some(BlendState::REPLACE)`
-  (aucun alpha blending dans l'engine) et le depth write est actif partout (Étape 9) →
-  l'ordre de rasterisation n'a pas d'impact visuel.
-- **Contrainte à documenter** (docs user + rustdoc) : si du blending transparent est ajouté un
-  jour, il faudra isoler les matériaux transparents (trier back-to-front en fin de passe) —
-  signalé ici comme prérequis d'un futur `Material.blend`. Le groupage par Material reste
-  correct en l'état ; seule l'ordre inter-groupes devra évoluer.
+### D2 — Un seul buffer packé par mesh, **niveau 0 à l'offset 0**
 
-### D5 — Groupage en fonction pure, testable sans GPU
-- Le groupage est factorisé en fonction libre :
-  `fn batch_slots<K: Eq + Hash>(keys: &[K]) -> Vec<Vec<usize>>`
-  (groupes dans l'ordre de première apparition de la clé ; indices dans l'ordre d'entrée ;
-  chaque indice apparaît exactement une fois).
-- Le `Renderer` l'appelle avec `keys = [*const Material]` (D1) ; les **tests unitaires**
-  l'appellent avec des clés `u32` → testable sans instance/device wgpu (un `Material` exige
-  un pipeline compilé = device ; les tests de la crate restent headless/CI-safe).
-- Les tombstones (`active == false`) sont filtrés **avant** l'appel (comme aujourd'hui) :
-  `batch_slots` ne voit que les slots actifs.
+Les vertices de tous les niveaux sont concaténés dans le `vertex_buffer` du mesh (idem indices).
+Niveau 0 en tête : la voie basse `draw_entity` (`draw(0..num_vertices)`, sans LOD) et tout draw
+direct existant restent **inchangés** — ils lisent le début du buffer, qui est encore L0.
 
-### D6 — Pass d'ombre : inchangé (déjà batché)
-- Un seul `shadow_pipeline`, `set_pipeline` une seule fois avant la boucle ; l'état résiduel
-  par slot (offset dynamique @1 + vertex/index buffers) n'est pas un changement d'état
-  driver → `render_shadow_map` n'est pas modifié par cette étape.
+### D3 — Indices rebasés par niveau
 
-## Mécanisme par frame (seul le point 7 change)
+Chaque niveau est une géométrie indépendante (indices 0-based sur ses propres vertices). Le
+packer décale les indices du niveau k de `vertex_offset(k)` ; le draw indirect du niveau k pose
+`baseVertex = vertex_offset(k)` → l'index buffer concaténé fonctionne tel quel. (Un niveau reste
+< 65 536 vertices, sinon erreur à l'ajout — `u16`.)
+
+### D4 — Hystérésis **asymétrique**
+
+Seuils descendants `t[0] > t[1] > …` (pixels) : `t[k]` = rayon **au-dessus** duquel le niveau
+k+1 est exigé (équiv. : le niveau k+1 est suffisant tant que `r ≤ t[k]`). Le niveau cible sans
+hystérésis est le **plus grossier** dont la borne est encore respectée (L0 n'a pas de borne).
+- Passer à un niveau **plus grossier** : seulement si `r ≤ borne × 0.8` (bande morte 20 %).
+- Passer à un niveau **plus fin** : immédiatement dès que `r` franchit la borne.
+Si un mesh a plus de niveaux que de seuils, les niveaux excédentaires partagent la dernière
+borne (clamp) — avec `[48, 12]` seuls les 3 premiers niveaux sont distincts.
+Le pop « perte de détail » (le plus visible) est retardé ; le pop « retour au détail » est
+immédiat. C'est la pratique standard des moteurs — et c'est testable en série de rayons
+oscillants autour d'un seuil.
+
+### D5 — Deux nouveaux petits buffers, layout des slots existants intact
+
+Les 4 composants de `TransformSlot.flags` sont tous occupés (x=mesh, y=active, z=count,
+w=has_index) — étendre le slot à 68 B ferait ripple dans tout le contrat documenté. À la place :
+- `lod_levels` : `array<u32>` par **slot** (256 × 4 B = 1 KB), re-uploadé chaque frame (comme
+  les transforms). Nouveau `@group(2) @binding(3)` du pass `cull`.
+- `lod_tables` : par **mesh** (80 B = count + pad + 4 lignes de 16 B), re-uploadé chaque frame
+  (mêmes motifs que le bbox buffer : petit, et le mapping mesh-index → tableau reste correct si
+  des meshes/niveaux sont ajoutés à chaud).
+
+`flags.z` (count plein) reste dans le slot (métadonne ; le GPU ne l'utilise plus pour la
+branche visible, qui passe par le tableau — voir D6).
+
+### D6 — Les deux branches visibles écrivent depuis le tableau LOD
+
+Dans `cull`, la branche « culling désactivé » et la branche « visible » remplacent
+`set_draw_count(i, flags.z)` par un helper `write_level_args(i, t)` : lire `lod_levels[i]`
+(clampé au count du mesh), indexer la ligne du mesh, écrire
+`.a = (count_ligne, 1, 0, baseVertex_ligne)` (indexé : `baseVertex = .a.w` ; non indexé :
+`firstVertex = .a.z`). Les branches zéro (slot ≥ num_slots, inactive) sont inchangées.
+Conséquence : un mesh **sans** LOD (1 niveau) a un tableau d'une seule ligne = count + offset 0
+→ comportement **bit-identique** à aujourd'hui.
+
+### D7 — Le pass d'ombre partage les draw args → il dessine le niveau sélectionné
+
+Le pass d'ombre lit le même buffer de draw args : les ombres utilisent **automatiquement** le
+niveau LOD (ombres moins chères, cohérent). Accepté pour v1 ; documenté. (Si un jour on veut
+des ombres au niveau fin, ce serait un deuxième buffer de draw args — hors périmètre.)
+
+### D8 — Niveaux ≤ 4, seuils `[48, 12]` px en `conf.rs` (v1)
+
+`MAX_LOD_LEVELS = 4`. Un mesh avec 1 seul niveau = LOD éteint pour lui (aucun changement de
+comportement). Les seuils par défaut sont des constantes (pas encore configurables par scene —
+extension triviale plus tard). Rayon projeté = le **même** rayon sphere que le culling
+(circonradius × max scale, centre transformé) → pas de nouvelle donnée géométrique.
+
+### D9 — Interrupteur global LOD au niveau du Renderer
+
+`Renderer::set_lod_enabled(bool)` (défaut `true`) — coupure générale, orthogonale au mode
+par mesh. Quand il est éteint, le calcul par entité est **court-circuité** (niveaux tous à
+0, aucune projection calculée) : tout se dessine au niveau 0, le GPU n'est pas touché
+(il lit simplement le niveau 0). Appelable à l'instanciation (juste après `Renderer::new`)
+ou **à chaud** (toggle de debug au runtime). Aucun changement de signature existante.
+
+### D10 — Niveaux **générés automatiquement** pour les géométries utilisateur
+
+L'utilisateur déclare sa géométrie comme aujourd'hui (`positions`/`indices`/`normals`/`uvs`,
+y compris générée procéduralement par lui) et la bibliothèque **calcule les niveaux LOD sous le
+capot**. Mécanisme : décimation gloutonne du maillage indexé —
 
 ```
-[CPU]     write_buffer TransformBuffer / CullUniforms / (BBoxBuffer si génération changée)
-[Compute 1] compute_matrices          [Compute 2] cull            (inchangés)
-[Ombre]    (si caster) draw indirect par slot, 1 pipeline          (inchangé — D6)
-[Main]     slots groupés par Material (D1/D2) :
-    groups = batch_slots(keys)
-    pour chaque groupe G :
-        set_pipeline(G) + set_bind_group(0) + set_bind_group(2, G) + set_bind_group(3)
-        pour chaque slot s de G :
-            set_bind_group(1, [offset(s)]) + set_vertex/set_index + draw_indirect(s)
-[Queue]   submit
+Geometry::decimated(&self, target_triangles: u32) -> Geometry   (pure, sans GPU)
+```
+- Triangles (non dégénérés) triés par aire croissante ; on retire le plus petit jusqu'à la
+  cible — **sans carte de topologie** (« Règle A ») : tout sous-ensemble de faces d'un mesh valide
+  est un mesh valide (pas de trou à boucher, pas de flip). La cible est donc toujours atteignable
+  (clamp `[1, T]`).
+- Sortie : re-indexation (weld par position exacte), **normales lisses recalculées** sur les faces
+  survivantes (normales de faces accumulées par coin soudé, puis normalisées), UVs/couleurs =
+  valeur du premier vertex de chaque groupe soudé (documenté : évite le bleeding entre seams UV ;
+  le LOD sacrifie la précision UV au profit de la silhouette).
+- Non indexé à l'entrée → weld par position préalable (la sortie est **toujours indexée**).
+  Triangles dégénérés jetés.
+- **Déterministe** (tri stable, tie-break par index d'origine) → counts reproductibles en tests.
+- Fallback : la cible est clampée à `[1, T]` — un mesh n'est jamais décimé sous un triangle, et
+  le count **réel** va dans le tableau LOD (`validate()` OK, jamais de géométrie corrompue).
+
+**L0 reste la géométrie exacte de l'utilisateur, byte-pour-byte** — seule la voie basse et les
+niveaux générés sont concernés par la simplification. Coût : setup uniquement (quelques ms pour
+des milliers de triangles), jamais par frame. Ratios par niveau : 0.5^k (50 %, 25 %, 12.5 %).
+
+`add_mesh_lod(id, level, geometry)` (niveaux explicites) est la voie **générale** : elle
+**remplace** un niveau existant ou **ajoute** le niveau libre suivant (≤ 4 ; même jeu
+**d'attributs** et même **indexation** que L0 — validé). Applicable à **tout** mesh, y compris
+Auto — ex. : remplacer un niveau décimé d'une primitive de la maison par une régénération à
+la tessellation divisée par 2 (plus propre que la décimation pour les meshes réguliers).
+`create_mesh_with_lod` est l'ergonomie qui génère les niveaux 1..n à la création ; les deux
+voies sont combinables.
+
+### D11 — Mode LOD par mesh (`Off` / `Auto` / `Manual`) — contrat pour les meshes updatables
+
+Le mesh porte un mode interne : `Off` (1 niveau = comportement d'aujourd'hui), `Auto` (niveaux
+décimés, D10), `Manual` (niveaux fournis, `add_mesh_lod`).
+
+Question posée : **un mesh updatable** (positions/normals réécrits par frame) — faut-il pouvoir
+désactiver le LOD au niveau mesh ? **Oui, et automatiquement** : les niveaux générés sont
+**dérivés de l'ancien L0** ; si la géométrie change, ils représentent une forme obsolète. Contrat
+réservé (pas d'API d'update dans v1, mais le design le prévoit) : toute future
+`mesh.update_geometry(…)` **réinitialise le mode à `Off`** (niveaux jetés, buffer packé reconstruit
+avec le seul nouveau L0, tableau à 1 ligne) — l'utilisateur n'a rien à désactiver : un mesh
+mis à jour par frame est simplement un mesh mono-niveau. Documenter cette règle quand l'API
+d'update existera.
+
+## Flux de données (changement en surgraisse)
+
+```
+CPU (chaque frame)                         GPU
+─────────────────────                      ───
+Transforms (slots)          ──upload──►   transforms
+CullUniforms (planes,…)     ──upload──►   cull_u
+BBoxes (par mesh)           ──upload──►   bboxes
+** LodLevels (par slot)     ──upload──►   lod_levels   (binding 3)
+** LodTables (par mesh)     ──upload──►   lod_tables   (binding 4)
+                                       │
+        compute_matrices (inchangé)    │
+        cull :  zéro si culled/inactive│
+                sinon write_level_args └──► draw_args
+                                       │
+        main pass (Étape 18 : groupé par material, set_vertex_buffer
+        du buffer packé par slot, draw indirect lit count+offset)
 ```
 
-## Gain attendu (changements d'état / frame, passe principale)
+## Niveaux dans le démo
 
-| Scène | Avant (par entité) | Après (par matériau distinct) |
-|---|---|---|
-| `demo` (7 entités, ~5 materials distincts) | 7 × (pipeline + @2) | 5 × (pipeline + @2) |
-| 200 cubes / 1 material | 200 × (pipeline + @2) | **1** × (pipeline + @2) |
+Le démo exerce l'**API utilisateur demandée** : géométrie L0 déclarée, niveaux générés sous le
+capot (D10). Les primitives de la maison sont des « géométries utilisateur » pour le LOD :
 
-Le `set_bind_group(1, offset dynamique)` et les vertex/index buffers restent par draw
-(paramètres de draw, pas d'état driver). Le gain est maximal quand peu de matériaux distincts
-pour beaucoup d'entités — le cas « instancé » en attendant le multi-instancing.
+| Mesh      | L0 (déclaré) | L1, L2 (auto : décimation 50 % / 25 %) |
+|-----------|--------------|-----------------------------------------|
+| sphere    | 32×20        | générés par `decimated`                  |
+| cylinder  | 32           | générés                                  |
+| cone      | 32           | générés                                  |
+| torus     | 24×16        | générés                                  |
+| icosphere | subdiv 2     | générés (triangles quasi uniformes → décimation propre) |
+| cube,plane| —            | `create_mesh` simple, 1 niveau           |
 
-## Fichiers touchés
+Setup du démo : `create_mesh_with_lod(id, geo, mat, 3)` pour les 5 meshes tessellés, `create_mesh`
+pour cube/plane. (Les niveaux « re-tessellés » du draft initial servent aux tests unitaires de
+l'issue de secours `add_mesh_lod`, pas au démo.)
 
-| Fichier | Action |
-|---------|--------|
-| `lib/src/core/renderer.rs` | `render_scene` : boucle plate → `batch_slots` + boucle par groupe ; fonction libre `batch_slots` + tests unitaires ; rustdoc du module alignée |
-| `docs/user/gpu-driven.md` | + note : draws groupés par matériau (interne, sans effet API) ; contrainte blending (D4) |
-| `docs/tech/ARCHI_CPU_GPU.md` | + note : la passe main émet les draws groupés par Material (Étape 18) |
-| `docs/ROADMAP.md` | Coche « Batching par Material » (4.3) + date |
+## API publique (ajouts — aucune rupture)
 
-## Périmètre exclus (reportés)
+```rust
+// Scene
+/// Crée un mesh dont les `levels` niveaux (2..=4) sont générés automatiquement
+/// par décimation (D10) de la géométrie fournie. L0 = la géométrie, exacte.
+pub fn create_mesh_with_lod(
+    &mut self, id: &str, geometry: Geometry, material: Option<&str>, levels: u8,
+) -> Result<String, String>;
 
-- **Multi-instancing** (1 draw par groupe mesh+material, matrice par instance) : demande un
-  changement de shader (matrice instanciée) + draw instancié par groupe — étape distincte,
-  plus lourde (déjà reportée depuis l'Étape 17).
-- **LOD, HDR + tone mapping** (items 2-3 de la Phase 4.3) : étapes distinctes.
-- **Sauter les no-ops par readback** (réduire les draw calls, pas seulement les états) : un
-  readback synchro stalle la boucle de rendu → rejeté en v1.
-- **Blending/transparent** : hors engine actuel (D4).
+/// Remplace (ou ajoute, si `level` est le niveau libre suivant) un niveau **explicite** du mesh
+/// `id` (≤ 4 niveaux ; même jeu d'attributs et même indexation que L0 ; pack total < 65 536
+/// vertices). Reconstruit les buffers packés (D2). Combinable avec `create_mesh_with_lod`.
+pub fn add_mesh_lod(&mut self, id: &str, level: u8, geometry: Geometry) -> Result<(), String>;
 
-## Risques & mitigations
+// Renderer
+/// Interrupteur global LOD (D9). Défaut `true`. `false` → tout se dessine au niveau 0,
+/// calcul par entité court-circuité. Appelable à l'instanciation ou à chaud.
+pub fn set_lod_enabled(&self, enabled: bool);
+```
 
-| Risque | Mitigation |
-|--------|-----------|
-| **Réordonnancement → rendu différent** | D4 : pipelines opaques (`REPLACE`) + depth write → le depth buffer résout l'ordre ; vérifié headless + visuellement (plan 4-5), draw args `debug_dump` inchangés (plan 6). |
-| **Pointeur-clé `Arc::as_ptr` en pend** | D1 : les `Arc` sont matérialisés dans un `Vec` vivant pendant la passe ; les groupes reconstruits chaque frame → aucune hypothèse de stabilité entre frames. |
-| **Groupage O(N) par frame** | N ≤ 256, `HashMap` ≤ 256 entrées → bruit ; pas de cache (D5 : toujours correct). |
-| **Ordre des groupes non déterministe** | D2 : première apparition sur des slots stables (Étape 17 D9) → déterministe ; verrouillé par test (D5). |
-| **Matériau transparent futur** | D4 documenté comme contrainte ; le groupage par Material reste correct, seule l'ordre inter-groupes devra évoluer. |
+`create_mesh` (sans LOD) reste la voie par défaut : un mesh simple se comporte exactement comme
+aujourd'hui. Le LOD s'active **explicitement** (`create_mesh_with_lod`) ou par niveaux explicites
+(`add_mesh_lod`) — pas de changement de comportement pour un utilisateur qui ne demande rien.
 
-## Plan de vérification
+## Plan de code
 
-1. `cargo build --workspace` — OK, sans avertissement.
-2. `cargo test --workspace` — vert, y compris les nouveaux tests `batch_slots` (première
-   apparition, ordre intra-groupe, chaque indice une fois, entrées vides, un seul groupe,
-   tout distinct).
-3. `cargo fmt --all -- --check` — clean.
-4. **`demo` headless** (`WGPU_BACKEND=vulkan timeout 10 ... --example demo`) → exit 0.
-5. **A/B changements d'état** : compteur temporaire de `set_pipeline` par frame (sous
-   `WSG_DEBUG_DUMP`) — avant : 7 dans le `demo` ; après : nombre de materials distincts.
-   (Compteur retiré après mesure, ou conservé sous `WSG_DEBUG_DUMP` au choix.)
-6. **Rendu identique** : `demo` avant/après → même image (opaque, D4) ; `debug_dump` :
-   draw args inchangés (le culling n'est pas touché).
-7. Check liens doc — 0 lien cassé.
+| Fichier | Changement |
+|---|---|
+| `resources/uniform.rs` | `LodTable` (80 B : `count` + 4 × `LodRow{base, count}` 16 B) + `LOD_TABLE_SIZE` ; export. |
+| `shaders/gpu_driven.wgsl` | structs `LodTable`/`LodRow` ; bindings 3+4 group(2) ; helper `write_level_args` ; `cull` : les 2 branches visibles l'appellent ; commentaire header mis à jour. |
+| `math/geometry.rs` | `Geometry::decimated(target) -> Geometry` (D10, pure) + tests ; `Geometry::generate_lod_levels(levels)` (ratios 0.5^k). |
+| `resources/mesh.rs` | champ `lod_geometries: Vec<Arc<Geometry>>` + `lod_mode` (D11) ; **packer** : concatène `to_vertices()` des niveaux → `vertex_buffer` packé ; indices rebasés concaténés → `index_buffer` packé ; `num_*` = niveau 0 ; `LodTable::from_geometry` par mesh. |
+| `scene/scene.rs` | `create_mesh_with_lod` + `add_mesh_lod` (validation + rebuild packé via le contexte GPU de la scene) ; `packed_lod_levels()` (par frame, par slot — décision D1) ; `mesh_lod_tables()` (par mesh, comme `mesh_bboxes`). |
+| `core/renderer.rs` | buffer `lod_levels_buffer` (1 KB) + `lod_table_buffer` ; layout group(2) +2 bindings ; upload par frame ; **D1** : `lod_levels: Vec<u32>` état par slot + fn pures `lod_level`/`projected_radius_px` (view + proj[1][1] + hauteur viewport, déjà disponibles) ; **D9** : champ `lod_enabled` + `set_lod_enabled` (court-circuit du calcul) ; `debug_dump` : readback du buffer de niveaux. |
+| `utils/conf.rs` | `MAX_LOD_LEVELS = 4` ; `LOD_THRESHOLDS: [f32; 2] = [48.0, 12.0]`. |
+| `examples/demo.rs` | `create_mesh_with_lod(id, geo, mat, 3)` pour les 5 meshes tessellés (D10) ; cube/plane en `create_mesh`. |
 
-## Critères d'acceptation (definition of done)
+### Fonction pure (testable, module `math` ou `resources::lod`)
 
-- [x] `render_scene` émet les draws **groupés par Material** (D1/D2) ; pass d'ombre inchangé (D6).
-- [x] `batch_slots` fonction pure testable (D5) + tests unitaires verts (6 tests, CI-safe).
-- [x] Aucune rupture d'API publique ; exemples non modifiés.
-- [x] Rendu identique (D4) — vérifié headless ; draw args `debug_dump` inchangés (6/36/3840/960/384/192/2304).
-- [x] Changements d'état réduits : compteur `set_pipeline` du `demo` = 3 = nb de materials distincts (avant : 7).
-- [x] Docs : `gpu-driven.md` § « Batching by material » + `ARCHI_CPU_GPU.md` + ROADMAP 4.3 coché.
+```rust
+/// Niveau cible : le plus grossier dont la borne est respectée, avec hystérésis asymétrique (D4).
+/// `thresholds[k]` = rayon px au-dessus duquel le niveau k+1 est exigé (descendants) ;
+/// niveaux au-delà du nb de seuils : borne clamped (dernier seuil).
+/// `last` = niveau de la frame précédente. Renvoie un niveau ≤ `max_level`.
+pub fn lod_level(radius_px: f32, last: u32, max_level: u32, thresholds: &[f32]) -> u32;
+
+/// Rayon projeté en pixels de la bounding sphere (même sphere que le culling, D8).
+/// `depth <= eps` (objet dans la caméra) → f32::INFINITY (niveau 0).
+pub fn projected_radius_px(center_world: Vec3, radius: f32, view: Mat4, proj: Mat4, height_px: f32) -> f32;
+
+/// Décimation gloutonne (D10, Règle A) : renvoie un `Geometry` indexé avec `target_triangles`
+/// triangles (clamp `[1, T]`) — les plus petits partent en premier (faible impact visuel),
+/// normales lisses recalculées. Déterministe.
+pub fn decimated(&self, target_triangles: u32) -> Geometry;   // sur Geometry
+```
+
+## Vérification
+
+1. **Unit tests `lod_level`** (sans GPU) : seuils simples (r > t0 → 0, entre → 1, < t1 → 2) ;
+   **anti-scintillement** : série de rayons oscillant ±10 % autour d'un seuil → le niveau reste
+   stable (montée immédiate, descente retardée par le facteur 0.8) ; clamp `max_level` ;
+   `INFINITY → 0`.
+2. **Unit tests `projected_radius_px`** : objet à l'origine, caméra sur Z → valeur analytique ;
+   invariance d'échelle (objets 10× plus gros 10× plus loin → même rayon px).
+3. **Unit tests du packer** : offsets/counts par niveau sur un cas 2 niveaux ; niveau 0 à
+   offset 0 ; indices rebasés.
+4. **Unit tests `decimated`** : grille 2×2 (4 triangles de tailles différentes) → cible 2 :
+   count exact, positions ⊆ entrée, les plus petits retirés en premier ; entrée non indexée →
+   sortie indexée weldée (coins dupliqués fondus, UV = premier rencontré) ; triangle dégénéré
+   en entrée → jeté ; **déterminisme** (deux appels → sortie identique) ; icosahèdre 20 → 10 :
+   count exact + bbox dans l'originale ; icosphere subdiv 1 → 50 % : count exact ; clamp : cible
+   0 ou > T → clone ; `validate()` OK.
+5. **GPU A/B** : entités temporaires à z = +6 / +30 / +60 (démo) → readback `debug_dump` :
+   niveaux 0 / 1 / 2 selon la distance et **draw args = count de la ligne du tableau
+   CPU-uploadé** (self-cohérent, pas de count codé en dur — les niveaux auto ont des counts
+   déterministes mais calculés) ; entité culled (hors frustum) → 0 quel que soit le niveau.
+6. **D9** : `set_lod_enabled(false)` au démarrage → draw args **bit-identiques** à l'exécutable
+   pré-LOD (tous niveaux 0) ; toggle à chaud → bascule visible au readback.
+7. **D11** (contrat) : `add_mesh_lod` s'applique à tout mesh (y compris Auto — le niveau
+   explicite remplace le niveau décimé au même index) ; le mode `Off` (1 niveau) = comportement
+   d'aujourd'hui ; un mesh updatable futur repasse en `Off` (D11).
+8. **Régression** : 69 tests verts ; démo silencieux par défaut ; batching (Étape 18) intact
+   (compteur de switches inchangé) ; mesh à 1 niveau → draw args **bit-identiques** à avant
+   l'étape (D6).
+9. **Visuel** : zoom arrière sur le démo → les primitives basses du ring passent au niveau
+   simplifié sans pop visible (silhouettes décimées proches + hystérésis D4).
+
+## Critères d'acceptation
+
+- [ ] `lod_level` + `projected_radius_px` pures, unit-testées (dont la série oscillante).
+- [ ] `decimated` pure, déterministe, unit-testée (counts, retire-les-plus-petits, weld + UV
+      premier rencontré, clamp `[1, T]`, dégénérés, `validate()` OK).
+- [ ] Packer multi-niveaux : un buffer packé, niveau 0 à offset 0, indices rebasés.
+- [ ] `create_mesh_with_lod` (niveaux auto) + `add_mesh_lod` (niveaux explicites, ≤ 4,
+      validation attributs/indexation/65536, combinables) ; aucune rupture d'API ;
+      `create_mesh` seul = comportement d'aujourd'hui.
+- [ ] `Renderer::set_lod_enabled` (D9) : `false` → bit-identique à pré-LOD ; toggle à chaud.
+- [ ] Pass `cull` : les 2 branches visibles écrivent depuis le tableau LOD ; mesh 1 niveau
+      bit-identique au comportement actuel.
+- [ ] A/B GPU : niveaux 0/1/2 choisis selon la distance, counts correspondants, culling intact.
+- [ ] 69+ tests verts, `cargo fmt` clean, démo silencieux par défaut.
+- [ ] Docs : `gpu-driven.md` (section LOD + contrainte buffers) ; `ARCHI_CPU_GPU.md` ; ROADMAP
+      4.3 coché.
 - [ ] DRAFT.md vidé après validation utilisateur (convention de la maison).
+
+## Hors périmètre (suivant)
+
+- **API d'update de géométrie** (mesh updatable par frame) — D11 réserve le contrat
+  (update ⇒ LOD réinitialisé à `Off`) mais l'API d'update elle-même est un autre sujet.
+- Décision du niveau **côté GPU** (viewProj dans CullUniforms + état GPU) — option D1 future.
+- Seuils **configurables par scene/mesh** (v1 : constantes `conf.rs`).
+- Réglage fin du **qualité/cout** de la décimation (poids par arête, quadric edge collapse)
+  — v1 : aire + flip, suffisant pour les silhouettes.
+- Geometric morphing / transitions douces entre niveaux (les pops restent discrets avec les
+  primitives procédurales ; le morphing est un sujet à part entière).
+- LOD de **shader** (simplification du lighting par distance) — autre item (HDR/tone mapping).
+- Ombres au niveau fin (D7 accepte le niveau LOD dans les ombres).