wsg/lib/examples/README.md

Exemples WSG

Chaque exemple est autonome et illustre un effet ou une fonctionnalité spécifique de la bibliothèque. Tous utilisent l'API déclarative (AppBuilder + AppHandler).

Lancer un exemple

cargo run -p wsg-lib --example <nom>

Exemple	Effet démontré
demo	Showcase complet (tous les effets combinés)
bloom	Post-process bloom (glow autour des zones brillantes)
hdr	HDR + Tone Mapping (ACES) + contrôle d'exposition
emissive	Matériaux émissifs (intensités croissantes 0 → 4.0)
shadow	Shadow mapping (ombre portée directionnelle)
culling	Culling GPU-driven (grille 20×20, objets hors frustum ignorés)
manual	Workflow bas niveau (Context + Renderer + PipelineCache)
import	Import de fichier OBJ (non graphique, stdout)

---

demo — Showcase complet

Combine tous les effets : primitives LOD, textures procédurales, lumières (directional + point + spot), ombres, HDR/ACES, exposition, émissif, bloom, culling.

cargo run -p wsg-lib --example demo

Touches

Touche	Action
Glisser (LMB)	Orbiter la caméra
Molette	Zoom
R	Reset caméra
1 / 2 / 3	Presets : face / côté / dessus
+ / -	Exposition ×1.3 / ÷1.3
0	Reset exposition

---

bloom — Post-process Bloom

Deux sphères émissives (orange intensité 2.0, bleue intensité 3.0) produisent un halo visible. Le cube et le sol servent de référence (non-émissifs).

Le bloom est un pipeline 4 passes GPU : threshold → blur H → blur V → composite.

cargo run -p wsg-lib --example bloom

Touches

Touche	Action
Glisser (LMB)	Orbiter la caméra
Molette	Zoom
R	Reset caméra
+ / -	Bloom threshold +0.1 / −0.1
[ / ]	Bloom intensity +0.1 / −0.1
I / O	Bloom radius +0.5 / −0.5
E / Q	Exposition ×1.3 / ÷1.3
0	Reset exposition

Ce qu'on voit

• threshold bas (0.0) : tout l'image "bloom" (effet très diffus).
• threshold élevé (2.0+) : seules les sphères émissives brillantes produisent du glow.
• intensity 0.0 : pas de glow visible (même si le threshold extrait des pixels).
• radius grand (10+) : le glow s'étend sur une grande zone.

---

hdr — HDR + Tone Mapping

Démontre le rendu HDR avec la courbe ACES Filmic. Trois objets :

• Cube : éclairage normal (aucun émissif) — référence LDR.
• Sphère brillante (émissif 3.0) : sans HDR, elle serait clampée à blanc. Avec ACES, les highlights "roulent" doucement vers le blanc (rolloff).
• Sphère sombre (émissif 0.3) : reste sombre même à haute exposition.

cargo run -p wsg-lib --example hdr

Touches

Touche	Action
Glisser (LMB)	Orbiter la caméra
Molette	Zoom
R	Reset caméra
E	Exposition ×1.3 (plus clair)
Q	Exposition ÷1.3 (plus sombre)
0	Reset exposition à 1.0

Ce qu'on voit

• À exposition 1.0 : la sphère brillante est blanche mais avec des détails (rolloff ACES).
• À exposition haute (E×E×E) : la scène s'éclaircit, la sphère brillante reste blanche (saturée), mais le cube gagne en détail.
• À exposition basse (Q×Q) : tout s'assombrit, la sphère brillante devient orangée (les valeurs HDR > 1.0 sont compressées).

Note

: le tone mapper est compilé dans le pipeline au build. Pour comparer ACES vs Reinhard, modifier ToneMapper::Aces → ToneMapper::Reinhard dans le source.

---

emissive — Matériaux Émissifs

Cinq sphères alignées avec des intensités émissives croissantes :

