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 15×15, objets hors frustum ignorés)
msaa	MSAA 4× (anti-aliasing multi-échantillons, arêtes lisses)
fog	Brouillard de distance (3 modes : linéaire, exp, exp²)
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).

---

msaa — MSAA 4× (Anti-aliasing)

Démontre l'anti-aliasing multi-échantillons : les arêtes des objets (cube, sphère) sont lisses au lieu d'être "en escalier". La scène contient un cube (arêtes nettes), une sphère (silhouette courbe) et un petit cube près de la caméra (aliasing maximal).

cargo run -p wsg-lib --example msaa

Touches

Touche	Action
Glisser (LMB)	Orbiter la caméra
Molette	Zoom
R	Reset caméra
M	Afficher le nombre d'échantillons

Pour comparer avec/sans MSAA

Supprimer la ligne .with_msaa(4) dans le source et recompiler : la scène est identique, seules les arêtes diffèrent (escaler vs lisse).

Note

: MSAA est un réglage de build-time (allocation de textures multi-échantillons). Il fonctionne indépendamment de HDR : avec HDR, la texture MSAA est Rgba16Float et résout dans la texture HDR avant bloom/TM.

---

fog — Brouillard de distance

Démontre les 3 modes de brouillard : linéaire, exponentiel, exponentiel². La scène contient une rangée de cubes qui s'éloignent et des sphères dispersées sur un grand plan au sol. Le brouillard fond les objets vers une couleur de fond, créant l'illusion d'un monde infini.

cargo run -p wsg-lib --example fog --features "all-prims"

Touches : 1 = linéaire, 2 = exp, 3 = exp², 4 = désactivé, R = reset.

Le brouillard est appliqué dans le shader fragment principal (après l'éclairage, avant le tone mapping). Il utilise la distance euclidienne du fragment à la caméra.

---

dof — Depth of Field (bokeh cinématique)

Démontre le flou de profondeur de champ : un objet au centre reste net tandis que le premier et arrière-plan se flouent selon leur distance au plan de mise au point. Crée un effet d'attention naturelle (type cinématique).

La scène contient un cube de focus au centre, des sphères en premier plan (proches) et des cubes en arrière-plan (loin), sur un plan au sol.

cargo run -p wsg-lib --example dof --features "all-prims"

Touches : 1 = cinématique, 2 = subtil, 3 = focus 2m, 4 = focus 10m, 5 = off, R = reset.

DoF opère en HDR linéaire (après bloom, avant tone mapping). Deux passes : CoC (depth → rayon de flou par pixel) puis blur disque 12-taps à rayon variable.

---

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.

---

pbr — PBR Metallic/Roughness + Normal Mapping (Étape 27)

Démonstration du workflow PBR Cook-Torrance : GGX distribution + Smith visibility + Schlick Fresnel + IBL hémisphérique + normal mapping.

cargo run -p wsg-lib --example pbr

Touche	Action
Drag (LMB)	Orbite caméra
Molette	Zoom
R	Reset caméra

Scène : 6 matériaux PBR (métal miroir, plastique, rouillé, céramique, bump map, sol matte). Le cube avec normal map montre des bumps procéduraux (sin wave).