WIP: perf(vk): the static shadow map made smaller on cards with little VRAM (RX_VK_SHADOW_MAP_SIZE) #1367

Draft
GrimVisage wants to merge 2 commits from GrimVisage/Longshot:perf/half-size-static-shadow into main
Contributor

Type: perf · Risk: medium · Tested on: Linux, RX 9070 XT (RADV) · Needs: Windows, an 8 GB card (RX 6600-class); a card under 6 GB

Why

On 8 GB cards the game runs out of video memory in some areas. Textures then get dropped and the frame rate falls,
for example to 15 fps on an RX 6600 in #1066. One piece of that is a single image the game makes whenever an area
loads: a 12288 x 12288 static shadow map that takes 288 MB of VRAM on every GPU. That is about 4% of everything
an 8 GB card lets the renderer use. Made smaller on cards with little VRAM, it gives back 126 MB at 3/4 size or
216 MB at half size, and the shadows still fall in the same places. Fixes #1295. See #1066.

What changed

The static shadow map can now be made at 75% or 50% of its side, as 9216 x 9216 (162 MB) or 6144 x 6144 (72 MB).
Its draws' viewport, scissor and clears shrink by the same share. Because the game samples it through normalized
coordinates as a depth comparison, the same coordinates land on the same spot in the smaller image. By default
(Auto) it is made at 50% where the driver allows the process under 6 GB, at 75% under 8.5 GB or on an integrated
GPU, and at full size everywhere else. RX_VK_SHADOW_MAP_SIZE=100, 75 or 50 picks the size on any card.

  • texture: gpu/vk/static_shadow_half.h (new) recognizes the image: 2D, NVN 0x32 (D16), one level and layer,
    not multisampled, square, at least 8192 a side. It holds the Auto rule (auto_percent), the switch
    (percent) and the rectangle and viewport scaling. create() in gpu/vk/vk_texture.cpp decides the size once
    per process, logs it, and sets Texture::rt_pct (vk_texture.h).
  • draw: in gpu/vk/vk_draw.cpp, targets() carries the depth target's share (Targets::depth_pct, only with no
    colour target bound; a colour target bound alongside it is logged once). dynamic_state scales the viewport
    and scissor, and clear_rect scales depth clears. The share goes into the fast-path key (up[14]).
  • transfers: in gpu/vk/vk_xfer.cpp, resolve() scales a copy's rectangle into or out of the image.
    copy_buffer out of it is skipped and logged.
  • uploads and write-back: upload_inner clears the image when the upload is all zero (the game's only upload of
    it). Any other upload is skipped and logged. Write-back to guest memory is never done for it. None of these
    happened in any run here.
  • switch: a row in gpu/vk/switches.def and in docs/development.md, "Switches for testing and debugging".
  • test: tests/test_static_shadow_half.cpp / .py cover which textures count, the Auto rule, the switch's
    values, the sizes, and the rectangle and viewport scaling at 75 and 50.

Measurements

Verdict: no cost and no measured gain on this PC. On this card (16 GB) Auto keeps the whole map, and main and
this PR are the same within the spread. With an 8 GB card's budget modelled (RX_VK_TEST_ALLOWED_MB=6500), Auto
makes the map at 9216 (126 MB less), and fps stays within the spread. That is shown best by the same build with only
the switch changed. A first main-against-PR series at that budget had Kokiri Forest slower on the PR's side. The
switch-only pairs didn't repeat it: there the best Kokiri run was a 75% one. At this budget a run's fps depends
mostly on how its area loads go, because a load that drops many textures leaves a lower texture budget for the rest
of the area. The modelled budget never makes the driver really short, so what 126 MB gives back on a real 8 GB card,
where the driver moves memory to system RAM, is in Must be tested.

