Jérôme Bousquié
62 lines
2.5 KiB
Markdown
62 lines
2.5 KiB
Markdown
# WSG Examples
|
|
|
|
The examples are organized into **four category folders**, one per theme. Each
|
|
folder has its own `README.md` documenting its examples in detail (what they
|
|
demonstrate, how to run them, keyboard controls, what to observe).
|
|
|
|
| Folder | Theme | Examples |
|
|
|--------|-------|----------|
|
|
| [meshes/](meshes/README.md) | Geometry, materials, file import, low-level workflow | `simple`, `cube`, `pbr`, `import`, `manual` |
|
|
| [lights/](lights/README.md) | Light types, shadow mapping, emissive materials | `shadow`, `shadow_test`, `spot_test`, `emissive` |
|
|
| [cameras/](cameras/README.md) | Camera-driven rendering (frustum culling) | `culling` |
|
|
| [effects/](effects/README.md) | HDR, tone mapping, post-process, full showcase | `demo`, `bloom`, `hdr`, `msaa`, `fog`, `dof` |
|
|
|
|
## Running an example
|
|
|
|
Example **names are stable** — from the repo root:
|
|
|
|
```sh
|
|
cargo run -p wsg-lib --example <name>
|
|
```
|
|
|
|
Examples gated behind a Cargo feature need the feature too:
|
|
|
|
```sh
|
|
cargo run -p wsg-lib --example import --features import-obj
|
|
```
|
|
|
|
All examples are **self-contained**: procedural textures, hard-coded geometries,
|
|
no on-disk assets. All use the declarative API (`AppBuilder` + `AppHandler`)
|
|
except `manual`, which demonstrates the low-level workflow instead.
|
|
|
|
> **Where do the files live?** Examples live in subfolders
|
|
> (`examples/<folder>/<name>.rs`). Cargo only auto-discovers top-level
|
|
> `examples/*.rs`, so every example is declared explicitly in
|
|
> [`lib/Cargo.toml`](../Cargo.toml) with its `path`. This keeps
|
|
> `--example <name>` working while allowing the folder organization.
|
|
|
|
## Suggested learning path
|
|
|
|
1. `simple` — the minimal declarative workflow (flat unlit quad, ~15 lines)
|
|
2. `cube` — the 3D MVP: a textured, lit, spinning cube
|
|
3. `pbr` — PBR materials and normal mapping
|
|
4. `spot_test`, `shadow_test` — isolated light and shadow behavior
|
|
5. `hdr` → `emissive` → `bloom` — the HDR chain, step by step
|
|
6. `culling` — GPU-driven frustum culling
|
|
7. `demo` — everything combined
|
|
8. `manual` — what the `App` facade actually encapsulates
|
|
|
|
## Adding your own example
|
|
|
|
1. Create `lib/examples/<folder>/my_example.rs` (pick the matching category;
|
|
add a new folder + README if needed).
|
|
2. Declare it in `lib/Cargo.toml` (Cargo won't discover it otherwise):
|
|
```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 it in the folder's `README.md` (and in `docs/user/examples.md`).
|