WIP: feat(options): Ground detail distance, so the pebbles and small flowers stop popping in 35 m away #1784

Draft
Jiro113 wants to merge 4 commits from Jiro113/Longshot:fix/gpu-culled-props-popin into main
Contributor

Type: feat · Risk: low · Tested on: Windows 11, RTX 4090 · Needs: an 8 or 12 GB card (Auto = 200% there), any OS

TL;DR

The small pebbles and white flowers along the paths stop being drawn about 35 m from the camera, so they pop in a few
steps ahead as Link walks. That distance is the game's own, written each frame by its foliage setup. This PR adds a
Graphics row, Ground detail distance, that draws them up to four times as far, shadows included. Its default, Auto,
follows the card's memory like Shadow resolution. On an RTX 4090 the frame time doesn't move. A new game-free test fails
on main and passes here, and I watched the pebbles in Hyrule Field at each setting.

Breakdown

  • Who it helps: anyone who walks the paths of Hyrule Field and sees pebbles and little flowers appear just ahead.
  • What was wrong: the game culls this family of ground details at a fixed 35 m fade (25 to 35 m in its data, scaled by the lens), on the GPU.
  • What changes: a hook after the game writes that distance scales it, and its squared twin, by the row's setting (100% to 400%).
  • What does not change: at 100% nothing is written: the game's block bit for bit. Minimum and Low (handhelds, integrated GPUs, cards up to 6 GB) stay at 100% on Auto. Grass, trees and the pixel-size cut are untouched.
  • How it was checked: a game-free test (fails on main, catches a wrong scale or tier), the full check suite (same failures as main), draw counts in the game, and 3 interleaved timing rounds against main.
  • What is still open: the cost on an 8 or 12 GB card (200% on Auto), a survey of the other regions, and the small items close by that the game's pixel-size cut hides (not this PR).
  • Risk: low: a few more small draws in the colour pass and the sun's cascades; at 100% the game's own block.

Why

On the path out of the Kokiri Forest and across Hyrule Field, pebbles and small white flowers pop in a few steps ahead of
Link: the game stops drawing them about 35 m away. It's the game's own choice, not a Longshot bug, but on a PC with
memory and GPU time to spare it can draw them farther, as it already does for shadows (Shadow resolution) and the
draw distance sliders asked for in #205. PR #227's sliders (Object detail, Foliage distance) don't reach this family: it
is culled on the GPU by a distance of its own (below).

See #205. See #227.

What changed

The game's foliage setup writes a per-frame block for its GPU culling. Its word 37 is the pebble family's cut, and word
118 is the same distance squared that the task and mesh stages use. A hook after that write scales word 37 by the
setting and word 118 by its square, so the fade keeps its shape and moves out. The row is read each frame, so a change
applies at once.

  • lifter: nx2/oot_scatter.py installs the hook at the store of word 118 in the foliage setup, for this game build only,
    after checking the instructions around it; nx2/lift.py calls it with the other standalone hooks.
  • host: host/oot_scatter.c hos_oot_scatter() reads rx_option(HOS_OPT_GROUND_DETAIL) and scales the two words on
    the stack; 100 (or anything outside 101 to 400) leaves them alone, as does a value that isn't a distance (0 when the fade is off).
  • menu: Graphics, "Ground detail distance" (opts.ground_detail, ini ground_detail_distance): Auto, then 100% to
    400% in steps of 50. menu_ground_detail() in gpu/vk/vk_menu.cpp resolves Auto by the memory tier, as
    menu_shadow_res() does: 100% on Minimum and Low, 200% on Balanced and High, 400% on Ultra. The Quality presets put
    it back on Auto (apply_preset). HOS_OPT_GROUND_DETAIL = 76 in gpu/vk/vk_api.h (an option id, not the interface:
    no MKWVK_API_VERSION change); vk_replay.cpp answers it.
  • strings: the row, its help and two hints, and the Quality preset's help (it now names this row), in the 13 tables of
    gpu/vk/menu_i18n.h.
  • docs: the README's option table and its Quality preset paragraph; docs/development.md's options file rows.
  • tests: tests/test_oot_scatter.py compiles the host helper against an authored stack block and checks the install,
    the menu wiring and Auto's tiers.

