From 3414d68819adb20bced5c9f287499717ffb0bfae Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Bousqui=C3=A9?= Date: Wed, 8 Jul 2026 15:58:20 +0200 Subject: [PATCH] Plan --- README.md | 89 ++++++++++++++++++++++++++++++++++++----- docs/PLAN.md | 67 +++++++++++++++++++++++++++++++ docs/SCHEMA.md | 23 ----------- lib/src/scene/README.md | 4 +- 4 files changed, 148 insertions(+), 35 deletions(-) create mode 100644 docs/PLAN.md delete mode 100644 docs/SCHEMA.md diff --git a/README.md b/README.md index c0f543b..82e1705 100644 --- a/README.md +++ b/README.md @@ -1,16 +1,83 @@ # WSG - WGPU Simple Graphics Library -A simple WGPU wrapper to expose basic objects for drawing and manipulation: Meshes, Vertices, Indexes, UVs +WSG is a Rust library that wraps [wgpu](https://github.com/gfx-rs/wgpu) to provide a simple, declarative API for 3D graphics. It abstracts away the complexity of managing GPU resources while exposing low-level primitives for advanced users. -| Component | Ownership | Role | -|-----------|-----------|------| -| Instance | wgpu | The entry point. It manages connections with graphics drivers (Vulkan, Metal, DX12). | -| Surface | wgpu | The link between wgpu and your window (winit). This is where rendering is displayed. | -| Adapter | wgpu | Represents your GPU (physical or software). | -| Device | wgpu | The engine's core. It creates buffers, textures, and pipelines. | -| Queue | wgpu | The queue. You send drawing commands for execution. | -| Context | Our Lib | A logical container. wgpu doesn't have a "Context" object; we create it to group these disparate objects and simplify your user API. | +## What it does -Context (Lib) : Initializes the GPU, creates the surface, and holds the Device and Queue. It is static (created once at startup). +WSG provides two complementary workflows: -Renderer (Lib) : Uses the Device to create pipelines, manages your 500,000 vertices, and uses the Queue to send rendering instructions each frame. It is dynamic (it changes depending on what you want to display). +### Declarative workflow (recommended) + +Register your scene's resources and entities before the render loop starts, then iterate them each frame: + +```rust +use wsg_lib::{App, AppHandler}; +use wsg_lib::resources::{Mesh, Material, Vertex}; + +struct MyGame { /* ... */ } + +impl AppHandler for MyGame { + fn render(&mut self, app: &mut App) { + // Draw every entity registered in app.scene + for (_, mesh, material) in app.scene.iter_entities() { + app.renderer.render(app.context.get_next_frame().view(), mesh, material); + } + } +} + +#[pollster::main] +async fn main() -> Result<(), wsg_lib::utils::WsgError> { + let mut app = AppBuilder::new().build().await?; + + // Declare resources + app.cache.register_shader("basic", "assets/shaders/basic_shader.wgsl")?; + let vertices: [Vertex; 4] = [/* ... */]; + let indices: [u16; 6] = [0, 1, 2, 0, 2, 3]; + let mesh = Mesh::new(app.context.device(), &vertices, Some(&indices)); + let material = Material::new(app.renderer.format(), "basic", &mut app.cache); + + app.scene.add_mesh("quad", Arc::new(mesh))?; + app.scene.add_material("mat", Arc::new(material))?; + app.scene.add_entity("my_quad", "quad", "mat")?; + + // Run the render loop + app.run(MyGame {}) +} +``` + +### Manual workflow + +For fine-grained control, bypass the Scene facade entirely and manipulate Context, Renderer, and PipelineCache directly through their public APIs. + +## Architecture overview + +WSG follows a two-layer architecture: + +- **Manager layer (Context)** — owns GPU hardware lifecycle (Instance → Surface → Adapter → Device → Queue). Created once at startup. +- **Executor layer (Renderer)** — orchestrates draw calls per frame by binding Materials + Meshes into RenderPasses. Dynamic, changes each frame. + +The high-level `App` facade ties everything together, automating window lifecycle, event processing, and frame presentation. Users implement the `AppHandler` trait to inject game logic. + +## Quick reference + +| Concept | Type | Responsibility | +|---------|------|---------------| +| App | Facade | Window lifecycle + event loop + render automation | +| AppHandler | Trait | User-defined update/render callbacks | +| Scene | Struct | Resource depot + entity graph (declarative) | +| Context | Struct | GPU hardware lifecycle (Manager) | +| Renderer | Struct | Draw call orchestration (Executor) | +| Material | Struct | Shader ID → compiled RenderPipeline | +| Mesh | Struct | Persistent GPU geometry container | +| Vertex | Struct | CPU-side vertex attribute tuple | +| PipelineCache | Struct | Shader compilation cache | +| Frame | Struct | Per-frame RAII wrapper for surface texture + view | + +## Getting started + +```bash +cargo add wsg-lib # Add the dependency +# Then build your app following the declarative example above +``` + +For details on the architecture and internal modules, see [ARCHI_APP](docs/ARCHI_APP.md). diff --git a/docs/PLAN.md b/docs/PLAN.md new file mode 100644 index 0000000..5abea13 --- /dev/null +++ b/docs/PLAN.md @@ -0,0 +1,67 @@ +# Plan d'Implémentation : Consolidation et Finalisation du Moteur wsg_lib + +Ce plan définit les étapes prioritaires pour stabiliser l'architecture actuelle. L'objectif est de rendre l'API intuitive pour l'utilisateur standard tout en conservant la puissance de contrôle pour l'utilisateur avancé. + +## Phase 1 : Finalisation et Nettoyage de l'Existant (Priorité Absolue) + +Cette phase vise à supprimer la dette technique et à unifier les accès. + +### Uniformisation des Modules + +- Vérifier que tous les traits (`AppHandler`) et structures (`App`, `Context`) sont explicitement marqués `pub` dans leurs fichiers sources. +- Ré-exporter l'API dans `lib.rs` pour permettre des imports simplifiés (ex : `use wsg_lib::{App, AppHandler}`). +- Nettoyer les accès internes pour que l'utilisateur n'ait pas à importer les modules système (`core`, `pipeline`) sauf besoin spécifique. + +### Abstraction de la Boucle (`App::run`) + +- Déplacer la gestion de `winit::event_loop` et des `Frame` à l'intérieur de la méthode `run()` de `App`. +- Garantir que le trait `AppHandler` reçoit une référence à `App` permettant d'appeler `app.renderer` ou `app.scene`. +- Supprimer toute gestion de `Frame` ou `EventLoop` manuelle des exemples utilisateurs (`simple.rs`). + +### Correction du Builder et Initialisation + +- Standardiser la création de `App` via un `AppBuilder` robuste. +- Gérer les `dev-dependencies` dans `lib/Cargo.toml` (notamment `pollster` avec la feature `macro`) pour permettre la compilation des exemples sans polluer les dépendances finales de la librairie. + +## Phase 2 : Structure de Rendu et Scène + +Une fois la plomberie encapsulée, nous devons rendre l'assemblage des objets cohérent. + +### Intégration de la Scene + +- Formaliser la structure `Scene` : un conteneur qui liste les Entities. +- Associer le `PipelineCache` à la Scene pour que le rendu des matériaux soit automatique. +- Implémenter la logique `app.render(scene)` : cette méthode doit parcourir la scène, récupérer les matériaux, gérer les pipelines via le cache, et soumettre les draw calls. + +### Gestion des Matériaux et Shaders + +- S'assurer que chaque Mesh possède une référence vers un Material. +- Implémenter le comportement par défaut : si aucun matériau n'est assigné, le moteur injecte automatiquement le `basic_shader`. + +## Phase 3 : Documentation et Interface (API "User-Friendly") + +### Refonte des Exemples + +- `simple.rs` doit devenir le modèle : **15 lignes** de code, pas de manipulation WGPU explicite. +- `manual.rs` doit rester disponible en tant que tutoriel pour ceux qui veulent contourner l'abstraction App. + +### Nettoyage du Code Interne + +- Vérifier les durées de vie (lifetimes) et les Arc pour s'assurer qu'aucune fuite mémoire ou accès concurrentiel invalide ne survient lors des changements de frame. + +## Phase 4 : Nouvelles Fonctionnalités (Planification Future) + +Une fois les phases 1 à 3 validées, nous pourrons introduire : + +- **Système de Lumières** : Ajout de buffers d'uniformes dans le PipelineCache. +- **Textures** : Intégration d'un module de chargement d'images et de BindGroups. +- **Caméras** : Gestion des matrices de projection/vue dans la Scene. + +## Check-list de Vérification pour le LLM d'Assistance + +- [ ] Est-ce que `simple.rs` compile sans importer `winit` ou `wgpu` ? +- [ ] Est-ce que `App::run` gère bien le cycle update → render → present ? +- [ ] Les modules sont-ils bien exposés via `lib.rs` ? +- [ ] `pollster` est-il uniquement en dev-dependencies ? + +Ce plan garantit que les fondations sont saines. Une fois la Scene rendue automatiquement par `app.render()`, l'ajout de toute nouvelle fonctionnalité (lumières, textures) deviendra une simple question d'ajout de données dans la structure de scène, sans modification de la boucle de rendu. diff --git a/docs/SCHEMA.md b/docs/SCHEMA.md deleted file mode 100644 index 34d1f6c..0000000 --- a/docs/SCHEMA.md +++ /dev/null @@ -1,23 +0,0 @@ -[ INITIALISATION ] - | - +---> Context (Manager) - | | - | +---> Renderer (Spécialiste) - | | - +---> PipelineCache (Bibliothèque) - | - +---> Material - | - +---> Mesh - -[ BOUCLE DE RENDU (Frame Loop) ] - | - +---> Frame (Acquisition) - | - +---> Renderer (Orchestrateur) - | | - | +--[Rendu]--> CommandEncoder - | - +---> Context (Présentation) - | - +--[Submit]--> Queue diff --git a/lib/src/scene/README.md b/lib/src/scene/README.md index 30c8f8d..b8149fe 100644 --- a/lib/src/scene/README.md +++ b/lib/src/scene/README.md @@ -4,6 +4,8 @@ The `scene` module defines Scene, the declarative layer of the WSG architecture. Users register resources (Meshes, Materials) by identifier before the render loop starts, then associate entities via labels. At runtime, Scene provides immutable access to these resources without exposing raw wgpu handles. +## Files + | File | Responsibility | |------|---------------| | **scene** | Scene struct — resource depot storing Meshes and Materials keyed by string identifiers, plus entity graph mapping labels to (mesh_id, material_id) pairs for rendering iteration. | @@ -17,4 +19,4 @@ The `scene` module defines Scene, the declarative layer of the WSG architecture. ## Architecture Note -Per ARCHI_APP_FACADE.md, Scene is one half of the "App" facade pattern. It enables a declarative workflow where all resources are declared before the render loop begins, while keeping the freedom to build the engine "brick by brick" through direct Context/PipelineCache/Renderer manipulation. +Per [ARCHI_APP](../../docs/ARCHI_APP.md), Scene is one half of the "App" facade pattern. It enables a declarative workflow where all resources are declared before the render loop begins, while keeping the freedom to build the engine "brick by brick" through direct Context/PipelineCache/Renderer manipulation.