doc
This commit is contained in:
Jérôme Bousquié
+63
-46
@@ -1,65 +1,82 @@
|
||||
# ARCHI_APP.md : Architecture et Responsabilités
|
||||
# Architecture du Moteur wsg_lib
|
||||
|
||||
Ce document définit l'architecture modulaire du moteur `wsg_lib`. L'objectif est de séparer la plomberie système de la logique métier tout en facilitant l'usage via une façade unifiée.
|
||||
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. Organisation des répertoires (`lib/src/`)
|
||||
## 1. Philosophie et Principes
|
||||
|
||||
L'organisation respecte les conventions Rust pour une bibliothèque modulaire :
|
||||
- **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.
|
||||
|
||||
* `core/` : Plomberie système (Context, Renderer, Frame).
|
||||
* `pipeline/` : Gestion des états GPU et compilation des shaders.
|
||||
* `resources/` : Dépôt de données (Mesh, Material, Vertex, Texture).
|
||||
* `scene/` : Logique métier et hiérarchie (Entités, Transformations).
|
||||
* `shaders/` : Shaders intégrés (accessibles via `include_str!`).
|
||||
* `utils/` : Transverses (Configuration, Erreurs).
|
||||
## 2. Organisation des Modules (`lib/src/`)
|
||||
|
||||
## 2. Répartition des responsabilités
|
||||
- **`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.
|
||||
|
||||
| Module | Responsabilité |
|
||||
| :--- | :--- |
|
||||
| **App** | Façade orchestratrice (Point d'entrée unique). |
|
||||
| **Renderer** | Exécution des commandes WGPU. |
|
||||
| **PipelineCache** | Traduction des données de `resources/` vers les pipelines GPU. |
|
||||
| **Scene** | Stockage et gestion des entités et de leurs relations. |
|
||||
| **AppHandler** | Trait implémenté par l'utilisateur pour la boucle de jeu. |
|
||||
## 3. Interfaces de Haut Niveau (`App` & `AppHandler`)
|
||||
|
||||
## 3. Workflow de l'utilisateur ("La Recette")
|
||||
### L'objet `App`
|
||||
|
||||
### Phase de Déclaration (Initialisation)
|
||||
L'utilisateur configure sa scène avant le démarrage de la boucle.
|
||||
```rust
|
||||
let mut app = App::builder()
|
||||
.with_runtime(my_runtime)
|
||||
.build()
|
||||
.await;
|
||||
La façade `App` orchestre la boucle de jeu. Elle encapsule :
|
||||
|
||||
let mat_id = app.resources.create_material("name", shader_id);
|
||||
let mesh_id = app.resources.load_mesh("path");
|
||||
app.scene.add_entity("id", mesh_id, mat_id);
|
||||
```
|
||||
- Le cycle de vie de la fenêtre.
|
||||
- La boucle d'événements.
|
||||
- La gestion automatique des Frame (acquisition et présentation).
|
||||
|
||||
### Phase d'Exécution (Render Loop)
|
||||
### Le trait `AppHandler`
|
||||
|
||||
L'utilisateur implémente `AppHandler` pour manipuler ses objets.
|
||||
L'utilisateur implémente ce trait pour définir la logique métier :
|
||||
|
||||
```rust
|
||||
impl AppHandler for MyGame {
|
||||
fn render(&mut self, app: &mut App) {
|
||||
// La scène est rendue automatiquement, l'utilisateur modifie l'état
|
||||
app.scene.get("id").transform.rotation += 0.01;
|
||||
}
|
||||
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);
|
||||
}
|
||||
app.run(MyGame::new());
|
||||
```
|
||||
|
||||
### 4. Points d'attention pour l'utilisateur avancé
|
||||
## 4. Workflow et Cycle de Vie
|
||||
|
||||
- **Accès Bas-Niveau** : App expose ses composants internes (`renderer`, `context`, `cache`). Un utilisateur avancé peut ignorer la Scene pour faire des appels manuels.
|
||||
- **Injection Async** : Le runtime est injecté à la création via le Builder.
|
||||
- **Identifiants** : La gestion des ressources repose sur des identifiants (`Handle<T>` ou `String`), garantissant la sécurité mémoire et évitant les problèmes de durée de vie (*borrow checker*).
|
||||
### A. Initialisation (Configuration)
|
||||
|
||||
### 5. Pourquoi cette architecture ?
|
||||
- **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`.
|
||||
|
||||
- **Performance** : La centralisation dans App permet d'optimiser le tri des entités et le *batching* par matériau.
|
||||
- **Maintenance** : Chaque dossier est indépendant. Ajouter une nouvelle fonctionnalité (ex: Lumières) consiste à créer un nouveau module dans `resources/` ou `scene/` sans impacter le cœur du rendu.
|
||||
- **Ergonomie** : L'utilisateur n'est plus confronté à la gestion des pipelines et des buffers, mais uniquement à la gestion de sa scène et de ses entités.
|
||||
### 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`.
|
||||
|
||||
Reference in New Issue
Block a user