Hardware: Fedora 45 (Linux 7.3.3), AMD Radeon RX 9070 XT 16 GB, radv Mesa 26.2.7, Ryzen 5 5600X, 32 GB
Scene: child Link, a test save, noon. The Market standing 30 s then turning 30 s, then Kokiri Forest and Hyrule
Field the same, each after a teleport and 15 s to settle. 2560x1440 fullscreen, the Auto preset's settings for this
PC (FSR 4 Quality, 1707x960 -> 2560x1440), mesh shaders by the default (the compute path), frame generation off, cap
240 (HOS_FPS_MAX=240; no part came near it), RX_VK_AUTO_TUNE=0.
Method: each part's median fps and 1% low from the frame log (RX_VK_FRAME_LOG); the texture budget and VRAM from
the log's vk: VRAM: lines. One job at a time through the job queue's timing mode, one options file for every run,
the route through scripts/longshot_ctl.py (debug tools on for the teleports). Series 1: two test builds from
6d72ca93 (dev_packs.py), a warm-up of each, then main, PR, PR, main, as this card and again with
RX_VK_TEST_ALLOWED_MB=6500. Series 2: the PR's build alone at 6500, RX_VK_SHADOW_MAP_SIZE=100 against 75, a
warm-up, then 100, 75, 75, 100 (stopped there: the sides overlapped). The median of the runs on each side.
How to reproduce: the same route on any save in the Market; RX_VK_TEST_ALLOWED_MB=6500 for the modelled budget,
RX_VK_SHADOW_MAP_SIZE=100 or 75 to pick the size.
Baseline: the measured commit was 7e080be9 on main 6d72ca93. This PR is that commit rebased onto 544229a2, whose one
commit (#1332) is Windows-only (load_global's #ifdef _WIN32), so the Linux numbers hold.

Series 1, as this card (Auto: the whole map on both sides), fps (runs; median):

Before: main @ 6d72ca93 After: this PR @ 7e080be9
Market, standing 45.7, 46.0; 45.9 46.1, 44.4; 45.3
Market, turning 53.5, 52.5; 53.0 53.6, 52.1; 52.9
Kokiri Forest, standing 65.1, 61.1; 63.1 66.2, 61.9; 64.1
Kokiri Forest, turning 65.5, 64.6; 65.1 66.4, 63.8; 65.1
Hyrule Field, standing 55.7, 59.0; 57.4 58.0, 56.0; 57.0
Hyrule Field, turning 53.2, 56.6; 54.9 54.2, 53.7; 54.0
The static shadow map 12288, 288 MB 12288, 288 MB

Series 1, RX_VK_TEST_ALLOWED_MB=6500 (Auto on this PR: 75%), fps (runs; median):

Before: main @ 6d72ca93 After: this PR @ 7e080be9
Market, standing 45.8, 46.6; 46.2 46.0, 45.2; 45.6
Market, turning 52.1, 54.4; 53.3 51.4, 52.5; 52.0
Kokiri Forest, standing 57.0, 54.1; 55.6 50.7, 48.5; 49.6
Kokiri Forest, turning 68.0, 68.1; 68.1 62.9, 62.3; 62.6
Hyrule Field, standing 42.9, 58.9; 50.9 43.0, 50.7; 46.9
Hyrule Field, turning 53.8, 61.7; 57.8 42.2, 37.0; 39.6
Texture budget in Kokiri Forest, MB 2808, 2791 2065, 1991
The static shadow map 12288, 288 MB 9216, 162 MB

Series 2, RX_VK_TEST_ALLOWED_MB=6500, the switch alone, fps (runs; median):

After, RX_VK_SHADOW_MAP_SIZE=100: this PR @ 7e080be9 After, RX_VK_SHADOW_MAP_SIZE=75: this PR @ 7e080be9
Market, standing 46.6, 46.9; 46.8 46.0, 46.9; 46.5
Market, turning 53.7, 54.2; 54.0 53.7, 53.9; 53.8
Kokiri Forest, standing 53.2, 49.4; 51.3 49.9, 58.1; 54.0
Kokiri Forest, turning 65.5, 63.9; 64.7 63.8, 67.5; 65.7
Hyrule Field, standing 48.1, 47.0; 47.6 46.7, 48.0; 47.4
Hyrule Field, turning 48.3, 47.2; 47.8 47.8, 47.4; 47.6
Texture budget in Kokiri Forest, MB 2768, 2210 2299, 2324
vk: texture 0x1147c16000 12288x12288 D16 (NVN 0x32), the static shadow map: made at 9216x9216, 75% (126 MB less; RX_VK_SHADOW_MAP_SIZE=100: whole)
vk: texture 0x1147c16000 9216x9216x1 x1 levels 1 NVN 0x32 -> vk 124 (478 textures, 1243 MB)
vk: texture budget: 4875 MB (driver allows 6500 MB, the card has 16304 MB, RAM 31987 MB)
main, 6500, Kokiri:  vk: VRAM: 5491 MB used of 6500 MB allowed (720 MB of it free in the blocks); textures 2480 MB (budget 2808 MB), 1454 textures
PR, 6500, Kokiri:    vk: VRAM: 5568 MB used of 6500 MB allowed (1188 MB of it free in the blocks); textures 2011 MB (budget 2065 MB), 954 textures
=100, 6500, Kokiri:  vk: VRAM: 5603 MB used of 6500 MB allowed (1205 MB of it free in the blocks); textures 2146 MB (budget 2210 MB), 1007 textures
=75, 6500, Kokiri:   vk: VRAM: 5520 MB used of 6500 MB allowed (988 MB of it free in the blocks); textures 2262 MB (budget 2324 MB), 1169 textures

Screenshots of the same spot and frame of a scripted route (RX 9070 XT, 2560x1440, the game's own upscaler: that
test build had no FSR 4), left to right RX_VK_SHADOW_MAP_SIZE=100 (whole, as main), 75, 50, all three on
this change on main 1764fed2 (the same code as this PR; the size the only difference):

Death Mountain Trail, the path's branch and grass shadows, full size crops. Left: After, RX_VK_SHADOW_MAP_SIZE=100 (as main). Middle: After, RX_VK_SHADOW_MAP_SIZE=75. Right: After, RX_VK_SHADOW_MAP_SIZE=50

Kokiri Forest, the whole frame scaled to half. Left: RX_VK_SHADOW_MAP_SIZE=100 (as main). Middle: 75. Right: 50

At 75 the edges are close to whole; at 50 the branches' shadows are visibly coarser and stepped.

Flags and settings

This adds one switch, RX_VK_SHADOW_MAP_SIZE.

Flag What it is Before this PR After this PR Effect Helps / doesn't help / untested Recommendation
RX_VK_SHADOW_MAP_SIZE The size of the static shadow map, as a share of its side (none: always 12288, 288 MB) Auto: 50 under 6 GB allowed, 75 under 8.5 GB or integrated, 100 otherwise; 100, 75 or 50 on any card 126 MB (75) or 216 MB (50) less VRAM. Shadow edges coarser by the same share 75: close to whole on screen (RX 9070 XT, 2560x1440). 50: the ground's grass and branch shadows visibly coarser and stepped. Not yet run on a real 8 GB or 6 GB card Auto for everyone; 100 to compare

Testing

Tested:

  • python -I -B tests/run_all.py on Linux, on this PR and on main 544229a2: the same tests fail on both on this PC
    (checks that read source main has since changed, lz4 not installed, tests/test_switch_table.py's
    RX_VK_PGO_FILE row, and tests/test_tested_configurations.py, which stops at
    2026-11-16-shadow-map-slots-gumminaomi-on.md from #1256). This PR's 12 docs/tested/ files read fine with its
    read_row. tests/test_static_shadow_half.py passes, and so does each test that differed between the
    two runs when run alone.
  • RX 9070 XT, Linux, RADV, at all three sizes: Market, Kokiri Forest, Hyrule Field, Kakariko Village and Death
    Mountain Trail, standing and turning. Shadows land in the same places at every size. The log shows no skipped
    copy, upload or write-back.
  • A human spot check of 100, 75 and 50 in the game, fullscreen: 75 looks close to whole, 50 is visibly coarser.
  • The measured runs above: in every run the map was made at the size asked for (12288, or 9216 at 75).

Not tested: a real card with 8 GB or less, and Windows. This PC has 16 GB; RX_VK_TEST_ALLOWED_MB only models
the budget. An integrated GPU (Auto: 75).

Must be tested:

  • Windows, an 8 GB AMD card (RX 6600 / 6600 XT / 6650 XT class), the driver's default: Kokiri Forest and the
    Market, standing then turning, on main and on this PR. Expect the log to say the static shadow map: made at 9216x9216, 75%, the frame rate in Kokiri Forest the same or better than main (the gain, if any, is what
    this PC could not show), and shadows in the
    same places (Test Farm: @Beanstalk windows, amd, 8 GB — see the request comment).
  • A card the driver allows under 6 GB (a 6 GB card, or a 4 GB one): the same, expecting 6144x6144, 50% and about
    216 MB less (Test Farm, if a farm PC has one).

Risks

What could break: the static shadow map's shadows, if a game path reads the image another way than the ones
seen here: a buffer copy out of it, an upload that isn't all zero, a write-back, or a colour target bound beside
it. Each one is logged when it happens. On cards that get a smaller map, its shadows' edges are coarser. Cards
allowed 8.5 GB or more get the whole map, as on main.

Turning it off: RX_VK_SHADOW_MAP_SIZE=100.

Compatibility: nothing changes for saves, longshot_options.ini or the vk ABI. The fast-path key gains the
depth target's share, so nothing is translated again.

Issues

Fixes #1295
See #1066

Checklist

Everyone

  • One topic.
  • The title is a Conventional Commit (type(scope): description) of the status line's type.
  • Why gives the reason plainly and links the issues that fit (the tracker searched).
  • Measurements has a verdict, or one line saying why there is nothing to measure.
  • Testing names what was tested, what wasn't, and what must still be tested, where and how.
  • Rebased on current main.
  • python -I -B tests/run_all.py passes (any failure that also fails on main is named).
  • No game files, dumps, build output or generated files.
  • third_party/ untouched (a new folder with a PROVENANCE.md instead).
  • The license is OK: GPL-3.0-or-later, nothing incompatible and nothing decompiled.

When it applies

  • AI assistance recorded with Assisted-by: / Co-Authored-By: trailers.
  • Numbers from the same PC, scene and settings, at least 2 interleaved runs each, the median reported.
  • Switches documented (docs/development.md; the README for a menu row) and shipped at their recommended value.
  • Screenshots of the same spot, captioned like the Measurements columns, for a change that shows on screen.
  • A file in docs/tested/ for each new measured run (format in docs/tested-configurations.md).
  • Docs updated.

🤖 Generated with Claude Code

**Type:** perf · **Risk:** medium · **Tested on:** Linux, RX 9070 XT (RADV) · **Needs:** Windows, an 8 GB card (RX 6600-class); a card under 6 GB ## Why On 8 GB cards the game runs out of video memory in some areas. Textures then get dropped and the frame rate falls, for example to 15 fps on an RX 6600 in #1066. One piece of that is a single image the game makes whenever an area loads: a 12288 x 12288 static shadow map that takes **288 MB of VRAM on every GPU**. That is about 4% of everything an 8 GB card lets the renderer use. Made smaller on cards with little VRAM, it gives back 126 MB at 3/4 size or 216 MB at half size, and the shadows still fall in the same places. Fixes #1295. See #1066. ## What changed The static shadow map can now be made at 75% or 50% of its side, as 9216 x 9216 (162 MB) or 6144 x 6144 (72 MB). Its draws' viewport, scissor and clears shrink by the same share. Because the game samples it through normalized coordinates as a depth comparison, the same coordinates land on the same spot in the smaller image. By default (Auto) it is made at 50% where the driver allows the process under 6 GB, at 75% under 8.5 GB or on an integrated GPU, and at full size everywhere else. `RX_VK_SHADOW_MAP_SIZE=100`, `75` or `50` picks the size on any card. - texture: `gpu/vk/static_shadow_half.h` (new) recognizes the image: 2D, NVN 0x32 (D16), one level and layer, not multisampled, square, at least 8192 a side. It holds the Auto rule (`auto_percent`), the switch (`percent`) and the rectangle and viewport scaling. `create()` in `gpu/vk/vk_texture.cpp` decides the size once per process, logs it, and sets `Texture::rt_pct` (`vk_texture.h`). - draw: in `gpu/vk/vk_draw.cpp`, `targets()` carries the depth target's share (`Targets::depth_pct`, only with no colour target bound; a colour target bound alongside it is logged once). `dynamic_state` scales the viewport and scissor, and `clear_rect` scales depth clears. The share goes into the fast-path key (`up[14]`). - transfers: in `gpu/vk/vk_xfer.cpp`, `resolve()` scales a copy's rectangle into or out of the image. `copy_buffer` out of it is skipped and logged. - uploads and write-back: `upload_inner` clears the image when the upload is all zero (the game's only upload of it). Any other upload is skipped and logged. Write-back to guest memory is never done for it. None of these happened in any run here. - switch: a row in `gpu/vk/switches.def` and in docs/development.md, "Switches for testing and debugging". - test: `tests/test_static_shadow_half.cpp` / `.py` cover which textures count, the Auto rule, the switch's values, the sizes, and the rectangle and viewport scaling at 75 and 50. ## Measurements **Verdict:** no cost and no measured gain on this PC. On this card (16 GB) Auto keeps the whole map, and main and this PR are the same within the spread. With an 8 GB card's budget modelled (`RX_VK_TEST_ALLOWED_MB=6500`), Auto makes the map at 9216 (126 MB less), and fps stays within the spread. That is shown best by the same build with only the switch changed. A first main-against-PR series at that budget had Kokiri Forest slower on the PR's side. The switch-only pairs didn't repeat it: there the best Kokiri run was a 75% one. At this budget a run's fps depends mostly on how its area loads go, because a load that drops many textures leaves a lower texture budget for the rest of the area. The modelled budget never makes the driver really short, so what 126 MB gives back on a real 8 GB card, where the driver moves memory to system RAM, is in Must be tested. Hardware: Fedora 45 (Linux 7.3.3), AMD Radeon RX 9070 XT 16 GB, radv Mesa 26.2.7, Ryzen 5 5600X, 32 GB Scene: child Link, a test save, noon. The Market standing 30 s then turning 30 s, then Kokiri Forest and Hyrule Field the same, each after a teleport and 15 s to settle. 2560x1440 fullscreen, the Auto preset's settings for this PC (FSR 4 Quality, 1707x960 -> 2560x1440), mesh shaders by the default (the compute path), frame generation off, cap 240 (`HOS_FPS_MAX=240`; no part came near it), `RX_VK_AUTO_TUNE=0`. Method: each part's median fps and 1% low from the frame log (`RX_VK_FRAME_LOG`); the texture budget and VRAM from the log's `vk: VRAM:` lines. One job at a time through the job queue's timing mode, one options file for every run, the route through `scripts/longshot_ctl.py` (debug tools on for the teleports). Series 1: two test builds from 6d72ca93 (`dev_packs.py`), a warm-up of each, then main, PR, PR, main, as this card and again with `RX_VK_TEST_ALLOWED_MB=6500`. Series 2: the PR's build alone at 6500, `RX_VK_SHADOW_MAP_SIZE=100` against `75`, a warm-up, then 100, 75, 75, 100 (stopped there: the sides overlapped). The median of the runs on each side. How to reproduce: the same route on any save in the Market; `RX_VK_TEST_ALLOWED_MB=6500` for the modelled budget, `RX_VK_SHADOW_MAP_SIZE=100` or `75` to pick the size. Baseline: the measured commit was 7e080be9 on main 6d72ca93. This PR is that commit rebased onto 544229a2, whose one commit (#1332) is Windows-only (`load_global`'s `#ifdef _WIN32`), so the Linux numbers hold. Series 1, as this card (Auto: the whole map on both sides), fps (runs; median): | | Before: main @ 6d72ca93 | After: this PR @ 7e080be9 | |---|---|---| | Market, standing | 45.7, 46.0; 45.9 | 46.1, 44.4; 45.3 | | Market, turning | 53.5, 52.5; 53.0 | 53.6, 52.1; 52.9 | | Kokiri Forest, standing | 65.1, 61.1; 63.1 | 66.2, 61.9; 64.1 | | Kokiri Forest, turning | 65.5, 64.6; 65.1 | 66.4, 63.8; 65.1 | | Hyrule Field, standing | 55.7, 59.0; 57.4 | 58.0, 56.0; 57.0 | | Hyrule Field, turning | 53.2, 56.6; 54.9 | 54.2, 53.7; 54.0 | | The static shadow map | 12288, 288 MB | 12288, 288 MB | Series 1, `RX_VK_TEST_ALLOWED_MB=6500` (Auto on this PR: 75%), fps (runs; median): | | Before: main @ 6d72ca93 | After: this PR @ 7e080be9 | |---|---|---| | Market, standing | 45.8, 46.6; 46.2 | 46.0, 45.2; 45.6 | | Market, turning | 52.1, 54.4; 53.3 | 51.4, 52.5; 52.0 | | Kokiri Forest, standing | 57.0, 54.1; 55.6 | 50.7, 48.5; 49.6 | | Kokiri Forest, turning | 68.0, 68.1; 68.1 | 62.9, 62.3; 62.6 | | Hyrule Field, standing | 42.9, 58.9; 50.9 | 43.0, 50.7; 46.9 | | Hyrule Field, turning | 53.8, 61.7; 57.8 | 42.2, 37.0; 39.6 | | Texture budget in Kokiri Forest, MB | 2808, 2791 | 2065, 1991 | | The static shadow map | 12288, 288 MB | 9216, 162 MB | Series 2, `RX_VK_TEST_ALLOWED_MB=6500`, the switch alone, fps (runs; median): | | After, RX_VK_SHADOW_MAP_SIZE=100: this PR @ 7e080be9 | After, RX_VK_SHADOW_MAP_SIZE=75: this PR @ 7e080be9 | |---|---|---| | Market, standing | 46.6, 46.9; 46.8 | 46.0, 46.9; 46.5 | | Market, turning | 53.7, 54.2; 54.0 | 53.7, 53.9; 53.8 | | Kokiri Forest, standing | 53.2, 49.4; 51.3 | 49.9, 58.1; 54.0 | | Kokiri Forest, turning | 65.5, 63.9; 64.7 | 63.8, 67.5; 65.7 | | Hyrule Field, standing | 48.1, 47.0; 47.6 | 46.7, 48.0; 47.4 | | Hyrule Field, turning | 48.3, 47.2; 47.8 | 47.8, 47.4; 47.6 | | Texture budget in Kokiri Forest, MB | 2768, 2210 | 2299, 2324 | ``` vk: texture 0x1147c16000 12288x12288 D16 (NVN 0x32), the static shadow map: made at 9216x9216, 75% (126 MB less; RX_VK_SHADOW_MAP_SIZE=100: whole) vk: texture 0x1147c16000 9216x9216x1 x1 levels 1 NVN 0x32 -> vk 124 (478 textures, 1243 MB) vk: texture budget: 4875 MB (driver allows 6500 MB, the card has 16304 MB, RAM 31987 MB) main, 6500, Kokiri: vk: VRAM: 5491 MB used of 6500 MB allowed (720 MB of it free in the blocks); textures 2480 MB (budget 2808 MB), 1454 textures PR, 6500, Kokiri: vk: VRAM: 5568 MB used of 6500 MB allowed (1188 MB of it free in the blocks); textures 2011 MB (budget 2065 MB), 954 textures =100, 6500, Kokiri: vk: VRAM: 5603 MB used of 6500 MB allowed (1205 MB of it free in the blocks); textures 2146 MB (budget 2210 MB), 1007 textures =75, 6500, Kokiri: vk: VRAM: 5520 MB used of 6500 MB allowed (988 MB of it free in the blocks); textures 2262 MB (budget 2324 MB), 1169 textures ``` Screenshots of the same spot and frame of a scripted route (RX 9070 XT, 2560x1440, the game's own upscaler: that test build had no FSR 4), left to right `RX_VK_SHADOW_MAP_SIZE=100` (whole, as main), `75`, `50`, all three on this change on main 1764fed2 (the same code as this PR; the size the only difference): ![Death Mountain Trail, the path's branch and grass shadows, full size crops. Left: After, RX_VK_SHADOW_MAP_SIZE=100 (as main). Middle: After, RX_VK_SHADOW_MAP_SIZE=75. Right: After, RX_VK_SHADOW_MAP_SIZE=50](https://git.magicbean.dev/attachments/c633257c-0cc9-44ad-a240-d21f9488ffca) ![Kokiri Forest, the whole frame scaled to half. Left: RX_VK_SHADOW_MAP_SIZE=100 (as main). Middle: 75. Right: 50](https://git.magicbean.dev/attachments/984675d8-37c4-49ba-8f4e-81db48976bd0) At 75 the edges are close to whole; at 50 the branches' shadows are visibly coarser and stepped. ### Flags and settings This adds one switch, `RX_VK_SHADOW_MAP_SIZE`. | Flag | What it is | Before this PR | After this PR | Effect | Helps / doesn't help / untested | Recommendation | |---|---|---|---|---|---|---| | `RX_VK_SHADOW_MAP_SIZE` | The size of the static shadow map, as a share of its side | (none: always 12288, 288 MB) | Auto: 50 under 6 GB allowed, 75 under 8.5 GB or integrated, 100 otherwise; `100`, `75` or `50` on any card | 126 MB (75) or 216 MB (50) less VRAM. Shadow edges coarser by the same share | 75: close to whole on screen (RX 9070 XT, 2560x1440). 50: the ground's grass and branch shadows visibly coarser and stepped. Not yet run on a real 8 GB or 6 GB card | Auto for everyone; `100` to compare | ## Testing **Tested:** - `python -I -B tests/run_all.py` on Linux, on this PR and on main 544229a2: the same tests fail on both on this PC (checks that read source main has since changed, `lz4` not installed, `tests/test_switch_table.py`'s `RX_VK_PGO_FILE` row, and `tests/test_tested_configurations.py`, which stops at `2026-11-16-shadow-map-slots-gumminaomi-on.md` from #1256). This PR's 12 `docs/tested/` files read fine with its `read_row`. `tests/test_static_shadow_half.py` passes, and so does each test that differed between the two runs when run alone. - RX 9070 XT, Linux, RADV, at all three sizes: Market, Kokiri Forest, Hyrule Field, Kakariko Village and Death Mountain Trail, standing and turning. Shadows land in the same places at every size. The log shows no skipped copy, upload or write-back. - A human spot check of 100, 75 and 50 in the game, fullscreen: 75 looks close to whole, 50 is visibly coarser. - The measured runs above: in every run the map was made at the size asked for (12288, or 9216 at 75). **Not tested:** a real card with 8 GB or less, and Windows. This PC has 16 GB; `RX_VK_TEST_ALLOWED_MB` only models the budget. An integrated GPU (Auto: 75). **Must be tested:** - Windows, an 8 GB AMD card (RX 6600 / 6600 XT / 6650 XT class), the driver's default: Kokiri Forest and the Market, standing then turning, on main and on this PR. Expect the log to say `the static shadow map: made at 9216x9216, 75%`, the frame rate in Kokiri Forest the same or better than main (the gain, if any, is what this PC could not show), and shadows in the same places (Test Farm: `@Beanstalk windows, amd, 8 GB` — see the request comment). - A card the driver allows under 6 GB (a 6 GB card, or a 4 GB one): the same, expecting `6144x6144, 50%` and about 216 MB less (Test Farm, if a farm PC has one). ## Risks **What could break:** the static shadow map's shadows, if a game path reads the image another way than the ones seen here: a buffer copy out of it, an upload that isn't all zero, a write-back, or a colour target bound beside it. Each one is logged when it happens. On cards that get a smaller map, its shadows' edges are coarser. Cards allowed 8.5 GB or more get the whole map, as on main. **Turning it off:** `RX_VK_SHADOW_MAP_SIZE=100`. **Compatibility:** nothing changes for saves, longshot_options.ini or the vk ABI. The fast-path key gains the depth target's share, so nothing is translated again. ## Issues Fixes #1295 See #1066 ## Checklist ### Everyone - [x] One topic. - [x] The title is a Conventional Commit (`type(scope): description`) of the status line's type. - [x] Why gives the reason plainly and links the issues that fit (the tracker searched). - [x] Measurements has a verdict, or one line saying why there is nothing to measure. - [x] Testing names what was tested, what wasn't, and what must still be tested, where and how. - [x] Rebased on current `main`. - [x] `python -I -B tests/run_all.py` passes (any failure that also fails on `main` is named). - [x] No game files, dumps, build output or generated files. - [x] `third_party/` untouched (a new folder with a `PROVENANCE.md` instead). - [x] The license is OK: GPL-3.0-or-later, nothing incompatible and nothing decompiled. ### When it applies - [x] AI assistance recorded with `Assisted-by:` / `Co-Authored-By:` trailers. - [x] Numbers from the same PC, scene and settings, at least 2 interleaved runs each, the median reported. - [x] Switches documented (docs/development.md; the README for a menu row) and shipped at their recommended value. - [x] Screenshots of the same spot, captioned like the Measurements columns, for a change that shows on screen. - [x] A file in `docs/tested/` for each new measured run (format in `docs/tested-configurations.md`). - [x] Docs updated. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
OoT makes one 12288 x 12288 D16 depth image when an area loads (288 MB on every GPU) and samples it as a depth
comparison. It can be made at 75 % (9216, 162 MB) or 50 % (6144, 72 MB) of its side, with its draws' viewport,
scissor and clears scaled by the same share. Copies into or out of it are scaled. Buffer copies, uploads that
are not all zero and write-backs to guest memory are skipped and logged. RX_VK_SHADOW_MAP_SIZE=100, 75 or 50 on
any card. Auto: 50 on cards the driver allows under 6 GB, 75 under 8.5 GB and on integrated GPUs, 100 on the
others; at 50 the ground's grass and branch shadows are visibly coarser. Issue 1295.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
docs(tested): the static shadow map at 100 and 75 % on an RX 9070 XT (RADV), as this card and at a modelled 6.5 GB
Some checks are pending
CI / Workflow lint (actionlint) (pull_request) Blocked by required conditions
CI / Conventional Commit title (pull_request) Blocked by required conditions
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Blocked by required conditions
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Blocked by required conditions
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Blocked by required conditions
Guide screenshots / Guide images and local UI source review (pull_request) Blocked by required conditions
Third-party parts / As their notes say (pull_request) Blocked by required conditions
Third-party parts / The same as upstream (pull_request) Blocked by required conditions
Website / Website on Cloudflare (pull_request) Blocked by required conditions
Website / Website on Cloudflare (pull_request_target) Has been skipped
PR description / Description follows the template (pull_request_target) Successful in 4s
beanstalk/approval waiting for a BigBean's 👍 on the request
581a9d5ddb
Twelve measured runs for #1295: main 6d72ca93 against the change (7e080be9), as this card and with
RX_VK_TEST_ALLOWED_MB=6500, and the change alone with RX_VK_SHADOW_MAP_SIZE=100 against 75 at 6500.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Author
Contributor

Tested in game: RX 9070 XT, radv Mesa 26.2.7, Fedora 45: Market, Kokiri Forest, Hyrule Field, Kakariko Village and Death Mountain Trail at RX_VK_SHADOW_MAP_SIZE=100, 75 and 50, and with Auto at RX_VK_TEST_ALLOWED_MB=6500; shadows in the same places at every size, edges coarser at 50, no copy, upload or write-back of the map skipped, no crash

Tested in game: RX 9070 XT, radv Mesa 26.2.7, Fedora 45: Market, Kokiri Forest, Hyrule Field, Kakariko Village and Death Mountain Trail at RX_VK_SHADOW_MAP_SIZE=100, 75 and 50, and with Auto at RX_VK_TEST_ALLOWED_MB=6500; shadows in the same places at every size, edges coarser at 50, no copy, upload or write-back of the map skipped, no crash
Collaborator

Possibly related, for context:

  • PR #211 WIP: fix(vk): keep the shadow map and other drawn textures the game samples again through evictions — Overlapping shadow-map VRAM handling; check interaction with its eviction retention/cap.
  • PR #1073 perf(vk): use smaller VMA block sizes on < 7 GB GPUs — Open low-VRAM Vulkan allocation work; related VRAM-pressure mitigation, but separate allocator changes.
  • issue #939 Game: on a 6 GB card VRAM goes over the driver's allowance after a few area changes, Hyrule Field falls from 31 to 14 fps until a restart (GTX 1060, nightly-189) — Open 6 GB GPU VRAM-overage and FPS-drop report in Hyrule Field.
Possibly related, for context: - PR #211 WIP: fix(vk): keep the shadow map and other drawn textures the game samples again through evictions — Overlapping shadow-map VRAM handling; check interaction with its eviction retention/cap. - PR #1073 perf(vk): use smaller VMA block sizes on < 7 GB GPUs — Open low-VRAM Vulkan allocation work; related VRAM-pressure mitigation, but separate allocator changes. - issue #939 Game: on a 6 GB card VRAM goes over the driver's allowance after a few area changes, Hyrule Field falls from 31 to 14 fps until a restart (GTX 1060, nightly-189) — Open 6 GB GPU VRAM-overage and FPS-drop report in Hyrule Field.
Author
Contributor

The measurements are of 7e080be9 on main 6d72ca93; this PR is that commit rebased onto main 544229a2 (1e0959fa, the same diff) plus the 12 docs/tested/ files (581a9d5d). The one commit in between, #1332, changes only Windows code (load_global under #ifdef _WIN32 in gpu/vk/vk_main.cpp, and its test), so the Linux numbers hold without measuring again.

The measurements are of 7e080be9 on main 6d72ca93; this PR is that commit rebased onto main 544229a2 (1e0959fa, the same diff) plus the 12 `docs/tested/` files (581a9d5d). The one commit in between, #1332, changes only Windows code (`load_global` under `#ifdef _WIN32` in `gpu/vk/vk_main.cpp`, and its test), so the Linux numbers hold without measuring again.
Author
Contributor

@Beanstalk windows, amd, an 8 GB card (RX 6600 / 6600 XT / 6650 XT class), the driver's default settings: compare main and this PR in Kokiri Forest and the Market, standing still, then turning. On this PR the log should say the static shadow map: made at 9216x9216, 75%. Compare VRAM used (the log's VRAM lines), fps and the 1% low against main, and check that the shadows on the ground fall in the same places. If a farm PC has a card the driver allows under 6 GB (a 6 GB or 4 GB card), the same there, expecting 6144x6144, 50%.

@Beanstalk windows, amd, an 8 GB card (RX 6600 / 6600 XT / 6650 XT class), the driver's default settings: compare main and this PR in Kokiri Forest and the Market, standing still, then turning. On this PR the log should say `the static shadow map: made at 9216x9216, 75%`. Compare VRAM used (the log's VRAM lines), fps and the 1% low against main, and check that the shadows on the ground fall in the same places. If a farm PC has a card the driver allows under 6 GB (a 6 GB or 4 GB card), the same there, expecting `6144x6144, 50%`.
Member

