# 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`.