Fichiers
vercora/NOTES-PHASE19.md
T
2026-10-11 01:54:18 +02:00

Brut Annotations Historique

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).