Document Forward+ measurements and Linux lighting evidence
This commit is contained in:
Emil
@@ -6,6 +6,7 @@ These files preserve bounded checks and their inputs. Each record states its sou
|
||||
- [P1 gameplay iteration](p1-iteration-2026-09-24/README.md): repeatable Debug C++/Lua workflow, raw samples, toolchain provenance, real compiler navigation and coverage limits.
|
||||
- [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, 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.
|
||||
|
||||
@@ -0,0 +1,124 @@
|
||||
# P3 lighting and shadows — acceptance record
|
||||
|
||||
This record tracks P3 lighting separately from temporal reconstruction. The
|
||||
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
|
||||
|
||||
- Authored directional, point, and spot lights are extracted from the same
|
||||
versioned Light schema used by the Inspector and MCP. No authored Light
|
||||
component retains the legacy sun; any authored Light, including disabled or
|
||||
local-only, suppresses that fallback.
|
||||
- Direct, GPU frustum, and GPU occlusion graphics paths use the same typed
|
||||
lighting data. Material descriptors remain set 0, lighting set 1, and GPU
|
||||
graphics scene data set 2. Sun and local light contributions accumulate before
|
||||
tone mapping. Sprites and UI remain unlit.
|
||||
- Four texel-snapped sun cascades cover up to 80 world units for an explicit
|
||||
camera frustum. A low-level Snapshot without one keeps a single sun view.
|
||||
Shadow caster selection uses each light view and source LOD 0, independent of
|
||||
camera visibility and prepared camera LOD. Missing/disabled sun and sprite-only
|
||||
scenes skip sun shadow raster.
|
||||
- The separate D32 local atlas admits 16 faces, one per spot or six atomically
|
||||
per point. Both shadow systems share a 4096-caster-draw frame budget. Up to 128
|
||||
local lights are submitted by priority, projected influence, then stable ID.
|
||||
Overflow or unsupported-atlas lights remain unshadowed when submitted; omitted
|
||||
lights beyond 128 do not illuminate. Both atlases try 2048², then 1024².
|
||||
- The editor overlay and Player profile expose actual submitted/omitted lights,
|
||||
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` | 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 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
|
||||
assert zero reported Vulkan errors; a test result is a validation-layer pass only
|
||||
when the layer was actually active. `render_window_lifecycle` can skip if the
|
||||
Linux compositor declines programmatic restore. The Windows workflow uses pinned
|
||||
SwiftShader, not a physical Windows GPU, and may lack the Khronos layer. Linux
|
||||
reference-GPU results cannot establish physical Windows performance.
|
||||
|
||||
## Reproduction and retained evidence
|
||||
|
||||
The P3 CTest registrations are `render_lighting_policy` and
|
||||
`render_lighting_benchmark_schema` (CPU), plus `render_lighting_sun`,
|
||||
`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 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
|
||||
`render_lighting_policy` and `render_lighting_benchmark_schema` 2/2 with zero
|
||||
failures. The [strict MkDocs build](strict-mkdocs.txt) passed for these Manual
|
||||
changes. This run deliberately excluded Vulkan tests while the 1920×1080
|
||||
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
|
||||
ctest --test-dir build/linux-debug --output-on-failure
|
||||
cmake --build --preset linux-release --parallel 2
|
||||
ctest --test-dir build/linux-release --output-on-failure
|
||||
```
|
||||
|
||||
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 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 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
|
||||
physical Windows GPU performance claim follows from these fixtures.
|
||||
@@ -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
|
||||
Reference in New Issue
Block a user