# 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 (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 |

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