jerome/wsg
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

réorg doc

Browse Source
This commit is contained in:
Jérôme Bousquié
2026-09-25 19:08:20 +02:00
parent 7e88390006
commit 24fbafc810
34 changed files with 684 additions and 383 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/user/examples.md
+40 -17
View File
@@ -1,17 +1,33 @@
# 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).
Sixteen examples live in [`lib/examples/`](../../lib/examples/), organized into
**four category folders** — [`meshes/`](../../lib/examples/meshes/README.md),
[`lights/`](../../lib/examples/lights/README.md),
[`cameras/`](../../lib/examples/cameras/README.md),
[`effects/`](../../lib/examples/effects/README.md) — each folder with its own
`README.md` (per-example details: keys, what to observe). All launch with
`cargo run -p wsg-lib --example <name>` (names are stable, run from the repo
root). 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 (left-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 |
| Folder | Example | What it shows | Corresponding page |
|--------|---------|---------------|--------------------|
| `meshes/` | `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) |
| `meshes/` | `cube` | The 3D MVP: a textured (checkerboard) cube, lit (directional + point + spot), spinning | [Meshes](meshes.md), [Materials](materials.md), [Lights](lights.md) |
| `meshes/` | `pbr` | PBR metallic/roughness + normal mapping (6 materials) | [Materials](materials.md) |
| `meshes/` | `import` | OBJ file import (non-graphical, prints stats to stdout) | [Meshes](mesh.md) |
| `meshes/` | `manual` | The **advanced** workflow: `Context`/`Renderer`/`PipelineCache` driven by hand, without the `App` facade | below |
| `lights/` | `shadow` | Shadow mapping in isolation (4 objects on a floor) | [Shadows](shadows.md) |
| `lights/` | `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) |
| `lights/` | `spot_test` | Isolated spot (ambient nearly zero): the directed beam, the penumbra, the attenuation | [Lights](lights.md) |
| `lights/` | `emissive` | Emissive materials (intensities 0 → 4.0) + runtime exposure | [Emissive & exposure](emissive-exposure.md) |
| `cameras/` | `culling` | GPU-driven frustum culling: 15×15 grid, off-frustum cubes skipped (zero CPU cost) | [GPU-driven](gpu-driven.md) |
| `effects/` | `demo` | The full showcase: ground + 6 LOD primitives, textures, 3 lights, **shadows**, **orbital camera** on keyboard/mouse, HDR/ACES, bloom | [All pages](README.md) |
| `effects/` | `bloom` | Post-process bloom (threshold → blur → composite) | [Bloom](bloom.md) |
| `effects/` | `hdr` | HDR + tone mapping (ACES) + runtime exposure control | [HDR](hdr.md) |
| `effects/` | `msaa` | MSAA 4× (smooth edges vs stair-stepped) | [MSAA](msaa.md) |
| `effects/` | `fog` | Distance fog (3 modes: linear, exp, exp²) | [Fog](fog.md) |
| `effects/` | `dof` | Depth of field (cinematic bokeh, focus presets) | [effects README](../../lib/examples/effects/README.md) |
## The `manual` workflow (advanced)
@@ -26,7 +42,7 @@ framework, experimentation), you bypass `App` and drive directly:
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
[`manual.rs`](../../lib/examples/meshes/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
@@ -34,12 +50,19 @@ The window and GPU are created in winit 0.30's `resumed()` callback (`run_app` +
## Adding your own example
Repo conventions (see `lib/examples/README.md`):
Repo conventions (see [`lib/examples/README.md`](../../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`).
1. Create `lib/examples/<folder>/my_example.rs` (pick the matching category —
`meshes/`, `lights/`, `cameras/`, `effects/` — or add a new folder + README).
2. Declare it in `lib/Cargo.toml` — examples live in subfolders, so Cargo does
**not** discover them automatically:
```toml
[[example]]
name = "my_example"
path = "examples/<folder>/my_example.rs"
```
3. Keep it **self-contained**: procedural textures, hard-coded geometries, no external assets.
4. Document the example in the folder's `README.md` (and here, `docs/user/examples.md`).
## Links