Sphere	Couleur	Intensité	Effet
1	Gris	0.0	Aucune glow (référence)
2	Orange	0.5	Légère lueur
3	Jaune	1.0	Lueur visible
4	Vert	2.0	Glow HDR (au-delà de 1.0)
5	Bleu	4.0	Glow intense (saturation)

Avec HDR, les intensités > 1.0 produisent un vrai "glow" (les valeurs dépassent [0,1] en espace linéaire). Sans HDR, elles seraient clampées à blanc.

cargo run -p wsg-lib --example emissive

Touches

Touche	Action
Glisser (LMB)	Orbiter la caméra
Molette	Zoom
R	Reset caméra
E / Q	Exposition ×1.3 / ÷1.3
0	Reset exposition
C	Cycler le multiplicateur d'émissif (1× → 2× → 0.5× → ...)

Ce qu'on voit

• La sphère 1 (intensité 0) est simplement éclairée par la lumière directionnelle.
• Les sphères 2-5 brillent de leur propre lumière, indépendamment de l'éclairage.
• C double ou réduit toutes les intensités en même temps (pour voir l'effet HDR).

---

shadow — Shadow Mapping

Quatre objets (cube, sphère, cône, cylindre) sur un sol, éclairés par une lumière directionnelle qui projette des ombres. La qualité des ombres est contrôlée par ShadowConfig (taille de la shadow map, biais anti-acne).

cargo run -p wsg-lib --example shadow

Touches

Touche	Action
Glisser (LMB)	Orbiter la caméra
Molette	Zoom
R	Reset caméra
1	Vue de face
2	Vue de côté
3	Vue de dessus (voir la forme des ombres clairement)
L	Changer la direction de la lumière (3 presets)

Ce qu'on voit

• Le cube tourne lentement → son ombre bouge sur le sol.
• La sphère a une transition ombre/lumière douce (terminateur lisse).
• Le cône produit une ombre triangulaire distincte.
• En vue de dessus (3), on voit la forme exacte des ombres projetées.
• La taille de la shadow map (1024 par défaut) détermine la résolution : modifier SHADOW_MAP_SIZE en haut du fichier pour tester 256 (pixelisé) ou 2048 (net).

---

culling — GPU Frustum Culling

Une grille de 15×15 = 225 cubes est placée sur un grand sol. Le culling GPU-driven (compute shader) détermine quels cubes sont visibles dans le frustum de la caméra et zéro leurs draw args indirects — zéro coût CPU.

cargo run -p wsg-lib --example culling

Touches

Touche	Action
Glisser (LMB)	Orbiter la caméra (regarder autour)
Molette	Zoom in/out
R	Reset (vue de dessus)
1	Vue de face (les cubes derrière sont culled)
2	Vue de côté
3	Vue de dessus (voir toute la grille)

Ce qu'on voit

• En vue de dessus (3) : toute la grille 20×20 est visible.
• Orbiter à 90° : les cubes derrière la caméra ne sont pas dessinés (culled).
• Zoomer très près : seuls les cubes proches du plan de near sont rendus.
• Les cubes tournent lentement (phases décalées) → le culling est dynamique (un cube peut entrer/sortir du frustum au cours d'une frame).

Note

: le culling est activé via AppBuilder::with_culling(true). Le modifier à false dans le source désactive le culling (tous les 400 cubes sont toujours dessinés, même hors écran).

---

manual — Workflow bas niveau

Démontre l'API sans la façade App : utilisation directe de Context, Renderer, PipelineCache, Mesh, Material. Rend un quad coloré (unlit).

Utile pour comprendre ce que la façade App encapsule.

cargo run -p wsg-lib --example manual

Pas de touches — rendu statique (quad unlit, 4 couleurs).

---

import — Import de fichier OBJ

Exemple non graphique : parse un fichier .obj et affiche les statistiques (nombre de sommets, normales, UVs, indices, bounding box) sur stdout.

# Avec un fichier :
cargo run -p wsg-lib --example import --features import-obj -- /path/to/model.obj

# Sans argument (triangle de démonstration) :
cargo run -p wsg-lib --example import --features import-obj

Pas de touches — s'exécute et quitte.