@GrimVisage only members of BigBeans can start the farm. One of them can approve this request by reacting 👍 to it or to this comment.

@GrimVisage only members of `BigBeans` can start the farm. One of them can approve this request by reacting 👍 to it or to this comment.
Some checks are pending
CI / Workflow lint (actionlint) (pull_request) Blocked by required conditions
CI / Conventional Commit title (pull_request) Blocked by required conditions
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Blocked by required conditions
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Blocked by required conditions
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Blocked by required conditions
Guide screenshots / Guide images and local UI source review (pull_request) Blocked by required conditions
Third-party parts / As their notes say (pull_request) Blocked by required conditions
Third-party parts / The same as upstream (pull_request) Blocked by required conditions
Website / Website on Cloudflare (pull_request) Blocked by required conditions
Website / Website on Cloudflare (pull_request_target) Has been skipped
PR description / Description follows the template (pull_request_target) Successful in 4s
beanstalk/approval waiting for a BigBean's 👍 on the request
This pull request has changes conflicting with the target branch.
  • docs/development.md
  • gpu/vk/switches.def
  • gpu/vk/vk_texture.cpp
Some workflows are waiting to be reviewed.
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.
git fetch -u 'perf/half-size-static-shadow:GrimVisage-perf/half-size-static-shadow'
git switch 'GrimVisage-perf/half-size-static-shadow'
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
3 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
MagicBeanDev/Longshot!1367
No description provided.