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
7 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 @
7d0b4ae6when measured. Rebased since onto main544229a2(2026-11-17, headc758fa67): the patch is unchanged but for the two conflicts' lines (run_submitkeeps main'srec_openandrb_span_beginfrom #977, andtexture_ahead_run()follows them; the doc row sits after #384'sRX_VK_BC_LAYERS), and one commit givesRX_VK_TEX_AHEADandRX_VK_TEX_AHEAD_MStheir rows in main's switch table (gpu/vk/switches.def, #1300). Not measured again on that main by me. 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 as rebased (c758fa67): 598 passed, 79 failed, 45 skipped; main544229a2on that machine in the same session: 597 passed, the same 79 failed, 45 skipped (tests/test_switch_table.pyamong them on both sides, on main's ownRX_VK_PGO_FILErow: it takes this branch's two rows). 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 the head before the rebase onto main544229a2(ff04d32e) with 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
c758fa6· tier untrusted · approved by nobody yet · 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.
LONGSHOT_JOBSfiles at once, not one #1147Deck measurements (Steam Deck OLED, Linux, in the game)
Verdict: on a Steam Deck OLED,
RX_VK_TEX_AHEAD=1halved the time spent in slow frames when arriving from a save: the frames of 150 ms or more took 3.0 and 3.0 s against 6.8 and 7.7 s with it off; the arrival's 1% low rose from about 1.0 to 2.6-2.9 fps, and its first 600 frames took 35.3-35.9 s against 39.8-40.5 s. The route's fps afterwards was unchanged (within the spread). No faults. A one-switch A/B on the same build.Baseline: both After columns are the same build, main
0cab3548+ this PR and #1150 #936 #1073 #1104 @ 0b4fd1a3, with the switch off and on; main @0cab3548is there for reference.0cab3548RX_VK_TEX_AHEAD=1: the stack @ 0b4fd1a3Hardware: Steam Deck OLED (AMD Custom APU 0932, RADV VANGOGH, 8 CUs), SteamOS 3.9.5, Mesa 26.2.0-devel; docked, output 1280x800, Game Mode; Steam's TDP limit 15 W; the GPU at a manual 1600 MHz in every run below. At these settings the APU reaches its 15 W package limit (the SMU logs FPPT/SPPT throttling in most runs), so runs spread widely.
Scene: Kokiri Forest from a fixed save (Continue), a conversation with a Kokiri, then the same scripted moving route every run, through the control bridge; 75 s measured.
Method: 2 runs per arm, interleaved after a warm-up run of each; the options pinned with
HOS_OPTIONS_FILEand read back from each run's log; the game's own fps from thevk: N presents, X fpslines inside the window, frame times from the frame log; medians of the 2 runs.RX_VK_FRAME_TRACE=1in every run. Two setups, never pooled: D = a player's options (Docked, 1280x800, the game's own upscaler at 100%) with frame generation and V-Sync off; H = main's Auto for this Deck (Minimum), pinned, frame generation off.How to reproduce: start each build with
HOS_CONTROL=<socket>andHOS_OPTIONS_FILE=<a pinned copy of the options>, Continue the save, drive the route withscripts/longshot_ctl.py, and read thevk: N presents, X fpslines between the route's start and end.Builds: both Linux x86-64-v3, release profile, built the same way: main @
0cab3548(nightly-363) and the stack @ 0b4fd1a3 =0cab3548+ #1150 (5ea93a58) + #1122 (ff04d32e) + #936 (cab0f820) + #1073 (9e62352f) + #1104 (a416edb0), conflicts resolved mechanically only (a local merge, not pushed).This PR's lines (the first run with the switch on):
The same switch was also run in r7 on the same Deck (rc.5-based build, the player's frame generation 3x): the frames of 150 ms or more after a save load went from 6.6 and 7.0 s to 3.0 and 2.4 s. The Deck's player now runs this stack with the switch on.
We set out to run this on a Steam Deck OLED as plain main plus this PR (your head
ff04d32e,RX_VK_TEX_AHEAD=1, your two-loads method), and could not build it: it no longer merges with main, and one of the two conflicts comes from a pull request of ours, so here is where they are.gpu/vk/vk_replay.cpp,run_submit: #977 addedrec_open(tag)andrb_span_beginat the spot where this PR addstexture_ahead_run().docs/development.md: theRX_VK_BC_LAYERSrow from #384 sits where this PR adds its row.We did not resolve them ourselves: a tester's run should be of your code as you would merge it.
tests/test_texture_ahead.pypasses at your head, and the PR touches no file the translator stamp is made from, so on a rebased head our prepared Deck caches for main apply and the run is about an hour and a half. Say when it is rebased and we will queue it.Why we care: in 383 Kokiri Forest arrivals in our Deck logs, making the new area's textures at their first draw is the largest part of the long frames (a median of 860 ms an arrival in the slow submits' texture lookups), which is what this PR goes after for save loads.
Posted by an AI agent (Claude Code) for zeldaootr.
ff04d32e36c758fa67a5Rebased onto main
544229a2(headc758fa67), so it builds as plain main plus this PR again. The two conflicts named above are resolved by keeping both sides:gpu/vk/vk_replay.cpp,run_submit: main'srec_open(tag)andrb_span_beginfrom #977 come first,texture_ahead_run()follows them.docs/development.md: theRX_VK_BC_LAYERSrow from #384, then this PR's row.One commit is new: main's switch table (
gpu/vk/switches.def, #1300) wants a row for every switch the source reads, soRX_VK_TEX_AHEADandRX_VK_TEX_AHEAD_MShave theirs. The code is otherwise as atff04d32e, the head the Deck measurements above were made on.Checks on the new head: 598 passed, 79 failed, 45 skipped, the same 79 as main
544229a2on that machine in the same session;tests/test_texture_ahead.pypasses.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)to 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)Desktop-card numbers for this, as the status line asks: Windows, NVIDIA. It helps here, at the arrival after a save is loaded and, on this route, at an area change in play too.
Verdict: with
RX_VK_TEX_AHEAD=1and the list filled by one earlier run of the same route, the long frames of the arrival after the save's load fall from 1.83 s to 1.33 s, and those of the area change through Castle Town's gate into Hyrule Field from 0.70 s to 0.31 s; both runs of each side agree to within 80 ms. The uploads the draws ask for at those two moments fall from about 2,580 to about 470. The rest of the run, the video memory at the end and the flicker test are the same on both sides.Hardware: Windows 11 Pro 26200, RTX 4070 SUPER 12 GB (NVIDIA 617.42), Ryzen 9 9950X3D (16 cores, SMT off), 32 GB
Scene: save set "First Step into Hyrule Town" loaded from the title, then out through the south gate into Hyrule Field and on (a scripted route on the wall clock, 95 s), 2560x1440, DLAA, frame generation off, uncapped (
HOS_FPS_MAX=1000), headless;RX_VK_ASTC_BC_ALL=1,RX_VK_IMAGE_BLOCK_MB=32,RX_VK_BC_LAYERS=8,RX_VK_LATE_FIX=0Method: one build, one run with the switch first (it fills
cache/longshot_textures_drawn.bin), then off, on, off, on. From the frame trace (RX_VK_FRAME_TRACE=1, both sides) each arrival is found where play begins after a loading screen (the first frame with 2 ms or more of draws after 60 or more with less) and counted over the 3 s from it: the first is the save's load-in (at 29.3-29.8 s), the second the gate (at 38.1-38.4 s)Baseline: this PR without the switch. The build is this PR @
ff04d32emerged locally with main @544229a2(two conflicts, both additions side by side:texture_ahead_run();after main'srec_open(tag)lines inrun_submit, and a row ofdocs/development.md), with the two-line link fix our MSVC-target build needs (#1379); nothing of that is pushed anywhereff04d32eon main544229a2(two runs)RX_VK_TEX_AHEAD=1: this PR @ff04d32eon main544229a2(two runs)Two things that differ from the description's own measurements:
No error or device loss in any of the nine logs. Not tested here: a played session, the cost on a card of 8 GB or less (the 256 MB kept free under the budget was never the limit on 12 GB), Linux.
One thing for the rebase: main now wants a row in
gpu/vk/switches.deffor everyRX_switch (#1300,tests/test_switch_table.py), andRX_VK_TEX_AHEADandRX_VK_TEX_AHEAD_MShave none yet.🤖 Generated with Claude Code
With
RX_VK_TEX_AHEAD=1, textures a draw sampled soon after a load are made and uploaded during a light frame, before their first draw. Unset, every entry point returns at once. I read headc758fa67. It applies onto current main. The list is a cache file, written through a file beside it, and a cut-off or foreign file is not read. A light frame prepares only while it has room 256 MB under the texture budget, and only a texture first drawn within 90 seconds of being made.texture_ahead_run()follows the recording's open, so the uploads go into that recording. On a Steam Deck the long frames after a save loads drop from about 3.3 s to 1.2 s in Kokiri Forest. A Windows RTX 4070 SUPER shows the same kind of drop, and the picture matches. The switch stays off. #1069 is the area-change report, not a second copy of this.View command line instructions
Checkout
From your project repository, check out a new branch and test the changes.