Jérôme Bousquié
58 lines
3.1 KiB
Markdown
58 lines
3.1 KiB
Markdown
# 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)
|