Fichiers
2026-10-11 01:54:18 +02:00

448 lignes
22 KiB
Markdown
Brut Lien permanent Annotations Historique

Ce fichier contient des caractères Unicode ambigus.
Ce fichier contient des caractères Unicode qui peuvent être confondus avec d'autres caractères. Si vous pensez que c'est intentionnel, vous pouvez ignorer cet avertissement. Utilisez le bouton Échappe pour les dévoiler.
# NOTES-PHASE19.md — Le profil de la Phase 18 était un profil de Debug
Session du 2026-08-26, à la suite de la Phase 18. Deux tâches étaient au
programme :
1. rendre `Renderer::addMesh` thread-safe pour paralléliser la construction de
mesh de tuile — la piste que la Phase 18 avait désignée comme le gain
suivant (83 % du coût restant) ;
2. profiler les autres postes du frame (terrain, végétation, faune) pour
trouver des gains sûrs.
**Le résultat principal de la phase n'est aucun des deux, et il les annule tous
les deux** : la mesure qui fondait la Tâche 1 avait été relevée en **Debug**, et
elle ne tient pas en **Release**. En Release, le maillage d'une tuile n'est plus
le poste dominant, et le frame entier n'est pas limité par le CPU.
C'est la leçon de la Phase 18 (« un commentaire n'est pas une mesure »)
appliquée un cran plus haut : **un profil de Debug n'est pas un profil de
Release.**
Configurations et matériel : Intel UHD 770, 20 cœurs logiques, 1280x720,
caméra **verrouillée** (`--lock-input`), cadrage fixé par `--start` / `--look`
(sans `--look`, tout diff d'image est un artefact — cf. MEMORY.md). Sauf mention
explicite de « Release », les mesures sont en **Debug avec couches de
validation**, la seule configuration où le projet valide. **Zéro message
`[Validation]` sur la totalité des mesures de ce document.**
---
## 1. TÂCHE 1 — la parallélisation
### 1.1 Ce qui empêche réellement `Renderer::addMesh` d'être appelé depuis plusieurs threads
La question posée était précise, la réponse l'est aussi. `addMesh` touche
**quatre** ensembles d'état partagé, de dangerosité très inégale :
| # | État | Nature du problème |
|---|---|---|
| 1 | `meshes_`, `freeMeshSlots_`, `liveMeshCount_` | `meshes_.push_back` peut **réallouer** le vecteur pendant que `recordCommandBuffer` l'indexe depuis le thread de rendu. Course franche, sur un pointeur. |
| 2 | `pendingCopies_`, `stagingBytesInFlight_` | `enqueueCopy` fait `push_back` + `+=` sans verrou ; vidés à chaque `recordCommandBuffer`. |
| 3 | `commandPool_` | `flushCopiesNow` y alloue un command buffer. Un `VkCommandPool` et **tous** ses command buffers exigent une synchronisation externe : allouer dedans pendant que le thread de rendu réinitialise et enregistre le sien est une violation directe de la spécification. |
| 4 | `graphicsQueue_` | `flushCopiesNow` fait `vkQueueSubmit` + `vkQueueWaitIdle`. Un `VkQueue` exige lui aussi une synchronisation externe ; en concurrence avec le `vkQueueSubmit` de `drawFrame`, c'est une corruption de driver, pas une erreur de validation. |
Les points 1 et 2 se règlent avec un mutex, moyennant un coût sur le chemin de
rendu (le point 1 impose de verrouiller aussi la **lecture** de `meshes_` à
chaque draw, ou de figer la capacité du vecteur).
**Ce sont les points 3 et 4 qui condamnent l'exercice**, et pour une raison qui
n'est pas la difficulté : `flushCopiesNow` n'est atteint que lorsque le staging
en vol dépasse **128 Mo** (`kMaxPendingStagingBytes`). Une tuile pèse ~385 Ko et
le budget est de 64 tuiles par frame, soit ~25 Mo : **ce chemin ne se déclenche
jamais pendant le streaming**. Il ne se déclenche que sur `--no-lod`, qui
téléverse la zone entière en un bloc — avant la première frame, donc sans
concurrence.
Autrement dit : la partie dangereuse du code serait **exactement celle qu'aucun
test de cette session n'aurait pu exercer**. Un verrou oublié là ne se
manifesterait ni dans le harnais, ni sous `VK_LAYER_VALIDATE_SYNC`, ni dans
aucune des mesures ci-dessous — mais un jour, chez l'utilisateur, sur une scène
plus grosse. C'est la définition même du bug de concurrence indétectable que la
consigne demandait d'éviter.
**`Renderer::addMesh` n'a donc pas été modifié. Aucun appel Vulkan ne change de
thread dans cette phase.**
### 1.2 Ce qui a été fait à la place, et pourquoi c'était le bon découpage
La Phase 18 avait déjà noté que `terrainNodeMeshData` est **pure**. Vérifié
ligne à ligne : elle ne lit que `Heightmap::at/spacing/worldCoord` et
`TerrainQuadtree::node` — tous `const`, sur des données immuables pour la durée
de la session — et écrit dans un `MeshData` qui lui appartient. Aucun `static`,
aucun `mutable`, aucun cache interne.
Le travail se découpe donc sans toucher au Renderer :
- **`TerrainStreamer::meshBatch`** maille tout le lot de la frame, en parallèle.
Aucun appel Vulkan. Chaque thread écrit dans des **éléments disjoints** de
vecteurs déjà dimensionnés : ni verrou, ni file, ni compteur partagé — donc
aucun état sur lequel une course serait possible ;
- **`TerrainStreamer::uploadNode`** pose la topologie et appelle `addMesh`, sur
le thread de rendu, en séquence, dans le même ordre qu'avant.
Trois précautions, chacune pour une raison précise :
- une exception ne traverse **jamais** la frontière d'un `std::thread` (elle
appellerait `std::terminate`) : elle est capturée et rendue comme une donnée
dans `batchErrors_[k]` ;
- rien n'est **journalisé** depuis un thread : les fonctions de journalisation
ne sont pas prévues pour ça. C'est l'appelant qui journalise, après jonction ;
- le chronomètre par tuile dépose sa durée dans un élément propre puis est sommé
après jonction. Une course sur un compteur de **mesure** serait la pire de
toutes : elle fausserait le chiffre censé prouver que le changement est bon.
Découpage **statique** en tranches contiguës, et non file de travail : une tuile
coûte toujours la même chose (65x65 sommets quel que soit son niveau), donc
l'équilibrage est naturel — et une file demanderait un verrou.
### 1.3 En Debug, le gain est réel
Survol scripté `--flythrough=900 --no-grass`, 45 s, **même binaire**, seule
l'option `--tile-threads` change (témoin de mesure, au même titre que
`--no-tile-cache`) :
| | `--tile-threads=1` (témoin) | 4 threads | écart |
|---|---:|---:|---:|
| Travail géométrie / tuile | 1278 / 1294 µs | 1542 / 1457 µs | **+16 %** |
| Temps de MUR du maillage | 7255 / 7341 ms | 3620 / 3322 ms | **−52 %** |
| Facteur de parallélisme | 1,00 | **2,42 / 2,49** | — |
| Images en 45 s | 11 046 / 11 253 | 13 320 / 12 081 | **+14 %** |
| Tuiles non couvertes | **0** | **0** | — |
Deux chiffres sont publiés, et il le faut : le **travail** par tuile ne doit
*pas* baisser — c'est la même fonction qui fait le même calcul — et il monte même
de 16 %, parce que quatre threads se disputent la bande passante mémoire en
parcourant une heightmap de 5001x5001. Ce qui doit baisser, c'est le temps que le
thread de rendu passe **bloqué** dessus. Publier un seul des deux laisserait
croire soit qu'il n'y a pas de gain, soit que le travail a diminué.
### 1.4 En Release, le gain disparaît — et c'est le résultat de la phase
Même survol, même méthode, **build Release** :
| | `--tile-threads=1` (témoin) | 4 threads |
|---|---:|---:|
| Travail géométrie / tuile | 141 / 139 µs | 154 / 146 µs |
| Temps de MUR du maillage | 819 / 811 ms | 1227 / 870 ms |
| Facteur de parallélisme | 1,00 | **0,73 / 0,97** |
| Images en 45 s | **32 206 / 32 327** | 29 776 / 32 104 |
**Le facteur est inférieur à 1 : paralléliser coûte plus que ça ne rapporte.**
La création des threads (~3 900 sur le survol, en rafales de 3) dépasse le
travail qu'elle répartit, parce qu'une tuile Release ne dure que 140 µs.
Une variante a été essayée avant de conclure — ne paralléliser qu'à partir de
**16 tuiles** par lot, pour ne viser que les grosses rafales. Résultat : 3 lots
parallélisés en 45 s, facteur 1,01, aucun effet mesurable. L'option devient
inerte, elle ne devient pas gagnante.
### 1.5 Pourquoi les deux mesures divergent : le coût d'une tuile, Debug vs Release
| Poste d'une tuile | Debug | Release |
|---|---:|---:|
| Géométrie | 1 344 µs (**79 %**) | 140 µs (**33 %**) |
| Indices | 16 µs (1 %) | 15 µs (4 %) |
| Téléversement GPU | 250 µs (15 %) | 262 µs (**63 %**) |
La géométrie est **9,6 fois moins chère** une fois optimisée ; le téléversement,
lui, ne bouge pas (c'est du memcpy et du pilote, pas du code compilé par nous).
Le poste dominant d'une tuile en Release n'est donc **pas** la géométrie, c'est
le **téléversement** — celui-là même que la Phase 12 avait traité et que la
Phase 18 avait rangé au rang de résidu à 11 %.
La Phase 18 n'a rien mesuré de faux : ses chiffres sont exacts, en Debug. Elle en
a tiré une priorité qui ne vaut que là. Et comme toutes les mesures du projet
sont en Debug (c'est la seule configuration avec les couches de validation), rien
ne pouvait le signaler.
### 1.6 Décision : défaut séquentiel, chemin parallèle conservé
`Params::meshThreads` vaut **1** par défaut — le réglage que la mesure désigne
en Release. Le chemin parallèle reste disponible par `--tile-threads=N`, testé
et documenté, pour trois raisons :
1. il est un **gain net de 2,4x et +14 % d'images en Debug**, c'est-à-dire dans
la configuration où tournent toutes les campagnes de mesure et de validation
du projet — ça a une valeur d'outillage réelle ;
2. il redeviendra intéressant en Release le jour où une tuile coûtera plus cher
(format de sommet plus lourd, pas LiDAR plus fin) ;
3. il sert de **témoin** : sans lui, l'écart Debug/Release ci-dessus ne serait
pas reproductible sur le même binaire.
Un troisième argument, mesuré incidemment, va dans le même sens. Sur la vue de
référence en Debug, `--tile-threads=4` donne une médiane identique (312 contre
311 FPS) mais un **minimum de 89 FPS contre 126** : les créations de threads
introduisent des à-coups que la médiane cache. Le défaut séquentiel est aussi le
plus régulier.
### 1.7 Un coût mémoire introduit puis retiré
Première version : tout passait par le lot, donc jusqu'à 53 `MeshData`
simultanés (~287 Ko chacun, ~15 Mo). Mesuré : **pic mémoire du processus
+5,6 Mo** sur la vue de référence, 338,3 Mo contre 332,7 en Phase 18.
Le chemin séquentiel (le défaut) maille et téléverse donc **une tuile à la
fois**, sans jamais garder plus d'un `MeshData` en vie, et le lot est relâché
(`shrink_to_fit`) à la fin de la frame sur le chemin parallèle. Pic revenu à
**331,7 Mo**, soit 1 Mo sous la Phase 18.
C'est le genre de régression qu'on n'aurait pas vue en ne regardant que le FPS.
### 1.8 Comment la correction a été vérifiée
**La comparaison d'images ne peut pas trancher ici, et c'est une conclusion en
soi.** Deux captures du jeu diffèrent déjà entre deux exécutions **identiques** :
l'herbe et la faune s'animent avec le temps écoulé, et le temps écoulé dépend du
débit d'images — que la phase change justement. Mesuré :
| Comparaison | Octets différents |
|---|---:|
| Témoin : parallèle vs parallèle, mêmes options | 0,65 % / 4,40 % |
| Témoin : séquentiel vs séquentiel, sans faune | 1,54 % |
| Séquentiel vs parallèle | 0,16 % / 6,67 % |
Le plancher de bruit est du même ordre que le signal cherché. Sur la vue de
référence, l'écart séquentiel/parallèle (0,16 %) est même **plus petit** que
l'écart entre deux runs parallèles (0,65 %). Ce test ne prouve rien — ni dans un
sens ni dans l'autre.
Le contrôle qui tranche est **headless et déterministe** (nouveau dans
`tests\logic_tests.cpp`) : 40 tuiles de niveaux mélangés sont maillées en
séquence puis sur 4 threads, et les sommets sont comparés **par `memcmp`**, pas à
une tolérance près — une course ne produirait pas un petit écart numérique, elle
produirait un sommet pris à la mauvaise tuile. Le test comprend son propre
témoin (vérifier que les tuiles comparées sont bien distinctes entre elles, sans
quoi la comparaison passerait sans rien prouver) et **12 passages
supplémentaires**, parce qu'une course se manifeste rarement et qu'un passage
unique ne dit presque rien.
### 1.9 Validation de synchronisation, avec son contrôle négatif
`VK_LAYER_VALIDATE_SYNC=1` sur le survol, chemin parallèle **et** chemin
séquentiel : **0 message**.
Un journal propre ne prouve rien tant qu'on n'a pas montré que l'outil regarde au
bon endroit (MEMORY.md, leçon de la Phase 12). **Contrôle négatif** : la barrière
`TRANSFER_WRITE -> VERTEX_ATTRIBUTE_READ | INDEX_READ` de
`Renderer::recordPendingCopies` a été retirée, le projet rebuildé, et la couche a
immédiatement crié :
```
vkCmdDrawIndexed(): READ_AFTER_WRITE hazard detected. vkCmdDrawIndexed reads
index VkBuffer 0xaf00000000af, which was previously written by vkCmdCopyBuffer.
```
10 messages, plafond de déduplication atteint. La barrière a été remise et le
journal est redevenu vide. L'outil regarde bien le chemin de téléversement des
tuiles.
---
## 2. TÂCHE 2 — où passe vraiment le temps d'une image
### 2.1 L'instrumentation
`src/main.cpp` chronomètre désormais cinq postes CPU par image, journalisés à la
fermeture (`Cout par image`) : streaming terrain, `gatherTrees`, `gatherGrass`,
construction du tronc de vision, et `drawFrame`. Même démarche que
`buildProfile` en Phase 18, appliquée à l'image entière.
Le chronomètre est pris **sans condition** : un profilage qu'on active à la
demande finit par mesurer un binaire différent de celui qui tourne. Coût mesuré :
« tronc de vision » vaut 0,3 à 0,9 µs en Release, ce qui borne le coût des
bornes elles-mêmes.
### 2.2 Ce que le Debug faisait croire
Vue d'alpage, Debug :
| Poste | µs/image |
|---|---:|
| **`gatherTrees`** | **1 747** |
| `gatherGrass` | 4 944 |
| `drawFrame` | 1 373 |
| Streaming terrain | 97 |
| Tronc de vision | 5 |
`gatherTrees` coûtait 1 630 à 1 936 µs **dans les trois scénarios testés**, y
compris le survol à 120 m d'altitude où les arbres sont à peine visibles. Coût
strictement constant, indépendant de ce qui est à l'écran : la signature d'un
coût de **balayage**, pas d'un coût de contenu. Deux redondances par image
étaient identifiées dans le code et prêtes à être corrigées :
- 5 appels à `terrain_.heightAt()` par **bloc** de 8x8 cellules pour estimer ses
bornes verticales, à chaque image, alors que ces bornes ne changent jamais
(~720 appels par image) ;
- la purge du cache parcourt les **~1 800 cellules** du cache à chaque image
pour y chercher des cellules à oublier, alors que la caméra bouge de quelques
centimètres par image.
### 2.3 Ce que le Release dit, et qui annule tout ce qui précède
Mêmes vues, build Release :
| Poste | Alpage | Vue de référence |
|---|---:|---:|
| **`drawFrame`** | **3 537 µs (81 %)** | **1 424 µs (83 %)** |
| `gatherGrass` | 515 µs | 128 µs |
| `gatherTrees` | 254 µs | 153 µs |
| Streaming terrain | 22 µs | 15 µs |
| Tronc de vision | 0,9 µs | 0,6 µs |
`gatherTrees` passe de 1 747 à 254 µs. La somme des postes (4 328 µs) rend
compte de la quasi-totalité de l'image mesurée (4,39 ms), donc rien d'important
n'échappe au profil.
### 2.4 Le frame est limité par le GPU — vérifié par ablation, pas affirmé
`drawFrame` inclut l'attente de la barrière de la frame en vol. Pour distinguer
« le CPU travaille » de « le CPU attend », on retire du travail **GPU** et on
regarde si les postes CPU bougent. Alpage, Release, 20 s :
| | Images | `drawFrame` | Arbres CPU | Herbe CPU | Temps/image |
|---|---:|---:|---:|---:|---:|
| Tout | 4 561 | 3 537 µs | 254 | 515 | 4,39 ms |
| `--no-grass` | 7 184 | 2 537 µs | 185 | 0 | 2,78 ms |
| `--no-vegetation` | 10 631 | 1 830 µs | 0 | 0 | 1,88 ms |
Retirer l'herbe économise 515 µs de CPU mais fait tomber le temps d'image de
1 610 µs : **le gain vient du GPU, pas du CPU.** Le CPU passe 81 % de l'image à
attendre dans `drawFrame`.
**Conséquence directe : aucune optimisation CPU ne vaut la peine d'être faite
ici.** Supprimer entièrement `gatherTrees` et `gatherGrass` — 769 µs sur 4 390 —
ne rendrait rien, puisque ce temps est déjà pris sur une attente. Les deux
redondances du §2.2 sont **réelles** et restent notées pour le jour où le
rapport de forces changera (GPU plus rapide, ou résolution plus basse) ; les
corriger aujourd'hui serait optimiser un artefact du build de test.
Conformément à la consigne — « n'implémente que ce qui est mesuré comme un vrai
gain » — **rien n'a été optimisé dans la Tâche 2.** Ce qu'elle livre est le
profileur permanent et la mesure qui réoriente le travail futur.
### 2.5 Une redondance réelle mais négligeable, signalée et non corrigée
`renderer.projectionMatrix() * camera.viewMatrix()` puis
`Frustum::fromViewProjection` sont calculés **deux fois par image** — une fois
pour le streaming, une fois pour la végétation. C'est bien une redondance, et
elle est maintenant mesurée : **0,3 à 0,9 µs par image en Release**. La
supprimer n'est pas une optimisation, c'est du ménage ; elle n'a pas été faite
dans cette phase pour ne pas mélanger un changement non mesurable avec des
changements mesurés.
---
## 3. Résumé des chiffres
### Vue de référence Phase 11 — E 901500 N 6436600, yaw 100, pitch -7 (Debug)
| État | FPS médian | Pic RAM |
|---|---:|---:|
| Phase 18 | 293 | 332,7 Mo |
| **Après la Phase 19** | **311** | **331,7 Mo** |
### Vue d'alpage — E 900500 N 6439000, yaw 100, pitch -7 (Debug)
| État | FPS médian | Pic RAM |
|---|---:|---:|
| Phase 18 | 122 | 340,2 Mo |
| **Après la Phase 19** | **131** | **339,1 Mo** |
Ces écarts sont **dans le bruit** de la mesure de FPS (~15 % entre deux runs
identiques, cf. MEMORY.md) : la phase ne prétend pas à un gain de FPS sur ces
vues. Ce qui est solide, c'est le **pic mémoire**, qui est plus stable et qui est
descendu de 1 Mo sur les deux vues.
### Coût d'une tuile — survol 900 m/s
| Poste | Debug | Release |
|---|---:|---:|
| Géométrie | 1 344 µs (79 %) | 140 µs (33 %) |
| Indices | 16 µs | 15 µs |
| Téléversement | 250 µs (15 %) | 262 µs (**63 %**) |
0 tuile non couverte sur toutes les mesures, Debug comme Release, séquentiel
comme parallèle.
---
## 4. Vérification
- **Tests headless : 902 assertions** (896 avant la phase, **+6**), toutes
passent. Nouvelle section « Phase 19 : maillage de tuiles en parallèle »
(§1.8).
- **Zéro message `[Validation]`** sur la totalité des mesures et des scénarios,
Debug et Release.
- **`VK_LAYER_VALIDATE_SYNC=1`** sur les deux chemins : 0 message, **avec son
contrôle négatif** (§1.9).
- **Harnais `run_vulkan_check.ps1`** : voir §4.1.
### 4.1 Résultat du harnais
Joué **deux fois en entier** (11 processus, scénarios A à I) : une fois après la
Tâche 1, une fois sur le binaire final.
- **0 message `[Validation]`, 0 ligne `[ERROR]`**, code de sortie 0 pour chacun
des onze processus, fermeture propre partout ;
- gameplay effectivement exercé : 2 arbres abattus (3 au sol), 3 débitages,
4 objets ramassés, percussion, vol de parapente complet, escalade avec
sommet atteint (+41,5 m, pente 65 à 155 %), éditeur (3 objets posés, un
supprimé, une annulation, sauvés/rechargés, **et rechargés en partie normale**
où ils arrêtent le joueur : 0,28 m parcourus contre 21,05 m pour le témoin
sans scène), boisson au point d'eau avec son contrôle négatif à 30 m, faune
qui se retire du voisinage (4 animaux à portée au premier relevé → 0 au
dernier).
Les 4 lignes `[WARN]` sont les avertissements bénins habituels (pas de point
d'eau ni de faune sur certaines dalles) ; le harnais ne les compte pas comme des
erreurs.
### Le point rouge, inchangé depuis la Phase 17
Le harnais sort en `[ECHEC]` sur **un seul critère** : scénario E (vélo),
« pied à terre » (`False`). C'est un échec **antérieur à cette phase**, documenté
dans NOTES-PHASE17.md puis dans NOTES-PHASE18.md §4, laissé non corrigé pour
cause de périmètre. La Phase 19 ne l'a ni causé ni aggravé — elle ne touche que
le maillage des tuiles de terrain, et le reste du scénario E est vert (en selle
`True`, 13 relevés à l'arrêt en côte au-delà de 23,6 % de pente).
Le scénario I, bruité en Phase 18, est **vert** cette fois (4 → 0).
---
## 5. Options et outils ajoutés
| Ajout | Rôle |
|---|---|
| `--tile-threads=N` | Degré de parallélisme du maillage CPU des tuiles, thread de rendu compris. Défaut **1** (séquentiel). **Témoin de mesure** : aucun appel Vulkan ne change de thread quelle que soit la valeur. |
| `tools\profile_tiles.ps1` | Relève le profil de construction des tuiles et le coût par image sur un scénario donné. La Phase 18 relevait ces lignes à la main ; ce script rend le relevé reproductible — ce que `measure_terrain.ps1` avait fait pour le FPS en Phase 9. |
| Journal `Cout par image` | Cinq postes CPU du frame, à la fermeture. Permanent, non conditionnel. |
| Journal `Maillage parallele` | Temps de mur **et** travail cumulé du maillage, dans `buildProfile`. Les deux, jamais un seul (§1.3). |
---
## 6. Prochaines étapes suggérées
1. **Refaire les mesures de performance des phases précédentes en Release.**
C'est la conséquence la plus large de cette phase : les priorités
d'optimisation du projet sont établies sur des profils de Debug, et on vient
de voir qu'au moins l'une d'elles ne survit pas au passage en Release. Les
conclusions des Phases 10, 11, 12 et 18 méritent une relecture sous cet
angle.
2. **Le vrai poste d'une tuile en Release est le TÉLÉVERSEMENT (63 %).** La
piste chiffrée existe déjà et n'a pas bougé : **partager un unique buffer
d'indices GPU** entre toutes les tuiles (Phase 18 §2.5) supprimerait 96 Ko de
copie par tuile et ~48 Mo de mémoire GPU. C'est désormais le chantier de
performance le mieux ciblé.
3. **Le frame est limité par le GPU, et le premier consommateur est la
végétation** : sur l'alpage, l'herbe pèse 1,0 ms et les arbres 0,7 ms des
3,5 ms de `drawFrame`. Le levier est le **nombre d'instances**, pas le
shader (la Phase 18 avait déjà montré que la découpe alpha coûte zéro). Un
LOD sur l'herbe — moins de touffes au-delà de 20 m — serait le gain le plus
important disponible aujourd'hui, mais il **touche la qualité visuelle** :
c'est un compromis à valider, pas une optimisation à décider seul.
4. **Les deux redondances de `gatherTrees`** (§2.2), si le rapport CPU/GPU
change un jour.
5. Rendre les scénarios E et I du harnais insensibles au FPS (hérité de la
Phase 18, toujours pas fait).