WIP: perf(vk): a save's textures are made and uploaded during its loading screen, not at their first draw (RX_VK_TEX_AHEAD=1, off by default) #1122
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!1122
Loading…
Reference in a new issue
No description provided.
Delete branch "p0lux/Longshot:perf/textures-ahead"
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?
Type: perf · Risk: low · Tested on: Linux (SteamOS), Steam Deck OLED (RADV VANGOGH) · Needs: none to merge it off; a desktop card (NVIDIA or AMD, Windows or Linux) before it is on by default
Why
After a save is loaded, the first seconds in the area stutter: on a Steam Deck, Kokiri Forest has 7 or 8 frames of 150 ms or more in its first 600, 3.3 s of them in all, and Hyrule Field 4 or 5, 2.3 s. The renderer makes and uploads a texture at the first draw that samples it, so the area's 800 to 1,200 textures all come in those frames, although the game made them 5 to 60 seconds before, during the loading screen, where nobody would notice the work.
This does that work on the loading screen. It is for the arrival after a save is loaded only: it does nothing at an area change in play (measured below), which is #1069's subject.
What changed
With
RX_VK_TEX_AHEAD=1the renderer remembers the textures a draw sampled soon after the game made them, and the next time the game makes one of them it is made and uploaded during a light frame, before its first draw. Off by default: without the switch nothing is remembered, nothing is prepared and no file is written.gpu/vk/texture_ahead.h(new, no Vulkan in it).signature()tells a texture by its shape and eight runs of 64 bytes of its storage;place()ties it to where the game put it (kept by signature alone, every area prepared what any area had drawn: 1,910 textures for the 770 Hyrule Field draws, 0.8 GB more video memory);learnable()keeps only a texture first drawn within 90 s of its making (one met minutes later in play would be prepared at every load);allowance_ns()lets a frame prepare only after a frame of under 200 draws (a loading screen has 5, the title and the menus under 100, play over 1,000: told by draws, not by time, so a fast PC does not prepare in play);room()keeps 256 MB free under the texture cache's budget, so a texture prepared never pushes another out;Queueholds what the game has made, oldest first, a second after its making and for two minutes at most;remember()bounds the list at 32,768 entries (256 KB), starting it again when full;load_drawn()/save_drawn()keep it in the game folder'scache/longshot_textures_drawn.bin, written through a file beside it.gpu/vk/vk_texture.cpp:texture_ahead_made()andtexture_ahead_gone()take the host's announcements (block-compressed textures in the game's own memory only:ahead_wanted());upload()notes a draw's first upload (ahead_learn());texture_ahead_frame()sets the next frame's allowance from the frame's draws and writes the list when it changed (every 300 frames at most);texture_ahead_run()takes textures from the queue and, for the ones in the list, callstexture_get()as a draw's first use would, up to 12 ms a frame (RX_VK_TEX_AHEAD_MS).gpu/vk/vk_replay.cpp:texture_created_of()andtexture_released_of()pass the announcements on;run_submit()callstexture_ahead_run()once a recording has begun, before the submission's commands, so the uploads go into that recording;status_tick()givestexture_ahead_frame()the frame's draws.scripts/dev_packs.pycountslongshot_textures_drawn.binamong the game folder's caches.tests/test_texture_ahead.pycompiles and runs the rules (tests/test_texture_ahead.cpp) and reads the renderer for where they are used (cut withtests/srccut.py).docs/development.mdhas the switch's row; a run file indocs/tested/.Measurements
Verdict: it helps the arrival after a save is loaded, on a Steam Deck OLED: the frames of 150 ms or more in the first 600 frames of play go from 3.35 s to 1.22 s in Kokiri Forest (7 or 8 frames to 2 or 3) and from 2.30 s to 1.41 s in Hyrule Field, the runs of the two sides not overlapping; the 1% low goes from 1.9 to 3.6 fps and from 2.4 to 3.5 fps, the frame rate over those 600 frames from 20.7 to 22.5 fps and from 23.6 to 24.5. The first load of a save only fills the list and is as main. It does not help an area change in play (last table). Cost: 35 to 100 MiB more GPU memory, nothing measurable on the time to reach play. Passed: no error in 16 runs. Not looked at on a screen (the Deck ran headless).
Hardware: SteamOS 3.9.5 (kernel 7.2.7-valve2), Steam Deck OLED: AMD Custom APU 0932 (4 cores, 8 threads), RADV VANGOGH, Mesa 26.2.0-devel, 16 GB shared with the GPU; the GPU's clock fixed at 1600 MHz
Scene: a save in Kokiri Forest (about 2,600 draws a frame) and one in Hyrule Field (about 1,600), standing still; no screen (headless), handheld profile, Minimum preset, the game's own upscaler, no frame generation, no cap
Method: the back end built alone from each commit (clang, ThinLTO, the play profile main commits, x86-64-v3), in a game built from main
c167ec67. Each run starts the game withRX_VK_FRAME_TRACE=1, loads the save by script, and stops after 600 presents in play. Read inlongshot_frames.csv: the arrival is the first frame of play after the loading screen (the first frame after a run of 60 frames or more that spend under 2 ms in draws), and the numbers are over the 600 frames from it: the frames of 150 ms or more, the frame rate (600 over their time), the 1% low (the mean of the 6 slowest, as fps), the median and 99th percentile frame time, and the uploads the draws asked for (the trace'suploadsandupload_mb). In each area: a warm-up of each side, then main, this PR, main, this PR; this PR's list was empty at the start, so its warm-up is the load that fills it. Two runs a side: both are given, with their mean. GPU memory: the process'sdrm-memory-gtt+drm-memory-vramat the end of the runHow to reproduce: a save in an area,
RX_VK_FRAME_TRACE=1, load it twice withRX_VK_TEX_AHEAD=1(the first load fills the list) and compare the frames after the loading screen with a load without the switch; the log'svk: textures ahead:line says what was preparedthis PR: perf/textures-ahead @
7d0b4ae6. Measured as b9f0ba85 (on the fork asmeasured/textures-ahead-b9f0ba85), the same patch on main5f131218, the last commit a game built fromc167ec67can load (#1102, the next one, takes the renderer interface to 25).git range-diff 5f131218..b9f0ba85 f9a2195c..7d0b4ae6shows the patch unchanged but for 8 lines of comments intexture_ahead.h. The six commits of main since (#1102 the microphone test, #1107RX_VK_TEST_VRAM_MB, #360 the builder, #311 DLSS's feature size, #1110 the release's CI, #903 the pipeline cache written before the title) touch none of the renderer files this PR changes, and the rebase had no conflict: not measured again onf9a2195c.5f131218RX_VK_TEX_AHEAD=1What it does not change, from the same runs:
An area change in play, the same two builds, one tour each: the Kokiri Forest save, then four teleports through the control bridge (Hyrule Field, Kokiri Forest, Hyrule Field, Kokiri Forest), 25 s in each, the texture budget at 4,000 MB as in every run here. Frames of 150 ms or more from each teleport to the next:
5f131218RX_VK_TEX_AHEAD=1Nothing gained there, and it cannot be with this design: on this route the game keeps both areas' textures (it makes about 100 to 150 again at each change, none of the area's own), so nothing is announced for the renderer to prepare; what a return uploads is what the texture cache's budget let go. With a 2,400 MB budget the returns cost 0.9 to 1.9 s each on this Deck (the comment on #1069 has those numbers).
Flags and settings
Two new switches, both read by the renderer only.
RX_VK_TEX_AHEAD=1cache/longshot_textures_drawn.bin) and, the next time the game makes them, made and uploaded during the loading screenRX_VK_TEX_AHEAD_MS=<n>The measured runs used the player's settings on both sides: Minimum preset (
RX_VK_LOW_SPEC=1), handheld profile (HOS_HANDHELD=1),RX_VK_READBACK_LATE=newest,3980,RX_VK_VRAM_MB=4000,RX_VK_TEX_MAX_DIM=1024,RX_VK_TEX_MAX_MB=128,RX_VK_TEX_SKIP_MB=4,RX_VK_IMAGE_BLOCK_MB=32,RX_VK_DESC_POOL_DIV=4,RX_VK_DESC_SLOTGEN=1,RX_VK_MESH_OPT=1,RX_VK_MASK_BLEND=0,RX_VK_FSR_FG=0,RX_VK_FRAMEGEN_MULT=2,RX_VK_LOAD=create,HOS_RESERVE_CORE=0.Testing
Tested:
python -I -B tests/run_all.pyon macOS with the Vulkan headers given, on this branch (ff04d32e): 578 passed, 55 failed, 44 skipped; mainf9a2195con that machine in the same session: 577 passed, the same 55 failed, 44 skipped. Every check that fails here fails on main there (no/proc, no Linux headers such aslinux/futex.handSOCK_CLOEXEC, Python 3.9'swrite_text); none reads this change. The one more that passes istests/test_texture_ahead.py. The checks that readvk_texture.cpp,vk_replay.cppanddev_packs.pypass as they are, none changed (tests/test_dev_packs.pyamong them);tests/test_tested_configurations.pypasses with Python 3.13.longshot_vk.dllcross-built from this branch's headff04d32ewith llvm-mingw 20261104, as.forgejo/workflows/build-windows.ymldoes it: 0 failed, no warning in the new code. Not run on Windows. The list's path iscache_path()'s, opened as the other cache files are;tests/test_utf8_paths.pypasses.Not tested:
texture_get()a draw uses.tests/test_texture_ahead.cppcovers it.Must be tested:
windowsorlinux,nvidiaoramd): load a save in Kokiri Forest twice withRX_VK_TEX_AHEAD=1and once without, expecting fewer frames of 150 ms or more in the first seconds of play on the second load, the same picture, and no more than about 100 MB more video memory (Test Farm:@Beanstalk a save loaded in Kokiri Forest twice with RX_VK_TEX_AHEAD=1 and once without, the frames over 150 ms in the first 20 s of play).Risks
What could break: with the switch off, nothing: its five entry points return at once, and
status_tick()reads the draw counters once a frame. With it on: a texture is made and uploaded up to a minute earlier than on main, from the same memory and through the same code; if the game wrote its storage again after that, the upload a draw's first use does on main for a written texture happens as on main (the dirty tracking is not touched). A texture prepared and never drawn holds video memory until the cache lets it go: measured at 35 to 100 MiB here, and never within 256 MB of the budget. A wrong match (two textures with the same shape, the same sampled bytes and the same address) only prepares a texture that was not needed. The list is a file incache/: a cut-off or foreign file is not read, and a write goes through a file beside it.Turning it off: it is off; set,
RX_VK_TEX_AHEAD=0or removing it. Deletingcache/longshot_textures_drawn.binstarts the list again.Compatibility: Nothing changes without the switch. With it, one new file in the game folder's
cache/. Saves andlongshot_options.iniare untouched, no shader or pipeline cache is rebuilt (no stamped file is touched),MKWVK_API_VERSIONis as it was (the host's announcementnvn_texture_createdexists already).Issues
See #1069
Checklist
Everyone
type(scope): description) of the status line's type.main.python -I -B tests/run_all.pypasses (any failure that also fails onmainis named).third_party/untouched (a new folder with aPROVENANCE.mdinstead).When it applies
Assisted-by:/Co-Authored-By:trailers.docs/tested/for each new measured run (format indocs/tested-configurations.md).tests/that reads changed source updated in this PR, not weakened.Tested in game: Steam Deck OLED (RADV VANGOGH, Mesa 26.2.0-devel, SteamOS 3.9.5), without a screen: 16 runs, a save loaded in Kokiri Forest and one in Hyrule Field, then four teleports between the two areas. With RX_VK_TEX_AHEAD=1 the second load of a save has 2 or 3 frames of 150 ms or more in its first 600 frames of play where main has 7 or 8 (Kokiri Forest), and 3 where main has 4 or 5 (Hyrule Field); the log's "vk: textures ahead" line counts 977 to 1,054 textures prepared on the loading screen in Kokiri Forest. No error, no device lost, no GPU timeout in the kernel log. This form of it was not looked at on a screen; an earlier form of the same mechanism was played on that Deck for an hour and a half on 2026-11-15 and again on 2026-11-16, nothing wrong reported.
Let's make this on by default
Also @Beanstalk
@HumanBean approval of
ff04d32recorded. This diff touches sensitive paths, so a second member ofBigBeansmust approve it too.Beanstalk test farm
Commit
ff04d32· tier untrusted · approved by HumanBean · dashboardThis diff touches sensitive paths, so it needs two members of
BigBeans:scripts/dev_packs.pyA member of
BigBeanscan review this commit and comment@Beanstalkto test it.Windows:
longshot_vk.dllcross-built from the headff04d32ewith llvm-mingw 20261104, as build-windows.yml does it: 0 failed. The description has it under Testing, with its box; the status line's risk is the one word the check asks for.@HumanBean happy to make it on by default once the farm has confirmed the gain on other hardware: so far it is measured on one Steam Deck only.
For this run, two things the farm needs to know, since the switch is off in
ff04d32:RX_VK_TEX_AHEAD=1, or the two sides are the same code path;cache/longshot_textures_drawn.bin), the gain shows from the second.What to compare: the frames of 150 ms or more in the first 20 s of play after the loading screen (Kokiri Forest is the heaviest here), and the log's
vk: textures ahead:line, which says how many textures were prepared. An area change in play is expected to show no difference.If the farm cannot set a switch, tell me and I will push the default on first so that it can run.
View command line instructions
Manual merge helper
Use this merge commit message when completing the merge manually.
Checkout
From your project repository, check out a new branch and test the changes.