doc

docs/user/examples.md

@@ -0,0 +1,47 @@
+# Examples
+
+Seven examples live in [`lib/examples/`](../../lib/examples/) and all launch with
+`cargo run -p wsg-lib --example <name>`. They are **self-contained**: no assets on disk
+(procedural textures, hard-coded geometries).
+
+| Example | Command | What it shows | Corresponding page |
+|---------|----------|---------------|--------------------|
+| `simple` | `cargo run -p wsg-lib --example simple` | The minimal declarative workflow: a two-tone 2D quad, **unlit**, rendered automatically. The "15 lines, no wgpu" model | [Quickstart](quickstart.md), [Materials](materials.md) (§ unlit) |
+| `cube` | `cargo run -p wsg-lib --example cube` | The 3D MVP: a textured (checkerboard) cube, lit (directional + point + spot), spinning | [Meshes](meshes.md), [Materials](materials.md), [Lights](lights.md) |
+| `demo` | `cargo run -p wsg-lib --example demo` | The full showcase: ground + 6 primitives, textures, 3 lights, **shadows**, **orbital camera** on keyboard/mouse (drag = orbit, wheel = zoom, `R` = reset, `1`/`2`/`3` = presets) | [All pages](README.md) |
+| `shadow_test` | `cargo run -p wsg-lib --example shadow_test` | Isolated shadow mapping: a cube casts a PCF-softened shadow on the ground (`clear_lights` technique → caster at index 0) | [Shadows](shadows.md) |
+| `spot_test` | `cargo run -p wsg-lib --example spot_test` | Isolated spot (ambient nearly zero): the directed beam, the penumbra, the attenuation | [Lights](lights.md) |
+| `manual` | `cargo run -p wsg-lib --example manual` | The **advanced** workflow: `Context`/`Renderer`/`PipelineCache` driven by hand, without the `App` facade (winit 0.30 `ApplicationHandler`) | below |
+
+## The `manual` workflow (advanced)
+
+When the `App` facade doesn't fit (fine-grained loop control, integration into an existing
+framework, experimentation), you bypass `App` and drive directly:
+
+- `Context` (*Manager* layer): GPU lifecycle — `Instance`/`Surface`/`Adapter`/`Device`/
+  `Queue`, `configure()` for the swapchain, `get_next_frame()`.
+- `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`), as in `app.rs`. The reference file is
+[`manual.rs`](../../lib/examples/manual.rs); the two-layer architecture is detailed in
+[ARCHI_APP](../tech/ARCHI_APP.md) and [FRAME_LOOP](../tech/FRAME_LOOP.md).
+
+> **Tip**: start with the declarative workflow. The manual workflow doesn't render more
+> pixels — it gives more control over command encoding.
+
+## Adding your own example
+
+Repo conventions (see `lib/examples/README.md`):
+
+1. Create `lib/examples/my_example.rs` (Cargo discovers it automatically).
+2. Keep it **self-contained**: procedural textures, hard-coded geometries, no external assets.
+3. Use the declarative workflow (`AppBuilder` + `Scene`) when possible.
+4. Document the example in `lib/examples/README.md` (and here, `docs/user/examples.md`).
+
+## Links
+
+- [User README](README.md) · [Quickstart](quickstart.md) · [Camera & input](camera-input.md)
+- [Root README](../../README.md) · [ROADMAP](../ROADMAP.md)