wsg/docs/user/README.md

# 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/](../tech/ARCHI_APP.md), and the exhaustive API reference is generated by rustdoc
> (`cargo doc -p wsg-lib --no-deps`).

## Where to start

1. [Quickstart](quickstart.md) — your first window and your first object, in ~30 lines.
2. Then, at your own pace, depending on what you need:

| Page | Topic |
|-------|-------|
| [Meshes](meshes.md) | Geometries: procedural primitives, custom `Geometry`, entities and `Transform` |
| [Materials & textures](materials.md) | Appearance: the `standard` shader, unlit mode, diffuse textures |
| [Lights](lights.md) | Directional, point, spot, ambient, `MAX_LIGHTS` |
| [Shadows](shadows.md) | Shadow mapping: picking the casting light, the packed-index pitfall |
| [Mesh & primitives](mesh.md) | Procedural generators + file import (OBJ), feature-gated |
| [HDR & tone mapping](hdr.md) | Offscreen float render + ACES/Reinhard, opt-in via `with_hdr` |
| [MSAA (anti-aliasing)](msaa.md) | Multi-sample edge smoothing, opt-in via `with_msaa(4)` |
| [Fog (distance)](fog.md) | Distance fog (3 modes), masks world edges, opt-in via `with_fog()` |
| [DoF (depth of field)](dof.md) | Cinematic bokeh blur, focus plane, opt-in via `with_dof()` |
| [GPU-driven rendering](gpu-driven.md) | GPU world matrices + indirect draws, opt-in frustum culling |
| [Camera & input](camera-input.md) | Active camera, orbital controller, unified keyboard/mouse state |
| [Examples](examples.md) | 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 |
| MSAA | `AppBuilder::with_msaa(4)` | Single-sample (1×), zero overhead |
| 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](../tech/ARCHI_APP.md) · [ARCHI_RENDU](../tech/ARCHI_RENDU.md) · [ARCHI_CPU_GPU](../tech/ARCHI_CPU_GPU.md) · [ARCHI_ARENES](../tech/ARCHI_ARENES.md) · [FRAME_LOOP](../tech/FRAME_LOOP.md)
- [Root README](../../README.md) · [ROADMAP](../ROADMAP.md) · [DRAFT](../DRAFT.md)
- Full API reference: `cargo doc -p wsg-lib --no-deps`