eng doc
This commit is contained in:
Jérôme Bousquié
+42
-49
@@ -1,64 +1,57 @@
|
||||
# User documentation — WSG
|
||||
# WSG — User documentation
|
||||
|
||||
**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`).
|
||||
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 own pace, depending on what you need:
|
||||
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):
|
||||
|
||||
| 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 16 repo examples in 4 folders (`meshes/`, `lights/`, `cameras/`, `effects/`), the advanced `manual` workflow, adding your own example |
|
||||
| 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) |
|
||||
|
||||
The pages are cross-linked: each page ends with a link to the next one.
|
||||
Plus [Examples](examples.md) — the 16 examples of the repo in 4 folders, the advanced
|
||||
`manual` workflow, and how to add your own example.
|
||||
|
||||
## Design principle: opt-in = zero cost
|
||||
The pages are cross-linked: each page ends with links to its related pages.
|
||||
|
||||
WSG follows a strict rule: **a feature you don't enable costs nothing at runtime**.
|
||||
## Design principles
|
||||
|
||||
| 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 |
|
||||
- **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`.
|
||||
|
||||
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.
|
||||
## Documentation tree
|
||||
|
||||
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.
|
||||
```
|
||||
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
|
||||
|
||||
- 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`
|
||||
- [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)
|
||||
|
||||
Reference in New Issue
Block a user