Document Forward+ measurements and Linux lighting evidence

2026-09-24 03:46:40 +03:00
parent a0a4e29d48
commit f32e4b4058
15 changed files with 1533 additions and 32 deletions
@@ -5,7 +5,7 @@ These files preserve bounded checks and their inputs. Each record states its sou
 - [MVP acceptance dossier](mvp-acceptance.md): criterion-by-criterion closure, tested revisions and remaining compatibility coverage.
 - [P2 GPU visibility Linux evidence](p2-gpu-visibility-2026-09-23/README.md): Debug/Release GPU acceptance, lavapipe functional checks, relocated Player exports, and explicit platform/performance limits.
 - [P2 pinned SwiftShader compatibility](p2-swiftshader-2026-09-23/README.md): the Windows CI regression, shader capability fix, independent review closure, final native CI and relocated Player evidence.
- [P3 lighting and shadows](p3-lighting-2026-09-24/README.md): implementation, acceptance matrix, bounded evidence, and remaining Forward+/platform checks; temporal reconstruction is tracked separately.
+- [P3 lighting and shadows](p3-lighting-2026-09-24/README.md): implementation, Forward+ A/B and image parity, acceptance matrix, bounded Linux evidence, and remaining Windows/platform checks; temporal reconstruction is tracked separately.
 - [Windows software Vulkan](windows-software-vulkan-2026-09-18/README.md): fresh native build, 35 tests, launcher/window/MCP workflows and both relocated Release games on SwiftShader.
 - [Checkpoint 5 Linux acceptance](checkpoint5-linux-2026-09-18/README.md): clean offline source build, first Editor launch, exact-candidate standalone games and live Blender checks.
 - [Final Linux source checks](final-linux-2026-09-18/README.md): `4cb8255` integrated test results and both Release games after the asset-relocation correction, including package manifests and standalone captures.
@@ -1,11 +1,11 @@
 # P3 lighting and shadows — acceptance record

 This record tracks P3 lighting separately from temporal reconstruction. The
-implementation checkpoint is source revision
-`b191ae0bed77a1544a49504b9a3f07e9a3c691f2` on `feat/p3-lighting`. The
-Manual/record edit itself is documentation-only. A later Forward+ change and
-its measurements require a new revision and validation entry before the lighting
-slice can be called complete. Temporal reconstruction has its own acceptance.
+implementation and measured Forward+ checkpoint is source revision
+`a0a4e29d480ed3344f19bd3565d48668ca913fed` on `feat/p3-lighting`.
+The earlier shadow/benchmark integration checkpoint was `b191ae0`. The
+lighting slice has Linux functional and reference-GPU evidence; Windows CI for
+the new tiled revision is pending. Temporal reconstruction has its own acceptance.

 ## Implemented at the checkpoint

@@ -31,18 +31,26 @@ slice can be called complete. Temporal reconstruction has its own acceptance.
  requested/effective views, drop reasons, atlas bytes, caster draws, GPU shadow
  durations, and the effective lighting path. Shadow tiles are redrawn every
  frame; no persistent depth cache is claimed.
+- An explicit 16×16 depth-free tiled Forward+ path uses at most 64 light indices
+  per tile and evaluates the complete submitted list on overflow. The compute
+  entry has checked reflection and is included in game builds. `Auto` uses
+  forward: three-run Release measurements found tile build + raster slower on
+  the dense fixed scene. The [paired study](../../studies/23-p3-forward-plus-2026-09-24.md)
+  retains a separate localized-light win and exact binary/shader provenance.

 ## Acceptance matrix

 | Case | Automated evidence | Current status |
 | --- | --- | --- |
-| Empty, disabled, local-only, multiple sun; schema bounds | `scene_view`, `render_lighting_policy`, `render_offscreen` | Covered by Debug tests at the implementation checkpoint; re-run on final revision |
-| Four cascades, split bounds, subtexel stabilization, offscreen/source-LOD0 caster | `render_lighting_policy`, `render_lighting_sun` | Covered by CPU policy and Linux Vulkan image tests; final-revision runs pending |
-| Spot cone, six point faces and seam, dropped whole point shadow | `render_lighting_local`, `render_lighting_policy` | Covered by Linux Vulkan image and CPU tests; final-revision runs pending |
+| Empty, disabled, local-only, multiple sun; schema bounds | `scene_view`, `render_lighting_policy`, `render_offscreen` | Linux Debug green at `a0a4e29`; integrated revision pending |
+| Four cascades, split bounds, subtexel stabilization, offscreen/source-LOD0 caster | `render_lighting_policy`, `render_lighting_sun` | Linux GPU and pinned SwiftShader P3 green at `a0a4e29` |
+| Spot cone, six point faces and seam, dropped whole point shadow | `render_lighting_local`, `render_lighting_policy` | Linux GPU and pinned SwiftShader P3 green at `a0a4e29` |
 | 128-light/16-face/4096-draw limits, unsupported-atlas fallback | `render_lighting_policy`, `render_offscreen`, `render_lighting_local` | CPU and supported-atlas GPU paths covered; actual unsupported Vulkan device not tested |
