# WSG — User documentation

WSG (WGPU Simple Graphics) is a 3D graphics engine built on top of
[wgpu](https://docs.rs/wgpu) and [winit](https://docs.rs/winit).
It deliberately provides **no scene-graph abstraction**: you create resources,
place entities, and write the frame loop yourself. The engine handles the rest
(GPU context, compilation, command encoding, presentation).

## Where to start

1. [Quickstart](quickstart.md) — your first window and your first object, in ~30 lines.
2. Then, at your pace, pick a **topic folder** (which mirrors the example folders in
   [`lib/examples/`](../../lib/examples/README.md) — each page is paired with its examples):

| Folder | Pages |
|--------|-------|
| [`meshes/`](meshes/README.md) | [Meshes](meshes/meshes.md) — geometries, entities and `Transform` · [Geometry sources](meshes/sources.md) — procedural generators + file import · [Materials & textures](meshes/materials.md) — the `standard` shader, unlit mode, textures |
| [`lights/`](lights/README.md) | [Lights](lights/lights.md) — directional/point/spot/ambient, `MAX_LIGHTS` · [Shadows](lights/shadows.md) — shadow mapping · [Emissive + Exposure](lights/emissive-exposure.md) |
| [`cameras/`](cameras/README.md) | [Camera & input](cameras/camera-input.md) — orbital controller, unified input · [GPU-driven rendering](cameras/gpu-driven.md) — culling, LOD |
| [`effects/`](effects/README.md) | [HDR](effects/hdr.md) · [Bloom](effects/bloom.md) · [MSAA](effects/msaa.md) · [Fog](effects/fog.md) · [DoF](effects/dof.md) |

Plus [Examples](examples.md) — the 16 examples of the repo in 4 folders, the advanced
`manual` workflow, and how to add your own example.

The pages are cross-linked: each page ends with links to its related pages.

## Design principles

- **Explicit over magic**: no scene graph, no ECS, no hidden state machine. What you write
  is what runs.
- **The handler drives the loop**: `AppHandler` is the only required trait (`setup`,
  `update`, `render` + optional event hook).
- **String IDs everywhere**: meshes, materials, textures and entities are referenced by
  label — no integer handles to manage, errors are readable.
- **Safe core, `unsafe` at the edges**: the public API is fully safe; `unsafe` is confined
  to the raw-pointer interop layer.
- **Feature-gated primitives**: every primitive and importer behind a Cargo feature
  (`prim-cube`, `import-obj`, …) — default is `all-prims` + `import-obj`.

## Documentation tree

```
README.md            this index (the one you are reading)
quickstart.md        the 30-line path to a window + a cube
examples.md          the 16 repo examples, the manual workflow, adding your own
meshes/              meshes, geometry sources, materials & textures
lights/              lights, shadows, emissive + exposure
cameras/             camera & input, GPU-driven rendering (culling, LOD)
effects/             HDR, bloom, MSAA, fog, DoF
```

## Links

- [Root README](../../README.md)
- Technical docs: [ARCHI_APP](../tech/ARCHI_APP.md) · [FRAME_LOOP](../tech/FRAME_LOOP.md) ·
  [ARCHI_CPU_GPU](../tech/ARCHI_CPU_GPU.md) · [ARCHI_RENDU](../tech/ARCHI_RENDU.md)
- [ROADMAP](../ROADMAP.md)