totk-pc-recomp/docs/pr-review-kit/04-knowledge.md

Knowledge base

Before investigating a symptom, or trusting a PR that "fixes" it, look for it here. Search by what the player sees (black, magenta, flicker, slow motion, missing, stale, streaks) and by the object (sky, grass, shadow, fog, HUD).

Invariants of recent changes

A PR that touches these areas must keep them.

• Queue order. When anything is submitted, every earlier part is already on the queue. Present, uploads, readbacks from guest threads and the vkDeviceWaitIdle sites rely on it. The recorder thread now begins, ends and submits the parts it records; the submitting thread still waits for that submission, so the order holds. TOTK_REC_END=0 restores the old split.
• GPU-written memory is never frozen. Storage-buffer stores, copies and fills land in imported guest memory without a fault or a write-watch bit, so a region only the GPU writes looks idle. Such regions are never frozen read-only, and a frozen region is thawed before a GPU write. LAS Recomp never changes the protection of imported memory because of NVIDIA. A suspected cause of NVIDIA "write invalid" device faults (#788, #802), not proven.
• VRAM pressure. Under pressure, released textures whose storage the game has given to another texture go first: 30 s after release and once no finalized slot has bound them for 600 submits. Clean mirrored entries wait 5 s. Both stop once use is back under the line. A PR touching texture lifetime is tested with TOTK_VRAM_LIMIT_MIB.
• Texture pins are freed. Each pin counts the recording copies naming it and is freed 1200 submits after its last use unless the replay holds it as a render target. Before that, pins leaked ~44 MiB a game minute (#670).

Fixed bug classes

If a PR touches this code, confirm the fix still holds.

Symptom	Cause	Where the fix is
lime silhouettes in grass; rectangles in the sky	a target outside the output map must keep its texel; zero-filling it wiped the half-res depth	vk_pipeline.c target_wmask
stale grass maps in the far terrain for a second after a hit	write-back of a texture the CPU had rewritten	vk_texture.c write_back
cut grass stays standing; fire does not spread (#132)	CPU reads of GPU-rendered textures without an invalidate	vk_texture.c vk_texture_write_back_small, nvn_ext.c nvn_pool_invalidate
cloud and fog volumes empty for the session	a one-shot draw skipped instead of waiting for its pipeline	vk_exec_draw.c prepare_draw
tile rectangles	storage buffers bound by Ryujinx first-use order, not the c0 slot	vk_exec_draw.c ssbo_slot
black dialog background and loading map	3D targets rejected, the grading LUT never written	vk_exec.c resolve_target
streaks on cliffs	primitive restart ignored	vk_exec_draw.c restart_for
streaky map screen	the newest texture picked at shared storage	vk_texture.c vk_texture_by_id
dark 16x16 blocks on the ground, sage spirit not drawn	G-buffer feedback loop	vk_exec_draw.c, TOTK_FEEDBACK
magenta cave walls, brown sky	CPU-filled textures without a flush	write-watched mirrors, vk_memory.c, vk_texture.c
black 3D scene	deferred texture binds	nvn_api_cmd.c Bind*Deferred
HUD prompt boxes, black stamina wheel	nvnTextureCompare ignored the channel mapping	nvn_api_obj.c
crash on world load	GetCommandMemoryUsed did not follow the driver's sizes; the game sizes model heaps from it	nvn_api_cmd.c
20 fps	a yield back-off starting before 2 ms	kernel.c SVC 0x0B: no back-off
weapons locked after a Fuse (#18)	timer remainder in (0, FLT_EPSILON] with the real-time step	patch under the realtime setting
magenta/blue garbage or device lost on RDNA1/2 (#5)	writes into 3D BC block views	in dev
black window after a driver update	a pipeline cache from another driver	vk_pipeline.c drops the cache by UUID

Known open risks

A PR touching these needs stronger proof.

• Buffer textures are not replayed and bind a stand-in: light and decal lists may read 0.
• New GPU-only colour images start undefined; feedback effects may show garbage.
• Clears with a partial channel or stencil mask are skipped (W_CLEAR_MASK, W_STENCIL_MASK).
• 8-bit indices are widened on the CPU at record time; a copy in the same submission gives stale indices.
• UpdateUniformBuffer is a copy between full barriers and ends the render pass (fps outdoors).
• Report timestamps carry host time at fence completion: the engine's GPU time is wrong.
• The game's SVC-free spin loops burn a host core (843 in main).
• Images aliased onto one GPU-only pool allocation do not see each other's data on AMD.

Past PR decisions

PR	Decision	Why
#690 shrine snapshots	rejected	a pass restart per copy, a VkPipeState copy per draw, broken bind_sig skip; fps loss
#674	rejected	a global STXR counter on the hot path
#660	rejected	the preview loses anti-aliasing
#713, #576	rejected	low memory block 10 GiB for everyone; should be 6 GiB plus the extra where needed
#573	rejected	dynamic resolution off by default for everyone, the 1.4.3 site never run
#568, #569	rejected	fake FSR4 and frame generation
#487	rejected	wrong metrics: percentiles over window means, counters over the wrong set
#451, #380	rejected	not painless to take
#566, #594, #534 DLSS	taken with changes	#594's shared paths gated on DLSS being on; nothing changes without DLSS
#489	partly taken	the runtime part checked by a frame dump; the installer's DLL download was the owner's call, its pinned hash re-checked
#519, #582 amiibo	rewritten by us	took the data-format fixes; left out the features and the Linux event rework
#483 vs #585	#585's mapping kept	#483's stick glyph mapping was rewritten unasked while #585 already had it right
#528 rain	taken after a check	code review fine, merged only after a run on a rain save
#767	taken with our fix	the default was skipped with prompts = xbox|pc when those folders did not exist
#625 frame queue	taken, off by default	a new frame queue, one field run with it on
#743 UB overlay	waiting	+25% in a Depths fight on an RTX 4080; needs review, fight runs x2 and shots on AMD

Our mistakes, not to repeat

• "-11%" was an A/B artifact of a moving scene. Whole runs off/on showed zero.
• Micro-optimizations from a flat profile (1-3% of samples each) gave 26.2 against 26.4 ms on the weak laptop: nothing. Nobody had computed a ceiling.
• A scheduler patch merged on run statistics added 50-75 ms hitches. Slow frames are a hard bar.
• Ten game runs on lock theories where one Ghidra read of the game's code narrowed it at once.
• 45 minutes of builds and benches on an idea its own first thread census had refuted: the game pins 53 of 56 threads itself. The cheapest refuting check goes first; when it refutes, stop and write the idea down.
• Tests of a bug that could not appear on the hardware at hand (NVIDIA paging on an AMD machine): 245k tokens and 37 minutes for nothing. Ask first where the bug reproduces.
• Turning the recorder off for a vendor instead of finding its bug. Stopped: the feature gets fixed, not silenced.
• Bisecting code when every build crashed the same way at once. The cause was a bad page of a game file in the OS file cache. When all builds fail identically, suspect inputs and caches first.
• A duplicate issue closed with a bare "Same as #N" lost the logs and links. Move everything useful to the issue that stays open first: hardware, driver, version, when it happens, workarounds, links from comments.