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é
@@ -2,7 +2,7 @@
|
||||
|
||||
WSG is a Rust library that wraps [wgpu](https://github.com/gfx-rs/wgpu) and [winit](https://crates.io/crates/winit) for simple GPU drawing. It groups the five core wgpu objects (Instance, Surface, Adapter, Device, Queue) behind a single `Context`, adds small building blocks (`Mesh`, `Material`, `PipelineCache`, `Frame`), and exposes the low-level primitives for advanced users.
|
||||
|
||||
> **Status: unstable development version.** The manual workflow below is fully working, the high-level "declarative" workflow (automatic `App` scene rendering) works for flat/NDC drawing, and the **3D MVP is reached** : the `cube` example (Étape 5) renders a rotating, Phong-lit cube through `App::render_scene`. The GPU-driven two-pass pipeline described in the architecture docs is **not implemented yet** — see [Status](#status) and [Roadmap](#roadmap).
|
||||
> **Status: unstable development version.** The manual workflow below is fully working, the high-level "declarative" workflow (automatic `App` scene rendering) works for flat/NDC drawing, and the **3D MVP is reached** : the `cube` example (Étape 5) renders a rotating, Phong-lit cube through `App::render_scene`. Since Étape 8, meshes are declared from a CPU `Geometry` (retained as `Arc<Geometry>` on the Mesh) instead of raw vertex arrays. The GPU-driven two-pass pipeline described in the architecture docs is **not implemented yet** — see [Status](#status) and [Roadmap](#roadmap).
|
||||
|
||||
## Status
|
||||
|
||||
@@ -28,7 +28,7 @@ use winit::event_loop::EventLoop;
|
||||
use winit::window::WindowBuilder;
|
||||
use wsg_lib::core::{Context, Frame, Renderer};
|
||||
use wsg_lib::pipeline::PipelineCache;
|
||||
use wsg_lib::resources::{Material, Mesh, Vertex};
|
||||
use wsg_lib::resources::{Geometry, Material, Mesh};
|
||||
use wsg_lib::utils;
|
||||
|
||||
fn main() {
|
||||
@@ -45,16 +45,23 @@ fn main() {
|
||||
let mut cache = PipelineCache::new(Arc::new(context.device.clone()));
|
||||
cache.register_shader("standard", utils::STANDARD_SHADER_PATH).unwrap();
|
||||
|
||||
// Material + mesh
|
||||
// Material + mesh (Étape 8 : le mesh est construit depuis une `Geometry` — positions,
|
||||
// attributs optionnels en builder, défauts blancs via `to_vertices`).
|
||||
let material = Material::new(renderer.format(), "standard", &mut cache);
|
||||
let vertices: [Vertex; 4] = [
|
||||
Vertex { position: [-0.5, 0.5, 0.0], normal: [0.0, 0.0, 1.0], uv: [0.0, 0.0], color: [1.0, 0.0, 0.0, 1.0] },
|
||||
Vertex { position: [ 0.5, 0.5, 0.0], normal: [0.0, 0.0, 1.0], uv: [1.0, 0.0], color: [0.0, 1.0, 0.0, 1.0] },
|
||||
Vertex { position: [ 0.5, -0.5, 0.0], normal: [0.0, 0.0, 1.0], uv: [1.0, 1.0], color: [0.0, 0.0, 1.0, 1.0] },
|
||||
Vertex { position: [-0.5, -0.5, 0.0], normal: [0.0, 0.0, 1.0], uv: [0.0, 1.0], color: [1.0, 1.0, 0.0, 1.0] },
|
||||
];
|
||||
let indices: [u16; 6] = [0, 1, 2, 0, 2, 3];
|
||||
let mesh = Mesh::new(renderer.device(), &vertices, Some(&indices));
|
||||
let geometry = Geometry::new(vec![
|
||||
[-0.5, 0.5, 0.0], // Haut-Gauche
|
||||
[ 0.5, 0.5, 0.0], // Haut-Droite
|
||||
[ 0.5, -0.5, 0.0], // Bas-Droite
|
||||
[-0.5, -0.5, 0.0], // Bas-Gauche
|
||||
])
|
||||
.with_colors(vec![
|
||||
[1.0, 0.0, 0.0, 1.0], // Rouge
|
||||
[0.0, 1.0, 0.0, 1.0], // Vert
|
||||
[0.0, 0.0, 1.0, 1.0], // Bleu
|
||||
[1.0, 1.0, 0.0, 1.0], // Jaune
|
||||
])
|
||||
.with_indices(vec![0, 1, 2, 0, 2, 3]);
|
||||
let mesh = Mesh::from_geometry(renderer.device(), Arc::new(geometry), None);
|
||||
|
||||
// Render loop
|
||||
event_loop.run(|event, elwt| {
|
||||
@@ -96,10 +103,13 @@ async fn main() -> Result<(), wsg_lib::utils::WsgError> {
|
||||
// Register your scene once (string IDs), then App renders it automatically each frame.
|
||||
// Since Étape 7 the Scene owns the pipeline cache: build materials/meshes through it and
|
||||
// link the material to the mesh (no material_id on the entity anymore).
|
||||
// Since Étape 8 meshes are declared from a `Geometry` (positions + optional attributes).
|
||||
// app.renderer_mut().set_unlit(true); // select flat 2D rendering (optional)
|
||||
// app.scene.register_shader("standard", wsg_lib::utils::STANDARD_SHADER_PATH)?;
|
||||
// app.scene.add_material_shader("mat", "standard")?; // build via the Scene's cache
|
||||
// app.scene.create_mesh("quad", &vertices, Some(&indices), Some("mat"))?; // mesh links its Material
|
||||
// let geometry = wsg_lib::resources::Geometry::new(vec![[-0.5,0.5,0.0],[0.5,0.5,0.0]])
|
||||
// .with_colors(vec![[1.0,0.0,0.0,1.0],[0.0,1.0,0.0,1.0]]);
|
||||
// app.scene.create_mesh("quad", geometry, Some("mat"))?; // mesh links its Material
|
||||
// app.scene.add_entity("my_quad", "quad")?;
|
||||
|
||||
app.run(MyGame)
|
||||
@@ -108,13 +118,14 @@ async fn main() -> Result<(), wsg_lib::utils::WsgError> {
|
||||
|
||||
> API note: `Scene::register_shader` / `add_material_shader` / `create_mesh` / `add_entity` and
|
||||
> `PipelineCache::register_shader` currently return `Result<_, String>` — typed error unification
|
||||
> is on the roadmap.
|
||||
> is on the roadmap. Since Étape 8, `Scene::create_mesh(id, geometry, material)` takes a CPU
|
||||
> `Geometry` (source of truth, retained on the Mesh) instead of raw `&[Vertex]`.
|
||||
|
||||
## Architecture overview
|
||||
|
||||
- **Manager layer (`Context`)** — owns the GPU hardware lifecycle (Instance → Surface → Adapter → Device → Queue). Created once at startup; `configure()` sets up the swapchain, `Frame` wraps each frame's surface texture + view.
|
||||
- **Executor layer (`Renderer`)** — binds a `Material` pipeline + `Mesh` buffers into a RenderPass and submits the commands. Rendering a whole `Scene` (`render_scene`) batches all entities into **one encoder + one submit per frame**; the low-level `render` still allocates one per object.
|
||||
- **Supporting pieces** — `PipelineCache` (shader → compiled RenderPipeline, `Arc`-shared), `Material`, `Mesh`/`Vertex`, `Scene` (string-ID registry), `Camera`/`Transform` (active camera wired to the frame uniforms, Étape 4.3).
|
||||
- **Supporting pieces** — `PipelineCache` (shader → compiled RenderPipeline, `Arc`-shared), `Material`, `Geometry`/`Mesh`/`Vertex`, `Scene` (string-ID registry), `Camera`/`Transform` (active camera wired to the frame uniforms, Étape 4.3). `Geometry` is the CPU source of truth (positions/normals/UVs/colors), `Mesh` uploads it to GPU buffers and retains the `Arc<Geometry>`, `Vertex` is the interleaved upload contract (Étape 8).
|
||||
|
||||
The planned target architecture — a GPU-driven two-pass pipeline (Compute Pass: world matrices + frustum culling → Indirect Draw Buffer, then a single `draw_indexed_indirect` per frame) — is specified in [docs/tech/ARCHI_APP.md](docs/tech/ARCHI_APP.md) and [docs/tech/ARCHI_CPU_GPU.md](docs/tech/ARCHI_CPU_GPU.md) but is **not implemented yet**.
|
||||
|
||||
@@ -129,7 +140,8 @@ The planned target architecture — a GPU-driven two-pass pipeline (Compute Pass
|
||||
| Renderer | Struct | Binds Material + Mesh into a RenderPass, submits | ✅ (`render_scene` batches one pass/frame) |
|
||||
| PipelineCache | Struct | Shader → compiled RenderPipeline cache | ✅ |
|
||||
| Material | Struct | Shader ID → RenderPipeline | ✅ |
|
||||
| Mesh / Vertex | Struct | GPU geometry container / CPU-side vertex tuple | ✅ |
|
||||
| Geometry | Struct | CPU-side scattered vertex data (positions/normals/UVs/colors/indices), source of truth | ✅ (Étape 8 — retained `Arc<Geometry>` on Mesh) |
|
||||
| Mesh / Vertex | Struct | GPU geometry container / CPU-side interleaved upload tuple | ✅ |
|
||||
| Frame | Struct | Per-frame RAII wrapper (surface texture + view) | ✅ |
|
||||
| Camera / Transform | Struct | Camera & transform math | ✅ Active camera + transform wired to per-frame uniforms (Étape 4.3) |
|
||||
|
||||
@@ -170,3 +182,4 @@ The architecture docs live in `docs/tech/` and are written in **French**. Each d
|
||||
4. ✅ **Real 3D pipeline (MVP atteint)** — MVP uniforms + camera support in the vertex shader. *(Engine plumbing done 2026-09-16 ; Étape 5, 2026-09-17 : `standard` branché sur l'exemple `cube` — un cube unitaire éclairé (Phong) qui tourne, rendu automatiquement par `App::render_scene`. Retrait de `basic` : le 2D plat = variante unlit de `standard` via `Renderer::set_unlit`.)*
|
||||
5. **Typed resource handles** — keep String IDs for the MVP (current design, source of truth in `Scene`); slotmap-based generational handles (`ARCHI_ARENES.md`) are deferred to a later performance pass.
|
||||
6. **Error unification** — replace `Result<_, String>` in `Scene`/`PipelineCache` with typed errors.
|
||||
7. ✅ **CPU geometry storage (Étape 8)** — `Mesh` retains a shared `Arc<Geometry>` (CPU source of truth with colors) alongside its GPU buffers; meshes are declared from a `Geometry` via `Mesh::from_geometry`/`Scene::create_mesh(id, geometry, material)` instead of raw `&[Vertex]` arrays. (Done 2026-09-18; `transform` stays on `Entity` — deviation D3.)
|
||||
|
||||
Reference in New Issue
Block a user