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/; each folder has its own README (description + how to run): meshes/, lights/, cameras/, effects/.

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, Materials
cube	meshes	A rotating cube: point + spot light, uv_texture.jpg UV-atlas texture	cargo run -p wsg-lib --example cube	Meshes, Materials, Lights
pbr	meshes	PBR materials (metal/roughness) + real textures: cave.jpg albedo, caveNormal.jpg normal map, ground.jpeg floor	cargo run -p wsg-lib --example pbr	Materials
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
manual	meshes	Advanced: the full manual workflow — buffers, pipelines, command encoding, no helpers	cargo run -p wsg-lib --example manual	ARCHI_APP, FRAME_LOOP
shadow	lights	Shadow mapping: the classic pitfall — the packed-index shadow caster	cargo run -p wsg-lib --example shadow	Shadows
shadow_test	lights	Shadow mapping in isolation (cleared list → your light is index 0)	cargo run -p wsg-lib --example shadow_test	Shadows
spot_test	lights	A single spotlight (cone + penumbra), ambient nearly zero	cargo run -p wsg-lib --example spot_test	Lights
emissive	lights	Emissive materials + HDR glow, runtime exposure (+/-/0 keys)	cargo run -p wsg-lib --example emissive	Emissive & exposure
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
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
bloom	effects	HDR + bloom: threshold → blur → composite	cargo run -p wsg-lib --example bloom	Bloom
hdr	effects	HDR + tone mapping (ACES / Reinhard), emissive showcase	cargo run -p wsg-lib --example hdr	HDR
msaa	effects	4x MSAA anti-aliasing on the swapchain	cargo run -p wsg-lib --example msaa	MSAA
fog	effects	Distance fog, 3 modes switchable at runtime (linear / exponential / exp²)	cargo run -p wsg-lib --example fog	Fog
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

Texture assets: the multi-mesh examples use real image files from lib/examples/assets/textures/ (see the Texture assets section there for the full table): uv_texture.jpg (UV atlas visualization), ground.jpeg (tiled floor albedo), stonewall.jpg, and the cave.jpg + caveNormal.jpg albedo/normal pair. Paths are resolved against CARGO_MANIFEST_DIR, so the examples run from any working directory.

The manual example: bypassing the helpers

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 and FRAME_LOOP.

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

   [[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 · Quickstart
• Root README · ROADMAP