WIP: docs(frame-pipeline): two frames ahead on a GPU-bound Windows PC, and three more ways to fill the GPU's wait, measured and dropped #1984
No reviewers
Labels
No labels
area/accessibility
area/audio
area/input
area/install
area/menu
area/renderer
area/saves
area/tooling
area/upscaling
beanstalk: approved
beanstalk: failed
beanstalk: needs approval
beanstalk: running
beanstalk: tested
ci: approved
good first issue
gpu/amd
gpu/igpu
gpu/intel
gpu/nvidia
help wanted
kind
bug
kind
chore
kind
docs
kind
feature
kind
performance
kind
question
needs measurements
platform/linux
platform/macos
platform/steam-deck
platform/windows
preview
priority
critical
priority
high
priority
low
regression
risk
high
risk
low
risk
medium
status
blocked
status
confirmed
status
duplicate
status
invalid
status
needs-info
status
wontfix
ci: approved
No milestone
No project
No assignees
3 participants
Notifications
Due date
No due date set.
Dependencies
No dependencies set
Reference
MagicBeanDev/Longshot!1984
Loading…
Reference in a new issue
No description provided.
Delete branch "siantm/Longshot:docs/frame-pipeline-experiments"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Summary
Architecture's "What does not shorten the frame" lists answering the frame wait early (closed #916's idea) as tried,
with the shadows' flicker as the reason. This adds what a GPU-bound Windows PC measured for that idea and for three
more ways to fill the GPU's wait before a frame's first draws: the frame wait answered a frame early (alone, with
RX_VK_PRESENTS_AHEAD=2, and with twoRX_VK_READBACK_LATEsettings), answered one to five submissions early within itsframe, the part size, and the parallel replay. In those runs each wait taken away came back at the next place the game
meets the GPU (the room for a present, then the readbacks, then the frame wait two frames back). The rows with more
than one run at the same clock (a frame early, with
RX_VK_PRESENTS_AHEAD=2, with the two late ranges) showed no cleargain in average frames a second; the one-run rows show only that run, and frame pacing was not measured. The
frame-overlap log's GPU gaps and the driver's busy reading are given apart, and how much of the gaps is idle is left
open. With the two late ranges the image darkened briefly for a frame; which read caused it was not found.
The numbers are not
main's and the text says so: they are a local performance branch's runs on this PC(
exp/x86-asm-syncat c8ca78b8, before main's render-thread rewrite #1763; RTX 4060, i7-9700, Windows 11, 2026-11-20).The change they measured (a hook in the frame wait and a switch) was never committed anywhere. The part size and the
parallel replay rows name switches main has since removed (
RX_VK_CHUNK,RX_VK_PARALLEL), and the text says that.Read first: the new subsection under "What does not shorten the frame" in
docs/dev/reference/architecture.md.Testing
Tested: Windows 11, i7-9700, RTX 4060, llvm-mingw clang 23.1.5, Python 3.14.7 (the Builder's). Documentation
only: there is nothing to run in the game. In hidden consoles of their own, through the PC's job queue, on this
branch's head
d94e82a6onmain@6e1521a7:python -I -B tests/run_all.py --strict --changed origin/main(1 filechanged, 5 checks read it; 8 at once): 3 passed, 2 failed, 0 skipped.
tests/byte_compile_tracked.py,tests/test_doc_anchors.pyandtests/test_framegen_fifo_cap.pypass.tests/test_frame_overlap.pyfails with "theframe ahead line is gone from the log or from the page", and fails the same way on
main@6e1521a7run by name in thesame queue job.
tests/test_present_queue_default.pyfound no Vulkan headers in that job and tested nothing; run again with them atd94e82a6and onmain@6e1521a7, it fails on both the same way (its source cut no longer finds the Present queue row ingpu/vk/vk_menu.cpp). The full suite (mise run test) was not run for thisdocs-only change.
mise run lint's hooks for a Markdown file are trailing whitespace and the end-of-file newline;pre-commit is not installed on this PC, so
git diff --check origin/main(clean) and the file's final newline werechecked instead.
Still to test:
Measurements
Nothing to measure: documentation only (the numbers it records are the local branch's runs, as the text says).
Risks
None: one docs page. The rows name
RX_VK_CHUNKandRX_VK_PARALLEL, which main has removed; the text says those runswere of the branch before #1763, so nobody is sent to set them.
Checklist
Ready for review
main; the title is a Conventional Commit.mise run testpasses (any failure that also fails onmainis named).main, or Measurements says why there is nothing to measure.third_party/untouched; nothing GPL-incompatible.When it applies
Assisted-by:/Co-Authored-By:trailers.Ready to merge
main, measured again or a comment says why the numbers still hold.Possibly related, for context:
Recommendation: Request changes. The historical runs are worth keeping, but the page draws conclusions about GPU idle time and part size that its own figures do not support. It also commits brightness counts derived from sampled game frames, which the repository rules exclude.
Records four attempts to improve frame overlap on a pre-#1763 renderer. The wait breakdown can help renderer developers avoid repeating old experiments. The cost is a misleading reference if the page presents one thermally limited setup as a general result.
@fixwill do (7)docs/dev/reference/architecture.md:175: The dark-block counts come from analysis of sampled game frames. (more on the line)docs/dev/reference/architecture.md:180: The GPU gaps do not establish the driver's 85–90% busy reading or show that most of the gap is idle. (more on the line)docs/dev/reference/architecture.md:186: The stated part sizes do not preserve the total gap. (more on the line)docs/dev/reference/architecture.md:176: Darkening alone cannot attribute the result to stale exposure. (more on the line)docs/dev/reference/architecture.md:182: The verdict covers rows that have no FPS result or only one run. (more on the line)docs/dev/reference/architecture.md:160: The new fence example reads as a general rule, but the frame sequence above calls the target the previous present's fence. (more on the line)Checks: Still running:
CI / Conventional Commit title (pull_request),CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request),CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request),CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request),CI / Workflow lint (actionlint) (pull_request),CI / Website build and checks (pull_request),Guide screenshots / Guide images and local UI source review (pull_request),Third-party parts / As their notes say (pull_request),Third-party parts / The same as upstream (pull_request),Website / Website on Cloudflare (pull_request).More: does it help, other systems, switches, what was read
Does it help: Docs-only. On the historical branch, the baseline was 53.9–55.1 FPS over four runs, versus 50.8–54.3 over four runs with the frame wait answered early and 53.4–54.9 over three runs with two presents allowed ahead. Those ranges show no clear average-FPS gain in that setup. Frame pacing and applicability to the current renderer are unverified.
Other systems: The diff changes one Markdown page. It has no runtime effect on Windows, Linux, Steam Deck, other GPUs, frame generation, or the build. The historical results cover one NVIDIA Windows setup and a renderer that predates changes to replay, part splitting, and presentation.
Switches: None added, changed, or removed. The historical runs varied RX_VK_PRESENTS_AHEAD and RX_VK_READBACK_LATE and used RX_VK_LOG_READBACK_RANGES. RX_VK_CHUNK and RX_VK_PARALLEL are already marked GONE in the current switch table. The experimental frame-wait switch is described as local and discarded.
Reviewed:
342996dcd2against6e1521a70a: Read the full architecture page and diff, the PR commit, AGENTS.md, CONTRIBUTING.md, standards, the Forgejo template, and both reported failing checks. Read the relevant replay, readback, frame-overlap, and flash-analysis code, including available pre-#1763 source. Skimmed recorded runs and related history. The checkout has no review checklist, adjacent Tooling checkout, local experiment commits, or raw runs for these results. No translations or generated files changed.; nothing run (a code review).Checked and fine:
Testing: Read-only review. The diff whitespace check passed. The author reports three passes and two failures shared with the previous base in the filtered Windows run. Current-head CI was still running, and the PR had no tester comments or prior reviews.
Overlaps and merge order: No overlapping pull request found in the checkout. #1763 is already in the base and marks the boundary of the historical results.
Automated code review by BeanBot (gpt-6.2-sol), on the pull request's opening. Nothing was run; a maintainer decides.
@ -150,0 +157,4 @@cooler ran about 60 frames a second whatever was changed, so only runs at the same clock are compared. The changeitself (one hook in the frame wait in `vk_replay.cpp`, and a switch) was taken out again and is in no tree.The frame wait's fence is the value just before the present's (logged: fence 14, the last present 15), not theL6 (minor): The new fence example reads as a general rule, but the frame sequence above calls the target the previous present's fence. The nearby early-wait bullet also calls a whole-frame shift the only earlier answer, while the table reports a shorter wait from shifting four or five submissions. Describe the fence target as an observation on the old branch and distinguish a shorter wait from a safe release.
@ -150,0 +172,4 @@The last two `RX_VK_READBACK_LATE` ranges are the ones that waited with the game ahead (`RX_VK_LOG_READBACK_RANGES=1`).With them read late the render thread's jobs took 17.6 to 17.9 ms of an 18.3 ms frame (10.0 to 10.3 by default), andthe frame log showed three frames with 12 or 13 blocks darker for one frame (none over 6 by default): the exposureL1: The dark-block counts come from analysis of sampled game frames. scripts/flash.py computes them from RGB pixels in the frame capture. Remove the pixel-derived counts and keep the qualitative observation of brief darkening.
@ -150,0 +173,4 @@The last two `RX_VK_READBACK_LATE` ranges are the ones that waited with the game ahead (`RX_VK_LOG_READBACK_RANGES=1`).With them read late the render thread's jobs took 17.6 to 17.9 ms of an 18.3 ms frame (10.0 to 10.3 by default), andthe frame log showed three frames with 12 or 13 blocks darker for one frame (none over 6 by default): the exposuremeter read a frame late, what the readbacks' wait is there for.L4: Darkening alone cannot attribute the result to stale exposure. The run changed both size rules together, and the readback code matches any pending range of either size. The 0x3980-byte rule also covers the culling camera block. Describe the darkening as consistent with stale exposure unless a separate observation identifies the affected read and its age.
@ -150,0 +177,4 @@So each wait taken away came back at the next place the game meets the GPU: the room for a present, then the readbacksof its results, then the frame wait itself two frames back. The GPU still waited 2.2 to 2.9 ms for each frame's firstdraws in every row, and 0.9 ms between its later parts; in an 18.3 ms frame that is the 85 to 90 % busy the driverL2: The GPU gaps do not establish the driver's 85–90% busy reading or show that most of the gap is idle. The stated gaps add to 3.1–3.8 ms of an 18.3 ms frame, which would imply about 79–83% busy if the gaps were entirely idle. The pre-rewrite counter includes the untimestamped window copy in its idle figure. Report the timestamp gaps and driver utilization separately and leave the split between copy work and true idle open.
@ -150,0 +179,4 @@of its results, then the frame wait itself two frames back. The GPU still waited 2.2 to 2.9 ms for each frame's firstdraws in every row, and 0.9 ms between its later parts; in an 18.3 ms frame that is the 85 to 90 % busy the drivercounts, so most of it is time with nothing to do (the window's copy, which has no timestamp, is in it too). No rowgained a frame a second, and the last `RX_VK_READBACK_LATE` row reads the game's GPU results a frame late.L5: The verdict covers rows that have no FPS result or only one run. The 1–3-submissions-early row gives wait times and a run count, so it cannot support the stated one-FPS threshold. The setup also omits the cap, present mode, and how clocks were matched per comparison, even though cooler runs reach about 60 FPS. Include the available setup and paired results, mark missing data, and say which comparisons showed no clear average-FPS gain. Apply the same scope to the PR summary.
@ -150,0 +183,4 @@The part size and the parallel replay, the other two ways tried to fill that wait, same PC and scene:- **The part size** (`RX_VK_CHUNK`, 240 then) moves the idle time between the frame's start and its later parts, notL3: The stated part sizes do not preserve the total gap. The figures add to 3.2–3.3 ms at 240 draws and 3.8–4.4 ms at 480. Report the totals and limit the conclusion to what matched runs show. If these figures came from different clock groups, label the groups.
Recommendation: Request changes. Keep the historical measurements, and narrow the conclusions to what each logged metric and run can establish.
The frame-overlap log explicitly combines GPU gaps and subsequent uploads. It does not independently corroborate driver utilization. Even treating the figures as disjoint idle intervals, 2.2–2.9 ms plus 0.9 ms in 18.3 ms implies about 79–83 percent busy, before considering what the timestamps omit. Separate the event timing from driver utilization. Describe the visual symptom as observed darkening without assigning it to exposure, and omit the image-derived block counts under the repository's game-data rule. Limit the no-gain statement to arms with useful measured comparisons. The one-run arms cannot establish a general no-gain result.
Testing: Documentation only. The author reported three targeted passes and two failures shared with the prior base, with present-head CI pending. Record current-head checks since the inherited tests inspect renderer code. No farm retest needed for the historical notes. Reviewed
342996dcd2against6e1521a70a. No code executed.Pushed
d94e82a6(docs(frame-pipeline): narrow the old branch's conclusions to what its runs show), onmain@6e1521a7, for the reviews of342996dc. The historical measurements stay; the conclusions are narrowed to what each run shows, the dark-block counts are gone, and the GPU gaps and the driver's busy reading are reported apart. Summary and Tested now describe this head; the docs checks ran on it through the job queue.Re #1984 (comment): done in
d94e82a6. The measurements are all still there. The frame-overlap gaps (which include uploads, and the window's copy has no timestamp) and the driver's 85 to 90 % are now separate readings, with the 79 to 83 % arithmetic stated and the idle share left open. The darkening is described as seen, not put on exposure or on one read, and the block counts are removed. The no-gain statement covers only the three rows with more than one run at a clock; the one-run rows say they show that run only. Current-head checks are in Tested.Re #1984 (comment) (L1): fixed in
d94e82a6. The image-derived block counts are removed; the page now says only that the branch's frame log showed brief one-frame darkening with that row, larger than any in the default runs.Re #1984 (comment) (L2): fixed in
d94e82a6. The timestamp gaps (2.2 to 2.9 ms before the first draws, 0.9 ms later) and the driver's 85 to 90 % busy are now given as separate readings. The page says the gaps include uploads and leave out the untimestamped window copy, that the gaps alone would mean about 79 to 83 % busy, and that the split between copy, uploads and true idle was not made.Re #1984 (comment) (L3): fixed in
d94e82a6. The totals are given (60: 3.0 to 3.3 ms, 240: 3.2 to 3.3, 480: 3.8 to 4.4), and "moves it, not its sum" now holds only for 60; 480 waited longer in both places. The page says the notes do not record which clock group each gap figure came from, and the frame-rate pairs stay with their two clock groups labelled, concluding only that no size ran faster than the one it was paired with.Re #1984 (comment) (L4): fixed in
d94e82a6. The darkening is no longer put on the exposure meter: the page says which read caused it was not found, since the row read both ranges late at once and the readback code matches a pending range of either size. futondestroyer asked not to tie it to exposure at all, so it is not called "consistent with" stale exposure either.Re #1984 (comment) (L5): fixed in
d94e82a6. The verdict now covers only the rows with more than one run at a clock (a frame early, 4 runs; with RX_VK_PRESENTS_AHEAD=2, 3; with the two late ranges, 2), each set against the default's 4. The 1 to 3 submissions row says no frame rate was recorded, and the one-run rows say they show that run only. The setup now gives the cooler runs' clock and frame rate and says the frame cap, the present mode and each run's exact clock are not in the run notes. The PR summary says the same.Re #1984 (comment) (L6): fixed in
d94e82a6. The fence value is now an observation of the old branch's log, not checked againstmain. A new paragraph after the table says answering 4 or 5 submissions early shortened the wait but releases the game before the frame's last recordings, which read and write its memory, are done: a shorter wait, not a safe release.Re #1984 (comment) (L7): Tested now covers head
d94e82a6onmain@6e1521a7.run_all.py --strict --changed origin/main: 3 passed, 2 failed.test_frame_overlap.pyfails the same way onmain@6e1521a7(run in the same queue job), andtest_present_queue_default.pyfails with "not found: vulkan_headers (--strict)", so it tested nothing on this PC. The full suite was not run for this docs-only change. pre-commit is not installed here, sogit diff --checkand the final newline were checked in place of lint's Markdown hooks. Tested says all of this.Tested corrected: an earlier run on this PC had no Vulkan headers for the renderer checks (
RX_CPMunset), so the ones it listed as also failing onmainhad compiled nothing on either side. They ran again with the headers atd94e82a6and onmain(queue job fb2-vk-1); the description now gives those results. No check fails at this head alone; nothing in the branch changed.View command line instructions
Checkout
From your project repository, check out a new branch and test the changes.