wsg/docs/tech/FRAME_LOOP.md

type, title, description, tags, actor, sources, generated, verified, status, stale_after

type	title	description	tags	actor	sources	generated	verified	status	stale_after
Technical Specification	Frame Loop Architecture	Technical specification for the frame loop architecture in wsg_lib, detailing the immutable frame lifetime cycle and resource management	architecture rendering frame-loop gpu wgpu	person/jerome		by at human:jerome 2026-07-31T00:00:00Z	true	current	2027-01-31

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.

Ressources GPU persistantes (single buffer) : Les buffers Transform et Matrix sont stockés en VRAM avec un single buffer en phase initiale. Le CPU écrit pendant update(), le compute shader lit au frame suivant via la séquence garantie par queue.submit(). Double buffering sera ajouté uniquement si des artefacts visuels apparaissent à haute fréquence.

---