Record startup splash flicker debt

This commit is contained in:
Meta Vens 2026-05-09 23:15:10 +01:00
commit 306190829f
3 changed files with 10 additions and 3 deletions

View file

@ -106,3 +106,4 @@
{"timestamp":"2026-05-09T22:59:44.0000000+01:00","topic":"d3d12-grid-taa-color-contract","lesson":"Stable temporal control, history age/weight, and field identity do not prove Grid TAA is smoothing color. D3D12 was still feeding stochastic hit/miss radiance into resolve/history. The fix is the D3D11 contract: post resolve reconstructs analytic Grid color from current Grid travel/world position using the Grid height target, nearest-loads Grid history, and skips color-delta rejection for Grid pixels while raw debug keeps showing the stochastic stream.","files":["src/Aquarium.Engine/Render/D3D12Renderer.cs","src/Aquarium.Engine/Render/Shaders/D3D12Post.hlsl","state/memory.json","state/scratch.md"]}
{"timestamp":"2026-05-09T23:08:12.0000000+01:00","topic":"d3d12-grid-expected-value-brightness","lesson":"Once D3D12 Grid resolve reconstructs the expected stochastic value, line brightness must be tuned as averaged transparent radiance, not as sparse on-sample brightness. The earlier 0.24 alpha scale made Cartesian and isoline contributions collapse when the color path became mathematically honest. Keep scene stochastic selection and post analytic reconstruction using identical Grid color/alpha constants.","files":["src/Aquarium.Engine/Render/Shaders/D3D12Scene.hlsl","src/Aquarium.Engine/Render/Shaders/D3D12Post.hlsl","state/evidence.jsonl"]}
{"timestamp":"2026-05-09T23:16:34.0000000+01:00","topic":"startup-splash-ready-gate","lesson":"Do not present D3D12 loading frames before the initial shader pipelines are ready. Presenting a black/loading swapchain frame takes visible ownership away from the Win32 splash, and DirectWrite loading text can persist into later frames because it wrote into a live backbuffer. While the async pipeline task runs, the renderer should avoid touching the swapchain; the host can keep repainting the GDI splash until HasPresentedReadyFrame becomes true.","files":["src/Aquarium.Engine/AquariumHost.cs","src/Aquarium.Engine/Render/D3D12Renderer.cs","state/evidence.jsonl"]}
{"timestamp":"2026-05-09T23:24:18.0000000+01:00","topic":"startup-splash-flicker-followup","lesson":"Current D3D12 startup splash behavior works but flickers slightly while the host repaints the Win32/GDI splash during async shader pipeline compilation. Treat that as a polish debt, not a reason to reintroduce swapchain loading frames. Future fix should either repaint only on invalidation/throttled intervals or use a proper pre-renderer splash state/window before D3D12 begins presenting.","files":["state/memory.json","state/scratch.md","state/evidence.jsonl"]}

View file

@ -23,7 +23,7 @@
"D3D12 Grid line width normalization should match the D3D11 reference: use periodic line domains with `fwidth()` and pixel-width constants, not world-space `ddx/ddy(p.xy)` footprint guesses. D3D12 binds Aetheria's 512x512 R8 blue-noise texture at `t15` with point/wrap sampling at `s1` for stochastic coverage. Animate it by shifting the blue-noise tile per frame with a low-discrepancy pixel offset, not by giving all pixels the same threshold.",
"D3D12 solid scene candidate discovery belongs in the view-froxel volume. At 720p the active tube is 160x90x32; primitive ids are indexed by low-res screen cell and depth slice, then scene rays test exact solid intersections inside that slice interval. The CPU-filled view-froxel buffers are bootstrap only; the durable path should become GPU/raster binning so per-frame upload bandwidth does not become the next stupid tax.",
"D3D12 pixel shader UAV registers share the output namespace. If a shader writes SV_Target0, bind the first manual UAV at u1, not u0.",
"D3D12 shader routing derives its editable source directory from --shader-source/AQUARIUM_SHADER_SOURCE, then watches D3D12Grid/Medium/Scene/Post/Smoke HLSL files directly. Shader/PSO builds run on a background task; startup presents a lightweight loading frame until the first pipeline set is ready, and hot reload keeps the previous pipeline set if compilation fails.",
"D3D12 shader routing derives its editable source directory from --shader-source/AQUARIUM_SHADER_SOURCE, then watches D3D12Grid/Medium/Scene/Post/Smoke HLSL files directly. Shader/PSO builds run on a background task. During initial startup, D3D12 should not touch or present the swapchain until the first pipeline set is ready; the host keeps repainting the Win32 splash instead. This can flicker slightly, but it avoids black loading frames and stale DirectWrite loading text in live backbuffers. Hot reload keeps the previous pipeline set if compilation fails.",
"Use Vortice at the graphics API membrane. Keep CultMath as the CPU math grammar. Do not let third-party math opinions leak inward unless the conversion is explicit.",
"The renderer currently uses a fullscreen HLSL path. Traditional geometry is allowed only as scaffolding; the visible Aquarium world should be shader-owned."
],

View file

@ -376,8 +376,14 @@ history rejection for Grid pixels. Raw debug remains the stochastic stream.
query timings.
- D3D12 async shader pipeline pass: initial D3D12 shader/PSO construction is no
longer on the startup/main-thread path. The renderer starts a background
pipeline build from the editable shader source directory and presents a cheap
loading clear while it compiles. D3D12 shader files are polled directly for
pipeline build from the editable shader source directory, but does not present
the swapchain until the first pipeline set is ready. The host repaints the
original Win32 splash with "Compiling renderer pipelines" while waiting. This
currently flickers a bit, likely because GDI splash repaint is fighting normal
window invalidation, but it is better than handing the user a black render
target or stale DirectWrite loading text written into a live backbuffer.
Future polish: throttle/repaint only when invalidated or build a proper
pre-renderer splash state/window. D3D12 shader files are polled directly for
hot reload; replacements compile on a background task, swap on the render
thread after a GPU wait, and failures preserve the previous pipeline set.
Headless smoke now waits for a ready rendered frame and uses a separate