perf(volumetric): preintegrate depth and record cost attribution #1110

Merged
SakulFlee merged 4 commits from sakulflee/perf/volumetric-cost-investigation into main 2026-11-12 00:15:36 +00:00 AGit
Owner

Summary

Refs #1080. The Windows volumetric measurement was blocked on stale GPU timestamps (#1076) and missing capture context (#1078). The timestamp path is fixed, but a Windows re-capture is still needed. This change makes the remaining investigation measurable and removes part of the composite cost.

  • Records the resolved froxel grid, texel count, integration depth, composite resolution, max distance and temporal-history state in the metadata sidecar and in per-row CSV columns.
  • Adds gpu_volumetric_integrate so the volumetric breakdown covers inject, accumulate, integrate and composite.
  • Pre-integrates each froxel column into cumulative in-scattering and transmittance. The composite now uses one fetch per pixel instead of integrating the volume per pixel. Integration runs at the froxel depth resolution (or the tier's requested steps, whichever is finer), so depth sampling does not get coarser.
  • Moves the adaptive depth-slice rule into VolumetricQuality::resolved_grid so the renderer and capture paths cannot disagree.

Measurements

AMD RX 9060 XT / RADV, Linux, 1920x1080 fullscreen, all-in-one, volumetrics Low, Mailbox, 30-unit range. Medians over stable rows:

Stage Before After
inject 0.248 ms 0.195-0.236 ms
accumulate 0.183 ms 0.176-0.186 ms
integrate - 0.098-0.100 ms
composite 0.344 ms 0.085-0.086 ms
volumetrics 0.776 ms 0.571-0.595 ms

Composite plus integration drops from 0.344 ms to about 0.183 ms. Total volumetric time drops about 25%, and the measured frame rate moves from about 384 to about 400 FPS on this GPU. The inject/accumulate numbers are unchanged within run-to-run GPU clock variance.

At the same camera in the volumetrics example the fullscreen output is unchanged within capture noise: maximum channel difference is 19/255 and no channel differs by more than 32/255.

Windows still needs the re-capture from #1076 to confirm the pass split and the actual laptop cost.

Testing

  • cargo fmt --all -- --check
  • cargo clippy -- -D warnings
  • cargo test --no-fail-fast
  • Ran template_all_in_one and template_volumetrics on Linux/Vulkan; both render without validation errors, and the CSV metadata contains the new grid and integration fields.
## Summary Refs #1080. The Windows volumetric measurement was blocked on stale GPU timestamps (#1076) and missing capture context (#1078). The timestamp path is fixed, but a Windows re-capture is still needed. This change makes the remaining investigation measurable and removes part of the composite cost. - Records the resolved froxel grid, texel count, integration depth, composite resolution, max distance and temporal-history state in the metadata sidecar and in per-row CSV columns. - Adds `gpu_volumetric_integrate` so the volumetric breakdown covers inject, accumulate, integrate and composite. - Pre-integrates each froxel column into cumulative in-scattering and transmittance. The composite now uses one fetch per pixel instead of integrating the volume per pixel. Integration runs at the froxel depth resolution (or the tier's requested steps, whichever is finer), so depth sampling does not get coarser. - Moves the adaptive depth-slice rule into `VolumetricQuality::resolved_grid` so the renderer and capture paths cannot disagree. ## Measurements AMD RX 9060 XT / RADV, Linux, 1920x1080 fullscreen, all-in-one, volumetrics Low, Mailbox, 30-unit range. Medians over stable rows: | Stage | Before | After | |---|---:|---:| | inject | 0.248 ms | 0.195-0.236 ms | | accumulate | 0.183 ms | 0.176-0.186 ms | | integrate | - | 0.098-0.100 ms | | composite | 0.344 ms | 0.085-0.086 ms | | volumetrics | 0.776 ms | 0.571-0.595 ms | Composite plus integration drops from 0.344 ms to about 0.183 ms. Total volumetric time drops about 25%, and the measured frame rate moves from about 384 to about 400 FPS on this GPU. The inject/accumulate numbers are unchanged within run-to-run GPU clock variance. At the same camera in the volumetrics example the fullscreen output is unchanged within capture noise: maximum channel difference is 19/255 and no channel differs by more than 32/255. Windows still needs the re-capture from #1076 to confirm the pass split and the actual laptop cost. ## Testing - `cargo fmt --all -- --check` - `cargo clippy -- -D warnings` - `cargo test --no-fail-fast` - Ran `template_all_in_one` and `template_volumetrics` on Linux/Vulkan; both render without validation errors, and the CSV metadata contains the new grid and integration fields.
Capture metadata only stored the volumetric quality tier. The actual
froxel grid also depends on the render resolution and max distance, so a
capture could not distinguish a resolution change from a quality change
or attribute GPU cost to a grid size.

Move the renderer's adaptive depth-slice rule into VolumetricQuality and
use it from both the renderer and the capture path. Record the resolved
grid, texel count, composite steps, composite resolution, max distance
and temporal-history state in the metadata sidecar and in per-row CSV
columns.
The fullscreen composite integrated the froxel volume once per pixel. At
Low quality that is 32 trilinear 3D samples per pixel even though each
froxel column only has a few dozen useful depth slices.

Add a compute pass that integrates each froxel column into cumulative
in-scattering and transmittance. The composite now samples that prefix
once at the scene depth. The integration runs at the froxel depth
resolution (or the requested composite step count, whichever is finer),
so it does not reduce the composite's existing quality.

Add a matching gpu volumetric integrate timing stage.
The pre-integrated composite runs at the froxel grid's native depth
resolution when that is finer than the tier's requested step count. Keep
that rule in VolumetricQuality and record the resolved value instead of
the requested minimum, so captures describe the work that actually ran.

Drop the now-unused composite step parameter from the composite uniform.
docs(perf): explain volumetric cost attribution
Some checks failed
Lint / lint (pull_request) Successful in 7m43s
PR / test (pull_request) Has been cancelled
60db7595ba
Document the new integrate stage and capture fields, including how each
volumetric stage scales with grid size, integration depth, render pixels,
and light count.
SakulFlee force-pushed sakulflee/perf/volumetric-cost-investigation from 60db7595ba
Some checks failed
Lint / lint (pull_request) Successful in 7m43s
PR / test (pull_request) Has been cancelled
to 5a637234e9
All checks were successful
Lint / lint (pull_request) Successful in 9m20s
Templates / templates (pull_request) Successful in 5m16s
PR / test (pull_request) Successful in 25m2s
2026-11-11 23:16:20 +00:00
Compare

Smart test results

Result: PASS

Scope: full workspace

Reason: unmapped change: Tools/performance/performance_report.ipynb

Elapsed: 24m 22s

Workflow run

Overall: 543 tests, 533 passed, 0 failed, 10 skipped

Nextest: 532 tests, 532 passed, 0 failed, 0 skipped
Doctests: 11 tests, 1 passed, 0 failed, 10 skipped

Outcome charts are split between nextest and doctests. The timing chart covers nextest only.

Crate Nextest Passed Failed Skipped Doctests Time
orbital 1 1 0 0 - 0.99s
orbital-cli 3 3 0 0 - 0.08s
orbital_2d 29 29 0 0 0/1 0.42s
orbital_app 25 25 0 0 0/1 0.36s
orbital_billboard 14 14 0 0 - 6.89s
orbital_camera 8 8 0 0 - 0.11s
orbital_core 2 2 0 0 - 0.02s
orbital_debug_render 2 2 0 0 0/1 0.02s
orbital_debug_ui 58 58 0 0 0/1 0.78s
orbital_ecs 114 114 0 0 0/2 1.67s
orbital_ecs_bridge 48 48 0 0 - 0.74s
orbital_file_manager 5 5 0 0 - 0.19s
orbital_iced 26 26 0 0 - 0.40s
orbital_importer_gltf 16 16 0 0 - 0.31s
orbital_input 11 11 0 0 - 0.14s
orbital_light 8 8 0 0 - 0.09s
orbital_macros 0 0 0 0 0/1 0.00s
orbital_material_shader 2 2 0 0 - 0.03s
orbital_math 4 4 0 0 - 0.07s
orbital_mesh 2 2 0 0 - 0.02s
orbital_procgeo 3 3 0 0 - 0.04s
orbital_render_graph 6 6 0 0 - 0.08s
orbital_renderer 23 23 0 0 - 0.46s
orbital_resources 29 29 0 0 - 0.48s
orbital_shader_core 0 0 0 0 1/1 0.00s
orbital_shader_pbr 4 4 0 0 - 0.05s
orbital_shader_preprocessor 12 12 0 0 - 0.14s
orbital_shadow 3 3 0 0 - 0.04s
orbital_text 15 15 0 0 0/1 0.84s
orbital_texture 11 11 0 0 - 0.17s
orbital_touch_ui 1 1 0 0 0/1 0.01s
orbital_ui 32 32 0 0 0/1 0.46s
orbital_world_environment 13 13 0 0 - 0.18s
template_all_in_one 2 2 0 0 - 0.01s
pie showData
    title Nextest outcomes
    "Passed" : 532
pie showData
    title Doctest outcomes
    "Passed" : 1
    "Skipped" : 10
xychart-beta
    title "Slowest crates (nextest seconds)"
    x-axis ["orbital_billboard", "orbital_ecs", "orbital", "orbital_text", "orbital_debug_ui", "orbital_ecs_bridge", "orbital_resources", "orbital_renderer"]
    y-axis "Seconds" 0 --> 6.9
    bar [6.89, 1.67, 0.99, 0.84, 0.78, 0.74, 0.48, 0.46]
<!-- orbital-ci-test-results --> ## Smart test results **Result:** PASS **Scope:** full workspace **Reason:** unmapped change: Tools/performance/performance_report.ipynb **Elapsed:** 24m 22s [Workflow run](https://forgejo.sakul-flee.de/SakulFlee/Orbital/actions/runs/1288) **Overall:** 543 tests, 533 passed, 0 failed, 10 skipped **Nextest:** 532 tests, 532 passed, 0 failed, 0 skipped **Doctests:** 11 tests, 1 passed, 0 failed, 10 skipped _Outcome charts are split between nextest and doctests. The timing chart covers nextest only._ | Crate | Nextest | Passed | Failed | Skipped | Doctests | Time | | --- | ---: | ---: | ---: | ---: | ---: | ---: | | orbital | 1 | 1 | 0 | 0 | - | 0.99s | | orbital-cli | 3 | 3 | 0 | 0 | - | 0.08s | | orbital_2d | 29 | 29 | 0 | 0 | 0/1 | 0.42s | | orbital_app | 25 | 25 | 0 | 0 | 0/1 | 0.36s | | orbital_billboard | 14 | 14 | 0 | 0 | - | 6.89s | | orbital_camera | 8 | 8 | 0 | 0 | - | 0.11s | | orbital_core | 2 | 2 | 0 | 0 | - | 0.02s | | orbital_debug_render | 2 | 2 | 0 | 0 | 0/1 | 0.02s | | orbital_debug_ui | 58 | 58 | 0 | 0 | 0/1 | 0.78s | | orbital_ecs | 114 | 114 | 0 | 0 | 0/2 | 1.67s | | orbital_ecs_bridge | 48 | 48 | 0 | 0 | - | 0.74s | | orbital_file_manager | 5 | 5 | 0 | 0 | - | 0.19s | | orbital_iced | 26 | 26 | 0 | 0 | - | 0.40s | | orbital_importer_gltf | 16 | 16 | 0 | 0 | - | 0.31s | | orbital_input | 11 | 11 | 0 | 0 | - | 0.14s | | orbital_light | 8 | 8 | 0 | 0 | - | 0.09s | | orbital_macros | 0 | 0 | 0 | 0 | 0/1 | 0.00s | | orbital_material_shader | 2 | 2 | 0 | 0 | - | 0.03s | | orbital_math | 4 | 4 | 0 | 0 | - | 0.07s | | orbital_mesh | 2 | 2 | 0 | 0 | - | 0.02s | | orbital_procgeo | 3 | 3 | 0 | 0 | - | 0.04s | | orbital_render_graph | 6 | 6 | 0 | 0 | - | 0.08s | | orbital_renderer | 23 | 23 | 0 | 0 | - | 0.46s | | orbital_resources | 29 | 29 | 0 | 0 | - | 0.48s | | orbital_shader_core | 0 | 0 | 0 | 0 | 1/1 | 0.00s | | orbital_shader_pbr | 4 | 4 | 0 | 0 | - | 0.05s | | orbital_shader_preprocessor | 12 | 12 | 0 | 0 | - | 0.14s | | orbital_shadow | 3 | 3 | 0 | 0 | - | 0.04s | | orbital_text | 15 | 15 | 0 | 0 | 0/1 | 0.84s | | orbital_texture | 11 | 11 | 0 | 0 | - | 0.17s | | orbital_touch_ui | 1 | 1 | 0 | 0 | 0/1 | 0.01s | | orbital_ui | 32 | 32 | 0 | 0 | 0/1 | 0.46s | | orbital_world_environment | 13 | 13 | 0 | 0 | - | 0.18s | | template_all_in_one | 2 | 2 | 0 | 0 | - | 0.01s | ```mermaid pie showData title Nextest outcomes "Passed" : 532 ``` ```mermaid pie showData title Doctest outcomes "Passed" : 1 "Skipped" : 10 ``` ```mermaid xychart-beta title "Slowest crates (nextest seconds)" x-axis ["orbital_billboard", "orbital_ecs", "orbital", "orbital_text", "orbital_debug_ui", "orbital_ecs_bridge", "orbital_resources", "orbital_renderer"] y-axis "Seconds" 0 --> 6.9 bar [6.89, 1.67, 0.99, 0.84, 0.78, 0.74, 0.48, 0.46] ```
Author
Owner

Closes #1080

Closes #1080
Sign in to join this conversation.
No description provided.