perf(host): a character's shadow map reserves stepped storage, so the frame's other render targets keep their addresses (HOS_SHADOW_BUCKET) #1256
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
2 participants
Notifications
Due date
No due date set.
Dependencies
No dependencies set
Reference
MagicBeanDev/Longshot!1256
Loading…
Reference in a new issue
No description provided.
Delete branch "GummiNaomi/Longshot:perf/shadow-map-slots"
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: Windows 11, RTX 4070 SUPER (NVIDIA 617.42), 2560x1440 and 3840x2160 · Needs: Linux; a Steam Deck; a long play at 3840x2160; other titles
Why
In Castle Town's market, with the camera turning, the game makes 15-16 new textures every frame and lets as many go: every render target of the frame, at a new address. The renderer tells textures apart by address, so each is a new texture object and often a new image, and the dead ones hold video memory until they are found.
The cause is in how the game sizes one kind of target. Each shadow-casting character near the camera gets its own square depth map (NVN format 0x34), and the game computes its side anew every frame from the camera's distance: 384 from far, more from near (up to 1277 seen here), a few pixels different each frame. In the market that gave sides such as 397, 439, 479, 517 ... and 1156, 1191, 1210 ... from one frame to the next. The game makes a frame's render targets one after another in a first-fit heap, asking the host for the storage size and alignment of each, so a shadow map a few pixels larger pushes every target made after it to a new address. With the camera still, the same sizes come in the same order and nothing moves (0.3-0.4 textures made a frame).
Related: #994 and the dead targets' sweep (how the renderer copes with the targets once they have moved; this PR stops most of them moving).
What changed
A character's shadow map reserves the storage of the next step of sides up, so the render targets made after it keep their addresses while its side changes.
nvnTextureBuilderGetStorageSizeandnvnTextureBuilderGetStorageAlignmentanswer a square, two-dimensional, one-level NVN 0x34 texture of side 385 to 1920 with the size and alignment of the next multiple of 384 up (768, 1152, 1536, 1920), where those are larger than its own (host/nvn_native.c,host/shadow_slot.h). Only the bytes the game sets aside change, by less than one step's worth for each such map: the texture keeps its own description, size and layout,nvnTextureGetStorageSizeof a made texture is unchanged, and nothing is drawn or sampled differently. The 384 x 384 maps, the frame's own targets, the static shadow maps (2400, 4096, 12288) and every other format keep their own storage.HOS_SHADOW_BUCKET=<step>sets the step (384);0turns it off.tests/test_shadow_slot.py(which textures get a slot and which side, compiled from the header; that both answers use the slot's layout and the texture's own description is not changed).HOS_SHADOW_BUCKETindocs/development.md;docs/tested/2026-11-16-shadow-map-slots-gumminaomi-off.mdand-on.md.Why this is safe to answer: the game uses these two numbers only to place the texture in its heap (the bytes it reserves are the size plus the alignment). No game code is in this change, and the rule goes only by a texture's shape and format as the host is asked for them. How the game sizes these maps and places its targets I read from the game statically, to understand the addresses in the log; it is described here in my own words.
Measurements
Verdict: 6.0-6.7 textures made a frame in the market with the camera turning, against 15.2-16.2 (9.0 in one run), and a third fewer new images; the frame rate is the same within the runs' spread at 2560x1440 (61.1 against 61.4 fps over five runs a side), and at 3840x2160 one run a side went from 45.7 to 50.8 fps with 150 frames over 25 ms against 335.
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", the walk into Castle Town's market and the camera turning (town-market.txt, wall clock, 100 s), DLAA, uncapped
Method: headless runs, the two sides in turn, five rounds at 2560x1440 and one at 3840x2160; the frame trace from 48 s on (the camera turn) and the log's status lines
Baseline: main's behaviour is this PR with
HOS_SHADOW_BUCKET=0; both sides are one build, mainac778751with this change. The branch has since been merged with maina413bf1c(no conflict) and built and run once there: 5.8 textures made a frame, no errorHow to reproduce:
HOS_SHADOW_BUCKET=0against no switch, on the route aboveHOS_SHADOW_BUCKET=0: this PR @4ad1d6004ad1d600texture_frame, a frameThe second run with the slots had nine frames over 100 ms (101 to 412 ms), all between 65 and 69 s, with the render thread's phases small in them. No other run of either side had one, and I did not find the cause: the game has such stalls of its own in play without this change (a 745 ms one in a played session on main), but I cannot show this one was that.
HOS_SHADOW_BUCKET=0: this PR @4ad1d6004ad1d600What is left at 6 a frame: the changing maps themselves (a new description each frame), the frames in which a map crosses a step, and characters gaining or losing their shadow, which moves what the game makes after them.
One round of the gate's flicker test (a 320x180 shot every present, ~13,000 frames): 54 frames with 1 % or more of the picture flipping for one frame without the slots, 38 with. Two played sessions in the market, a shop and back with this change (and the dead targets' sweep): no flicker seen, and the texture budget was not cut once.
Flags and settings
One new switch, on by default.
HOS_SHADOW_BUCKETTesting
Tested: Windows 11, RTX 4070 SUPER, NVIDIA 617.42: the runs above; two played sessions;
tests/test_shadow_slot.py,tests/test_nvn_tex_builder_guard.pyandtests/test_nvn_host_tables.pypass;python -I -B tests/run_all.py: 391 passed, 90 failed, 213 skipped, the same 90 failing as on mainac778751on this PC (390 passed there; its toolchain: no gcc, Windows line endings, fixtures needing tools not installed).Not tested: Linux, the Steam Deck, AMD, Intel; a long session at 3840x2160 (the game's heap for these targets is 512 MB at 2560x1440 and 686 MB at 3840x2160,
hos_rt_pool_size; each such map reserves at most 1.8 MB more at the first step and under 4 MB at the last); handheld mode; other titles (the rule is by shape and format: another game's square one-level 0x34 textures of 385 to 1920 would reserve a little more too).Must be tested:
Risks
What could break: the game's heap for a frame's targets has a fixed size (512 MB at 2560x1440,
hos_rt_pool_size), and a slot reserves more of it than the map needs; if it ran out, the game's allocation would fail (a missing shadow or a crash). It held at 3840x2160 for 100 s here; a long session there is not tested. Another title's textures of the same shape would reserve slightly more memory.Turning it off:
HOS_SHADOW_BUCKET=0.Compatibility: Nothing changes.
Issues
None found for this exactly.
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.🤖 Generated with Claude Code
@Beanstalk linux: Castle Town's market with the camera turning (save set "First Step into Hyrule Town", the walk north into the market, then the camera turned for a minute), once with this PR's default and once with
HOS_SHADOW_BUCKET=0(the behaviour before it). Expecting: no crash; the same picture on both, shadows included; with the default fewer textures made a frame (the log'sN textures made a framelines: about 6 against about 15 here), and a frame rate no worse.🤖 Generated with Claude Code
Beanstalk test farm
Commit
2297e55· tier reviewed · approved by GummiNaomi · dashboardWhat will be tested · AI plan (
gpt-6.1-terra)On Linux, the plan teleports a new child save to Castle Town Market and applies camera-turn input for 3,600 frames with shadow bucketing enabled and disabled. It compares pictures against main and measures frame rate, frame times and VRAM after the turn; crashes, material visual differences or a frame-rate drop over 10% fail. The requested town-entry save is unavailable, and the farm cannot measure texture creations per frame or collect performance metrics during the turn, so those expectations are not directly tested. The two configurations take roughly 28 minutes per tester.
HOS_SHADOW_BUCKET=0), then teleport to Market, take the picture market-before to compare with main, 6 times: move the stick, take the picture market-after to compare with main, measure market-rest for 10 s (after 5 s warm-up); 1 run on each side.Done. Comment
@Beanstalkto run it again.AMD Radeon RX 7900 XTX (RADV NAVI31), 26.2.7Measurements · linux
Verdict: fail on linux (1/1 report):
market-default market-rest.fps_mean.min_delta_pct (-78.5%);market-default screenshot.max_diff;market-bucketing-off screenshot.max_difffailed.Hardware: 1: linux+amd+radv+dgpu
AMD Radeon RX 7900 XTX (RADV NAVI31), 26.2.7AMD Ryzen 7 5800X3D 8-Core Processor, 64 GB RAMScene: market-default, from a new save (frame_rate_cap=6); market-bucketing-off, from a new save (frame_rate_cap=6, HOS_SHADOW_BUCKET=0); each cell's settings and switches as the table names them
Method: the Beanstalk test farm: main and this PR built and run on the same PC in one session, game starts alternating (ABBA); market-default: 1 game start a side, market-rest 10 s after 5 s warm-up; market-bucketing-off: 1 game start a side, market-rest 10 s after 5 s warm-up; each number the median of the runs, then of 1 report
How to reproduce: the farm's plan above (
@Beanstalkon this PR runs it again)a413bf12297e55Flags and settings
None: the plan varied no setting, switch or build option.
Markdown for the PR description
WIP: perf(host): a character's shadow map reserves stepped storage, so the frame's other render targets keep their addresses (HOS_SHADOW_BUCKET)to perf(host): a character's shadow map reserves stepped storage, so the frame's other render targets keep their addresses (HOS_SHADOW_BUCKET)