Jérôme Bousquié
83 lines
3.5 KiB
Markdown
83 lines
3.5 KiB
Markdown
# Architecture du Moteur wsg_lib
|
|
|
|
wsg_lib est un moteur de rendu modulaire basé sur wgpu. Il adopte une architecture à deux niveaux : une façade de haut niveau pour la productivité et un accès bas niveau pour un contrôle total.
|
|
|
|
## 1. Philosophie et Principes
|
|
|
|
- **Abstraction vs Transparence** : Le moteur masque la complexité (wgpu, winit, gestion des Frame) via `App`, tout en exposant les briques élémentaires pour les utilisateurs avancés.
|
|
- **Approche orientée Scène** : Le rendu repose sur la composition d'une `Scene` contenant les entités, matériaux et géométries.
|
|
- **Pipeline Data-Driven** : Les ressources (Shaders, Meshes, Materials) sont découplées. Le `PipelineCache` gère automatiquement la compilation et la réutilisation des pipelines GPU.
|
|
|
|
## 2. Organisation des Modules (`lib/src/`)
|
|
|
|
- **`core/`** : Plomberie système (`Context`, `Renderer`, `Frame`). Accès bas niveau.
|
|
- **`pipeline/`** : `PipelineCache` pour la gestion des états GPU et shaders.
|
|
- **`resources/`** : Données (`Mesh`, `Material`, `Vertex`).
|
|
- **`scene/`** : Hiérarchie et stockage des objets à visualiser (Entités, Transformations).
|
|
- **`shaders/`** : Assets WGSL.
|
|
- **`utils/`** : Utilitaires transverses.
|
|
|
|
## 3. Interfaces de Haut Niveau (`App` & `AppHandler`)
|
|
|
|
### L'objet `App`
|
|
|
|
La façade `App` orchestre la boucle de jeu. Elle encapsule :
|
|
|
|
- Le cycle de vie de la fenêtre.
|
|
- La boucle d'événements.
|
|
- La gestion automatique des Frame (acquisition et présentation).
|
|
|
|
### Le trait `AppHandler`
|
|
|
|
L'utilisateur implémente ce trait pour définir la logique métier :
|
|
|
|
```rust
|
|
pub trait AppHandler {
|
|
// Appelé avant la préparation de la frame
|
|
fn update(&mut self, _app: &mut App) {}
|
|
|
|
// Appelé au moment de la présentation
|
|
fn render(&mut self, app: &mut App);
|
|
}
|
|
```
|
|
|
|
## 4. Workflow et Cycle de Vie
|
|
|
|
### A. Initialisation (Configuration)
|
|
|
|
- **Shaders** : Chargés avant la renderloop.
|
|
- **PipelineCache** : Enregistre les shaders.
|
|
- **Matériaux** : Créés avec un shader associé. Un mesh sans matériau explicite utilise `basic_shader` par défaut.
|
|
- **Scene** : Assemblage des objets. L'utilisateur peuple la scène via `app.scene`.
|
|
|
|
### B. Boucle de Rendu (Automatisée)
|
|
|
|
Le moteur gère la renderloop interne :
|
|
|
|
1. **Update** : Appel à `AppHandler::update`.
|
|
2. **Acquisition** : Gestion interne de `wgpu::SurfaceTexture`.
|
|
3. **Render** : Appel à `AppHandler::render` où l'utilisateur exécute `app.render(scene)`.
|
|
4. **Présentation** : Gestion interne de `present()`.
|
|
|
|
## 5. Accès Avancé
|
|
|
|
Les utilisateurs souhaitant ignorer l'abstraction `App` peuvent accéder directement à :
|
|
|
|
- `wsg_lib::core::Context` et `Renderer` pour gérer manuellement les RenderPass.
|
|
- `wsg_lib::pipeline::PipelineCache` pour des besoins de shaders personnalisés.
|
|
- `winit` pour la gestion précise des événements système.
|
|
|
|
## 6. Structure des données (pour LLM)
|
|
|
|
```
|
|
App (Facade) -> Scene (Conteneur) -> Entities -> Mesh + Material (Shader)
|
|
|
|
|
+-> Renderer (WGPU) <-> PipelineCache (Shaders)
|
|
```
|
|
|
|
## Notes pour l'implémentation future
|
|
|
|
- `app.render(scene)` : Cette méthode doit devenir l'API principale pour le rendu de la scène complète.
|
|
- Trait `AppHandler` : Il est recommandé de faire passer la `Scene` ou une référence à celle-ci comme argument ou de permettre à `AppHandler` d'être le lieu où la `Scene` est manipulée (ex : `MyGame { scene: Scene, ... }`).
|
|
- `PipelineCache` : Son utilisation doit être invisible pour l'utilisateur standard lors de la création d'un `Material`.
|