Jérôme Bousquié
b72c4e43ae
Clarify for each docs/tech document whether it describes the current (implemented) or target (planned) architecture, and reconcile with the readme/roadmap source of truth: - ARCHI_APP, ARCHI_CPU_GPU, ARCHI_RENDU: mark status=target and add a banner stating the GPU-driven two-pass pipeline, persistent VRAM buffers and scene auto-render are not implemented (they are ROADMAP Phase 3 / README roadmap items 1-3). render() still cannot draw the scene. - ARCHI_ARENES: status=target/deferred. String IDs are the current design; slotmap generational handles are the deferred 'typed handles' step and the slotmap dependency is currently absent (supersedes the retired dep). - FRAME_LOOP: stays status=current; correct the described API flow (Frame based via get_next_frame/Renderer::present, plus the low-level begin_frame/end_frame variant) and move the single-buffer VRAM note to target. - README: label each tech doc as current or target in the Documentation section.
69 lines
5.0 KiB
Markdown
69 lines
5.0 KiB
Markdown
---
|
|
type: Technical Specification
|
|
title: Rendering Architecture: Update/Render Cycle and Data Management
|
|
description: Technical specification for the rendering architecture of wsg_lib, defining strategies for mutability and data management to maximize performance and memory safety in Rust
|
|
tags: [architecture, rendering, rust, performance, memory-safety]
|
|
actor: person/jerome
|
|
sources: []
|
|
generated: { by: human:jerome, at: 2026-07-31T00:00:00Z }
|
|
verified: true
|
|
status: target
|
|
stale_after: 2027-01-31
|
|
---
|
|
|
|
# Architecture de Rendu : Cycle Update/Render et Gestion des Données
|
|
|
|
Ce document définit la stratégie de gestion de la mutabilité et des données du moteur wsg_lib, conçue pour maximiser la performance et garantir la sécurité mémoire via Rust.
|
|
|
|
> **État du document : CIBLE (modèle de mutabilité pour le futur rendu automatisé).**
|
|
> Le cycle update/render strict, l'itération **automatique** des entités et `renderer.render_scene()`
|
|
> décrits ici ne sont **pas implémentés** : c'est l'**étape 1 du Roadmap README** (scene auto-rendering).
|
|
> Aujourd'hui `App::run` acquiert/présente la frame mais `render()` ne peut pas encore dessiner la scène,
|
|
> et le `Renderer` ne dessine qu'un objet par soumission, à la main (exemple `manual`). La terminologie
|
|
> `MeshId`/`MaterialId` (handles typés) est celle de la **cible** ; l'état actuel utilise des **String IDs**
|
|
> dans `Scene`. La dichotomie update/render reste toutefois le modèle de référence retenu pour la suite.
|
|
|
|
## 1. La Dichotomie Update / Render
|
|
|
|
Pour éviter les conflits de données et optimiser le pipeline GPU, le moteur sépare strictement le cycle de vie de la frame en deux phases :
|
|
|
|
### Phase Update (Mutabilité Totale)
|
|
|
|
- L'utilisateur peut modifier librement l'état de la Scene (transformations, propriétés des matériaux, ajout/suppression d'entités).
|
|
- C'est l'unique zone de mutation autorisée. Le système est en "lecture-écriture".
|
|
|
|
### Phase Render (Lecture et Orchestration)
|
|
|
|
- La Scene est considérée comme immuable vis-à-vis du rendu.
|
|
- Le moteur itère automatiquement sur les entités pour soumettre les commandes au GPU.
|
|
- L'utilisateur dispose d'une "trappe" via `AppHandler::render()` pour injecter du code de rendu personnalisé, mais sans modifier l'état métier des objets.
|
|
|
|
## 2. Gestion des Données : Indirection par ID (Handle)
|
|
|
|
Pour contourner les limitations du Borrow Checker de Rust lors de l'accès aux ressources, le moteur utilise une approche par **Indirection (Handles/IDs)**.
|
|
|
|
- **HashMaps et Vecs indexés** : Les ressources (`Mesh`, `Material`) ne sont pas stockées sous forme de références directes (`&Mesh`) dans les entités. Elles sont stockées dans des conteneurs centralisés dans la Scene.
|
|
- **Identifiants (Handles)** : Chaque entité possède un `MeshId` ou `MaterialId`.
|
|
- **Avantage** : Cela élimine les problèmes de durées de vie (lifetimes) complexes. Vous pouvez passer des IDs partout sans bloquer la mutabilité des conteneurs parents.
|
|
- **Performance** : Cette approche permet au moteur de trier les entités par `MaterialId` avant le rendu, réduisant drastiquement les changements d'état GPU (**State Change Overhead**).
|
|
|
|
## 3. Points d'Attention du Borrow Checker
|
|
|
|
Bien que cette architecture facilite la gestion de la mémoire, des règles strictes s'appliquent à `App` :
|
|
|
|
- **Conflit de Mutabilité** : App contient à la fois la Scene et le Renderer. Il est interdit d'emprunter `&mut scene` et `&mut renderer` simultanément.
|
|
- **Solution** : Dans la boucle de rendu interne (`App::run`), le moteur doit être structuré pour séquencer les accès : `let scene = &app.scene;` suivi de `let renderer = &mut app.renderer;` puis `renderer.render_scene(scene);`.
|
|
- **Séparation des Responsabilités** : Le RenderLoop doit posséder la main sur l'ordonnancement pour éviter que l'utilisateur ne tente de muter la scène pendant que le renderer est en train de lire les données.
|
|
|
|
## 4. Synthèse des Avantages
|
|
|
|
- **Performance (Batching)** : Le rendu automatique par le moteur permet d'implémenter des stratégies de rendu optimales invisibles pour l'utilisateur.
|
|
- **Ergonomie** : L'utilisateur n'écrit pas de boucles de rendu complexes. Il se concentre sur sa logique métier dans `update()`.
|
|
- **Sécurité** : L'utilisation d'IDs évite les cycles de références et les références pendantes, rendant le code plus sûr et plus facile à maintenir.
|
|
|
|
## 5. Guide de Développement pour l'Utilisateur
|
|
|
|
> "Si vous devez changer la position d'un objet ou son matériau, faites-le dans `update()`. Si vous avez besoin d'afficher un élément de debug ou un rendu spécial, faites-le dans `render()`, mais traitez les objets de la scène comme des données en lecture seule."
|
|
|
|
Cette structure permet au projet d'être extrêmement scalable. L'ajout futur de fonctionnalités (Lumières, Textures, Caméras) ne nécessitera que d'ajouter de nouveaux conteneurs dans la Scene et de mettre à jour le système de tri dans `Renderer::render_scene()` (méthode à créer — cible de l'étape 1 du Roadmap README).
|