jerome/wsg
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

MSAA

Browse Source
This commit is contained in:
Jérôme Bousquié
2026-09-25 11:20:20 +02:00
parent 35aeb769a8
commit 9614156848
15 changed files with 822 additions and 333 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/DRAFT.md
+257 -302
View File
@@ -1,343 +1,298 @@
# Étape 23 — Bloom (post-process HDR)
# Étape 24 — MSAA 4× (Anti-aliasing multi-échantillons)
**Statut** : ✅ Terminé
**Prérequis** : HDR + Tone Mapping (Étape 20 ✅), Emissive (Étape 22 ✅)
**Statut** : ⬜ En cours
**Roadmap** : 6.4
**Prérequis** : Pipeline HDR (étape 20) + Bloom (étape 23)
---
## Objectif
## Problème
Ajouter un effet **bloom** : les zones très brillantes de la scène (emissive > 1.0, spéculaires,
overbright lighting) diffusent une lueur vers les zones voisines. C'est l'effet "glow" qui rend
les néons et les sources de lumière visuellement impactants.
Sans anti-aliasing, les bords des géométries présentent du **staircasing** (aliasing) :
les silhouettes ont des escaliers visibles, surtout sur les contours fins et les
lointains. C'est le défaut visuel le plus flagrant d'un moteur sans post-process.
Le bloom est un **post-process** qui opère sur la texture HDR, entre le rendu de la scène et le
tone mapping. Il est **opt-in** (`AppBuilder::with_bloom(...)`) et n'a **zéro coût** quand
désactivé (aucune texture/pipeline allouée).
## Solution
Rendre la scène avec **N échantillons par pixel** (4× par défaut), puis **résoudre**
(en moyenne) vers une texture single-sample. Le reste du pipeline (bloom, TM)
opère sur la texture résolue — aucun changement.
---
## Pipeline
## Pipeline actuel vs avec MSAA
### Sans HDR, sans MSAA (actuel)
```
Scene render → HDR texture (Rgba16Float, full res)
│
├─[bloom actif?]─→ 1. Threshold (half res) : extrait les pixels > threshold
│ 2. Blur H (half res) : Gaussian 9 taps
│ 3. Blur V (half res) : Gaussian 9 taps
│ 4. Composite (full res) : HDR += bloom × intensity
│
▼
TM pass → surface
Scene → swapchain (Rgba8UnormSrgb) → present
```
Quand bloom est désactivé : `Scene → HDR → TM → surface` (comme aujourd'hui, zéro overhead).
### Sans HDR, avec MSAA
```
Scene → MSAA texture (4×, format surface) ──resolve──→ swapchain → present
+ MSAA depth (4×)
```
Le resolve est fait **automatiquement par wgpu** dans le render pass
(`resolve_target` sur la color attachment).
**4 passes fullscreen** supplémentaires (seulement si HDR + bloom actifs).
### Avec HDR, sans MSAA (actuel)
```
Scene → HDR texture (Rgba16Float) → [Bloom] → TM → swapchain → present
```
### Avec HDR, avec MSAA (nouveau)
```
Scene → MSAA HDR (4×, Rgba16Float) ──resolve──→ HDR texture (Rgba16Float)
+ MSAA depth (4×) → [Bloom] → TM → swapchain → present
```
**Principe** : MSAA s'insère **uniquement** entre le rasterizer et le premier
consommateur de la texture de scène. Les post-processes (bloom, TM) voient
toujours une texture single-sample.
---
## Composants
## Décisions de design
### `BloomConfig` (pub, dans `core/bloom.rs`)
```rust
pub struct BloomConfig {
/// Seuil de luminance (en unités HDR linéaires). Au-dessus → contribue au bloom.
/// Défaut : 1.0 (seul ce qui dépasse 1.0 "bloom" — les emissives > 1.0, les spéculaires).
pub threshold: f32,
/// Intensité du bloom (multiplicateur sur le résultat du blur). Défaut : 0.8.
pub intensity: f32,
/// Rayon du blur en pixels (à la résolution half-res). Défaut : 4.0.
pub radius: f32,
}
impl Default for BloomConfig { /* threshold=1.0, intensity=0.8, radius=4.0 */ }
```
### `BloomPipeline` (interne, dans `core/bloom.rs`)
```rust
struct BloomPipeline {
/// Texture half-res pour le bloom (Rgba16Float).
bright_texture: wgpu::Texture,
bright_view: wgpu::TextureView,
/// Texture half-res pour le blur ping-pong (2nd buffer).
blur_texture: wgpu::Texture,
blur_view: wgpu::TextureView,
/// Sampler linear pour le blur.
sampler: wgpu::Sampler,
/// Pipeline threshold (fullscreen → half-res).
threshold_pipeline: wgpu::RenderPipeline,
/// Pipeline blur (fullscreen half-res, direction via uniform).
blur_pipeline: wgpu::RenderPipeline,
/// Pipeline composite (full-res: HDR += bloom).
composite_pipeline: wgpu::RenderPipeline,
/// Bind groups pré-alloués.
threshold_bg: wgpu::BindGroup,
blur_bg_a: wgpu::BindGroup, // reads bright, writes blur
blur_bg_b: wgpu::BindGroup, // reads blur, writes bright (ping-pong)
composite_bg: wgpu::BindGroup, // reads HDR + bright
/// Uniform buffer pour le blur (direction + radius).
blur_uniform: wgpu::Buffer,
/// Uniform buffer pour le threshold (threshold value).
threshold_uniform: wgpu::Buffer,
/// Half-res dimensions.
width: u32,
height: u32,
}
```
### Shaders (3 fichiers WGSL)
#### `bloom_threshold.wgsl`
- Vertex : fullscreen triangle
- Fragment : lit la texture HDR (full res), calcule la luminance, sort `color × smoothstep(threshold, threshold+knee, lum)` ou `max(color - threshold, 0)` si `lum > threshold`, sinon `0`
- Écrit dans la texture half-res
#### `bloom_blur.wgsl`
- Vertex : fullscreen triangle (à la résolution half-res)
- Fragment : 9-tap Gaussian séparable. L'offset est `texel_size × radius × i` dans la direction donnée par l'uniform.
- Uniform : `vec2<f32> direction` (dx, dy), `f32 radius`
- Weights Gaussian : `[0.227027, 0.194595, 0.121622, 0.054054, 0.016216]` (symétrique)
#### `bloom_composite.wgsl`
- Vertex : fullscreen triangle (full res)
- Fragment : `result = hdr_color + bloom_color × intensity`
- Uniform : `f32 intensity`
- Lit les 2 textures (HDR full-res + bloom half-res, upscalé par le sampler linear)
---
## Shaders
### `bloom_threshold.wgsl`
```wgsl
// Fullscreen triangle vertex (même pattern que tonemap)
struct VsOut {
@builtin(position) pos: vec4<f32>,
@location(0) uv: vec2<f32>,
};
@vertex
fn vs_main(@builtin(vertex_index) vi: u32) -> VsOut {
var pos: vec2<f32>;
pos.x = f32((vi << 1) & 2) * 2.0 - 1.0;
pos.y = f32(vi & 2) * 2.0 - 1.0;
var out: VsOut;
out.pos = vec4<f32>(pos.x, -pos.y, 0.0, 1.0);
out.uv = vec2<f32>(pos.x * 0.5 + 0.5, 0.5 - pos.y * 0.5);
return out;
}
struct ThresholdUniforms {
threshold: f32,
knee: f32,
pad: vec2<f32>,
};
@group(0) @binding(0) var<uniform> tmu: ThresholdUniforms;
@group(0) @binding(1) var src_tex: texture_2d<f32>;
@group(0) @binding(2) var src_sampler: sampler;
@group(0) @binding(3) var<atomic u32> pad; // placeholder — not needed, use texture_storage
@fragment
fn fs_main(in: VsOut) -> @location(0) vec4<f32> {
let color = textureSample(src_tex, src_sampler, in.uv).rgb;
let lum = dot(color, vec3<f32>(0.2126, 0.7152, 0.0722));
// Soft knee: smooth transition above threshold
let soft = max(lum - tmu.threshold, 0.0);
let contrib = soft / (soft + tmu.knee); // 0..1 smooth
return vec4<f32>(color * contrib, 1.0);
}
```
### `bloom_blur.wgsl`
```wgsl
// Même VsOut / vs_main que threshold (fullscreen triangle)
struct BlurUniforms {
direction: vec2<f32>, // texel offset: (1/w, 0) or (0, 1/h)
radius: f32,
pad: vec2<f32>,
};
@group(0) @binding(0) var<uniform> bu: BlurUniforms;
@group(0) @binding(1) var src_tex: texture_2d<f32>;
@group(0) @binding(2) var src_sampler: sampler;
const W: array<f32, 5> = array<f32, 5>(
0.2270270270, 0.1945945946, 0.1216216216, 0.0540540541, 0.0162162162
);
@fragment
fn fs_main(in: VsOut) -> @location(0) vec4<f32> {
let center = textureSample(src_tex, src_sampler, in.uv).rgb;
var sum = center * W[0];
for (var i: u32 = 1u; i < 5u; i = i + 1u) {
let off = bu.direction * (f32(i) * bu.radius);
let s = textureSample(src_tex, src_sampler, in.uv + off).rgb
+ textureSample(src_tex, src_sampler, in.uv - off).rgb;
sum = sum + s * W[i];
}
return vec4<f32>(sum, 1.0);
}
```
### `bloom_composite.wgsl`
```wgsl
// Même VsOut / vs_main
struct CompositeUniforms {
intensity: f32,
pad: vec3<f32>,
};
@group(0) @binding(0) var<uniform> cu: CompositeUniforms;
@group(0) @binding(1) var hdr_tex: texture_2d<f32>;
@group(0) @binding(2) var hdr_sampler: sampler;
@group(0) @binding(3) var bloom_tex: texture_2d<f32>;
@group(0) @binding(4) var bloom_sampler: sampler;
@fragment
fn fs_main(in: VsOut) -> @location(0) vec4<f32> {
let hdr = textureSample(hdr_tex, hdr_sampler, in.uv).rgb;
let bloom = textureSample(bloom_tex, bloom_sampler, in.uv).rgb;
return vec4<f32>(hdr + bloom * cu.intensity, 1.0);
}
```
---
## Intégration dans `Renderer::render_scene`
```
Step 7: Main render pass → HDR texture (ou surface si pas HDR)
Step 8: [Bloom] Si HDR + bloom actifs :
8a. Threshold pass (HDR full → bright half)
8b. Blur H (bright half → blur half)
8c. Blur V (blur half → bright half) [ping-pong]
8d. Composite (HDR full + bright half → HDR full)
8e. write_buffer(exposure) — comme aujourd'hui
Step 9: TM pass (HDR full → surface)
```
Le composite **modifie la texture HDR in-place** (rend dans une 2ème texture puis swap, ou
rend directement dans la HDR texture si on utilise un ping-pong). En pratique : le composite
rend dans la `HDR texture` elle-même (le bind group lit la HDR comme input ET écrit dedans —
**NON**, c'est undefined behavior en wgpu).
**Solution** : le composite écrit dans un **3ème buffer full-res** (ou on swap les rôles :
le bloom écrit dans la HDR texture en lisant une copie). La solution la plus simple :
- Le threshold lit la HDR texture et écrit dans `bright` (half res)
- Le blur ping-ponge entre `bright` et `blur` (half res)
- Le composite lit la HDR texture + `bright` (half res) et écrit dans la **HDR texture**
(c'est OK car le composite est une pass séparée qui commence APRÈS que le threshold/blur
ont fini d'écrire — et le composite lit la HDR texture en input mais écrit aussi dedans)
Attendez — **non**, en wgpu/WebGPU, on ne peut PAS lire et écrire la même texture dans la même
render pass. Mais on peut le faire dans des **passes différentes** (le composite est une pass
séparée du threshold). Le problème est que le composite lit la HDR texture (qui n'a pas été
modifiée par threshold/blur — ils ont écrit dans bright/blur) et écrit dans la HDR texture.
C'est **valide** car c'est dans une render pass unique : le GPU ne permet pas de lire ET écrire
la même texture attachment dans la même pass.
**Solution propre** : utiliser un **ping-pong full-res** :
- `hdr_texture` (existante) : contient le rendu de la scène
- `bloom_composite_texture` (full-res, allouée avec le bloom) : reçoit le résultat du composite
- Le TM pass lit `bloom_composite_texture` au lieu de `hdr_texture`
Quand bloom est inactif : le TM lit `hdr_texture` directement (comme aujourd'hui).
| # | Décision | Rationale |
|---|----------|-----------|
| D1 | `AppBuilder::with_msaa(count)` — opt-in, zero cost désactivé | Principe WSG : chaque effet est optionnel |
| D2 | `sample_count` configurable (2, 4, 8) — default 4 | 4× est le bon rapport qualité/coût ; 8× pour du "max" |
| D3 | Texture MSAA **offscreen** (jamais le swapchain en MSAA direct) | Uniformité : même code path que HDR, resize plus simple |
| D4 | Depth buffer recréé en MSAA quand actif | Le depth doit avoir le même `sample_count` que le color |
| D5 | Resolve via `RenderPassColorAttachment::resolve_target` | Natif wgpu, pas de shader supplémentaire |
| D6 | **Aucun nouveau shader** | MSAA est une feature rasterizer, pas un post-process |
| D7 | Format MSAA = format de la cible (Rgba16Float si HDR, surface format sinon) | Le resolve produit la même texture qu'avant |
| D8 | Resize recrée les textures MSAA + depth | Même pattern que HDR resize |
| D9 | Bloom/TM inchangés — ils lisent la texture résolue (single-sample) | Zéro impact sur les passes post |
| D10 | `MsaaConfig { sample_count: u32 }` — public, re-exporté | API minimale, extensible |
---
## API utilisateur
| Composant | Changement |
|-----------|-----------|
| `AppBuilder` | `with_bloom(config: BloomConfig)` — active le bloom |
| `App` | `set_bloom_config(config)`, `bloom_enabled() -> bool` |
| `Renderer` | Champ `bloom: Option<BloomPipeline>`, `bloom_config: BloomConfig` |
| `core/mod.rs` | `pub mod bloom;` + re-export `BloomConfig` |
| `lib.rs` | Re-export `BloomConfig` |
| `prelude.rs` | Re-export `BloomConfig` |
```rust
use wsg_lib::prelude::*;
**Règle** : le bloom n'a d'effet que si HDR est actif. `with_bloom()` sans `with_hdr()` est
un no-op (log un warning).
let app = AppBuilder::new()
.title("MSAA Demo")
.with_hdr(ToneMapper::Aces)
.with_msaa(4) // ← 4 échantillons (2, 4, ou 8)
.with_bloom(BloomConfig::default())
.build()
.await?;
```
Sans `.with_msaa(...)` → comportement identique à aujourd'hui (0 échantillon overhead).
---
## Resize
## Implémentation
Au resize, si le bloom est actif :
- Recréer les textures half-res (bright, blur)
- Recréer le composite texture full-res
- Recréer les bind groups
- Mettre à jour les uniforms (dimensions)
### 24.1 — `MsaaConfig` (public)
Fichier : `lib/src/core/msaa.rs`
```rust
/// Configuration MSAA. `sample_count` doit être 2, 4, ou 8
/// (valeur supportée par le GPU — vérifiée à l'init).
#[derive(Clone, Copy, Debug)]
pub struct MsaaConfig {
pub sample_count: u32,
}
impl Default for MsaaCapable {
fn default() -> Self {
Self { sample_count: 4 }
}
}
```
### 24.2 — Champs `Renderer`
Ajouter à `Renderer` :
```rust
msaa_config: MsaaConfig, // toujours présent (sample_count=1 si désactivé)
msaa_color_texture: Option<wgpu::Texture>, // Some si msaa active
msaa_color_view: Option<wgpu::TextureView>,
msaa_depth_texture: Option<wgpu::Texture>,
msaa_depth_view: Option<wgpu::TextureView>,
```
Quand `msaa_config.sample_count > 1` :
- `msaa_color_texture` = texture `sample_count=N`, format = HDR ou surface
- `msaa_depth_texture` = texture depth `sample_count=N`
- Le render pass scène utilise ces views + `resolve_target`
Quand `sample_count == 1` :
- Tous les `Option` sont `None`
- Le render pass utilise la texture/view existante (comportement actuel)
### 24.3 — Allocation à l'init (`Renderer::new`)
```rust
let sample_count = msaa_config.map(|c| c.sample_count).unwrap_or(1);
// Vérifier que le format supporte ce sample_count
let formats = device.limits(); // ou surface.capabilities()
// Pour le surface : surface.capabilities().formats
// Pour l'offscreen : device.limits().max_color_attachments, etc.
// En pratique : Rgba16Float et Rgba8Unorm supportent 4× partout.
if sample_count > 1 {
let msaa_tex = device.create_texture(&TextureDescriptor {
size: Extent3d { width, height, depth_or_array_layers: 1 },
sample_count,
dimension: Dimension::D2,
format: target_format, // Rgba16Float ou surface format
usage: TextureUsages::RENDER_ATTACHMENT,
..
});
// + depth MSAA
}
```
### 24.4 — Render pass scène (modification `render_scene`)
Le render pass principal doit utiliser les views MSAA quand actif :
```rust
// Déterminer la color attachment
let (color_view, resolve_target) = if let Some(msaa_view) = &self.msaa_color_view {
// MSAA actif : render dans MSAA, resolve vers la texture single
let resolve = if self.hdr.is_some() {
Some(self.hdr.as_ref().unwrap().view.clone()) // resolve → HDR tex
} else {
Some(view.clone()) // resolve → swapchain
};
(msaa_view.clone(), resolve)
} else {
// Pas de MSAA : comportement actuel
let color_view = if let Some(hdr) = &self.hdr {
hdr.view.clone()
} else {
view.clone()
};
(color_view, None)
};
// Depth : MSAA ou single
let depth_view = if let Some(msaa_depth) = &self.msaa_depth_view {
msaa_depth.clone()
} else {
self.depth_view.clone()
};
encoder.render_pass(RenderPassDescriptor {
color_attachments: &[Some(RenderPassColorAttachment {
view: &color_view,
resolve_target: resolve_target.as_ref(),
load_op: LoadOp::Clear,
store_op: StoreOp::Store, // Store même en MSAA (wgpu gère le resolve)
})],
depth_stencil_attachment: Some(RenderPassDepthStencilAttachment {
view: &depth_view,
..
}),
..
});
```
### 24.5 — Resize
```rust
fn resize(&mut self, device, width, height) {
// ... resize depth existant ...
if self.msaa_config.sample_count > 1 {
// Recréer MSAA color + depth
self.msaa_color_texture = Some(create_msaa_texture(...));
self.msaa_color_view = Some(...);
self.msaa_depth_texture = Some(create_msaa_depth(...));
self.msaa_depth_view = Some(...);
}
// HDR resize existant
// Bloom resize existant
}
```
### 24.6 — Plomberie App/AppBuilder
```rust
// AppBuilder
pub fn with_msaa(mut self, sample_count: u32) -> Self {
assert!((2..=8).contains(&sample_count) && sample_count.is_power_of_two(),
"sample_count must be 2, 4, or 8");
self.msaa_config = Some(MsaaConfig { sample_count });
self
}
// App
pub fn msaa_enabled(&self) -> bool { ... }
pub fn set_msaa(&mut self, sample_count: u32) { ... } // nécessite resize
```
Plomberie : `AppBuilder → App → AppRunner → Renderer::new(msaa_config)`
### 24.7 — Re-exports
`lib.rs` + `prelude.rs` : `pub use crate::core::MsaaConfig;`
### 24.8 — Exemple `msaa.rs`
Scène simple (cube + sphere + ground) avec/without MSAA commutable à la runtime
(clavier `M`). Camera orbitale pour voir les bords de près.
Contrôles :
- `M` — toggle MSAA (nécessite un resize/recréation des textures)
- `R`/`1`/`2`/`3` — presets caméra
- Drag/wheel — orbit/zoom
### 24.9 — Documentation
- `docs/user/msaa.md` : activation, config, coûts, limitations
- `docs/user/README.md` : section "Anti-aliasing"
- `lib/examples/README.md` : entrée `msaa`
- `docs/ROADMAP.md` : 6.4 → ✅
---
## Décisions
## Coût GPU
| # | Décision | Justification |
|---|----------|---------------|
| D1 | 4 passes (threshold + blur H + blur V + composite) | Bonne qualité/performances. Un seul niveau de mip suffit pour un bloom "soft" |
| D2 | Résolution half-res pour le bloom | Standard. Le blur à half-res est 4× moins coûteux et le résultat upscalé par le sampler linear est lisse |
| D3 | Soft-knee threshold (pas un cutoff dur) | `soft/(soft+knee)` donne une transition douce, pas d'aliasing au seuil |
| D4 | Composite via ping-pong full-res (3ème texture) | Évite le conflit read/write sur la même texture dans une même pass |
| D5 | Bloom seulement si HDR actif | Le bloom opère en espace linéaire HDR. Sans HDR, les valeurs sont déjà clampées [0,1] → pas de "bright" à extraire |
| D6 | `BloomConfig` avec 3 champs (threshold, intensity, radius) | Minimum utile. Pas de multi-mip, pas de directional bloom pour MVP |
| D7 | Sampler `Linear` + `ClampToEdge` pour le blur | Les bords ne doivent pas sampler hors-texture (artefacts noirs) |
| D8 | Le TM pass lit la texture composite (si bloom) ou la HDR (si pas bloom) | Le TM est agnostique de la source — il lit juste une texture full-res Rgba16Float |
| D9 | Uniform threshold : 16 bytes (threshold + knee + 2 pad) | Aligned 16, simple |
| D10 | Uniform blur : 16 bytes (direction vec2 + radius + pad) | Aligned 16 |
| D11 | Uniform composite : 16 bytes (intensity + 3 pad) | Aligned 16 |
| Config | Coût relatif |
|--------|:---:|
| Sans MSAA | 1× |
| MSAA 4× | ~1.3–1.5× (le rasterizer sur-échantillonne, le fill rate est partagé) |
| MSAA 8× | ~1.5–2× |
---
MSAA est **beaucoup** moins coûteux qu'un post-process AA (FXAA, TAA) car le
sur-coût est dans le rasterizer (edges only) et pas dans un blur fullscreen.
Les post-processes (bloom, TM) ne sont **pas** affectés — ils tournent sur la
texture résolue (1 échantillon/pixel).
## Fichiers modifiés / créés
## Limitations / non-goals
| Fichier | Changement |
|---------|-----------|
| `lib/src/core/bloom.rs` | **Nouveau** : `BloomConfig`, `BloomPipeline`, allocation + bind groups |
| `lib/src/core/renderer.rs` | + `bloom: Option<BloomPipeline>`, `bloom_config` ; passes 8a-8d ; TM lit composite ou HDR ; resize |
| `lib/src/core/hdr.rs` | `create_hdr_bind_group` accepte une texture arbitraire (pas seulement `self.texture`) |
| `lib/src/core/mod.rs` | + `pub mod bloom;` + re-exports |
| `lib/src/shaders/bloom_threshold.wgsl` | **Nouveau** |
| `lib/src/shaders/bloom_blur.wgsl` | **Nouveau** |
| `lib/src/shaders/bloom_composite.wgsl` | **Nouveau** |
| `lib/src/shaders/conf.rs` | + `BLOOM_THRESHOLD_SHADER`, `BLOOM_BLUR_SHADER`, `BLOOM_COMPOSITE_SHADER` |
| `lib/src/app.rs` | + `bloom_config`, `bloom_enabled`, `set_bloom_config`, builder `with_bloom` |
| `lib/src/lib.rs` | Re-export `BloomConfig` |
| `lib/src/prelude.rs` | Re-export `BloomConfig` |
| `lib/tests/wgsl_validate.rs` | + 3 tests (threshold, blur, composite) |
| `lib/examples/demo.rs` | + `with_bloom(BloomConfig::default())` |
| `docs/user/bloom.md` | **Nouveau** : doc utilisateur |
| `docs/ROADMAP.md` | 6.3 → ✅ |
---
- **Pas de TAA** (temporal AA) — nécessiterait un history buffer + motion vectors,
bien plus complexe. MSAA 4× couvre 90% du besoin pour un lib "simple".
- **Pas de MSAA sur les post-processes** — le bloom/TM lissent déjà l'image.
- **Pas de coverage sampling** (DX12-only) — WebGPU expose seulement MSAA.
- **Resize = recréation** des textures MSAA (pas de resize in-place).
## Tests
| Test | Vérifie |
|------|---------|
| `bloom_config_default` | threshold=1.0, intensity=0.8, radius=4.0 |
| `bloom_requires_hdr` | `with_bloom` sans `with_hdr` → warning, bloom inactif |
| `bloom_pipeline_allocates_half_res` | dimensions = (w/2, h/2) |
| `bloom_zero_intensity_is_noop` | intensity=0 → composite = HDR (pas de changement) |
| WGSL threshold | compile avec naga |
| WGSL blur | compile avec naga |
| WGSL composite | compile avec naga |
---
- [ ] `MsaaConfig` Default = 4
- [ ] Validation `sample_count` (rejette 3, 5, 16)
- [ ] Build avec `with_msaa(4)` + HDR + Bloom → compile
- [ ] Exemple `msaa.rs` compile
- [ ] WGSL validation inchangé (pas de nouveau shader)
- [ ] Test unit : `Renderer::new` avec `msaa_config=Some(4)` ne panique pas
(nécessite un device mock — peut être un test intégration ignoré)
## Critères d'acceptation
- [ ] `cargo test` passe (tous tests existants + nouveaux)
- [ ] `cargo run --example demo` : le glow sphere produit un halo visible
- [ ] Sans bloom : rendu identique à avant (zéro régression)
- [ ] Sans HDR + avec bloom : pas de crash (bloom ignoré, warning)
- [ ] Resize : le bloom continue de fonctionner
- [ ] 0 warnings
1. `cargo check` 0 errors, 0 warnings
2. `cargo test` tous verts
3. `cargo run -p wsg-lib --example msaa` → bords lisses avec M, escaliers sans M
4. `cargo run -p wsg-lib --example demo` → inchangé (pas de `with_msaa`)
5. Combinaison HDR + Bloom + MSAA fonctionne (demo avec `.with_msaa(4)`)
docs/ROADMAP.md
+6 -1
View File
@@ -66,10 +66,15 @@ Ce document est la **vue d'ensemble de progression**. Chaque étape a son DRAFT
| 6.1 | **Exposure control** (clavier / API live) | ⭐⭐ | Trés faible | ✅ |
| 6.2 | **Emissive materials** (champ `emissive` → bénéficie du HDR) | ⭐⭐⭐ | Faible | ✅ |
| 6.3 | **Bloom** (post-process : downsample → threshold → blur → composite) | ⭐⭐⭐ | Moyen | ✅ |
| 6.4 | **MSAA 4×** (anti-aliasing multi-échantillons + resolve) | ⭐⭐⭐ | Moyen | ⬜ |
| 6.4 | **MSAA 4×** (anti-aliasing multi-échantillons + resolve) | ⭐⭐⭐ | Moyen | ✅ |
| 6.5 | **Normal mapping / PBR** (nouveau shader, tangent space, metalness-roughness) | ⭐⭐⭐ | Élevé | ⬜ |
| 6.6 | **Cascaded Shadow Maps** (2–3 cascades + blend, plus de précision près de la camera) | ⭐⭐ | Élevé | ⬜ |
| 6.7 | **SSAO** (ambient occlusion screen-space, depth + normal buffer) | ⭐⭐ | Élevé | ⬜ |
| 6.13 | **Fog** (exponential / exponential² / height fog, paramètre par scène ou par matériau) | ⭐⭐⭐ | Faible | ⬜ |
| 6.14 | **Area lights** (rectangular area light, BRDF approx — specular + diffuse) | ⭐⭐⭐ | Élevé | ⬜ |
| 6.15 | **Textured area lights** (area light avec texture d’émission, e.g. panneaux LED, néons) | ⭐⭐⭐ | Moyen | ⬜ |
| 6.16 | **Volumetric lighting** (god rays / light scattering — radial blur ou ray-march 3D) | ⭐⭐⭐⭐ | Élevé | ⬜ |
| 6.17 | **Depth of field** (post-process CoC : circle-of-confusion + bokeh blur) | ⭐⭐⭐ | Moyen | ⬜ |
### Cibles techniques (refactoring)
docs/user/README.md
+2
View File
@@ -22,6 +22,7 @@ GPU graphics background is required.
| [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)` |
| [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 7 repo examples, the advanced `manual` workflow, adding your own example |
@@ -36,6 +37,7 @@ WSG follows a strict rule: **a feature you don't enable costs nothing at runtime
|---------|--------------|----------------|
| 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 |
docs/user/msaa.md
+127
View File
@@ -0,0 +1,127 @@
# MSAA (Anti-aliasing)
Multi-Sample Anti-Aliasing (MSAA) smooths jagged edges by rendering the scene
at a higher sample count (e.g. 4 samples per pixel), then averaging the samples
into the final image.
## Activation
MSAA is opt-in via the builder. When disabled (default), the renderer uses
single-sample rendering with zero overhead:
```rust
let app = AppBuilder::new()
.title("My App")
.with_msaa(4) // 4× MSAA (also: 2 or 8)
.build()
.await?;
```
## How it works
MSAA is a **rasterizer feature** — no new shader is needed. The pipeline:
```text
┌─────────────────────────────────────────────────────────────────────┐
│ Without MSAA (default) │
│ │
│ Main pass ──→ HDR texture (1 sample) ──→ [Bloom] ──→ TM ──→ Surface │
└─────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────┐
│ With MSAA 4× (and HDR) │
│ │
│ Main pass ──→ MSAA texture (4 samples, Rgba16Float) │
│ ↓ resolve (hardware average) │
│ HDR texture (1 sample) │
│ ↓ │
│ [Bloom] ──→ TM ──→ Surface │
└─────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────┐
│ With MSAA 4× (no HDR) │
│ │
│ Main pass ──→ MSAA texture (4 samples, surface format) │
│ ↓ resolve │
│ Swapchain (surface) │
└─────────────────────────────────────────────────────────────────────┘
```
Key points:
- The **main scene pass** renders into the MSAA texture (N samples/pixel).
- The **resolve** (hardware average) produces the single-sample output.
- **Post-processes** (bloom, tone mapping) operate on the **resolved**
single-sample texture — they are completely unaffected by MSAA.
- The **shadow map** is always single-sample (depth-only, not visible directly).
## Sample count
| Count | Quality | Cost (approx.) | Use case |
|-------|---------|----------------|----------|
| 2 | Basic | ~1.1× | Low-end / battery |
| **4** | **Good** | **~1.3–1.5×** | **Default, most games** |
| 8 | Excellent | ~1.6–2.0× | High-end / static scenes |
The cost is in the rasterizer/fill-rate (each pixel is shaded N times at
triangles' edges). Interior pixels (covered by a single triangle) are
shaded only once — MSAA only multiplies the **edge** cost.
## Runtime query
```rust
// In AppHandler::setup or update:
let active = app.renderer().msaa_enabled(); // true if sample_count > 1
let count = app.renderer().msaa_sample_count(); // 1, 2, 4, or 8
```
MSAA is a **build-time** setting: the multi-sample textures are allocated
at startup. Changing the sample count requires recreating the textures
(window resize does this automatically).
## Configuration struct
```rust
use wsg_lib::MsaaConfig;
let config = MsaaConfig { sample_count: 4 };
// Or use the builder shortcut (validated):
let app = AppBuilder::new().with_msaa(4).build().await?;
```
## Compatibility
| Feature | Compatible? | Notes |
|---------|-------------|-------|
| HDR + Tone Mapping | ✅ | MSAA texture is `Rgba16Float`, resolves into HDR |
| Bloom | ✅ | Bloom reads the resolved (single-sample) HDR texture |
| Shadows | ✅ | Shadow map is always single-sample |
| Frustum Culling | ✅ | Independent (compute pass) |
| LOD | ✅ | Independent (draw args) |
| Emissive | ✅ | Per-entity, in the main pass |
## Limitations
- **Does not smooth UV-dependent aliasing** (texture shimmer). For that,
use mipmaps + anisotropic filtering (future: texture module).
- **Cost scales with overdraw**: fully transparent or heavily overlapping
geometry pays the full N× cost.
- **GPU support**: most modern GPUs support 4× for all formats. 8× may be
limited for float formats (check `Device::limits().max_color_attachment_samples`).
## Example
```rust
use wsg_lib::app::AppBuilder;
use wsg_lib::core::ToneMapper;
let app = AppBuilder::new()
.title("MSAA Demo")
.size(1280, 720)
.with_msaa(4)
.with_hdr(ToneMapper::Aces)
.build()
.await?;
```
See `examples/msaa.rs` for a full interactive demo with cube, sphere,
and ground plane where aliasing is clearly visible without MSAA.