docs: plan Étape 15 (primitives + input unifié + exemple final) ; ROADMAP items 2.2/2.3
This commit is contained in:
Jérôme Bousquié
+155
-19
@@ -1,23 +1,159 @@
|
|||||||
# DRAFT — Étape suivante
|
# DRAFT — Étape suivante
|
||||||
|
|
||||||
> 📅 **Document vidé le 2026-09-19** (fin de l'Étape 14, Shadows — Phase 4.2, bilan archivé
|
> 📅 **Plan de l'Étape 15 (2026-09-19).** L'Étape 14 (shadow mapping) est **FAIT & vérifié** (voir
|
||||||
> dans l'historique git). Ce fichier accueillera le plan de l'étape suivante.
|
> historique git + ROADMAP 4.2). Cette étape est une **« grosse étape »** : elle réunit les acquis en
|
||||||
>
|
> un **exemple final interactif** et pose deux briques réutilisables — une **bibliothèque de meshes
|
||||||
> **Étape 14 (2026-09-19) : Shadow mapping mono-lumière — FAIT & vérifié (build + tests).**
|
> primitifs** et un **module d'input unifié** (clavier / souris / gamepad). Elle relance aussi deux
|
||||||
> Ombres portées classiques en **deux passes** sur une lumière unique (directionnelle **ou** spot),
|
> items de la ROADMAP : `2.2` (primitifs) et `2.3` (input), prérequis de l'exemple final (Phase 5).
|
||||||
> choisie par `Scene::set_shadow_caster(index)` (D1). Le `Renderer` possède désormais la shadow map
|
|
||||||
> (1024², `Depth32Float`, `RENDER_ATTACHMENT | TEXTURE_BINDING`), le sampler **comparateur**
|
|
||||||
> (`LessEqual`, WebGPU NDC [0,1]), le bind group **@3** (sampler + texture), un buffer uniform
|
|
||||||
> `light_view_proj` + sa bind group, et une **pipeline depth-only** (`shadow_shader.wgsl` + bias
|
|
||||||
> slope-scaled) — tout alloué dans `Renderer::new`, comme la depth texture de scène (D2/D4).
|
|
||||||
> `render_scene` exécute d'abord `render_shadow_map` (même `CommandEncoder`), puis la passe principale
|
|
||||||
> échantillonne la map via **PCF 3×3** dans `standard_shader.wgsl` (l'ombre ne touche pas l'ambiant).
|
|
||||||
> `FrameUniforms` est passé de 704 à 784 octets (`shadow_light_index`, `light_view_proj`, `shadow_params`).
|
|
||||||
> Ombres **éteintes par défaut** (indice sentinelle `MAX_LIGHTS`) → non-régression des exemples
|
|
||||||
> `simple`/`cube`/`manual`/`spot_test`. Exemple `shadow_test` : cube projetant une ombre douce sur
|
|
||||||
> un sol (lumière avant-droite basse, `toward_light (1.0, 0.5, 0.0)` — ombre visible). Commit-log :
|
|
||||||
> `c2cbd7f` (impl), `39167ee` (comparateur), `67bd7af` (direction directionnelle),
|
|
||||||
> `9a51ff7` (test : clip depth WebGPU + NdotL), `ab13fa7` (fix visibilité : réapplique `LessEqual`
|
|
||||||
> + lumière réglée après probe offscreen — ombre invisible car trop raide/occultée par le cube).
|
|
||||||
>
|
>
|
||||||
> Source de vérité = code + README.md. Ce document est vidé à la complétion de chaque étape.
|
> Source de vérité = code + README.md. Ce document est vidé à la complétion de chaque étape.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Objectif de l'Étape 15
|
||||||
|
|
||||||
|
Produire un **démonstrateur `demo`** interactif qui cumule tout le travail des étapes 8-14 :
|
||||||
|
un sol + plusieurs **primitives** (cube, icosphère, cylindre, cône) **texturées**, **éclairées**
|
||||||
|
(multi + spot, Étapes 12-13), projetant des **ombres** (Étape 14), et survolées par une **caméra
|
||||||
|
orbitale** pilotée au **clavier/souris** via un nouveau module d'input unifié — le tout dans le
|
||||||
|
workflow déclaratif `AppBuilder` + `AppHandler`, sans importer wgpu.
|
||||||
|
|
||||||
|
Trois volets, à faire en sous-étapes de façon **incrémentale** (chaque volet compilable/testable seul) :
|
||||||
|
|
||||||
|
- **15.A — `math::primitives`** : générateurs de `Geometry` prêts à l'emploi.
|
||||||
|
- **15.B — `core::input`** : `InputState` unifié (clavier/souris/gamepad) branché dans `App`.
|
||||||
|
- **15.C — `demo`** : exemple final = primitives + textures + lumières + ombres + caméra orbitale.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Décisions (D1…Dn) — à confirmer au fil de l'étape
|
||||||
|
|
||||||
|
- **D1 — Emplacement des primitives : `math::primitives`** (à côté de `math::geometry`). Les
|
||||||
|
primitives **produisent une `Geometry`** (purement CPU, sans GPU) ; les ranger dans `math` préserve
|
||||||
|
la cohérence avec `Geometry`/`GeometryError` (`math/geometry.rs`). Exposées via `math::primitives::*`.
|
||||||
|
*Alternative* : `resources::primitives` (discoverabilité près de `Mesh`) — **rejetée** car on reste
|
||||||
|
en mathématiques pures avant tout upload GPU.
|
||||||
|
- **D2 — API des primitives** : chaque générateur renvoie une **`Geometry` complète** (positions +
|
||||||
|
normales + UVs + indices, pas de couleurs → défaut blanc opaque). Signatures proposées :
|
||||||
|
- `cube(size: f32) -> Geometry` (arête `size`, normales/UVs par face, 24 sommets / 36 indices)
|
||||||
|
- `plane(width: f32, depth: f32, seg_x: u32, seg_z: u32) -> Geometry` (normales +Y, UVs étirés)
|
||||||
|
- `uv_sphere(radius: f32, sectors: u32, stacks: u32) -> Geometry` (normales sphériques + UV lat/long)
|
||||||
|
- `icosphere(radius: f32, subdivisions: u32) -> Geometry` (subdivision d'icosaèdre ; normales = position normalisée)
|
||||||
|
- `cylinder(radius: f32, height: f32, sectors: u32) -> Geometry` (couvercle/haut/bas + flanc)
|
||||||
|
- `cone(radius: f32, height: f32, sectors: u32) -> Geometry` (sommet + base ouverte/fermée)
|
||||||
|
- `torus(major: f32, minor: f32, major_segments: u32, minor_segments: u32) -> Geometry` *(bonus)*
|
||||||
|
Chaque fonction documente les conventions de repère (axe Y vers le haut) et l'orientation des
|
||||||
|
normales (pertinent pour l'éclairage car le culling reste désactivé par défaut).
|
||||||
|
- **D3 — Factorisation du `cube_geometry` des exemples** : remplacer le helper local de `cube.rs`
|
||||||
|
(et le `shadow_test`/`spot_test` s'ils en ont un) par `math::primitives::cube(1.0)`. Pas de
|
||||||
|
changement visuel (mêmes normales/UVs) → non-régression vérifiable.
|
||||||
|
- **D4 — Emplacement de l'input : `core::input`** (à côté de `context.rs`/`frame.rs`/`renderer.rs`).
|
||||||
|
`InputState` est **CPU** (consomme les événements winit) ; il n'est **pas** dans WGSL (langage de
|
||||||
|
shader côté GPU, sans I/O) — D4a. Un éventuel uniform `InputUniforms` consultable en WGSL (ex.
|
||||||
|
debug/gizmo) est **hors périmètre** pour l'instant, gardé en note pour une étape ultérieure.
|
||||||
|
- **D5 — Modèle d'état `InputState`** : sémantique **pressed / held / released** par frame, plus
|
||||||
|
souris (position, delta, boutons, molette) et gamepad (v1 minimale). Rotation par
|
||||||
|
`begin_frame()` (à chaque `about_to_wait`, avant `AppHandler::update`) et `end_frame()` (après
|
||||||
|
render), permettant de dériver `pressed`/`released` depuis les événements et de remettre les deltas
|
||||||
|
à zéro proprement.
|
||||||
|
- **D6 — Exposition dans `App`** : `App` possède un `InputState` ; `app.input()` (lecture) /
|
||||||
|
`app.input_mut()` (écriture) disponibles dans `setup`/`update`/`render`. Le `event_handler`
|
||||||
|
(winit 0.30) **forwarde** les `WindowEvent` concernés (KeyboardInput, MouseInput, CursorMoved,
|
||||||
|
MouseWheel, CursorLeft/Entered) et les `DeviceEvent` (MouseMotion, boutons de gamepad si
|
||||||
|
activés) vers `InputState::handle(...)`. `KeyboardInput` demande `listen_device_events` si on veut
|
||||||
|
le delta souris hors capture — à vérifier selon la config winit 0.30.
|
||||||
|
- **D7 — Gamepad (v1 minimale / optionnelle)** : winit fournit les `DeviceEvent::GamepadButtonChanged` /
|
||||||
|
`GamepadAxisChanged` (virtuels) ; on les capture **si présent** dans l'API (`Rc`/`Vec` par slot ou
|
||||||
|
index), sans abstraction complète de mapping. Si le support winit 0.30 s'avère trop fragile, on
|
||||||
|
**reporte** le gamepad (item ROADMAP `2.3` reste alors partiellement `[ ]`) et on livre d'abord
|
||||||
|
clavier/souris — l'exemple final n'a besoin **que** du clavier + souris.
|
||||||
|
- **D8 — Caméra orbitale** : **contrôleur** `CameraController { yaw, pitch, distance, target }` qui
|
||||||
|
met à jour la `Camera` active (position recomputée sphériquement autour de `target`, `with_perspective`
|
||||||
|
inchangée) depuis `InputState`. Le **cline multi-caméras (`set_active_camera`, ROADMAP 2.1) n'est PAS
|
||||||
|
requis** pour l'étape : on pilote la caméra active unique. 2.1 reste un item à part plus tard (ou est
|
||||||
|
optionnel ici si le temps le permet).
|
||||||
|
- **D9 — Exemple `demo`** : scène statique de primitives (sol = `plane` texturé damier ; cube,
|
||||||
|
icosphère, cylindre, cône posés dessus, chacun texturé procéduralement) + lumière directionnelle
|
||||||
|
ombre-porteuse (Étape 14) + point + spot (Étapes 12-13). `update` fait lentement tourner la scène
|
||||||
|
(comme `cube`) **et** met à jour la caméra orbitale via l'input (glisser = orbite, molette = zoom,
|
||||||
|
touches = reset / présettes / bascule light). Un petit helper de **texture procédurale**
|
||||||
|
(damier/couleurs) évite tout asset disque (réutilise le pattern `checkerboard_rgba` de `cube.rs`).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Détail d'implémentation
|
||||||
|
|
||||||
|
### 15.A — `math::primitives` (bibliothèque de meshes prédéfinis)
|
||||||
|
|
||||||
|
Fichier : `lib/src/math/primitives.rs` (+ `pub mod primitives;` dans `math/mod.rs`).
|
||||||
|
|
||||||
|
- Algorithmes procéduraux classiques ; chaque sortie est une `Geometry` validée
|
||||||
|
(`Geometry::validate` ne doit pas renvoyer d'erreur — invariant testé).
|
||||||
|
- Conventions : axe **Y vers le haut**, origine centrée (sauf `plane` éventuellement ancré),
|
||||||
|
normales **orientées vers l'extérieur**, UVs [0,1]² aussi continus que possible.
|
||||||
|
- `cube` : quotient le code de `cube_geometry` de `cube.rs` (mêmes faces/normales/UVs/indices).
|
||||||
|
|
||||||
|
Tests (dans `math/primitives.rs` ou un `#[cfg(test)]`) :
|
||||||
|
- comptes attendus : cube → 24 sommets / 36 indices ; uv_sphere → `(sectors+1)*(stacks+1)` sommets ;
|
||||||
|
- `icosphere` : subdivision 0 → icosaèdre (12 sommets / 20 faces / 60 indices), refinement augmente ;
|
||||||
|
- normales de longueur == positions, normes ≈ 1 (tolérance), indices dans les bornes ;
|
||||||
|
- `plane(width, depth, 1, 1)` → 4 sommets / 6 indices, normales +Y.
|
||||||
|
|
||||||
|
### 15.B — `core::input` (module d'input unifié)
|
||||||
|
|
||||||
|
Fichier : `lib/src/core/input.rs` (+ `pub mod input;` et `pub use input::InputState;` dans
|
||||||
|
`core/mod.rs` si pertinent).
|
||||||
|
|
||||||
|
Structures :
|
||||||
|
- `struct InputState { keys: KeyStates, mouse: MouseState, gamepad: GamepadState }`
|
||||||
|
- `KeyStates` : ensembles `pressed/held/released` sur une clé
|
||||||
|
(`winit::keyboard::Key`/`VirtualKeyCode` selon la version winit 0.30 — à trancher en D-impl) ;
|
||||||
|
- `MouseState` : `position: (f32, f32)`, `delta: (f32, f32)`, `scroll: (f32, f32)`,
|
||||||
|
boutons `MouseButton` avec sémantique pressed/held/released ;
|
||||||
|
- `GamepadState` : (v1 minimale) tableaux boutons/axes par index, optionnels.
|
||||||
|
- `GamepadState` peut être factorable/ignoré si winit ne livre pas proprement (D7).
|
||||||
|
|
||||||
|
Méthodes publiques :
|
||||||
|
- `begin_frame()` / `end_frame()` — rotation des états, remise à zéro des deltas ;
|
||||||
|
- `handle(event: &winit::event::WindowEvent)` / `handle_device(event: &impl)` —
|
||||||
|
dispatch interne (kbd/mouse/scroll/gamepad) ;
|
||||||
|
- requêtes : `key_pressed/held/released(k)`, `mouse_button_*`, `mouse_position()/delta()/scroll()`.
|
||||||
|
|
||||||
|
Branchement (`app.rs`) :
|
||||||
|
- le `AppRunner` (window_event, ~l.293) forwarde les événements concernés vers `app.input_mut()`,
|
||||||
|
et à chaque `about_to_wait` (l.283) appelle `input_mut().begin_frame()` avant
|
||||||
|
`handler.update()`, puis `input_mut().end_frame()` après la frame.
|
||||||
|
- `App` expose `input()` / `input_mut()`.
|
||||||
|
|
||||||
|
### 15.C — Caméra orbitale + exemple final `demo`
|
||||||
|
|
||||||
|
- `COMBO` : ajouter `OrbitalCamera` (dans `resources/camera.rs` ou un controleur proche) —
|
||||||
|
`pub struct CameraController { pub yaw: f32, pub pitch: f32, pub distance: f32, pub target: Vec3 }`
|
||||||
|
+ `fn apply_to(&self, cam: &mut Camera)` (repositionne `cam.position` en sphériques).
|
||||||
|
- Exemple `lib/examples/demo.rs` (workflow déclaratif, comme `cube`/`shadow_test`) :
|
||||||
|
- `setup` : textures procédurales par mesh, `primitives::*`, matériaux `standard`,
|
||||||
|
lumières directionnelle (ombre-porteuse via `set_shadow_caster`) + point + spot, caméra par défaut ;
|
||||||
|
- `update` : lire `app.input()`, mettre à jour `CameraController` (glisser/déplacer la souris =
|
||||||
|
yaw/pitch ; molette = distance ; `R` = reset ; touches `1/2/3` = présettes de vue), appliquer à
|
||||||
|
la caméra active, rotation lente des primitives ;
|
||||||
|
- doc du fichier en anglais (convention README/exemples), commentaires internes au besoin.
|
||||||
|
|
||||||
|
### Livrables & checklist finale
|
||||||
|
|
||||||
|
- [x] 15.A `math::primitives` + tests (build + `cargo test`)
|
||||||
|
- [ ] 15.B `core::input` + boucle `App` + tests légers
|
||||||
|
- [ ] 15.C caméra orbitale + exemple `demo` vérifié au runtime
|
||||||
|
- [ ] Factorisations exemples (primitives::cube) sans régression visuelle
|
||||||
|
- [ ] `cargo fmt --all -- --check` propre, build workspace + exemples + tests
|
||||||
|
- [ ] ROADMAP : cocher `2.2` et `2.3` (ou marquer le gamepad `[~]` partiel si reporté) ;
|
||||||
|
README : ajouter les items roadmap N°13-15 (primitives, input, démo)
|
||||||
|
- [ ] Fin d'étape : vider ce `DRAFT.md` (bandeau bilan archivé)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Périmètre hors-étape (reporté / refusé)
|
||||||
|
|
||||||
|
- `set_active_camera` multi-caméras (ROADMAP 2.1) — sauf si trivial, sinon item séparé.
|
||||||
|
- Uniform `InputUniforms` consultable en WGSL (debug/gizmo shader) — note pour plus tard.
|
||||||
|
- GPU-driven (Phase 3), batching matériau (4.3), LOD, HDR/tone mapping — étapes ultérieures.
|
||||||
|
- Gamepad complet (mapping abstrait) — v1 minimale seulement (D7).
|
||||||
|
|||||||
@@ -104,6 +104,16 @@ generated: { by: human:jerome, at: 2026-07-31T00:00:00Z }
|
|||||||
- [ ] Permettre plusieurs caméras (actuelle/inactive) et une sélection par identifiant (`scene.set_active_camera(camera_id)`)
|
- [ ] Permettre plusieurs caméras (actuelle/inactive) et une sélection par identifiant (`scene.set_active_camera(camera_id)`)
|
||||||
- [ ] Exposer une caméra orbitale contrôlable (exemple final, Phase 5)
|
- [ ] Exposer une caméra orbitale contrôlable (exemple final, Phase 5)
|
||||||
|
|
||||||
|
### 2.2 Meshes primitifs (bibliothèque procédurale, WSGL)
|
||||||
|
- [ ] Module `math::primitives` générant des `Geometry` prêts à l'emploi (positions + normales + UVs + indices) : `cube`, `plane`, `uv_sphere`, `icosphere`, `cylinder`, `cone` (et `torus` en bonus) — *(Étape 15, avec l'exemple final)*
|
||||||
|
- [ ] Factoriser le `cube_geometry` des exemples (`cube.rs`) vers `primitives::cube`
|
||||||
|
- [ ] Tests unitaires : comptes de sommets/indices cohérents, normales unitaires orientées
|
||||||
|
|
||||||
|
### 2.3 Input unifié (clavier / souris / gamepad, WSGL)
|
||||||
|
- [ ] Module `core::input` : `InputState` à sémantique cross-frame (pressed/held/released), consommation des `WindowEvent`/`DeviceEvent` winit, souris (position, delta, boutons, molette), clavier (touches), gamepad (v1 minimale optionnelle)
|
||||||
|
- [ ] Boucle dans `App::run` (`begin_frame`/`end_frame`) + exposition `app.input()` / `app.input_mut()`
|
||||||
|
- [ ] Contrôleur caméra orbitale (`CameraController`) construit sur l'input — *(Étape 15, prérequis de l'exemple final)*
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Phase 3️⃣ — GPU-Driven Rendering
|
## Phase 3️⃣ — GPU-Driven Rendering
|
||||||
|
|||||||
Reference in New Issue
Block a user