spec OKF pour doc

2026-07-31 19:10:04 +02:00
parent 2cc79be2ec
commit 8d61e4231e
10 changed files with 1608 additions and 0 deletions
@@ -0,0 +1,39 @@
+---
+type: Technical Specification
+title: Frame Loop Architecture
+description: Technical specification for the frame loop architecture in wsg_lib, detailing the immutable frame lifetime cycle and resource management
+tags: [architecture, rendering, frame-loop, gpu, wgpu]
+status: stable
+generated: { by: human:jerome, at: 2026-07-31T00:00:00Z }
+---
+
+# La Boucle de Rendu (Frame Loop)
+
+Pour afficher quelque chose, nous suivons un cycle immuable appelé la Frame Lifetime. Dans ton `main.rs` (l'orchestrateur), le flux est désormais le suivant :
+
+- **Context::begin_frame() :** Acquiert la surface texture et crée la TextureView.
+- **Renderer::render(...)** : Utilise le CommandEncoder pour écrire les ordres de dessin.
+- **Context::end_frame()** : Soumet les commandes à la file (`queue`) et présente l'image.
+
+---
+
+## Pourquoi cette séparation est vitale
+
+Le bloc `{ let mut render_pass = ... }` est crucial. Dans Rust, `render_pass` emprunte mutablement `encoder`. Il doit être détruit (via la fin du bloc ou un `drop()`) avant que tu puisses appeler `encoder.finish()`. Si tu oublies cela, le compilateur Rust refusera de compiler, empêchant ainsi des bugs critiques de synchronisation GPU.
+
+---
+
+## Ressources : Persistantes vs Par-Frame
+
+Avec notre nouvelle architecture "Atelier", la distinction est devenue encore plus nette :
+
+| Élément | Durée de vie | Pourquoi ? |
+|---------|-------------|------------|
+| SurfaceConfiguration | Persistante | Ne change qu'au redimensionnement. |
+| RenderPipeline | Persistante | Stocké dans le PipelineCache (`Arc`), compilation unique. |
+| Material | Persistante | Définit le look ; partage le pipeline via `Arc`. |
+| Mesh | Persistante | Les données géométriques sont envoyées une fois au GPU. |
+| CommandEncoder | Par-Frame | Ton "carnet de notes" temporaire pour les ordres du GPU. |
+| TextureView | Par-Frame | Fenêtre temporaire sur la texture active du swapchain. |
+
+---