wsg/docs/user/examples.md

# Examples

16 examples in **4 folders** (mirroring the topic folders of this documentation), covering the
full range of the engine — from a 2D quad to GPU-driven rendering.

All examples are in [`lib/examples/`](../../lib/examples/README.md); each folder has its own
README (description + how to run): [`meshes/`](../../lib/examples/meshes/README.md),
[`lights/`](../../lib/examples/lights/README.md), [`cameras/`](../../lib/examples/cameras/README.md),
[`effects/`](../../lib/examples/effects/README.md).

| Example | Folder | What it shows | How to run | Corresponding page |
|---------|--------|---------------|------------|--------------------|
| `simple` | meshes | A 2D quad with vertex colors, unlit mode (~30 lines) | `cargo run -p wsg-lib --example simple` | [Quickstart](quickstart.md), [Materials](meshes/materials.md) |
| `cube` | meshes | A rotating cube: point + spot light, checkerboard texture, procedural normal map, orbit/zoom | `cargo run -p wsg-lib --example cube` | [Meshes](meshes/meshes.md), [Materials](meshes/materials.md), [Lights](lights/lights.md) |
| `pbr` | meshes | A procedural PBR material (metal/roughness) + a checker diffuse | `cargo run -p wsg-lib --example pbr` | [Materials](meshes/materials.md) |
| `import` | meshes | Wavefront **OBJ** import (CLI: file path as argument, procedural cube as fallback) | `cargo run -p wsg-lib --example import --features import-obj -- model.obj` | [Geometry sources](meshes/sources.md) |
| `manual` | meshes | **Advanced**: the full manual workflow — buffers, pipelines, command encoding, no helpers | `cargo run -p wsg-lib --example manual` | [ARCHI_APP](../tech/ARCHI_APP.md), [FRAME_LOOP](../tech/FRAME_LOOP.md) |
| `shadow` | lights | Shadow mapping: the classic pitfall — the packed-index shadow caster | `cargo run -p wsg-lib --example shadow` | [Shadows](lights/shadows.md) |
| `shadow_test` | lights | Shadow mapping in isolation (cleared list → your light is index 0) | `cargo run -p wsg-lib --example shadow_test` | [Shadows](lights/shadows.md) |
| `spot_test` | lights | A single spotlight (cone + penumbra), ambient nearly zero | `cargo run -p wsg-lib --example spot_test` | [Lights](lights/lights.md) |
| `emissive` | lights | Emissive materials + HDR glow, runtime exposure (+/-/0 keys) | `cargo run -p wsg-lib --example emissive` | [Emissive & exposure](lights/emissive-exposure.md) |
| `culling` | cameras | **GPU-driven**: world matrices + indirect draws on the GPU, opt-in frustum culling, LOD | `cargo run -p wsg-lib --example culling` | [GPU-driven](cameras/gpu-driven.md) |
| `demo` | effects | The full showcase: all features combined (shadows, HDR, bloom, MSAA, fog, lights, orbital camera) | `cargo run -p wsg-lib --example demo` | [All pages](README.md) |
| `bloom` | effects | HDR + bloom: threshold → blur → composite | `cargo run -p wsg-lib --example bloom` | [Bloom](effects/bloom.md) |
| `hdr` | effects | HDR + tone mapping (ACES / Reinhard), emissive showcase | `cargo run -p wsg-lib --example hdr` | [HDR](effects/hdr.md) |
| `msaa` | effects | 4x MSAA anti-aliasing on the swapchain | `cargo run -p wsg-lib --example msaa` | [MSAA](effects/msaa.md) |
| `fog` | effects | Distance fog, 3 modes switchable at runtime (linear / exponential / exp²) | `cargo run -p wsg-lib --example fog` | [Fog](effects/fog.md) |
| `dof` | effects | Depth of field: Gaussian blur scaled by defocus distance, cinematic bokeh; focus presets 1-4 + continuous zoom | `cargo run -p wsg-lib --example dof` | [DoF](effects/dof.md) |

## The `manual` example: bypassing the helpers

[`manual.rs`](../../lib/examples/meshes/manual.rs) renders a rotating cube with **no
high-level helper at all** — no `Scene`, no `Renderer` convenience API, no `AppHandler`
default `render()`. It shows the full pipeline:

1. **`setup`**: manual creation of vertex/index buffers, bind groups, render/compute
   pipelines, the swapchain.
2. **`render` (overridden)**: manual command encoding per frame (clear, draw, present) —
   the handler controls **every** `CommandEncoder` operation.
3. **Uniforms written by hand** with `queue.write_buffer` (projection, view, model matrices).

This is the reference for what the high-level API does under the hood, and the starting
point for features that don't exist yet in the engine (custom pipelines, post-processes,
custom compute). The technical details are in [ARCHI_APP](../tech/ARCHI_APP.md) and
[FRAME_LOOP](../tech/FRAME_LOOP.md).

Rule of thumb: **use `AppHandler` + `Scene` for everything the engine already does, and drop
to `manual` style only when you need what it doesn't** — the two styles can be mixed in the
same app (e.g. `Scene` for the scene, a manual post-process pass in `render()`).

## Adding your own example

1. Create `lib/examples/<folder>/<name>.rs` — pick the folder it belongs to
   (`meshes` / `lights` / `cameras` / `effects`).
2. Declare the `[[example]]` entry in `lib/Cargo.toml` (the folder structure means Cargo
   no longer auto-discovers examples):

   ```toml
   [[example]]
   name = "<name>"
   path = "examples/<folder>/<name>.rs"
   ```

3. Required features: the base crate has no primitives by default in examples — declare
   `required-features` if your example uses them (e.g. `required-features = ["prim-cube"]`).
4. Register it in the folder's README and in the table above.
5. Verify: `cargo build --workspace --examples` + run it.

## Links

- [User README](README.md) · [Quickstart](quickstart.md)
- [Root README](../../README.md) · [ROADMAP](../ROADMAP.md)