-| Direct/GPU frustum/GPU occlusion image parity, P2 reload and 2D/UI independence | `render_lighting_sun`, `render_lighting_local`, `render_shader_reload`, `render_offscreen` | Linux supported-driver paths covered; final-revision runs pending |
-| Driver, profile, real 64×64 benchmark smoke | `render_lighting_benchmark_schema`, `render_lighting_benchmark_smoke`, `player_shutdown_diagnostics` | Focused integration tests passed on `b191ae0`; full raw log pending |
-| 1920×1080 0/4/16/32/64/128 Release sweep, three repeats, both shadow states | `tools/benchmark_p3_lighting.py --sweep` | Baseline measured on Linux physical GPU; raw CSV and post-Forward+ comparison pending publication |
+| Direct/GPU frustum/GPU occlusion image parity, P2 reload and 2D/UI independence | `render_lighting_sun`, `render_lighting_local`, `render_shader_reload`, `render_offscreen` | Linux Debug green at `a0a4e29`; integrated revision pending |
+| Forward+/forward parity, near plane, resize, overflow, and shader reload | `render_lighting_tiled`, `render_shader_reload`, `render_shader_reflection`, `build_schema_publication` | Linux Debug and pinned SwiftShader P3 green at `a0a4e29`; 128-light localized Release captures match exactly |
+| Driver, profile, real 64×64 benchmark smoke | `render_lighting_benchmark_schema`, `render_lighting_benchmark_smoke`, `player_shutdown_diagnostics` | Full Linux Debug green at `a0a4e29` |
+| 1920×1080 0/4/16/32/64/128 Release sweep, three repeats, both shadow states | `tools/benchmark_p3_lighting.py --sweep` | Forward baseline measured; its separate raw study is being integrated |
+| 1920×1080 paired paths, 32/64/128 dense and localized lights | `faset_p3_lighting_benchmark --lighting forward|tiled` | Raw 1080 frames and six diagnostic samples retained in study 23; dense slower, localized faster by build+raster |
 | Windows native build, pinned SwiftShader GPU tests, relocated Release 2D/3D Players | `windows-graphics.yml`, `ci.yml` | New P3 revision has not yet completed Windows CI |

 The supported-atlas GPU tests create a renderer with validation requested and
@@ -56,11 +64,12 @@ reference-GPU results cannot establish physical Windows performance.

 The P3 CTest registrations are `render_lighting_policy` and
 `render_lighting_benchmark_schema` (CPU), plus `render_lighting_sun`,
-`render_lighting_local`, and `render_lighting_benchmark_smoke` (labelled
-`gpu;p3`). Use `ctest --test-dir build/linux-debug -N -L p3` to confirm those
-five cases exist before running them; an empty test selection is not a pass.
+`render_lighting_local`, `render_lighting_tiled`, and
+`render_lighting_benchmark_smoke` (labelled `gpu;p3`). Use
+`ctest --test-dir build/linux-debug -N -L p3` to confirm those six cases exist
+before running them; an empty test selection is not a pass.
 The Windows full graphics job runs all registered tests, while the native
-Windows CPU job uses `-LE gpu` and therefore excludes the three Vulkan cases.
+Windows CPU job uses `-LE gpu` and therefore excludes the four Vulkan cases.

 On the Linux host at `b191ae0`, the [CTest inventory](linux-debug-p3-inventory.txt)
 listed all five cases. The [CPU-only P3 run](linux-debug-cpu-ctest.txt) passed
@@ -71,6 +80,22 @@ physical-GPU baseline was being measured, so it is not a final GPU acceptance
 result. The local host was Linux x86_64, kernel 7.0.0-31-generic; the source
 checkout had documentation changes only during these checks.

