wsg/docs/DRAFT.md

DRAFT — Étape 11 : Gestion du Resize (cycle de vie Surface + Depth)

📅 2026-09-18 — Plan de l'étape suivante. Source de vérité = code + README.md. Ce document est vidé à la complétion de l'étape. Références : ROADMAP Phase 4.4 · PLAN Phase 4 · décision D3 (2026-09-18).

---

Contexte

L'application ne gère aucun resize aujourd'hui : la surface est configurée une seule fois, au démarrage, dans AppRunner::resumed (context.configure(&adapter, width, height)), et la depth texture est allouée une seule fois, à la taille initiale, dans Renderer::new (Étape 9). Quand l'utilisateur redimensionne la fenêtre :

• la surface reste configurée à l'ancienne taille → get_current_texture() retourne Suboptimal/Outdated, le rendu est cassé ou artefacté ;
• la depth texture reste à l'ancienne taille → les attachments color/depth n'ont plus la même taille → erreur de validation wgpu (tailles des attachments divergentes).

Le helper isolé create_depth_texture(device, width, height) (Étape 9, D3) rend le recreate de la depth texture trivial. C'est le chantier dédié planifié en Phase 4.4, hors périmètre de l'Étape 9.

Objectif

Rendre le moteur robuste au redimensionnement de la fenêtre : à chaque WindowEvent::Resized, reconfigurer la surface et recréer la depth texture à la nouvelle taille, en gardant la scène et les pipelines valides.

Critère d'acceptation : redimensionner la fenêtre (agrandir, rétrécir) ne produit ni crash, ni artefact, ni erreur de validation wgpu ; le rendu se met à jour à la nouvelle taille ; le rapport hauteur/largeur (aspect) de la projection suit la fenêtre en continu.

Périmètre

Inclus

• Handler WindowEvent::Resized dans AppRunner::window_event (lib/src/app.rs).
• Reconfiguration de la surface (Context::configure) à la nouvelle taille.
• Recréation de la depth texture (Renderer::resize_depth).
• Garde contre les tailles invalides (0).
• Mise à jour du format de surface et re-synchronisation Renderer ↔ Scene si nécessaire.

Hors périmètre

• Le present mode (FIFO figé — voir Notes de Décision ROADMAP).
• Le culling/rendu GPU-driven (Phase 3).
• La LOD / batching / HDR (Phase 4.3).
• Toute modification du shader ou des bind groups.

Décisions

Id	Décision	Raison
D1	Le resize est encapsulé dans une méthode App::resize(&mut self, w, h) appelée par AppRunner::window_event	La logique reste testable et réutilisable, distincte de la couche winit ; window_event reste fine (dispatch uniquement).
D2	La depth texture est recréée via Renderer::resize_depth(w, h), qui réutilise le helper create_depth_texture existant	Cohérent avec l'Étape 9 (D3) ; le helper isolé existe déjà et est prêt.
D3	Garde if w == 0 || h == 0 { return; } : on ne reconfigure jamais à une taille nulle (fenêtre minimisée)	Resized(0x0) arrive au minimize ; configurer une surface 0×0 est une erreur wgpu.
D4	Le format de surface est comparé avant/après configure : s'il change, on re-synchronise Renderer et Scene ; dans le cas normal (stable sRGB) on se contente du swap surface+depth	Le format est déterministe pour une même fenêtre (premier sRGB) ; le cas « format changé » est rare mais documenté et structuré.
D5	L'aspect de projection reste dérivé en continu de window().inner_size() dans App::render_scene (déjà le cas) — pas de champ de taille « stale » à maintenir	Évite un état redondant : la source de vérité du rendu est la taille live de la fenêtre. Les champs App.width/height ne servent qu'à l'init.
D6	Pendant une taille invalide (0), on ne rend pas la frame (garde dans RedrawRequested)	Évite un get_next_frame()/rendu sur une surface de taille nulle.

Tâches détaillées

11.1 App::resize (orchestration du resize)

• Ajouter une méthode resize(&mut self, width: u32, height: u32) -> Result<(), WsgError> sur App (lib/src/app.rs) :
  • Récupérer self.context (Option) → ok/err si absent.
  • let new_format = self.context().configure(&self.context().adapter, width, height)?; (reconfigure la surface à la nouvelle taille ; renvoie le format choisi).
  • self.renderer_mut().resize_depth(width, height); (recrée depth à la nouvelle taille).
  • Synchroniser le format : mettre à jour Renderer::format (via un setter, cf. 11.2) et, si new_format != format_anterieur, re-synchroniser la Scene (cf. D4).
  • Retourner Ok(()).
