wsg/docs/user/examples.md

Examples

Seven examples live in 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, Materials (§ unlit)
cube	cargo run -p wsg-lib --example cube	The 3D MVP: a textured (checkerboard) cube, lit (directional + point + spot), spinning	Meshes, Materials, Lights
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
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
spot_test	cargo run -p wsg-lib --example spot_test	Isolated spot (ambient nearly zero): the directed beam, the penumbra, the attenuation	Lights
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; the two-layer architecture is detailed in ARCHI_APP and FRAME_LOOP.

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 · Quickstart · Camera & input
• Root README · ROADMAP