Jérôme Bousquié
3.5 KiB
User documentation — WSG
Usage documentation for the wsg-lib crate: how to build a 3D rendering application
without touching wgpu directly. It targets a developer with basic Rust knowledge; no prior
GPU graphics background is required.
Not to be confused: these pages explain how to use the API. The technical documentation (internal architecture, design decisions, future targets) lives in ../tech/, and the exhaustive API reference is generated by rustdoc (
cargo doc -p wsg-lib --no-deps).
Where to start
- Quickstart — your first window and your first object, in ~30 lines.
- Then, at your own pace, depending on what you need:
| Page | Topic |
|---|---|
| Meshes | Geometries: procedural primitives, custom Geometry, entities and Transform |
| Materials & textures | Appearance: the standard shader, unlit mode, diffuse textures |
| Lights | Directional, point, spot, ambient, MAX_LIGHTS |
| Shadows | Shadow mapping: picking the casting light, the packed-index pitfall |
| Mesh & primitives | Procedural generators + file import (OBJ), feature-gated |
| HDR & tone mapping | Offscreen float render + ACES/Reinhard, opt-in via with_hdr |
| GPU-driven rendering | GPU world matrices + indirect draws, opt-in frustum culling |
| Camera & input | Active camera, orbital controller, unified keyboard/mouse state |
| Examples | The 7 repo examples, the advanced manual workflow, adding your own example |
The pages are cross-linked: each page ends with a link to the next one.
Design principle: opt-in = zero cost
WSG follows a strict rule: a feature you don't enable costs nothing at runtime.
| Feature | How to enable | If NOT enabled |
|---|---|---|
| Shadows | scene.set_shadow_caster(Some(idx)) |
No shadow map allocated, no depth pass, no PCF sampling |
| HDR + Tone mapping | AppBuilder::with_hdr(ToneMapper::Aces) |
No offscreen texture, no TM pass, direct-to-surface render |
| GPU-driven culling | AppBuilder::with_gpu_driven(true) |
No compute pipeline, no indirect draw buffers |
| LOD | scene.create_mesh_with_lod(…, levels) |
Single-level mesh, no decimation, no hysteresis |
| Primitives | Cargo feature prim-* (default: all) |
Not compiled at all |
| File import | Cargo feature import-* |
Not compiled at all |
The distinction matters:
- Runtime opt-in (shadows, HDR, culling, LOD): the code is compiled into your binary but is completely inert if you never call the activation method. No GPU resources are allocated, no passes execute, no per-frame overhead. The cost of the code being in the binary is a few KB — negligible.
- Compile-time opt-in (primitives, import): the code is not compiled at all unless you opt in via Cargo features. This matters when you want to minimize compile time or binary size for a minimal build.
You can mix both: build with --no-default-features --features "prim-cube" for a minimal
binary, then enable shadows/HDR at runtime only for the scenes that need them.
Links
- Technical documentation (architecture): ARCHI_APP · ARCHI_RENDU · ARCHI_CPU_GPU · ARCHI_ARENES · FRAME_LOOP
- Root README · ROADMAP · DRAFT
- Full API reference:
cargo doc -p wsg-lib --no-deps