• Gérer l'erreur : si configure échoue, propager WsgError sans crash silencieux.

11.2 Renderer::resize_depth (+ synchronisation du format)

• Ajouter resize_depth(&mut self, width: u32, height: u32) sur Renderer (lib/src/core/renderer.rs) :
  • let (t, v) = create_depth_texture(&self.device, width, height);
  • Remplacer self._depth_texture = t; self.depth_view = v; (l'ancienne texture est dropée par le remplacement — pas de fuite, pas de double allocation).
• (Optionnel, D4) Ajouter un accès pour mettre à jour Renderer::format si le format change ; le champ format est actuellement wgpu::TextureFormat non-mutable depuis l'extérieur.
• Vérifier que create_depth_texture reste privé au module (pas d'exposition publique).

11.3 Handler WindowEvent::Resized dans AppRunner::window_event

• Dans le match event de window_event (lib/src/app.rs), ajouter :
  • WindowEvent::Resized(size):
    • let w = size.width as u32; let h = size.height as u32;
    • if w == 0 || h == 0 { return; } (D3).
    • if let Err(e) = app.resize(w, h) { /* log/propager ; ne pas paniquer */ }
    • app.window().request_redraw(); pour rendre immédiatement la nouvelle taille.
• (D6) Dans WindowEvent::RedrawRequested, gardez la garde : si la taille courante de la fenêtre est 0, sauter get_next_frame()/render/present pour cette frame.

11.4 Synchronisation du format Renderer ↔ Scene (D4)

• Après configure, comparer new_format avec le format en cours :
  • Cas normal (identique) : rien à faire, le swap surface+depth suffit.
  • Cas format changé : re-initialiser le GPU de la Scene (Scene::init_gpu(device, queue, new_format)) et documenter que les pipelines doivent être revalids — pour le MVP, lever une erreur explicite (le format est stable pour une même fenêtre ; ce chemin est structuré mais pas exercé couramment).
• S'assurer que Renderer::format et Scene (via SceneGpu) portent le même format.

11.5 Exemple / vérification manuelle

• Aucun exemple ne doit changer de code (le resize est transparent).
• Vérification manuelle : lancer cube (ou simple), redimensionner la fenêtre (agrandir + rétrécir), confirmer : pas de crash, pas d'artefact, rendu correct à la nouvelle taille, aspect correct (pas de distorsion de la projection).

Fichiers touchés

Fichier	Changement
lib/src/app.rs	App::resize (nouveau) ; window_event : branchement Resized + garde 0 dans RedrawRequested.
lib/src/core/renderer.rs	Renderer::resize_depth (nouveau) ; éventuellement setter du format (D4).
lib/src/core/context.rs	Aucun — configure existe déjà et reconfigure à une taille donnée.
lib/src/scene/scene.rs	Aucun en cas normal ; seul le chemin format-changé (D4) toucherait init_gpu.

create_depth_texture (helper) et Context::configure existent déjà — réutilisés, pas créés.

Check-list de vérification

• Redimensionner la fenêtre n'émet aucune erreur de validation wgpu (attachments color/depth de même taille).
• La surface est reconfigurée à la taille réelle de la fenêtre (Context::configure).
• La depth texture est recréée à la taille réelle (Renderer::resize_depth).
• Pas de crash au minimize (garde w==0 || h==0, D3) ni au restore.
• L'aspect de la projection suit la fenêtre (pas de distorsion au redimensionnement).
• Le format Renderer == format Scene (synchronisation D4).
• cargo build --workspace et cargo test --workspace passent ; exemples cube/simple compiles sans changement.
• Pas de fuite : l'ancienne depth texture est bien dropée au remplacement.

Risques & notes

• Minimize/restore : Resized(0x0) puis Resized(n,m) — la garde D3 + la reconfiguration au restore couvrent le cycle complet.
• Format changé : pathologique pour une même fenêtre (le choix est déterministe). Structuré mais non exercé couramment (D4) ; si jamais un backend change de format, le MVP lève une erreur claire plutôt que de produire un rendu corrompu.
• Présence du adapter : configure nécessite &adapter — Context porte déjà adapter (utilisé dans resumed), donc accessible sans nouvelle API.