réorg doc

2026-09-25 19:08:20 +02:00
parent 7e88390006
commit 24fbafc810
34 changed files with 684 additions and 383 deletions
@@ -0,0 +1,118 @@
+# Meshes, Materials & Import
+
+Examples covering **geometry and materials**: the minimal workflow, the 3D MVP,
+PBR shading, file import, and the low-level (non-`App`) workflow.
+
+| Example | Run command | What it shows |
+|---------|-------------|---------------|
+| `simple` | `cargo run -p wsg-lib --example simple` | The minimal declarative workflow: a flat two-tone quad, **unlit**, rendered automatically |
+| `cube` | `cargo run -p wsg-lib --example cube` | The 3D MVP: a textured (checkerboard) cube, lit (directional + point + spot), spinning |
+| `pbr` | `cargo run -p wsg-lib --example pbr` | PBR metallic/roughness + normal mapping |
+| `import` | `cargo run -p wsg-lib --example import --features import-obj` | OBJ file import (non-graphical, prints stats to stdout) |
+| `manual` | `cargo run -p wsg-lib --example manual` | The **advanced** workflow: `Context`/`Renderer`/`PipelineCache` driven by hand, without the `App` facade |
+
+> All commands run from the repo root. The `import` example additionally
+> requires the `import-obj` Cargo feature.
+
+---
+
+## `simple` — Minimal Declarative Workflow
+
+The "15 lines, no wgpu" model: `AppBuilder` creates the window + GPU, and
+`App::run` drives the update → render → present loop. The scene renders
+**automatically** — the default `AppHandler::render` calls
+`app.render_scene(frame.view())`.
+
+The mesh is a flat two-tone quad declared from a `Geometry` (per-vertex
+positions + colors) and drawn with the `standard` shader in **unlit** mode
+(`renderer.set_unlit(true)`): flat 2D is a special case of 3D, one pipeline for all.
+
+```sh
+cargo run -p wsg-lib --example simple
+```
+
+No keys — static render.
+
+---
+
+## `cube` — The 3D MVP
+
+A lit unit cube that rotates, **textured** with a procedural 8×8 checkerboard
+via the diffuse path (bind group `@group(2)`). Follows the declarative workflow
+(like `simple`): `AppBuilder` + automatic scene, **no wgpu import**. The texture
+is generated procedurally (RGBA bytes → `Texture::from_rgba8`) to stay
+self-contained; the default camera at (0, 0, 3) frames the cube, and
+`update()` rotates the entity via `set_entity_transform` each frame.
+
+```sh
+cargo run -p wsg-lib --example cube
+```
+
+No keys — the cube spins on its own.
+
+---
+
+## `pbr` — PBR Metallic/Roughness + Normal Mapping
+
+Demonstrates the Cook-Torrance PBR workflow: GGX distribution + Smith geometry +
+Schlick Fresnel + hemispheric IBL + normal mapping.
+
+```sh
+cargo run -p wsg-lib --example pbr
+```
+
+| Key | Action |
+|-----|--------|
+| Drag (LMB) | Orbit camera |
+| Wheel | Zoom |
+| `R` | Reset camera |
+
+Scene: 6 PBR materials (mirror metal, smooth plastic, rusty metal, ceramic,
+bump map, matte floor). The bump-map cube shows procedural sin-wave surface
+detail.
+
+---
+
+## `import` — OBJ File Import
+
+**Non-graphical** example: parses a `.obj` file and prints statistics
+(vertex count, normals, UVs, indices, bounding box) to stdout.
+
+```sh
+# With a file:
+cargo run -p wsg-lib --example import --features import-obj -- /path/to/model.obj
+
+# Without argument (demo triangle):
+cargo run -p wsg-lib --example import --features import-obj
+```
+
+No keys — runs and exits.
+
+---
+
+## `manual` — Low-level Workflow (no `App` facade)
+
+Demonstrates the API **without** the `App` facade: direct use of `Context`,
+`Renderer`, `PipelineCache`, `Mesh`, `Material`. Renders a colored quad (unlit).
+
+Useful for understanding what the `App` facade encapsulates:
+
+- `Context` (*Manager* layer): GPU lifecycle — `Instance`/`Surface`/`Adapter`/
+  `Device`/`Queue`, `configure()` for the swapchain, per-frame surface texture.
+- `Renderer` (*Executor* layer): `render(view, mesh, material)` = one object per
+  submission; `present(frame)`.
+- `PipelineCache`: `register_shader(id, path)` then `Material::new(format, id, &mut cache)`.
+
+The window and GPU are created in winit 0.30's `resumed()` callback
+(`run_app` + `ApplicationHandler`). The two-layer architecture is detailed in
+[`docs/tech/ARCHI_APP.md`](../../docs/tech/ARCHI_APP.md) and
+[`FRAME_LOOP.md`](../../docs/tech/FRAME_LOOP.md).
+
+```sh
+cargo run -p wsg-lib --example manual
+```
+
+No keys — static render (unlit quad, 4 colors).
+
+> **Tip**: start with the declarative workflow. The manual workflow doesn't
+> render more pixels — it gives more control over command encoding.