wsg/docs/ROADMAP.md

type, title, description, tags, status, generated

type	title	description	tags	status	generated
Roadmap	WSG Engine Development Roadmap	Development roadmap for the WSG engine from prototype to full-featured 3D rendering engine	roadmap development planning wsg-lib 3d-rendering	stable	by at human:jerome 2026-07-31T00:00:00Z

Roadmap WSG — Prototype → Moteur Complet

Basé sur l'architecture existante (ARCHI_APP, ARCHI_ARENES, ARCHI_CPU_GPU, ARCHI_RENDU). Objectif : prototype fonctionnel d'abord, enrichissement progressif ensuite.

Point de départ (état réel au 2026-09-14 — la source de vérité est README.md). Les fondations suivantes existent et fonctionnent déjà ; cette roadmap décrit la trajectoire à venir à partir de cet état (elle reprend les étapes 1-4 du README avant la montée GPU-driven) :

• Workflow manuel (Context + Renderer + PipelineCache) : ✅ fonctionnel (exemple manual).
• Façade App / AppBuilder / AppHandler : 🚧 scaffold — boucle et présentation OK, mais render() ne peut pas encore dessiner (vue de frame non exposée) et le rendu de la scène n'est pas automatisé.
• Scene avec identifiants String (décision prise — voir tableau Notes de Décision) : 🚧 enregistrement seul.
• Camera / Transform et glam : types et mathématiques présents (math/, resources/camera.rs), non branchés au pipeline.

---

Phase 1️⃣ — Prototype MVP : Un Mesh 3D éclairé à l'écran

Objectif : Afficher un cube (ou autre mesh) 3D avec un éclairage Phong basique.

1.1 Dépendances & Mathématiques

• glam = "0.33" ajouté (lib/Cargo.toml) — déjà présent, utilisé par math/transform.rs et resources/camera.rs
• slotmap retiré — décision prise : String IDs pour le MVP ; slotmap reporté à l'étape "handles typés" (voir Notes de Décision)
• Créer module math/ (ou transform.rs) :
  • Struct Transform { translation: Vec3, rotation: Quat, scale: Vec3 }
  • Méthode to_matrix() -> Mat4 pour calculer la matrice locale
  • Struct Camera { position: Vec3, target: Vec3, up: Vec3 } : resources/camera.rs
  • Fonctions view_matrix() et projection_matrix(fov, aspect, near, far)

1.2 Geometry & Mesh

• Créer struct Geometry (math/geometry.rs) :
  • positions: Vec<[f32; 3]> (obligatoire)
  • indices: Option<Vec<u16>> (optionnel)
  • normals: Option<Vec<[f32; 3]>> (pour Phong)
• Refactorer Mesh pour contenir :
  • geometry: Arc<Geometry>
  • vertex_buffer: wgpu::Buffer
  • index_buffer: Option<wgpu::Buffer>
  • transform: Transform (état CPU)
• Ajouter un mesh de test (cube unitaire) en exemple

1.3 Shader Phong Minimal

• Créer standard_shader.wgsl :
  • Vertex shader : projection * view * world * position
  • Fragment shader : éclairage hémisphérique + diffuse avec une lumière directionnelle
  • Uniforms : view_matrix, proj_matrix, world_matrix, light_dir, light_color
• Mettre à jour Material pour supporter les uniforms du shader Phong

1.4 Scene avec identifiants (MVP : String IDs)

• Scene implémentée avec String IDs (HashMap<String, Arc<Mesh>>, ...Material, entités) — état actuel validé ; décision : rester en String IDs pour le MVP
• Méthodes : add_mesh(), get_mesh(), add_material(), add_entity(), iter_entities(), remove_entity()
• Reporté (étape "Handles typés") : migrer vers slotmap générationnel (MeshId/MaterialId) quand l'éviction/les performances le justifieront

1.5 Rendu du Prototype

• Uniform buffer pour la frame : view_matrix, proj_matrix, light_dir
• Uniform buffer par mesh : world_matrix (calculée sur CPU pour le MVP)
• Renderer::render() itère sur les meshes de la Scene et dessine chacun
• Exemple fonctionnel : un cube éclairé tourne à l'écran