How the cut was found: the pebbles and small flowers are mesh programs 8e2f7af4245747ef (colour), 51183fe750d5d0c8
(the same objects, a second pass) and 28dd2baa17ba10e1 (the sun's three cascades), fed by indirect arguments that
compute b612216258832b9c writes. Scaling the scene buffer's words in the replay showed b612 cuts this kind at word 37
(39.4 m at the default field of view), and the task stage again at sqrt(word 118 / word 119), the same distance. Moving
both (x4, x16) took the colour pass from 1760 to 3360 mesh groups and the shadow pass from 3904 to 6464; moving either
alone did not. The game computes word 37 as 35 m times the lens factor, from a fade of 25 to 35 m in its data: a
constant, so this is the game's design rather than a Longshot fault.

Measurements

Verdict: no cost measured. At 100% the branch matches main (GPU 8.01 against 8.02 ms a frame), and Auto (400% on
this card) is within the spread of the runs (7.90 ms). The scene is CPU-bound at about 91 to 95 fps on both sides.

Hardware: Windows 11 Home 10.0.26300, RTX 4090 24 GB, NVIDIA 621.24, Core i9-13900K, 64 GB RAM
Scene: Hyrule Field on the path (position 119.09, 161.4, 198.91), standing still, camera untouched; output 2560x1440
with ultrawide on, presented 5120x1440 SDR; DLSS 3414x960 to 5120x1440, preset K; frame generation off;
HOS_FPS_MAX=1000; Quality preset Auto (Ultra tier, memory_budget 5)
Method: packs over the same main base, one for main @ 9ea65c7b and one for this PR @ 5c0228fe; job queue in timing
mode; a warm-up run of each, then 3 interleaved rounds of main, 100%, Auto; each run 45 s in play after 900 presents,
the last 30 log samples (vk: GPU time lines, 0.1 ms steps), mean GPU time and median fps; the median of the 3 runs
How to reproduce: a save on that path, ground_detail_distance=1 (100%) or =0 (Auto) in longshot_options.ini

Before: main @ 9ea65c7b After, 100%: this PR @ 5c0228fe After, Auto (400% here): this PR @ 5c0228fe
GPU time a frame, runs a / b / c (ms) 8.067 / 8.023 / 7.730 8.013 / 8.037 / 7.777 8.113 / 7.810 / 7.900
GPU time, median (ms) 8.023 8.013 7.900
fps, runs a / b / c 91.2 / 91.2 / 94.7 91.2 / 91.4 / 94.6 91.4 / 94.2 / 93.0
fps, median 91.2 91.4 93.0
render thread, median (ms a frame) 10.98 10.92 10.79
draws a frame, median 2601 2600 2604
main, run b:
vk: GPU time 7.9 ms a frame (the longest submission 3.9 ms); 0.0 textures made a frame
vk: 21240 presents, 92.2 fps; a frame: 2561 draws (0 skipped), 135 dispatches, 152 passes, 131 barriers, 6 submits, ...
vk: the render thread (600 presents, 10.96 ms a frame): its jobs 8.86 ms a frame (submits 1.01, presents 0.45, others 7.41), idle 2.09; ...
this PR at 100%, run b:
vk: GPU time 8.0 ms a frame (the longest submission 3.8 ms); 0.0 textures made a frame
vk: 20760 presents, 90.3 fps; a frame: 2557 draws (0 skipped), 137 dispatches, 153 passes, 132 barriers, 6 submits, ...
vk: the render thread (600 presents, 11.01 ms a frame): its jobs 8.88 ms a frame (submits 1.05, presents 0.45, others 7.38), idle 2.13; ...
this PR on Auto (400%), run b:
vk: GPU time 7.8 ms a frame (the longest submission 3.5 ms); 0.0 textures made a frame
vk: 23520 presents, 94.1 fps; a frame: 2567 draws (0 skipped), 135 dispatches, 153 passes, 132 barriers, 6 submits, ...
vk: the render thread (600 presents, 10.63 ms a frame): its jobs 8.65 ms a frame (submits 0.80, presents 0.43, others 7.41), idle 1.98; ...

An earlier series on this branch at 100%, 200% and 400% (same spot, same settings) gave 8.01, 8.00 and 8.08 ms. With
RX_VK_PASS_TIMING=1 the pebble passes take about 0.1 ms each at 400%. The build, loading, memory and the launcher
can't be affected beyond a few small draws: one hook of a few instructions, no new image or buffer.

The PR was rebased onto main 3653c9c5 after these runs; its diff is the same (the translation tables were merged again
by hand, entry for entry). The 10 commits in between are the Mods tab and ExeFS patches (#134), vibration (#405), the
FSR frame generation HUD (#1755), build speed (#756), TLS (#755), the Tracy build, the release channels and the window
icon: they touch nx2/build.py, nx2/exefs_patches.py, nx2/make_game.py, the host's mods, cheats and pad code,
vk_menu.cpp and vk_framegen.cpp, and nothing in the foliage setup or the passes these objects draw in. The rebased
commits, run again at the same spot (main @ 3653c9c5 against this PR @ d5fadaa0 on Auto), draw exactly the counts of
the timed runs (Testing), so the timing still holds; it was not re-timed. It was then rebased once more, onto main
a433db32, over two commits that don't reach these passes either (#1747, the amiibo model number in NFC; #1778, the
renhdrum DLL in the release build); the diff is unchanged. The last commit, f162d3fb, only changes which part of the
bug report lists this row (Testing); main @ a433db32 against this PR @ f162d3fb on Auto, at the same spot, draw the
same counts again (colour 1760 against 3360 mesh groups, shadow 2496 / 3904 against 23520 / 6464).

Flags and settings

One menu row and its ini key.

Flag What it is Before this PR After this PR Effect Helps / doesn't help / untested Recommendation
Ground detail distance (ground_detail_distance) Graphics row: how far the pebbles and small flowers are drawn none (the game's 35 m) Auto: 100% on Minimum and Low, 200% on Balanced and High, 400% on Ultra; 1 to 7 = 100% to 400% scales the game's cut distance and its squared twin helps on the RTX 4090 at no measured cost; untested on 8 and 12 GB cards (200%) Auto

Testing

Tested: on Windows 11, RTX 4090, NVIDIA 621.24, in Hyrule Field on the path: at 100% the pebble passes draw exactly
main's mesh groups; at 400% the colour pass goes from 1760 to 3360 mesh groups and the shadow pass from 3904 to 6464,
the same on two runs each, and the pebbles and flowers far ahead stay drawn as Link walks. Auto resolved to 400% here
(the log's auto_tier=5), the timing series above, no device lost, NGX started in every run.
After the rebase, main @ 3653c9c5 (longshot v3.0.0-rc.8-62-g3653c9c57) against this PR @ d5fadaa0 (rc.8-65-gd5fadaa0b)
on Auto, same spot, one run each, from one base:

                         main @ 3653c9c5          this PR @ d5fadaa0, Auto
8e2f7af4245747ef colour   1760 mesh groups, 4512   3360 mesh groups, 7980 primitives
28dd2baa17ba10e1 shadow   2496 task / 3904 mesh    23520 task / 6464 mesh
6ea0c171f1a7b6d8 grass    480 mesh, 686            480 mesh, 686 (the same grass on both sides)

python -I -B tests/run_all.py: 701 passed, 46 failed, 120 skipped on this branch at f162d3fb (rebased on a433db32;
the 45 files below and test_longshot_ctl.py, see below); main 3653c9c5 on the same PC: 700 passed, the same 45 files failed (this PC's Windows failures, e.g. test_tested_configurations.py's CRLF
pipe check). One of them, test_bug_report_defaults.py's auto-profile case, already fails on main with "Auto-controlled
shadow_res missing" (it did on main @ 9ea65c7b too; I believe since #773, which made Shadow resolution follow Auto): it
wants every row apply_preset sets in the report's "depends on this PC" part. This row is one of them, so
report_default_depends_on_pc() now puts it there while a Quality preset is on (the preset leaves it on Auto, which
the memory tier resolves); on Custom its default is plain Auto and a moved value reads "(default: Auto)". The case's
output on this branch is now main's, line for line: only "shadow_res missing", whose fix is a PR of its own.
test_longshot_ctl.py failed once in a full run while a Linux build ran beside it (a temporary file still held,
WinError 32) and passed twice alone; it doesn't read the files this PR changes.
Linux, in a WSL 2 Ubuntu 22.04 with scripts/linux/Dockerfile's packages, at f162d3fb: the renderer alone
(RX_VK_ONLY=1 nx2/build.py --standalone, 0 failed) and host/oot_scatter.c with tools.lock's clang 23 and its sysroot
and with gcc 11, both with the host's flags and -Wall -Wextra -Werror; test_oot_scatter.py passes there and
test_bug_report_defaults.py fails only on shadow_res, as on Windows. No run in the game on Linux.
tests/test_oot_scatter.py fails on main ("nx2/oot_scatter.py is missing ...") and catches a wrong tier mapping and a
missing preset reset.

Screenshots

Hyrule Field on the path (position 119.09, 161.4, 198.91, camera untouched), 5120x1440, the Measurements settings, one
run each from one base (also in this comment).

Why they barely differ. Standing still, the two frames differ only where grass, leaves, mist, Link and Navi move
from one run to the next. The pebbles and small flowers this row adds lie 35 to 140 m out: most are behind the rise in
front of Link, and the rest are a few pixels each at that distance. 100% against 400% switched live in one run, from 10
camera views, gave the same: no still where the difference reads. What the row fixes is the pop-in as Link walks, which
a still can't show; the draw counts above (colour 1760 against 3360 mesh groups, shadow 3904 against 6464) are what
show it ran.

Whole frame (JPEG, quality 92):

Before: main @ a433db32

After: this PR @ f162d3fb (Auto = 400% here)

The field beyond the rise, a full-resolution crop (x 1000-3600, y 500-860, PNG):

Before: main @ a433db32, the field

After: this PR @ f162d3fb (Auto = 400% here), the field

Not tested: other regions (Kakariko, Lon Lon Ranch, Death Mountain, Lake Hylia) beyond Hyrule Field; a run in the game on Linux; AMD and
Intel cards.

Must be tested:

  • an 8 or 12 GB card, any OS (Auto = 200% there): stand on a Hyrule Field path with the Dev FPS counter, switch Ground
    detail distance between 100% and Auto, expecting the GPU time to move by a small fraction of a millisecond
    (Test Farm: @Beanstalk an 8-12 GB card, Ground detail distance 100% against Auto at the Hyrule Field path).

Risks

What could break: a game update that moves the foliage setup: the hook checks the build id and the instructions
around its site, and installs nothing otherwise (the game's distance). More pebbles in the cascades cost a little on
small cards, which is why Auto keeps 100% on Minimum and Low.

Turning it off: the row at 100% (ground_detail_distance=1).

Compatibility: the options file gains ground_detail_distance (absent: Auto); the Quality presets now also set this
row back to Auto. No cache, save or ABI change.

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).
  • Tested on my own PC where it runs (in the game, for a change the game runs), as Testing's Tested says; what
    can't be run by hand is in Testing's Not testable by hand, with why.
  • Measurements has a verdict, or one line saying why there is nothing to measure.
  • Nothing gets worse that I know of: any cost (speed, latency, memory, a setup that worked before) is measured and
    in Risks.
  • 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. (Testing's
    Screenshots; a still barely shows this change, said there)
  • A file in docs/tested/ for each new measured run (format in docs/tested-configurations.md).
  • A game-free test added for the fix, failing on main and passing here.
  • A check under tests/ that reads changed source updated in this PR, not weakened.
  • Host code builds on both Windows (llvm-mingw) and Linux, with UTF-8 paths.
  • Docs updated.

🤖 Generated with Claude Code

**Type:** feat · **Risk:** low · **Tested on:** Windows 11, RTX 4090 · **Needs:** an 8 or 12 GB card (Auto = 200% there), any OS ## TL;DR The small pebbles and white flowers along the paths stop being drawn about 35 m from the camera, so they pop in a few steps ahead as Link walks. That distance is the game's own, written each frame by its foliage setup. This PR adds a Graphics row, Ground detail distance, that draws them up to four times as far, shadows included. Its default, Auto, follows the card's memory like Shadow resolution. On an RTX 4090 the frame time doesn't move. A new game-free test fails on main and passes here, and I watched the pebbles in Hyrule Field at each setting. ## Breakdown - **Who it helps:** anyone who walks the paths of Hyrule Field and sees pebbles and little flowers appear just ahead. - **What was wrong:** the game culls this family of ground details at a fixed 35 m fade (25 to 35 m in its data, scaled by the lens), on the GPU. - **What changes:** a hook after the game writes that distance scales it, and its squared twin, by the row's setting (100% to 400%). - **What does not change:** at 100% nothing is written: the game's block bit for bit. Minimum and Low (handhelds, integrated GPUs, cards up to 6 GB) stay at 100% on Auto. Grass, trees and the pixel-size cut are untouched. - **How it was checked:** a game-free test (fails on main, catches a wrong scale or tier), the full check suite (same failures as main), draw counts in the game, and 3 interleaved timing rounds against main. - **What is still open:** the cost on an 8 or 12 GB card (200% on Auto), a survey of the other regions, and the small items close by that the game's pixel-size cut hides (not this PR). - **Risk:** low: a few more small draws in the colour pass and the sun's cascades; at 100% the game's own block. ## Why On the path out of the Kokiri Forest and across Hyrule Field, pebbles and small white flowers pop in a few steps ahead of Link: the game stops drawing them about 35 m away. It's the game's own choice, not a Longshot bug, but on a PC with memory and GPU time to spare it can draw them farther, as it already does for shadows (Shadow resolution) and the draw distance sliders asked for in #205. PR #227's sliders (Object detail, Foliage distance) don't reach this family: it is culled on the GPU by a distance of its own (below). See #205. See #227. ## What changed The game's foliage setup writes a per-frame block for its GPU culling. Its word 37 is the pebble family's cut, and word 118 is the same distance squared that the task and mesh stages use. A hook after that write scales word 37 by the setting and word 118 by its square, so the fade keeps its shape and moves out. The row is read each frame, so a change applies at once. - lifter: `nx2/oot_scatter.py` installs the hook at the store of word 118 in the foliage setup, for this game build only, after checking the instructions around it; `nx2/lift.py` calls it with the other standalone hooks. - host: `host/oot_scatter.c` `hos_oot_scatter()` reads `rx_option(HOS_OPT_GROUND_DETAIL)` and scales the two words on the stack; 100 (or anything outside 101 to 400) leaves them alone, as does a value that isn't a distance (0 when the fade is off). - menu: Graphics, "Ground detail distance" (`opts.ground_detail`, ini `ground_detail_distance`): Auto, then 100% to 400% in steps of 50. `menu_ground_detail()` in `gpu/vk/vk_menu.cpp` resolves Auto by the memory tier, as `menu_shadow_res()` does: 100% on Minimum and Low, 200% on Balanced and High, 400% on Ultra. The Quality presets put it back on Auto (`apply_preset`). `HOS_OPT_GROUND_DETAIL = 76` in `gpu/vk/vk_api.h` (an option id, not the interface: no `MKWVK_API_VERSION` change); `vk_replay.cpp` answers it. - strings: the row, its help and two hints, and the Quality preset's help (it now names this row), in the 13 tables of `gpu/vk/menu_i18n.h`. - docs: the README's option table and its Quality preset paragraph; `docs/development.md`'s options file rows. - tests: `tests/test_oot_scatter.py` compiles the host helper against an authored stack block and checks the install, the menu wiring and Auto's tiers. How the cut was found: the pebbles and small flowers are mesh programs `8e2f7af4245747ef` (colour), `51183fe750d5d0c8` (the same objects, a second pass) and `28dd2baa17ba10e1` (the sun's three cascades), fed by indirect arguments that compute `b612216258832b9c` writes. Scaling the scene buffer's words in the replay showed b612 cuts this kind at word 37 (39.4 m at the default field of view), and the task stage again at sqrt(word 118 / word 119), the same distance. Moving both (x4, x16) took the colour pass from 1760 to 3360 mesh groups and the shadow pass from 3904 to 6464; moving either alone did not. The game computes word 37 as 35 m times the lens factor, from a fade of 25 to 35 m in its data: a constant, so this is the game's design rather than a Longshot fault. ## Measurements **Verdict:** no cost measured. At 100% the branch matches main (GPU 8.01 against 8.02 ms a frame), and Auto (400% on this card) is within the spread of the runs (7.90 ms). The scene is CPU-bound at about 91 to 95 fps on both sides. Hardware: Windows 11 Home 10.0.26300, RTX 4090 24 GB, NVIDIA 621.24, Core i9-13900K, 64 GB RAM Scene: Hyrule Field on the path (position 119.09, 161.4, 198.91), standing still, camera untouched; output 2560x1440 with ultrawide on, presented 5120x1440 SDR; DLSS 3414x960 to 5120x1440, preset K; frame generation off; `HOS_FPS_MAX=1000`; Quality preset Auto (Ultra tier, memory_budget 5) Method: packs over the same main base, one for main @ 9ea65c7b and one for this PR @ 5c0228fe; job queue in timing mode; a warm-up run of each, then 3 interleaved rounds of main, 100%, Auto; each run 45 s in play after 900 presents, the last 30 log samples (`vk: GPU time` lines, 0.1 ms steps), mean GPU time and median fps; the median of the 3 runs How to reproduce: a save on that path, `ground_detail_distance=1` (100%) or `=0` (Auto) in `longshot_options.ini` | | Before: main @ 9ea65c7b | After, 100%: this PR @ 5c0228fe | After, Auto (400% here): this PR @ 5c0228fe | |---|---|---|---| | GPU time a frame, runs a / b / c (ms) | 8.067 / 8.023 / 7.730 | 8.013 / 8.037 / 7.777 | 8.113 / 7.810 / 7.900 | | GPU time, median (ms) | **8.023** | **8.013** | **7.900** | | fps, runs a / b / c | 91.2 / 91.2 / 94.7 | 91.2 / 91.4 / 94.6 | 91.4 / 94.2 / 93.0 | | fps, median | **91.2** | **91.4** | **93.0** | | render thread, median (ms a frame) | 10.98 | 10.92 | 10.79 | | draws a frame, median | 2601 | 2600 | 2604 | ``` main, run b: vk: GPU time 7.9 ms a frame (the longest submission 3.9 ms); 0.0 textures made a frame vk: 21240 presents, 92.2 fps; a frame: 2561 draws (0 skipped), 135 dispatches, 152 passes, 131 barriers, 6 submits, ... vk: the render thread (600 presents, 10.96 ms a frame): its jobs 8.86 ms a frame (submits 1.01, presents 0.45, others 7.41), idle 2.09; ... this PR at 100%, run b: vk: GPU time 8.0 ms a frame (the longest submission 3.8 ms); 0.0 textures made a frame vk: 20760 presents, 90.3 fps; a frame: 2557 draws (0 skipped), 137 dispatches, 153 passes, 132 barriers, 6 submits, ... vk: the render thread (600 presents, 11.01 ms a frame): its jobs 8.88 ms a frame (submits 1.05, presents 0.45, others 7.38), idle 2.13; ... this PR on Auto (400%), run b: vk: GPU time 7.8 ms a frame (the longest submission 3.5 ms); 0.0 textures made a frame vk: 23520 presents, 94.1 fps; a frame: 2567 draws (0 skipped), 135 dispatches, 153 passes, 132 barriers, 6 submits, ... vk: the render thread (600 presents, 10.63 ms a frame): its jobs 8.65 ms a frame (submits 0.80, presents 0.43, others 7.41), idle 1.98; ... ``` An earlier series on this branch at 100%, 200% and 400% (same spot, same settings) gave 8.01, 8.00 and 8.08 ms. With `RX_VK_PASS_TIMING=1` the pebble passes take about 0.1 ms each at 400%. The build, loading, memory and the launcher can't be affected beyond a few small draws: one hook of a few instructions, no new image or buffer. The PR was rebased onto main 3653c9c5 after these runs; its diff is the same (the translation tables were merged again by hand, entry for entry). The 10 commits in between are the Mods tab and ExeFS patches (#134), vibration (#405), the FSR frame generation HUD (#1755), build speed (#756), TLS (#755), the Tracy build, the release channels and the window icon: they touch `nx2/build.py`, `nx2/exefs_patches.py`, `nx2/make_game.py`, the host's mods, cheats and pad code, `vk_menu.cpp` and `vk_framegen.cpp`, and nothing in the foliage setup or the passes these objects draw in. The rebased commits, run again at the same spot (main @ 3653c9c5 against this PR @ d5fadaa0 on Auto), draw exactly the counts of the timed runs (Testing), so the timing still holds; it was not re-timed. It was then rebased once more, onto main a433db32, over two commits that don't reach these passes either (#1747, the amiibo model number in NFC; #1778, the renhdrum DLL in the release build); the diff is unchanged. The last commit, f162d3fb, only changes which part of the bug report lists this row (Testing); main @ a433db32 against this PR @ f162d3fb on Auto, at the same spot, draw the same counts again (colour 1760 against 3360 mesh groups, shadow 2496 / 3904 against 23520 / 6464). ### Flags and settings One menu row and its ini key. | Flag | What it is | Before this PR | After this PR | Effect | Helps / doesn't help / untested | Recommendation | |---|---|---|---|---|---|---| | Ground detail distance (`ground_detail_distance`) | Graphics row: how far the pebbles and small flowers are drawn | none (the game's 35 m) | Auto: 100% on Minimum and Low, 200% on Balanced and High, 400% on Ultra; 1 to 7 = 100% to 400% | scales the game's cut distance and its squared twin | helps on the RTX 4090 at no measured cost; untested on 8 and 12 GB cards (200%) | Auto | ## Testing **Tested:** on Windows 11, RTX 4090, NVIDIA 621.24, in Hyrule Field on the path: at 100% the pebble passes draw exactly main's mesh groups; at 400% the colour pass goes from 1760 to 3360 mesh groups and the shadow pass from 3904 to 6464, the same on two runs each, and the pebbles and flowers far ahead stay drawn as Link walks. Auto resolved to 400% here (the log's `auto_tier=5`), the timing series above, no device lost, NGX started in every run. After the rebase, main @ 3653c9c5 (`longshot v3.0.0-rc.8-62-g3653c9c57`) against this PR @ d5fadaa0 (`rc.8-65-gd5fadaa0b`) on Auto, same spot, one run each, from one base: ``` main @ 3653c9c5 this PR @ d5fadaa0, Auto 8e2f7af4245747ef colour 1760 mesh groups, 4512 3360 mesh groups, 7980 primitives 28dd2baa17ba10e1 shadow 2496 task / 3904 mesh 23520 task / 6464 mesh 6ea0c171f1a7b6d8 grass 480 mesh, 686 480 mesh, 686 (the same grass on both sides) ``` `python -I -B tests/run_all.py`: 701 passed, 46 failed, 120 skipped on this branch at f162d3fb (rebased on a433db32; the 45 files below and `test_longshot_ctl.py`, see below); main 3653c9c5 on the same PC: 700 passed, the same 45 files failed (this PC's Windows failures, e.g. `test_tested_configurations.py`'s CRLF pipe check). One of them, `test_bug_report_defaults.py`'s auto-profile case, already fails on main with "Auto-controlled shadow_res missing" (it did on main @ 9ea65c7b too; I believe since #773, which made Shadow resolution follow Auto): it wants every row `apply_preset` sets in the report's "depends on this PC" part. This row is one of them, so `report_default_depends_on_pc()` now puts it there while a Quality preset is on (the preset leaves it on Auto, which the memory tier resolves); on Custom its default is plain Auto and a moved value reads "(default: Auto)". The case's output on this branch is now main's, line for line: only "shadow_res missing", whose fix is a PR of its own. `test_longshot_ctl.py` failed once in a full run while a Linux build ran beside it (a temporary file still held, WinError 32) and passed twice alone; it doesn't read the files this PR changes. Linux, in a WSL 2 Ubuntu 22.04 with `scripts/linux/Dockerfile`'s packages, at f162d3fb: the renderer alone (`RX_VK_ONLY=1 nx2/build.py --standalone`, 0 failed) and `host/oot_scatter.c` with tools.lock's clang 23 and its sysroot and with gcc 11, both with the host's flags and `-Wall -Wextra -Werror`; `test_oot_scatter.py` passes there and `test_bug_report_defaults.py` fails only on shadow_res, as on Windows. No run in the game on Linux. `tests/test_oot_scatter.py` fails on main ("nx2/oot_scatter.py is missing ...") and catches a wrong tier mapping and a missing preset reset. ### Screenshots Hyrule Field on the path (position 119.09, 161.4, 198.91, camera untouched), 5120x1440, the Measurements settings, one run each from one base (also in [this comment](https://git.magicbean.dev/MagicBeanDev/Longshot/pulls/1784#issuecomment-55869)). **Why they barely differ.** Standing still, the two frames differ only where grass, leaves, mist, Link and Navi move from one run to the next. The pebbles and small flowers this row adds lie 35 to 140 m out: most are behind the rise in front of Link, and the rest are a few pixels each at that distance. 100% against 400% switched live in one run, from 10 camera views, gave the same: no still where the difference reads. What the row fixes is the pop-in as Link walks, which a still can't show; the draw counts above (colour 1760 against 3360 mesh groups, shadow 3904 against 6464) are what show it ran. Whole frame (JPEG, quality 92): ![Before: main @ a433db32](https://git.magicbean.dev/attachments/cb0a76c6-d0fa-4df3-9f20-f7c959b2cbf1) ![After: this PR @ f162d3fb (Auto = 400% here)](https://git.magicbean.dev/attachments/781b7e47-90a6-435d-b751-22030600c6cf) The field beyond the rise, a full-resolution crop (x 1000-3600, y 500-860, PNG): ![Before: main @ a433db32, the field](https://git.magicbean.dev/attachments/3fec4947-3e09-4555-ae75-7875f04a7ebe) ![After: this PR @ f162d3fb (Auto = 400% here), the field](https://git.magicbean.dev/attachments/caad6e41-78ec-4cf0-8fb3-bba8e26391d4) **Not tested:** other regions (Kakariko, Lon Lon Ranch, Death Mountain, Lake Hylia) beyond Hyrule Field; a run in the game on Linux; AMD and Intel cards. **Must be tested:** - an 8 or 12 GB card, any OS (Auto = 200% there): stand on a Hyrule Field path with the Dev FPS counter, switch Ground detail distance between 100% and Auto, expecting the GPU time to move by a small fraction of a millisecond (Test Farm: @Beanstalk an 8-12 GB card, Ground detail distance 100% against Auto at the Hyrule Field path). ## Risks **What could break:** a game update that moves the foliage setup: the hook checks the build id and the instructions around its site, and installs nothing otherwise (the game's distance). More pebbles in the cascades cost a little on small cards, which is why Auto keeps 100% on Minimum and Low. **Turning it off:** the row at 100% (`ground_detail_distance=1`). **Compatibility:** the options file gains `ground_detail_distance` (absent: Auto); the Quality presets now also set this row back to Auto. No cache, save or ABI change. ## 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] Tested on my own PC where it runs (in the game, for a change the game runs), as Testing's Tested says; what can't be run by hand is in Testing's Not testable by hand, with why. - [x] Measurements has a verdict, or one line saying why there is nothing to measure. - [x] Nothing gets worse that I know of: any cost (speed, latency, memory, a setup that worked before) is measured and in Risks. - [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. (Testing's Screenshots; a still barely shows this change, said there) - [x] A file in `docs/tested/` for each new measured run (format in `docs/tested-configurations.md`). - [x] A game-free test added for the fix, failing on `main` and passing here. - [x] A check under `tests/` that reads changed source updated in this PR, not weakened. - [x] Host code builds on both Windows (llvm-mingw) and Linux, with UTF-8 paths. - [x] Docs updated. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
A game-free check that the foliage setup's hook (nx2/oot_scatter.py) is installed at the store of word 118, only on
the code it was written for, and that host/oot_scatter.c scales word 37 by the row's share and word 118 by its square,
keeping the fade's shape (word 119) and leaving the block bit for bit at 100% and out of range; and that the row's
Auto takes the distance for the card's memory tier and a Quality preset puts it back on Auto. It fails on main: there
is no hook, no option 76 and no menu row.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The game draws the pebbles and white flower creepers on the ground (the foliage culling's kind 8, and their shadows)
only within a fade that ends 35 m away, a constant in its data read by the foliage setup (f_80587c80). A hook after
the setup stores the scene constants scales the fade's end (word 37) and its square (word 118) by a new Insert menu
row, Graphics > Detail > Ground detail distance: Auto, or 100% (the game's own) to 400%, saved as
ground_detail_distance. Auto goes by the card's memory tier as Shadow resolution's does: 100% on Minimum and Low,
200% on Balanced and High, 400% on Ultra; a Quality preset puts the row back on Auto. The game's data is never
written; grass is drawn by other passes and is not changed.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
docs(tested): Ground detail distance timing runs, main against 100% and Auto (jiro113)
Some checks failed
Website / Website on Cloudflare (pull_request_target) Has been skipped
PR description / Description follows the template (pull_request_target) Successful in 25s
CI / Conventional Commit title (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been cancelled
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been cancelled
CI / Workflow lint (actionlint) (pull_request) Has been cancelled
Guide screenshots / Guide images and local UI source review (pull_request) Has been cancelled
Third-party parts / As their notes say (pull_request) Has been cancelled
Third-party parts / The same as upstream (pull_request) Has been cancelled
Website / Website on Cloudflare (pull_request) Has been cancelled
56abb324a4
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Author
Contributor

Tested in game: RTX 4090, NVIDIA 621.24, Windows 11: Hyrule Field, on the path out of the forest. At 100% the pebble passes draw main's counts; on Auto (400% here) the pebbles and small flowers far ahead stay drawn as Link walks, shadows included (colour pass 1760 -> 3360 mesh groups, shadow pass 3904 -> 6464, rebased build checked again). No device lost, DLSS on, no visible cost: GPU time 8.02 ms on main, 7.90 ms on Auto.

Tested in game: RTX 4090, NVIDIA 621.24, Windows 11: Hyrule Field, on the path out of the forest. At 100% the pebble passes draw main's counts; on Auto (400% here) the pebbles and small flowers far ahead stay drawn as Link walks, shadows included (colour pass 1760 -> 3360 mesh groups, shadow pass 3904 -> 6464, rebased build checked again). No device lost, DLSS on, no visible cost: GPU time 8.02 ms on main, 7.90 ms on Auto.
feat(options): the bug report puts Ground detail distance with this PC's settings on a Quality preset
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
PR description / Description follows the template (pull_request_target) Successful in 6s
f162d3fb84
A preset leaves the row on Auto, which the memory tier resolves, so its value is the PC's, like the other rows a
preset sets (test_bug_report_defaults' auto-profile case). On Custom its default is plain Auto, and a moved value
reads "(default: Auto)". The case still fails on main for shadow_res, a fix of its own.

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

Screenshots, Hyrule Field on the path (position 119.09, 161.4, 198.91, camera untouched), 5120x1440, same settings as
Measurements, one run each from one base.

Why they barely differ. Standing still, the frames differ only where grass, leaves, mist, Link and Navi move from
one run to the next. The pebbles and small flowers this row adds are 35 to 140 m out: most sit behind the rise in front
of Link, and the rest are a few pixels each at this distance. What the row fixes is the pop-in as Link walks, which a
still can't show; the draw counts in the description's Testing (colour 1760 against 3360 mesh groups, shadow 3904
against 6464) are what shows it ran.

Whole frame (JPEG, quality 92):

Before: main @ a433db32

After: this PR @ f162d3fb (Auto = 400% here)

The field beyond the rise, a full-resolution crop (x 1000-3600, y 500-860, PNG):

Before: main @ a433db32, the field

After: this PR @ f162d3fb (Auto = 400% here), the field

Screenshots, Hyrule Field on the path (position 119.09, 161.4, 198.91, camera untouched), 5120x1440, same settings as Measurements, one run each from one base. **Why they barely differ.** Standing still, the frames differ only where grass, leaves, mist, Link and Navi move from one run to the next. The pebbles and small flowers this row adds are 35 to 140 m out: most sit behind the rise in front of Link, and the rest are a few pixels each at this distance. What the row fixes is the pop-in as Link walks, which a still can't show; the draw counts in the description's Testing (colour 1760 against 3360 mesh groups, shadow 3904 against 6464) are what shows it ran. Whole frame (JPEG, quality 92): ![Before: main @ a433db32](https://git.magicbean.dev/attachments/cb0a76c6-d0fa-4df3-9f20-f7c959b2cbf1) ![After: this PR @ f162d3fb (Auto = 400% here)](https://git.magicbean.dev/attachments/781b7e47-90a6-435d-b751-22030600c6cf) The field beyond the rise, a full-resolution crop (x 1000-3600, y 500-860, PNG): ![Before: main @ a433db32, the field](https://git.magicbean.dev/attachments/3fec4947-3e09-4555-ae75-7875f04a7ebe) ![After: this PR @ f162d3fb (Auto = 400% here), the field](https://git.magicbean.dev/attachments/caad6e41-78ec-4cf0-8fb3-bba8e26391d4)
Author
Contributor

Pushed f162d3fb (rebased on main a433db32): the bug report now lists Ground detail distance with this PC's settings while a Quality preset is on, so test_bug_report_defaults' auto-profile case prints main's output line for line (only its shadow_res failure, already on main, is left). main @ a433db32 against this PR @ f162d3fb on Auto draw the same counts as before. Built and checked on Linux (WSL 2 Ubuntu 22.04: the renderer alone, host/oot_scatter.c with clang 23 and gcc 11 under -Werror, test_oot_scatter passes). Description: Testing gains a Screenshots part (the pictures of the previous comment) and why a still barely shows this change; the Screenshots, check and Linux boxes are ticked.

Pushed f162d3fb (rebased on main a433db32): the bug report now lists Ground detail distance with this PC's settings while a Quality preset is on, so test_bug_report_defaults' auto-profile case prints main's output line for line (only its shadow_res failure, already on main, is left). main @ a433db32 against this PR @ f162d3fb on Auto draw the same counts as before. Built and checked on Linux (WSL 2 Ubuntu 22.04: the renderer alone, host/oot_scatter.c with clang 23 and gcc 11 under -Werror, test_oot_scatter passes). Description: Testing gains a Screenshots part (the pictures of the previous comment) and why a still barely shows this change; the Screenshots, check and Linux boxes are ticked.
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
PR description / Description follows the template (pull_request_target) Successful in 6s
This pull request has changes conflicting with the target branch.
  • README.md
  • docs/development.md
  • gpu/vk/vk_api.h
  • gpu/vk/vk_menu.cpp
  • nx2/lift.py
  • tests/test_menu_sections.py
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 'fix/gpu-culled-props-popin:Jiro113-fix/gpu-culled-props-popin'
git switch 'Jiro113-fix/gpu-culled-props-popin'
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
1 participant
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!1784
No description provided.