Jérôme Bousquié
48 lines
3.2 KiB
Markdown
48 lines
3.2 KiB
Markdown
# 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)
|