docs(étape8): valider et documenter le refactor stockage CPU Arc<Geometry> (8.6)
- DRAFT.md : cases 8.1-8.6 cochées, état 'terminée et vérifiée 2026-09-18', bilan final. - README.md : workflow manuel et déclaratif (extraits Mesh::new -> Geometry/from_geometry), note API create_mesh(Geometry), section architecture + table quick reference, roadmap +1 (CPU storage). - ROADMAP.md (1.2) : colors + refactor Mesh/Scene cochés 'fait', déviation D3 'implémenté'. - PLAN.md : statut réel à jour 2026-09-18 (Étape 8 effectuée). - resources/README.md : Mesh::new() -> from_geometry() + rétention CPU.
This commit is contained in:
Jérôme Bousquié
+42
-19
@@ -4,8 +4,8 @@
|
||||
> **Son contenu est effacé au début de chaque nouvelle étape.** La source de vérité de l'état est
|
||||
> le code + README.md ; les autres docs `docs/*` restent stables.
|
||||
|
||||
> **État.** Étape 8 en préparation — refactor du stockage CPU des données géométriques :
|
||||
> `Mesh` contient `geometry: Arc<Geometry>`. Étape 7 terminée et vérifiée le 2026-09-17.
|
||||
> **État.** Étape 8 **terminée et vérifiée le 2026-09-18** : `Mesh.geometry: Arc<Geometry>` + buffers
|
||||
> dérivés, API `create_mesh` basée `Geometry`, exemples réécrits, validation verte, docs à jour.
|
||||
|
||||
---
|
||||
|
||||
@@ -54,7 +54,7 @@ Valeurs apportées :
|
||||
|
||||
## Étape 8.1 — Étendre `Geometry` (couleur + validation) — **proposition validée 2026-09-18**
|
||||
|
||||
- [ ] Dans `lib/src/math/geometry.rs` :
|
||||
- [x] Dans `lib/src/math/geometry.rs` :
|
||||
- [ ] ajouter `colors: Option<Vec<[f32; 4]>>` en champ optionnel (parallèle à `normals`/`uvs`).
|
||||
- [ ] documenter les invariants : `positions` obligatoire ; `normals`, `uvs`, `colors`,
|
||||
`indices` optionnels mais doivent avoir la même longueur que `positions` quand présents.
|
||||
@@ -67,7 +67,7 @@ Valeurs apportées :
|
||||
|
||||
## Étape 8.2 — Convertisseur `Geometry` → `Vec<Vertex>`
|
||||
|
||||
- [ ] Dans `lib/src/math/geometry.rs` (ou un petit trait dédié), implémenter :
|
||||
- [x] Dans `lib/src/math/geometry.rs` (ou un petit trait dédié), implémenter :
|
||||
- [ ] `Geometry::to_vertices() -> Vec<Vertex>` qui zip `positions`/`normals`/`uvs`/`colors`
|
||||
avec des valeurs par défaut : normale `[0,0,1]`, uv `[0,0]`, couleur blanche `[1,1,1,1]`.
|
||||
- [ ] documenter clairement ces défauts (i.e. une géométrie sans normales via Phong sera plate).
|
||||
@@ -75,7 +75,7 @@ Valeurs apportées :
|
||||
|
||||
## Étape 8.3 — `Mesh` contient `Arc<Geometry>` et construit ses buffers
|
||||
|
||||
- [ ] Dans `lib/src/resources/mesh.rs` :
|
||||
- [x] Dans `lib/src/resources/mesh.rs` :
|
||||
- [ ] ajouter le champ `geometry: Arc<Geometry>`.
|
||||
- [ ] remplacer/ajouter `Mesh::from_geometry(device: &wgpu::Device, geometry: Arc<Geometry>,
|
||||
material: Option<Arc<Material>>) -> Mesh` :
|
||||
@@ -90,7 +90,7 @@ Valeurs apportées :
|
||||
|
||||
## Étape 8.4 — Adapter `Scene` / l'API déclarative
|
||||
|
||||
- [ ] Dans `lib/src/scene/scene.rs` :
|
||||
- [x] Dans `lib/src/scene/scene.rs` :
|
||||
- [ ] changer `create_mesh(id, vertices: &[Vertex], indices, material)` →
|
||||
`create_mesh(id, geometry: Geometry, material: Option<&str>) -> Result<...>` :
|
||||
- [ ] il construit `Arc<Geometry>`, appelle `Mesh::from_geometry(self.device(), arc, mat)`.
|
||||
@@ -100,38 +100,61 @@ Valeurs apportées :
|
||||
|
||||
## Étape 8.5 — Réécrire les exemples (non contraignants) sur `Geometry`
|
||||
|
||||
- [ ] `lib/examples/cube.rs` :
|
||||
- [x] `lib/examples/cube.rs` :
|
||||
- [ ] remplacer `cube_vertices() -> Vec<Vertex>` / `cube_indices()` par un builder de
|
||||
`Geometry` (ou `Geometry::new(...).with_normals(...).with_indices(...)`) ; couleur blanche
|
||||
par défaut → vérifier le rendu Phong inchangé.
|
||||
- [ ] appeler `scene.create_mesh("cube_mesh", geometry, Some("cube_material"))`.
|
||||
- [ ] `lib/examples/simple.rs` :
|
||||
- [x] `lib/examples/simple.rs` :
|
||||
- [ ] construire une `Geometry` (positions ± couleurs par sommet pour le quad unlit) ;
|
||||
- [ ] `scene.create_mesh("quad", geometry, None)` (matériau par défaut).
|
||||
- [ ] `lib/examples/manual.rs` (exemple bas-niveau, utilise `Mesh::new(renderer.device(),
|
||||
- [x] `lib/examples/manual.rs` (exemple bas-niveau, utilise `Mesh::new(renderer.device(),
|
||||
&vertices, ...)`) :
|
||||
- [ ] réécrire sur `Mesh::from_geometry(device, Arc<Geometry>, None)`.
|
||||
- [ ] mettre à jour les en-têtes / commentaires des exemples (références à `Vertex` en public).
|
||||
- [x] mettre à jour les en-têtes / commentaires des exemples (références à `Vertex` en public).
|
||||
|
||||
## Étape 8.6 — Validation
|
||||
|
||||
- [ ] `cargo fmt --all` (aucun diff résiduel).
|
||||
- [ ] `cargo check --workspace` puis `cargo build --workspace` **sans warning** (veiller à la
|
||||
- [x] `cargo fmt --all` (aucun diff résiduel).
|
||||
- [x] `cargo check --workspace` puis `cargo build --workspace` **sans warning** (veiller à la
|
||||
régularité des tableaux dans les exemples).
|
||||
- [ ] `cargo test --workspace` (zéro test à ce stade, mais compilation clean).
|
||||
- [ ] `cargo doc --no-deps` **sans warning `missing_docs`** (la crate est en `#![warn(missing_docs)]`).
|
||||
- [ ] Lancer les 3 exemples (simple, cube, manual) et constater l'absence de panic / rendu visé.
|
||||
- [ ] Mettre à jour `README.md` (extraits de code `Mesh::new` → `Geometry`, section architecture)
|
||||
- [x] `cargo test --workspace` (zéro test à ce stade, mais compilation clean).
|
||||
- [x] `cargo doc --no-deps` **sans warning `missing_docs`** (la crate est en `#![warn(missing_docs)]`).
|
||||
- [x] Lancer les 3 exemples (simple, cube, manual) et constater l'absence de panic / rendu visé.
|
||||
- [x] Mettre à jour `README.md` (extraits de code `Mesh::new` → `Geometry`, section architecture)
|
||||
et les statuts `docs/PLAN.md` + `docs/ROADMAP.md` (cocher le refactor 1.2 « stockage CPU » ;
|
||||
laisser `transform` documenté comme déviation en D3).
|
||||
|
||||
## Point d'étape
|
||||
|
||||
- [ ] Caser le refactor : `Mesh.geometry: Arc<Geometry>` + buffers dérivés, API `create_mesh`
|
||||
- [x] Caser le refactor : `Mesh.geometry: Arc<Geometry>` + buffers dérivés, API `create_mesh`
|
||||
basée `Geometry`, exemples réécrits, validation verte, docs à jour.
|
||||
- [ ] Deux commits séparés comme d'habitude : un `refactor(...)` (8.1–8.5) puis un `docs(...)`
|
||||
- [x] Deux commits séparés comme d'habitude : un `refactor(...)` (8.1–8.5) puis un `docs(...)`
|
||||
(8.6). Rédiger un court bilan et ouvrir la question du prochain chantier.
|
||||
|
||||
## Bilan (2026-09-18)
|
||||
|
||||
L'Étape 8 est **terminée et vérifiée** :
|
||||
- `Geometry` (math) : champ `colors`, constructeur `Geometry::new(positions)` + builder
|
||||
fluent (`.with_normals/.with_uvs/.with_colors/.with_indices`), `validate()` + `GeometryError`,
|
||||
`indices()` et `to_vertices()`/`try_into_vertices()` (zip positions/normals/uvs/colors avec défauts
|
||||
normale `[0,0,1]`, uv `[0,0]`, blanc opaque).
|
||||
- `Mesh` (resources) : retient `geometry: Arc<Geometry>` (CPU, D5) + buffers GPU pré-uploadés ;
|
||||
constructeur **unique** `Mesh::from_geometry(device, Arc<Geometry>, Option<Arc<Material>>)`
|
||||
(D4) — `Mesh::new`/`with_material` (`&[Vertex]`) supprimés ; accesseurs `geometry()`/`material()`/`set_material()`.
|
||||
- `Scene` : `create_mesh(id, Geometry, Option<&str>)` (D4) ; `Geometry` exposé via `math` (D2)
|
||||
et ré-exporté en convenance depuis `resources`.
|
||||
- Exemples cube/simple/manual réécrits sur `Geometry` (8.5). `simple` passe par `None` pour
|
||||
vérifier le matériau par défaut (`Scene::default_material`).
|
||||
- Validation : `cargo fmt` (aucun diff), `build`/`check` sans warning, `test` vert (1 unitaire
|
||||
shader + 1 doc-test `Geometry::new`), `doc` sans `missing_docs`, 3 exemples lancés (rendu sans panic).
|
||||
- Commits : `refactor(...)` (8.1–8.5) + `docs(...)` (8.6).
|
||||
|
||||
**Prochain chantier possible** : la suite du ROADMAP — gestion des matériaux/textures (Phase 2/4,
|
||||
ex. `Texture` + `uniform` diffuse), ou remonter vers les **handles typés** (Phase 2/5) / pipeline
|
||||
**GPU-driven** (Phase 3) avec la bounding box dans `Geometry` (le champ `colors` et la rétention CPU
|
||||
`Arc<Geometry>` posent déjà la base du culling).
|
||||
|
||||
---
|
||||
|
||||
_Fin du DRAFT Étape 8 — à valider avant implémentation._
|
||||
_Fin du DRAFT Étape 8 — implémentée et vérifiée le 2026-09-18._
|
||||
|
||||
+6
-2
@@ -11,7 +11,7 @@ generated: { by: human:jerome, at: 2026-07-31T00:00:00Z }
|
||||
|
||||
Ce plan définit les étapes prioritaires pour finaliser 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é.
|
||||
|
||||
> **Statut réel (à jour au 2026-09-17).** Ce plan couvre la phase de *consolidation* passée ; la source
|
||||
> **Statut réel (à jour au 2026-09-18).** Ce plan couvre la phase de *consolidation* passée ; la source
|
||||
> de vérité sur l'état actuel est **README.md** et le code. Depuis la révision du 2026-09-14, l'étape
|
||||
> **« Scene auto-render »** a été réalisée : le rendu de la `Scene` est **automatisé** en une seule
|
||||
> passe groupée via `App::render_scene(frame.view())` (appelée par défaut dans `AppHandler::render`),
|
||||
@@ -21,7 +21,11 @@ Ce plan définit les étapes prioritaires pour finaliser l'architecture actuelle
|
||||
> le buffer frame chaque frame, matrices monde par entité. **Étape 5 (2026-09-17) : MVP 3D atteint** —
|
||||
> l'exemple `cube` rend un cube unitaire éclairé (Phong) en rotation via `App::render_scene` ; le
|
||||
> shader `basic` est supprimé, le 2D plat devient la **variante unlit** de `standard`
|
||||
> (`Renderer::set_unlit` / `app.renderer_mut().set_unlit(true)`).
|
||||
> (`Renderer::set_unlit` / `app.renderer_mut().set_unlit(true)`). L'**Étape 7 (2026-09-17)** a rattaché
|
||||
> le `PipelineCache` à la `Scene` et fait référencer son `Material` par chaque `Mesh`. L'**Étape 8
|
||||
> (2026-09-18)** a donné à `Mesh` une source de vérité **CPU partagée** (`geometry: Arc<Geometry>`) :
|
||||
> `Scene::create_mesh(id, Geometry, material)` déclare les meshes depuis une `Geometry` (avec couleurs),
|
||||
> `Mesh::from_geometry` dérive ses buffers GPU, et les exemples cube/simple/manual utilisent `Geometry`.
|
||||
|
||||
## Phase 1 : Finalisation et Nettoyage de l'Existant (Priorité Absolue)
|
||||
|
||||
|
||||
+15
-10
@@ -53,24 +53,29 @@ generated: { by: human:jerome, at: 2026-07-31T00:00:00Z }
|
||||
- [x] `positions: Vec<[f32; 3]>` (obligatoire)
|
||||
- [x] `indices: Option<Vec<u16>>` (optionnel)
|
||||
- [x] `normals: Option<Vec<[f32; 3]>>` (pour Phong) — plus `uvs: Option<Vec<[f32; 2]>>`
|
||||
- [ ] `colors: Option<Vec<[f32; 4]>>` — **décidé en DRAFT Étape 8 (D1)** : le shader lit la couleur
|
||||
unlit, il faut la porter dans `Geometry` ; conversion `Geometry -> Vec<Vertex>` pour l'upload.
|
||||
- [ ] Refactorer `Mesh` pour contenir :
|
||||
- [ ] `geometry: Arc<Geometry>`
|
||||
- [ ] `vertex_buffer: wgpu::Buffer`
|
||||
- [ ] `index_buffer: Option<wgpu::Buffer>`
|
||||
- [x] `colors: Option<Vec<[f32; 4]>>` — **fait (Étape 8, 8.1, 2026-09-18)** : décidé en DRAFT Étape 8 (D1) ;
|
||||
le shader lit la couleur unlit, elle est donc portée dans `Geometry`. Conversion
|
||||
`Geometry -> Vec<Vertex>` via `Geometry::to_vertices()` (D6) pour l'upload.
|
||||
- [x] Refactorer `Mesh` pour contenir — **fait (Étape 8, 8.3, 2026-09-18)** :
|
||||
- [x] `geometry: Arc<Geometry>` (rétention CPU, D5) + accesseur `geometry()`
|
||||
- [x] `vertex_buffer: wgpu::Buffer`
|
||||
- [x] `index_buffer: Option<wgpu::Buffer>`
|
||||
- Construction via `Mesh::from_geometry(device, Arc<Geometry>, material)` (D4) ; les anciennes
|
||||
voies `Mesh::new`/`with_material` (`&[Vertex]`) sont supprimées.
|
||||
- `Scene::create_mesh(id, Geometry, Option<&str>)` (8.4) ; exemples cube/simple/manual réécrits
|
||||
sur `Geometry` (8.5).
|
||||
- [x] Ajouter un mesh de test (cube unitaire) en exemple — **fait** (helper `cube_geometry` dans l'exemple `cube`, Étape 5, 2026-09-17)
|
||||
|
||||
> **Note (2026-09-17, DRAFT Étape 7)** : le refactor « Mesh contient `Arc<Geometry>` » ci-dessus reste
|
||||
> **reporté** (il porte sur le *stockage CPU* des données géométriques). En revanche le volet *matériau*
|
||||
> de `Mesh` a été fait en Étape 7 : `Mesh.material: Option<Arc<Material>>` (cf. PLAN Phase 2, gestion des
|
||||
> matériaux), indépendant de la structure `Geometry`.
|
||||
> **Note (2026-09-17, DRAFT Étape 7)** : le volet *matériau* de `Mesh` a été fait en Étape 7 :
|
||||
> `Mesh.material: Option<Arc<Material>>` (cf. PLAN Phase 2, gestion des matériaux), indépendant de
|
||||
> la structure `Geometry`.
|
||||
>
|
||||
> **Décision **D3** (2026-09-18, DRAFT Étape 8)** : le ROADMAP listait `transform: Transform` sur `Mesh`.
|
||||
> **Déviation validée : `transform` reste sur `Entity` et n'est PAS ajouté à `Mesh`.** Un mesh est
|
||||
> **partagé** par plusieurs entités à des transforms différents (modèle instancé, Étape 4/7) : un
|
||||
> `transform` unique sur `Mesh` casserait ce modèle. L'Étape 8 met donc en œuvre le refactor de
|
||||
> *stockage CPU* (`Mesh.geometry: Arc<Geometry>` + buffers dérivés) **sans** le champ `transform`.
|
||||
> *(Implémenté 2026-09-18.)*
|
||||
|
||||
### 1.3 Shader Phong Minimal
|
||||
- [x] Créer `standard_shader.wgsl` (Étape 2, 2026-09-16) :
|
||||
|
||||
Reference in New Issue
Block a user