---

Phase 2️⃣ — Système de Ressources complet

Objectif : Étoffer la Scene avec tous les types de ressources.

2.1 Arènes complètes

• SlotMap<MaterialId, Material>
• SlotMap<TextureId, Texture> (struct de base)
• SlotMap<LightId, Light> (struct de base)
• SlotMap<EntityId, Entity> pour les entités de la scène

2.2 Entités & Hiérarchie

• Struct Entity { mesh_id: Option<MeshId>, material_id: Option<MaterialId>, transform: Transform }
• Scene::add_entity() → retourne EntityId
• Scene::iter_entities() → pour le render loop

2.3 Camera dans la Scene

• Intégrer Camera comme ressource de la Scene
• Permettre plusieurs caméras (actuelle/inactive)
• Exposer API : scene.set_active_camera(camera_id)

---

Phase 3️⃣ — GPU-Driven Rendering

Objectif : Déléguer les calculs de transformation et culling au GPU (suivre ARCHI_CPU_GPU.md).

3.1 Compute Shader

• Buffer TransformBuffer (CPU → GPU) : positions/rotations/échelles brutes
• Buffer MatrixBuffer (GPU calculé) : World Matrices finales
• Compute shader : calcul des World Matrices pour tous les meshes

3.2 Frustum Culling GPU

• Ajouter BBox dans Geometry (center + extents)
• Buffer BoundingBoxBuffer (CPU → GPU, statique)
• Compute shader : culling basé sur la frustum de caméra
• Buffer IndirectDrawBuffer rempli par le GPU

3.3 Rendu Indirect

• draw_indexed_indirect() au lieu de draw calls individuels
• Un seul command draw pour tous les objets visibles

---

Phase 4️⃣ — Fonctionnalités Avancées

Objectif : Qualité visuelle et performances.

4.1 Textures

• Struct Texture avec chargement d'image
• Ajouter uvs: Option<Vec<[f32; 2]>> dans Geometry
• BindGroup pour les textures dans le shader
• Material supporte une texture diffuse

4.2 Éclairage avancé

• Support multi-lumières (directionnelles, ponctuelles)
• Lumières hémisphériques
• Shadows (optionnel)

4.3 Optimisations

• Batching par Material (réduction des state changes GPU)
• Level of Detail (LOD)
• HDR + Tone Mapping (optionnel)

---

Phase 5️⃣ — Documentation & Polish

• Exemple complet : mesh texturé, éclairé, avec caméra orbitale
• Documentation API (docs/ARCHI_SCENE.md)
• Tests unitaires : Geometry, Scene, Transform
• README mis à jour avec les nouvelles fonctionnalités

---

Notes de Décision

Décision	Raison
Normals dès Phase 1	Nécessaires pour le shader Phong ; sans elles, pas d'éclairage
UVs en Phase 4	Inutiles avant les textures ; on garde Geometry simple au départ
BBox en Phase 3	Utile uniquement pour le frustum culling GPU
World Matrix CPU → MVP, GPU → Phase 3	Le MVP est plus simple avec un uniform par mesh ; la migration GPU-driven est progressive
String IDs pour le MVP, slotmap reporté	Le code et le README utilisent des String IDs (simples, sûrs, figés avant la boucle de rendu) ; ARCHI_ARENES.md reste la cible "handles typés" pour plus tard. La dépendance slotmap a été retirée tant qu'elle est inutilisée
Present mode FIFO figé pour l'instant	Le swapchain utilise PresentMode::Fifo avec desired_maximum_frame_latency: 2 (double buffering vsync) — défaut sûr : pas de tearing, énergie minimale, zéro artefact. On gèle ce choix ; Mailbox (triple buffering) pourra être exposé en option et Immediate restera réservé à l'offscreen, on s'occupera du present mode le moment venu (quand le pipeline GPU-driven arrivera, Phase 3) — ce n'est pas bloquant pour les étapes 1-2