primitive meshes

docs/user/README.md

@@ -20,6 +20,7 @@ GPU graphics background is required.
 | [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` |
 | [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 |
@@ -27,6 +28,31 @@ GPU graphics background is required.
 
 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](../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)