doc

docs/tech/FRAME_LOOP.md

@@ -14,12 +14,25 @@ stale_after: 2027-01-31
 # La Boucle de Rendu (Frame Loop)
 
 > **État du document : ACTUEL (implémenté).** Ce document décrit la frame lifetime telle qu'elle est
-> réellement implémentée. Il concerne le rendu **CPU-piloté actuel** (objet par objet, exemple `manual`).
-> Le pipeline GPU-driven de l'état **visé** est décrit dans ARCHI_APP.md / ARCHI_CPU_GPU.md (cible).
+> réellement implémentée. **Deux flux coexistent** : le flux **facade `App`** (rendu automatique de la
+> scène, `App::render_scene` — le workflow recommandé, exemples `simple`/`cube`/`demo`) et le flux
+> **manuel** (`Context`/`Renderer`/`Frame` pilotés à la main — exemple `manual`, un objet par soumission).
+> Le pipeline **GPU-driven** (compute pass + draw indirect) de l'état **visé** est décrit dans
+> [ARCHI_APP](ARCHI_APP.md) / [ARCHI_CPU_GPU](ARCHI_CPU_GPU.md) (cible).
 
-Pour afficher quelque chose, nous suivons un cycle immuable appelé la Frame Lifetime. Deux flux coexistent, tous deux basés sur `Frame` :
+Pour afficher quelque chose, nous suivons un cycle immuable appelé la Frame Lifetime, basé sur `Frame` :
 
-**Flux `Frame` (utilisé par `App::run` et l'exemple `manual`) :**
+**Flux facade `App` (recommandé — `App::run` + `AppHandler`) :**
+- **`Context::get_next_frame()`** : acquiert la surface texture et crée sa `TextureView` (dans `Frame`).
+- **`AppHandler::render` (défaut) → `App::render_scene(view)`** : le moteur itère les entités de la
+  scène et les dessine en **une passe groupée** (un `CommandEncoder` + une soumission par frame ;
+  passe d'ombre en tête si un caster est actif).
+- **`Renderer::present(frame)`** : présente l'image à l'écran.
+- Chaque frame, avant `update`, le moteur appelle `device.poll()` (les callbacks asynchrones wgpu —
+  `on_submitted_work_done`, `map_async` — ne se déclenchent que lors d'un poll), et la fenêtre
+  redimensionnée est gérée par `App::resize` (surface + depth texture recréées ensemble).
+
+**Flux `manual` (exemple `manual` — un objet par soumission) :**
 - **`Context::get_next_frame()`** (ou `Frame::try_new(&context.surface)`) : acquiert la surface texture et crée sa `TextureView` (dans `Frame`).
 - **`Renderer::render(&view, &mesh, &material)`** : crée un `CommandEncoder`, écrit les ordres de dessin dans la `TextureView`, puis soumet à la file (`queue`).
 - **`Renderer::present(frame)`** : présente l'image à l'écran.
@@ -28,6 +41,12 @@ Pour afficher quelque chose, nous suivons un cycle immuable appelé la Frame Lif
 - **`Context::begin_frame()`** : acquiert la surface et renvoie la `wgpu::SurfaceTexture` (sans vue).
 - **`Context::end_frame(surface_texture)`** : soumet et présente cette texture.
 
+## Liens
+
+- [ARCHI_APP](ARCHI_APP.md) · [ARCHI_RENDU](ARCHI_RENDU.md) · [ARCHI_CPU_GPU](ARCHI_CPU_GPU.md) · [ARCHI_ARENES](ARCHI_ARENES.md)
+- Documentation utilisateur : [docs/user](../user/README.md) · [README racine](../../README.md) · [ROADMAP](../ROADMAP.md)
+- Référence API : `cargo doc -p wsg-lib --no-deps`
+
 ---
 
 ## Pourquoi cette séparation est vitale