# 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`).