docs(guides): recapture the Graphics guide image for the NFC tab and advance its review record #1501
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
1 participant
Notifications
Due date
No due date set.
Dependencies
No dependencies set
Reference
MagicBeanDev/Longshot!1501
Loading…
Reference in a new issue
No description provided.
Delete branch "mooki/Longshot:docs/guide-review-graphics"
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: docs · Risk: low · Tested on: Linux x86-64, no GPU (the picture is drawn in memory by SDL2's software renderer; the checks need no game) · Needs: any PC with a browser (the site's Settings page, once the site's tests pass again), and a maintainer's look at the pictures
TL;DR
The guide-screenshot check is red on main, so every pull request inherits the failure: the Graphics picture in the Settings guide was last reviewed before thirteen of its source files changed. I did that review with the project's own capture helper. The picture now differs in one visible way, the NFC tab that #280 added to the menu's tab strip; every row, value and help sentence is pixel-identical. So this PR replaces the picture with a fresh capture of main and advances its record: the check passes and its 14 tests pass.
Breakdown
310e7c9df(a strip of six tabs), and its manifest entry, the guide's caption, the guide README's provenance line and the review note move with it.REVIEW REQUIREDlines and exits 1 on main, and exits 0 here; six renders of five commits compared pixel by pixel and looked at; 14, 4 and 51 tests; the whole suite here and on main (below).Why
mainfails its own Guide images check, and every pull request shows the same red status, which has nothing to do with it. The Graphics picture in the Settings guide is recorded against the files it is drawn from (reviewed_source.files); when one changes,scripts/check_guide_screenshots.py --review-sourcesprintsREVIEW REQUIREDand exits 1 until someone compares the picture with a rendering of the new source and either retains it or recaptures it (docs/images/guide/README.md, "Capture and maintenance", step 5). #1466 did that at 21:18 UTC on 17 Nov (415a8944c). Since then 43 commits reached main and 15 of them changed a recorded file or the capture fixture, the first of them (#1388, 21:43 UTC) about 25 minutes later; none carried a review, so the check has been red since. The tracker was searched by five phrases (guide screenshot, guide images, REVIEW REQUIRED, settings-graphics, the check's name): no issue and no open pull request carries this review; #1467 and #68 replace the picture too, for their own changes (see Overlaps).Doing the review found that the picture is no longer what the menu draws: #280 added an NFC tab, so the tab strip has six tabs and the guide's picture shows five. A retention (the pattern of #1466) would have recorded a stale picture as current, so this PR recaptures it.
What changed
The Graphics picture is replaced by a render of main, and everything that records where it came from moves with it: the manifest entry, the caption and the provenance paragraph. The comparison that justifies it, and a line for each recorded source, is in
source-review-fullscreen-monitor.mdand below.docs/images/guide/settings-graphics.png: the helper's render of main310e7c9df, 1280x720,sha256 1b0d6de3…(96,658 bytes; was3531f6ab…, 92,938).docs/images/guide/manifest.json,settings-graphics.png's entry:sha256;captured_at2026-11-17;game_versionnightly-464-310e7c9d;captured_source(revision310e7c9d…, the 76 files the helper's compiler pass lists);reviewed_source(the same 76 files,revisionsha256:9617d811…, the SHA-256 of the sortedpath=hashlines, a formula I checked first on the old 77 entries: it gives exactly the oldsha256:006bc251…); the fixture'smenu.cpphash;capture.toolchain(clang 23.1.3, SDL2 2.32.74, libpng 1.6.59: the render's real ones);review.notes.vk_vendor.hleaves both lists (#1390 deleted it), and no file joins them.docs/images/guide/source-review-fullscreen-monitor.md: a "Recapture after #280 (2026-11-17)" section (+75 lines): the renders compared, a line for each recorded source and what is not claimed.docs/graphics-and-controls.md: the caption names the new build ("development build310e7c9d(Nightly 464)"); the alt text is unchanged, since the view still shows the same things.docs/images/guide/README.md: the provenance paragraph says the Graphics image comes from main310e7c9d…after #280, and where the earlier capture is.Measurements
Verdict: the guide check fails on main (exit 1, 15
REVIEW REQUIREDlines) and passes with this PR (exit 0). The first Graphics view rendered from415a8944c(the last commit it passed on) and from main differs in 13,009 of 921,600 pixels, all in the top 55 rows: the banner's version text and the tab strip, which now has the NFC tab. Nothing below the strip differs. Nothing else to measure: a record, a note and a picture change no code.Hardware: Linux 7.2.15 (Arch, x86-64), Intel Core i9-13900K, 94 GB; the PC has a GPU, which nothing here opens
Scene: none; the Graphics view of the menu fixture, 1280x720, Medium menu scale, English, SDL2's software renderer
Method:
scripts/check_guide_screenshots.py --review-sourceson main and on this PR; the capture helper's renders of415a8944c,c7db6c026,6d949cf95(#280) and310e7c9dfcompared pixel by pixel (any channel differs) with a script of a dozen lines (below); one run each, the render of310e7c9dftwice (byte-identical)How to reproduce: below, "How to rerun it"
310e7c9df0ce593910scripts/check_guide_screenshots.py --review-sourcesREVIEW REQUIRED(13 changed sources,vk_vendor.hgone, the fixture changed)tests/test_guide_screenshots.pytests/test_launcher_capture.pytests/run_all.pytest_prepare_stall, passes when rerun alonetests/guide-screenshots.test.tssettings-graphics.png)3531f6ab…, tabs: Graphics, Audio, Gameplay, Controls, Debug1b0d6de3…, tabs: Graphics, Audio, Gameplay, Controls, NFC, DebugThe check on main, whole, as the program printed it (
python3 -I -B scripts/check_guide_screenshots.py --review-sources, exit 1; the checkout's folder name is cut from thevk_vendor.hline):On this PR's head (exit 0; the six Launcher pictures are
NOT CHECKEDhere and on main alike: there is no Launcher checkout in CI):The renders (the capture helper from this PR's checkout for every one, so the fixture is the same unless said; clang 23.1.3, SDL2 2.32.74, libpng 1.6.59):
415a8944c, with its own fixture and with the new one415a8944cand310e7c9df415a8944candc7db6c026(everything before #280)c7db6c026and6d949cf95(#280 alone)6d949cf95and310e7c9df(everything after #280)310e7c9dfrendered twicemenu-capture.json415a8944cThe last row is why the comparison is between renders, and why the new picture is a render on the current toolchain, recorded as such.
compare_renders.py
Pictures
Flags and settings
None.
Review of the recorded sources
What each of the 14 sources and the fixture changed since
415a8944c, and whether it alters what the picture shows (the full reading is insource-review-fullscreen-monitor.md):gpu/vk/vk_menu.cpp(#1486, #280, #1318, #1442, #1388): yes, one thing:tab_titlesandTAB_COUNTgain the NFC tab, so the strip shows six tabs. The rest is on rows or help this view does not show (Frame generation's help, the Frame pacing hints, Layout preset, the Controller menu button, the NFC rows, the pipeline-list message,menu_memory_tier).gpu/vk/vk_menu.h(#280, #1388): no.Options::pad_menu(default 1) and a comment; the declarations ofmenu_memory_tierandmenu_rumble_tick.gpu/vk/menu_i18n.h(#1486, #1318, #1442): no. The other languages' tables and a helper that takes each table's length; the English strings are keys invk_menu.cpp.gpu/vk/vk_framegen.h(#1486): no. Declaresframegen_cappedandframegen_now; the fixture'sframegen_cappedreturns the value as set, so Frame generation stays "Off".gpu/vk/vk_dlss.h(#1486): no. Declaresdlss_fg_mostand rewords comments; the fixture answers 0.gpu/vk/vk_api.h(#280, #1150): no. ABI 30 to 33: new host callbacks (rumble test, NFC) andnvn_invalidate_quick; the fixture's host is null.gpu/vk/vk_internal.h(#1484, #1390, #560, #1150, #1442, #426): no. Thevk_vendor.hinclude andDevice::fixesgo,memory_priorityand declarations for frame overlap, memory sync and the preparation watchdog arrive; the fixture'sDeviceis empty.gpu/vk/device_policy.h(#1390, #1296, #426): no. The vendor fixes move here,networks_left_outis new, the Radeon 860M joins ASTC on the CPU, Mesa's Intel driver gets a phi limit: rules and log text the menu does not read.gpu/vk/fallback_size_policy.h(#426): no. Phi and call limits for Mesa's Intel driver, used by the shader preparation.gpu/vk/vk_fsr3fi.h(#1487): no.Inputs::present, an image view for FSR 3.1 frame generation's HUD-less mode.gpu/vk/vk_draw.h(#391): no.ub_overlaytakes a function pointer and an alignment.gpu/vk/vk_temporal.h(#1447): no. Two declarations for the hidden-mesh rule.gpu/vk/vk_texture.h(#1122, #1150): no. Thetexture_ahead_*declarations andtexture_gpu_written_ever.gpu/vk/vk_vendor.h(#1390): deleted, no. Its three fixes are indevice_policy.hand nothing includes it; the helper's compiler pass lists 76 files, the previous 77 less this one.scripts/screenshots/menu.cpp(#1486): no. Two stubs (dlss_fg_most0,framegen_cappedthe value as set) so the menu links; the old source rendered with the old and the new fixture gives identical PNGs.Each "no" rests on reading the change and on the pixel comparison above: the renders differ in the top 55 rows only, and #280 alone accounts for the tab strip.
How to rerun it
(
capture_menu.pyis run from the checkout that has this PR, so the fixture is the same for both renders; it needs a C++20 compiler, pkg-config, SDL2 and libpng development files and the Vulkan headers.cmpis silent when the committed picture is the render of main, given the same toolchain: clang 23.1.3, SDL2 2.32.74, libpng 1.6.59.)Testing
Tested: on Linux x86-64 (kernel 7.2.15), clang 23.1.3, SDL2 2.32.74 (sdl2-compat), libpng 1.6.59, Python 3.12.16, Node 22.23.5, no GPU, on 17 Nov 2026, base main
310e7c9df, head0ce593910. For this docs-only change "tested on my own PC" is the checks I ran: the Guide images check on main and here (above); the capture helper's renders from five commits, compared by pixel and looked at (the three pictures at full size, and three rows of the old and new at twice the size);tests/test_guide_screenshots.py(14),tests/test_launcher_capture.py(4) andtests/test_check_pr_description.py(51) pass; the wholetests/run_all.pythrough the idle gate, here and in a worktree of main310e7c9df(below); the site'stests/guide-screenshots.test.ts, with the site's packages from an unrelated checkout of the same lockfile: 2 of 4 pass here and on main (the two failures are the same on both, below). The suite, the launcher-capture and description-checker tests and the site test ran on this patch's first commit,518d7f8de; the head differs from it in one paragraph of the review note only, and the guide check and its 14 tests were rerun on the head.The whole suite,
python -I -B tests/run_all.py --jobs 8 --junit FILE, here and on main: 637 passed, 35 failed, 95 skipped here (296 s), 638 passed, 34 failed, 95 skipped on main. The two JUnit files compared by test name: the same 767 tests in both, one status differs,test_prepare_stall(the watchdog's timing test of the shader preparation: it failed here at a load average near 40 on the PC, "the log lacks 'STOPPED: nothing moved for 12 s'", passed on main in its run, and passes here when run alone: 1 passed, 101 s). The 34 that fail on both, by name:test_bug_report_defaults,test_compute_warm_apart,test_cpu_report,test_crt_options,test_damage_debug_menu,test_dev_packs,test_display_startup_failure,test_dlss_feature_size,test_failed_compile_keeps_objects,test_guest_imported,test_hud_layout_row,test_invalidate_quick,test_invalidate_vcore,test_libc_hooks,test_linux_preflight,test_linux_pressure,test_linux_update,test_log_open_failure,test_mirror_budget,test_missing_nup,test_mods_size_table,test_pending_guest_import,test_pipeline_play_cache,test_present_thread,test_profiling_mode,test_psychov35_fsr3_fg,test_readback_timeout_source,test_run_all_changed,test_slow_frames,test_switch_table,test_target_image_pool,test_upscaler_rows,test_vcore_escape,test_walk_key. They fail on main too, with the same status; I did not look into why they fail on this PC. The 95 skipped are the same tests on both (the run's log gives, for some, "not found here: vulkan_headers").Not tested: the website's Settings page rendered: the site's own
renderPagefor it throws "README menu table has an unknown tab" (website/src/repo-docs/graphics-settings.ts) for the README's NFC rows, sotests/guide-screenshots.test.tsfails its two tests that render that page, on main and here alike (#280 added the tab without the site's list knowing it, which this PR does not touch); I did not run the site's build itself, and the caption and the picture on the page were not looked at; Windows and Intel (the picture is the UI-only fixture, not a live Vulkan frame, as its caption says); a render with the toolchain recorded for the old PNG (clang 23.1.6, SDL2 2.32.10, libpng 1.6.57); rows below the first Graphics view and the other tabs (the picture does not show them); no game was run, none is needed for a record, a note and a picture.Must be tested:
website/README.mdsays, at desktop width and at 360 to 390 px, in both themes, expecting the new Graphics picture to load from the site's own files with its caption "development build310e7c9d(Nightly 464)" and the six tabs readable (look at the picture and its caption, as the guide README's "Completing a refresh" asks).Risks
What could break: nothing at run time: a PNG, a JSON record and Markdown files. The one way to be wrong is the review itself: a difference I did not see between the old picture and the menu. I compared every pixel of the first Graphics view across five commits and read the rows, so the first view is the same except the tab strip; rows below it and the other tabs are not shown by the picture and not claimed. Costs: the PNG is 96,658 bytes, 3,720 more than before, on the Settings page of the site; nothing else, since nothing the game runs changes.
Turning it off: revert the commit; the check is red again on main, as now.
Compatibility: nothing changes for a player or for a saved setting. The site copies the PNG unchanged; its guide caption names the new build.
Overlaps
By the open pull requests' file lists (the forge's
pulls/N/files), and for #1488 and #1489 a trial merge onto this PR's head with the check run on the result: #1467 (Reset to defaults at the top of the Graphics tab) and #68 (the co-op tab) also replacesettings-graphics.pngand edit its manifest entry, the caption and the provenance paragraph; each takes its own entry on rebase and renders the view again (the helper command above), now with six tabs underneath it. #1358, #1408, #1411 and #1426 also editmanifest.json(and #1358, #1411 and #1426 the review note), so each needs a rebase onto this; no trial merge was run for them. #1488 and #1489 merge onto this PR without a conflict, and the check on the result still fails, with exactly the files they themselves edit: #1488 namesgpu/vk/device_policy.h(it includesmodule_drop.hand a rule that now covers Windows) andgpu/vk/vk_draw.h(CommitNowandprivate_bytes_nowdeclarations), and its new include would addmodule_drop.hto the helper's dependency list (read from the include, not rendered); #1489 namesgpu/vk/vk_texture.h(two members of the texture's eviction bookkeeping). Those are declarations and rules the menu does not draw, but each PR needs its own review line and hash update; this PR cannot carry them.Issues
See #1466 (the last review of this picture) and #280 (the NFC tab).
Checklist
Everyone
type(scope): description) of the status line's type.can't be run by hand is in Testing's Not testable by hand, with why. (Docs only, nothing the game runs: the checks I ran are what Testing's Tested says.)
in Risks. (Nothing the game runs changes; the one cost, the PNG's 3,720 bytes, is in Risks.)
main. (Based on310e7c9df, forge main when this was written.)python -I -B tests/run_all.pypasses (any failure that also fails onmainis named). (34 tests fail here and on main, named under Testing; the 35th,test_prepare_stall, failed once under load and passes alone.)third_party/untouched (a new folder with aPROVENANCE.mdinstead).When it applies
Assisted-by:/Co-Authored-By:trailers.415a8944cand from main, and the new picture.)New on this forge; not opened on GitHub.
WIP: docs(guides): recapture the Graphics guide image for the NFC tab and advance its review recordto docs(guides): recapture the Graphics guide image for the NFC tab and advance its review recordView command line instructions
Checkout
From your project repository, check out a new branch and test the changes.