+At `a0a4e29`, the [full Linux Debug run](linux-debug-tiled-ctest.txt) had
+63 registered cases: 62 passed, no failures, and the compositor-dependent
+window lifecycle case skipped. The [pinned Linux SwiftShader P3 run](linux-swiftshader-tiled-p3-ctest.txt)
+passed all six P3 cases without a skip. The Vulkan image cases requested
+validation and asserted zero reported errors. The RTX 2080 Ti A/B used NVIDIA
+driver 595.84.0.0; study 23 records the executable and shader bundle hashes,
+all raw per-frame timings, tile overflow counts, and exact image equality for
+the localized 128-light capture. Its first dense 32-light forward run was an
+outlier, so the decision uses the median of three process medians rather than
+the apparent win in one paired run.
+
+At the earlier `b191ae0` checkpoint, [GitHub native/manual CI](https://github.com/emil28092005/Faset_Engine/actions/runs/35935899512)
+and [Windows graphics/SwiftShader CI](https://github.com/emil28092005/Faset_Engine/actions/runs/35935899505)
+passed. These jobs did **not** include the new tile shader; Windows CI for
+`a0a4e29` is still required.
+
 ```sh
 cmake --build --preset linux-debug --parallel 2
 ctest --test-dir build/linux-debug -L p3 --no-tests=error --output-on-failure
@@ -83,15 +108,16 @@ The benchmark wrapper retains one raw CSV per run, a merged CSV, and a summary.
 It rejects visibility fallback, missing GPU timestamps, missing lights, duplicate
 frames, and validation errors. An offscreen capture's `cpu_ms` includes GPU wait
 and readback; it is not thread CPU time. The exact Release benchmark revision,
-driver, CSV paths, before/after Forward+ gate, Linux SwiftShader results, final
-Debug/Release CTest logs, and Windows Actions links will be added after those
-checks run. Do not use this provisional record as a P3 completion claim.
+driver and paired path data are retained in study 23. Release full CTest,
+final integrated Windows Actions and relocated Player checks still need to be
+added before this is a complete P3 lighting acceptance record.

 ## Limits carried forward

-The current checkpoint scans all submitted lights in each mesh fragment; the
-measured Forward+ threshold was reached on the Linux reference GPU, so a bounded
-tiled path is in progress. Transparent/game UI and sprites keep their existing
+The default path scans all submitted lights in each mesh fragment; the
+measured Forward+ threshold prompted a bounded tiled implementation. `Auto`
+still uses forward because this dense fixed workload was slower after tile
+construction. Transparent/game UI and sprites keep their existing
 ordering and unlit behavior. The atlas caps are fixed budgets, not adaptive
 quality settings, and shadow depth is redrawn each frame. The renderer still
 performs synchronous framebuffer readback. No broad scene/driver matrix or
@@ -0,0 +1,140 @@
+Test project /home/emil/Desktop/.worktrees/Faset_Engine-p3-lighting/build/linux-debug
+      Start  1: authoring
+ 1/63 Test  #1: authoring ..........................   Passed    0.06 sec
+      Start  2: runtime_contracts
+ 2/63 Test  #2: runtime_contracts ..................   Passed    0.12 sec
+      Start  3: assets_pipeline
+ 3/63 Test  #3: assets_pipeline ....................   Passed    0.14 sec
+      Start  4: assets_blender_bundle
+ 4/63 Test  #4: assets_blender_bundle ..............   Passed    0.08 sec
+      Start  5: lua_contracts
+ 5/63 Test  #5: lua_contracts ......................   Passed    0.11 sec
+      Start  6: lua_safety_contracts
+ 6/63 Test  #6: lua_safety_contracts ...............   Passed    0.21 sec
+      Start  7: render_lighting_sun
+ 7/63 Test  #7: render_lighting_sun ................   Passed    0.92 sec
+      Start  8: render_lighting_local
+ 8/63 Test  #8: render_lighting_local ..............   Passed    0.87 sec
+      Start  9: render_lighting_tiled
+ 9/63 Test  #9: render_lighting_tiled ..............   Passed    2.75 sec
+      Start 10: render_lighting_policy
+10/63 Test #10: render_lighting_policy .............   Passed    0.04 sec
+      Start 11: render_graph
+11/63 Test #11: render_graph .......................   Passed    0.00 sec
+      Start 12: render_offscreen
+12/63 Test #12: render_offscreen ...................   Passed    0.43 sec
+      Start 13: render_sprite_alpha
+13/63 Test #13: render_sprite_alpha ................   Passed    0.36 sec
+      Start 14: render_shader_reload
+14/63 Test #14: render_shader_reload ...............   Passed    4.49 sec
+      Start 15: render_gpu_shader_contract
+15/63 Test #15: render_gpu_shader_contract .........   Passed    0.06 sec
+      Start 16: render_shader_reflection
+16/63 Test #16: render_shader_reflection ...........   Passed    3.63 sec
+      Start 17: render_window_lifecycle
+17/63 Test #17: render_window_lifecycle ............***Skipped   4.02 sec
+      Start 18: render_lighting_benchmark_schema
+18/63 Test #18: render_lighting_benchmark_schema ...   Passed    4.02 sec
+      Start 19: render_lighting_benchmark_smoke
+19/63 Test #19: render_lighting_benchmark_smoke ....   Passed    0.44 sec
+      Start 20: visibility_policy
+20/63 Test #20: visibility_policy ..................   Passed    0.01 sec
+      Start 21: gpu_visibility
+21/63 Test #21: gpu_visibility .....................   Passed    0.90 sec
+      Start 22: render_gpu_empty
+22/63 Test #22: render_gpu_empty ...................   Passed    0.59 sec
+      Start 23: render_gpu_capacity
+23/63 Test #23: render_gpu_capacity ................   Passed    0.65 sec
+      Start 24: render_gpu_dense
+24/63 Test #24: render_gpu_dense ...................   Passed    0.64 sec
+      Start 25: render_gpu_door
+25/63 Test #25: render_gpu_door ....................   Passed    0.60 sec
+      Start 26: render_gpu_shadow
+26/63 Test #26: render_gpu_shadow ..................   Passed    0.60 sec
+      Start 27: render_gpu_cut
+27/63 Test #27: render_gpu_cut .....................   Passed    0.60 sec
+      Start 28: render_gpu_resize
+28/63 Test #28: render_gpu_resize ..................   Passed    0.63 sec
+      Start 29: render_gpu_lod
+29/63 Test #29: render_gpu_lod .....................   Passed    0.66 sec
+      Start 30: render_gpu_teleport
+30/63 Test #30: render_gpu_teleport ................   Passed    0.61 sec
+      Start 31: render_gpu_near
+31/63 Test #31: render_gpu_near ....................   Passed    0.61 sec
+      Start 32: render_gpu_lifecycle
+32/63 Test #32: render_gpu_lifecycle ...............   Passed    1.32 sec
+      Start 33: render_gpu_views
+33/63 Test #33: render_gpu_views ...................   Passed    0.59 sec
+      Start 34: render_gpu_projection
+34/63 Test #34: render_gpu_projection ..............   Passed    0.57 sec
+      Start 35: render_gpu_open_sequence
+35/63 Test #35: render_gpu_open_sequence ...........   Passed    1.80 sec
+      Start 36: render_gpu_transparent
+36/63 Test #36: render_gpu_transparent .............   Passed    0.62 sec
+      Start 37: player_scene_contracts
+37/63 Test #37: player_scene_contracts .............   Passed    0.03 sec
+      Start 38: player_shutdown_diagnostics
+38/63 Test #38: player_shutdown_diagnostics ........   Passed    1.53 sec
+      Start 39: lua_cli_contracts
+39/63 Test #39: lua_cli_contracts ..................   Passed    0.13 sec
+      Start 40: lua_player_reload
+40/63 Test #40: lua_player_reload ..................   Passed    2.45 sec
+      Start 41: editor_mcp
+41/63 Test #41: editor_mcp .........................   Passed    0.01 sec
+      Start 42: process_and_cook
+42/63 Test #42: process_and_cook ...................   Passed    0.32 sec
+      Start 43: build_schema_publication
+43/63 Test #43: build_schema_publication ...........   Passed    9.27 sec
+      Start 44: editor_plugins
+44/63 Test #44: editor_plugins .....................   Passed    0.03 sec
+      Start 45: editor_session_settings
+45/63 Test #45: editor_session_settings ............   Passed    0.02 sec
+      Start 46: ui_widgets
+46/63 Test #46: ui_widgets .........................   Passed    0.12 sec
+      Start 47: ui_render
+47/63 Test #47: ui_render ..........................   Passed    0.48 sec
+      Start 48: editor_ui_import_conflicts
+48/63 Test #48: editor_ui_import_conflicts .........   Passed    0.82 sec
+      Start 49: editor_ui_project_settings
+49/63 Test #49: editor_ui_project_settings .........   Passed    0.97 sec
+      Start 50: editor_ui_reload
+50/63 Test #50: editor_ui_reload ...................   Passed    4.04 sec
+      Start 51: editor_ui_launcher
+51/63 Test #51: editor_ui_launcher .................   Passed    0.84 sec
+      Start 52: editor_ui_templates
+52/63 Test #52: editor_ui_templates ................   Passed    2.48 sec
+      Start 53: editor_ui_gizmos
+53/63 Test #53: editor_ui_gizmos ...................   Passed    0.92 sec
+      Start 54: editor_ui_authoring
+54/63 Test #54: editor_ui_authoring ................   Passed    1.71 sec
+      Start 55: editor_mcp_stdio
+55/63 Test #55: editor_mcp_stdio ...................   Passed    0.27 sec
+      Start 56: editor_gui_mcp
+56/63 Test #56: editor_gui_mcp .....................   Passed    4.65 sec
+      Start 57: core
+57/63 Test #57: core ...............................   Passed    0.16 sec
+      Start 58: tutorial_moving
+58/63 Test #58: tutorial_moving ....................   Passed    0.02 sec
+      Start 59: tutorial_following
+59/63 Test #59: tutorial_following .................   Passed    0.01 sec
+      Start 60: tutorial_spawning
+60/63 Test #60: tutorial_spawning ..................   Passed    0.02 sec
+      Start 61: tutorial_physics
+61/63 Test #61: tutorial_physics ...................   Passed    0.06 sec
+      Start 62: playable_2d
+62/63 Test #62: playable_2d ........................   Passed    0.40 sec
+      Start 63: playable_3d
+63/63 Test #63: playable_3d ........................   Passed    0.93 sec
+
+100% tests passed, 0 tests failed out of 63
+
+Label Time Summary:
+gpu       =  47.20 sec*proc (35 tests)
+p2        =  12.02 sec*proc (16 tests)
+p3        =   9.05 sec*proc (6 tests)
+window    =   8.67 sec*proc (2 tests)
+
+Total Test time (real) =  67.51 sec
+
+The following tests did not run:
+	 17 - render_window_lifecycle (Skipped)
@@ -0,0 +1,21 @@
+Test project /home/emil/Desktop/.worktrees/Faset_Engine-p3-lighting/build/linux-debug
+    Start  7: render_lighting_sun
+1/6 Test  #7: render_lighting_sun ................   Passed    5.14 sec
+    Start  8: render_lighting_local
+2/6 Test  #8: render_lighting_local ..............   Passed    4.76 sec
+    Start  9: render_lighting_tiled
+3/6 Test  #9: render_lighting_tiled ..............   Passed   14.30 sec
+    Start 10: render_lighting_policy
+4/6 Test #10: render_lighting_policy .............   Passed    0.03 sec
+    Start 18: render_lighting_benchmark_schema
+5/6 Test #18: render_lighting_benchmark_schema ...   Passed    4.04 sec
+    Start 19: render_lighting_benchmark_smoke
+6/6 Test #19: render_lighting_benchmark_smoke ....   Passed    1.23 sec
+
+100% tests passed, 0 tests failed out of 6
+
+Label Time Summary:
+gpu    =  25.42 sec*proc (4 tests)
+p3     =  29.50 sec*proc (6 tests)
+
+Total Test time (real) =  29.50 sec
@@ -0,0 +1,20 @@
+warning: An executable named `mkdocs` is not provided by package `mkdocs-material` but is available via the dependency `mkdocs`. Consider using `uvx --from mkdocs mkdocs` instead.
+
+[31m │  ⚠  Warning from the Material for MkDocs team[0m
+[31m │[0m
+[31m │[0m  MkDocs 2.0, the underlying framework of Material for MkDocs,
+[31m │[0m  will introduce backward-incompatible changes, including:
+[31m │[0m
+[31m │  × [0mAll plugins will stop working – the plugin system has been removed
+[31m │  × [0mAll theme overrides will break – the theming system has been rewritten
+[31m │  × [0mNo migration path exists – existing projects cannot be upgraded
+[31m │  × [0mClosed contribution model – community members can't report bugs
+[31m │  × [0mCurrently unlicensed – unsuitable for production use
+[31m │[0m
+[31m │[0m  Our full analysis:
+[31m │[0m
+[31m │[0m  [4mhttps://squidfunk.github.io/mkdocs-material/blog/2026/02/18/mkdocs-2.0/[0m
+[0m
+INFO    -  Cleaning site directory
+INFO    -  Building documentation to directory: /home/emil/Desktop/.worktrees/Faset_Engine-p3-lighting/build/manual
+INFO    -  Documentation built in 0.76 seconds