11 Renderer rework plan
HumanBean edited this page 2026-11-17 10:34:12 +00:00

Renderer rework plan

Status: draft proposal (2026-11-16), for discussion. Nobody is assigned to anything here and nothing is scheduled. This page says which parts of the renderer to rework, in what order, what has to exist first, and what "done" means for each part. It is not a full rewrite: the lifter, the Horizon layer and everything outside the four files named below stay as they are.

Contents: 1 Why · 2 What stays and what is reworked · 3 Where things stand · 4 Tracks · 5 Milestones · 6 What waits for what · 7 Questions to answer first · 8 Decisions needed · 9 Rules for every piece · 10 What this plan does not fix · 11 Notes, milestone by milestone

1. Why

Checked on the forge and on main on 2026-11-16. Counts are from titles, labels and text searches, not from reading every report.

The open issues (363). 201 are bugs, and 113 carry area/renderer.

Problem What the forge shows
Crashes 55 reports titled "Longshot closed unexpectedly": 40 in play, 9 at the start, 4 in shader preparation. By card: AMD 19, NVIDIA 17, Intel 14. Intel is far above its share of players
Crashes that are memory Of six reports opened, three ended with no crash record ("often for running out of memory"). #1280: at Windows' commit limit the game ends as "An unexpected error"
Memory grows RAM: #1014, #388, #805. VRAM: #939, #130, #395
Fps fades until a restart #1111, #879, #812, #89
Busy areas are CPU-bound in the submission path #410, #402, #750, #1153; waits on a GPU fence: #1268, #241
Device lost and driver timeouts #1234, #1061, #986, #606, #583
Shader preparation hangs or takes hours #1178, #462, #407

The code. Four files in gpu/vk hold most of it, about 28,500 lines together.

File Lines Switch references Lock and atomic references
vk_draw.cpp 10,931 431 234
vk_replay.cpp 6,388 289 166
vk_memory.cpp 6,003 200 137
vk_texture.cpp 5,191 177 67
  • About 600 places guard shared state one at a time, and dozens of threads are started inline and detached. Races and one-frame glitches are the expected result.
  • The source reads about 607 distinct RX_* and HOS_* switches, each where it is used.
  • Many checks in tests/ cut a function out of a source file by its text, because the code cannot be linked in pieces.

The open pull requests (275). 49 are fix(vk) and 28 are perf(vk). Three patterns repeat:

What to expect. #1034 measured the frame at 1.26 times its ceiling on an RTX 4070 Ti, in two scenes. On a strong PC this plan can buy about a quarter at most. Its gain is on small-VRAM cards and integrated GPUs, and in stability.

2. What stays and what is reworked

Stays Why
The lifter (nx2/, third_party/a64-kit) Every instruction translated, and checked against Unicorn
The Horizon layer (host/), apart from its writes to guest memory (track B) Few open issues point at it
The shader recompiler (gpu/vk/eden) Shared with its upstream
Upscalers, frame generation, the menu, the Builder, the launcher Not where the failures are
The renderer's interface (gpu/vk/vk_api.h) The rework happens behind it
Reworked Files
Memory budgets vk_memory.cpp, vk_texture.cpp, vk_vma.cpp, the budget headers
Memory sync vk_memory.cpp, parts of vk_texture.cpp and vk_replay.cpp, guest writes in host/
The frame pipeline's threads vk_replay.cpp, vk_jobs.cpp
Draw translation vk_draw.cpp
Pipeline preparation vk_progcache.cpp, vk_programs.cpp, vk_predict.cpp
Switches and device capabilities every file that reads a switch or a device feature

3. Where things stand

Part State
Memory-sync redesign In flight, by TrashPanda. #1034 (Stage 0, WIP): the ceiling report, the write-mark audit, a memory line every 600 submits; #1037 (Stage 1, WIP) is stacked on it. Track B continues this work
Memory budgets The dozen open pull requests in section 1; no shared accountant
Threads #1121 (WIP): the render thread replays jobs as they come
Draw path Small costs removed one at a time: #391, #794, #795, #796, #800
Pipeline preparation #426, #517, #789, #1161; all compile inside the game's process
Trace replay Not started. Asked for in #1198, #1113, #43
Crash grouping #1288 (WIP): scripts/crash_groups.py. Related: #81, #44, #1056
Switch table #1300 (WIP): gpu/vk/switches.def. #980 makes on/off values read by one rule

4. Tracks

Track What Starts when
T. Tools Trace replay, crash grouping, and Stage 0's measurements merged Now
A. Budgets One accountant for every pool of RAM and VRAM the renderer holds Now
B. Memory sync One owner for each range of guest memory, with explicit hand-overs After Stage 0 merges
C. Frame pipeline Fixed stages joined by queues, each owning its state After trace replay runs a recorded scene
D. Draw translation vk_draw.cpp split into four parts that link and test alone After C's stages exist
E. Pipeline preparation Compiles in a process of their own, with a time limit and recovery Now; it touches none of the four files
F. Switches and capabilities One typed table of switches; one probe of the device Now

T. Tools

  • Trace replay. Record the op stream the game submits and the memory captured with it to a file, and replay the file with no game process. The renderer becomes a function from a trace to frames, which can be compared between commits, cards and drivers, and run under the Vulkan validation layers. A trace is made from game files: it stays on the PC that recorded it, and each test farm machine records its own.
  • Crash grouping. Group crash records by faulting module and offset, by how the process ended, and by RAM, commit and VRAM at the end. The 55 open reports become a short ranked list.
  • Stage 0's measurements. The ceiling report (scripts/chain.py --log), the write-mark audit (RX_VK_MARK_AUDIT) and scripts/memtour.py's memory line judge every later stage.

A. Budgets

  • Every pool registers with one accountant: textures, render targets, mirrors, captures, staging, pipelines, retired pool records, and what the process has committed.
  • The accountant holds one budget for VRAM and one for RAM, taken from the device and the system at the start and followed while the game runs. It decides what gives memory back, in one order.
  • Reaching the limit is an ordinary state with a defined answer (evict, wait, lower a quality step), never an allocation that throws.
  • The open memory-pressure pull requests become rules in the accountant's order, or close.

B. Memory sync

  • Each range of guest memory the GPU touches has one owner at a time, the CPU or the GPU, and the hand-overs are named states: uploaded, GPU-written, written back, retired.
  • Every write the host makes to guest memory goes through one function that marks it. Stage 0's audit found four that were never marked; a build check or test should make that class impossible.
  • Mirrors, captures, shadows and write-backs become views of that one state, not separate mechanisms with their own rules.

C. Frame pipeline

  • Four stages: record, translate, submit, present. Each has its own state and a queue to the next.
  • Worker pools are created once and named. Nothing starts a detached thread where it is needed.
  • What crosses a stage boundary is a message, so most of the 600 guarded places disappear with the sharing.

D. Draw translation

  • State to pipeline key: pure, with no Vulkan calls, tested directly.
  • Descriptor binding: what a draw reads, resolved once per change.
  • Pass building: the rules for clears after draws and for targets sampled while written (design.md, section 4).
  • Command emission: the only part that calls Vulkan.

E. Pipeline preparation

  • A helper process compiles pipelines. A compile that crashes or passes its time limit ends the helper, is noted for that driver version, and the rest go on.
  • Fossilize does this for Proton and is the first thing to try.
  • In play, a pipeline that is not ready is waited for or drawn with a quickly linked stand-in. A draw is never dropped.

F. Switches and capabilities

  • One table lists every switch: name, type, default, owner, what it is for, and for a test switch the date it goes. It is read once at the start into a structure nothing changes afterwards.
  • One probe reads the device's features and limits. Defaults that depend on the card come from it, in one place.
  • Every Vulkan call that needs a feature asks the probe. Trace replay under validation finds the ones that do not.

5. Milestones

Milestone Done when
M0 Stage 0 merged; crash grouping The ceiling report and the audit run on main; every open crash report is in a named group
M1 Trace replay A recorded Kokiri Forest and a recorded Castle Town replay to the same pictures as the live run, and replay clean under validation on one card of each vendor
M2 Switch table Every switch has a row; a test fails on a switch read without one. (First written as "no file but the table's reads the environment": see the notes)
M3 Budgets A memtour.py tour of two laps on a 6 GB card and on a 16 GB PC stays inside both budgets, with the second lap's fps within the run-to-run noise of the first
M4 Pipeline preparation out of process A compile made to hang, and one made to crash, each end with the preparation finished and the game started
M5 Memory sync The audit reports no missed write over a tour; the stale-texture pull requests of section 1 are merged into it or closed with the case covered by a trace
M6 Frame pipeline The dark-frame count of design.md section 11 is zero over the same test; frame time over ceiling does not rise in either Stage 0 scene
M7 Draw translation vk_draw.cpp's four parts link separately; their checks call them and no longer cut source text

6. What waits for what

  • M0 and M2 wait for nothing. M4 waits for nothing.
  • M1 waits for nothing but is the slowest of the tools; start it first.
  • M3 needs M0's memory line to be judged.
  • M5 needs M0 (the audit) and M1 (traces to compare against), and is easier after M3.
  • M6 needs M1. M7 needs M6.

7. Questions to answer first

  1. How large is a trace? A minute of play with its captures may be tens of gigabytes. If so, record the captures' changes only.
  2. Is a replay the same twice? The dark frames were a race with the game's threads. A trace fixes the order; check that the same trace gives the same pictures on repeat runs.
  3. Does Fossilize carry what the game's pipelines use? Mesh and task shaders and cooperative matrices need checking before track E commits to it.
  4. What do the 55 crash reports group into? Answered on 2026-11-16 by #1288: 16 groups. 27 are a lost GPU device (11 of them on Intel cards, 5 with VRAM full), 10 are access violations in the game's lifted code, 9 ended at a memory limit (6 with no crash record, 3 as an out-of-memory exception), 2 are crashes inside a graphics driver. So device loss comes first for stability, then memory; the lifted-code crashes are outside this plan's files.
  5. Can a software Vulkan driver (Mesa's lavapipe) replay a trace? If it can, it tells a driver's fault from ours.
  6. How much of the fps fade is memory? Run memtour.py on a 6 GB card with the memory line on before M3 is designed.

8. Decisions needed

  1. Who owns each track, and whether track B stays with the author of Stage 0.
  2. What happens to the open pull requests against a file being reworked. Proposed: merge or close them before the track starts, then take only fixes for that file until the track lands.
  3. Whether fixes still come over from Hookshot for files this plan reworks. Each reworked file gets harder to patch from upstream.
  4. Whether Fossilize joins third_party/, with its provenance entry.
  5. The lowest card and system the budgets promise to hold (proposed: 4 GB of VRAM, 16 GB of RAM).

9. Rules for every piece

  • Behind the interface. The old path stays, selectable, until the new one gives the same pictures on the recorded traces. Then the old path is deleted in its own pull request.
  • One area at a time in one file. Two tracks do not rework the same file at once.
  • Measured. A pull request that changes speed or memory brings Stage 0's numbers, before and after.
  • No new switch outside the table once M2 lands, and a test switch names the date it goes.
  • Nothing made from the game leaves the PC. Traces, captures and pipeline lists made from a dump are game files.
  • MKWVK_API_VERSION goes up with every change to MkwVkHost or MkwVkRenderer.

10. What this plan does not fix

  • Game logic above 60 fps (#988, #439, #414): the game counts frames; that is work in the game's code, not the renderer's.
  • Install and build failures (20 open issues): the Builder's own.
  • Speed on a strong PC: about a quarter at most, by Stage 0's ceiling.
  • Driver bugs themselves. The plan makes them cheaper to find, isolate and work around; it does not remove them.

11. Notes, milestone by milestone

Written as each milestone's pull request opens. One pull request a milestone, each stacked on the one before. The stack does not build on #1034: its measurements stay that pull request's own.

M0: crash grouping (2026-11-16, #1288, WIP)

  • What it is: scripts/crash_groups.py. It reads the issues the crash window titled, their attached records and the ends of their logs, and names a group by how the run ended, whose code the fault was in, and whether VRAM or Windows' commit was at its limit. None of the three changes between builds.
  • Result on the 55 open reports: 16 groups. 27 are a lost GPU device (11 on Intel cards), 10 are access violations in the game's lifted code, 9 ended at a memory limit, 2 are crashes inside a graphics driver.
  • The device losses do not share a place. The last markers before the loss are draws, dispatches, texture uploads and write-backs, on different programs. Nothing here says one bug causes them; a run under the validation layers is the next step, and this PC has no validation layers installed.
  • A fault in lifted code groups by the game's own caller address, which is the same in every build. Two of the ten reports share one.
  • Not done: the ceiling report and the write-mark audit, which the plan's M0 also names, are in #1034 and were not rebuilt here.
  • Not run: tests/test_crash_groups.py (no checks are run on the PC this was written on).

Measurements made before choosing what to rework (2026-11-16)

On an RTX 3090 and a Ryzen 9 7900X, Linux, 2560x1440 with no upscaler, main at 8e9cfc3a, Threaded rendering on.

  • The frame is the GPU's time plus 3 to 7 ms. Kokiri Forest standing: 18.0 ms a frame, 13.1 of them GPU time. Hyrule Field: 12.6 and 9.9. The Market: 17.5 and 10.3. Were the replay and the GPU to overlap fully, those would be about 76, 101 and 97 fps against 55, 79 and 57.
  • The render thread's own work is about 5 to 6 ms a frame in Hyrule Field (draws 2.5, descriptors 1.1). With the sampler on it was blocked in vkQueuePresentKHR for half of its time.
  • The presenter thread does not buy that back. RX_VK_PRESENT_THREAD=1 against 0, two interleaved timed sessions each: every scene within the spread between runs. Other builds ran on the PC during them, so a small gain could hide in the noise; a large one could not.
  • Why the overlap is missing is not answered. The game waits once a frame for the GPU to finish the frame before (#916, closed: letting it run two frames ahead made shadows flicker). That wait, and the game's reads of GPU results, are the likely reason, and they are track C's subject. No fix was attempted.
  • So no large fps gain was found that one change gives. The table of switches below is the first piece instead, because every later decision about a default needs it.

M2: the switch table (2026-11-16, #1300, WIP, stacked on M0)

Done before M1 because the request was to cut the switches down and decide the defaults in one place, and both start from a list that did not exist.

  • What it is: gpu/vk/switches.def, one row for each of the 571 RX_ switches: its kind, what the renderer does with it unset, what setting it does. tests/test_switch_table.py fails on a switch read without a row, a row nothing reads and a removed switch still read. The renderer's start logs the switches a run has set, and each RX_ name set that is none.

  • What the 571 are:

    Kind Count What it means for the rework
    diag (logs, dumps, checks) 189 Keep, but they are a third of the names: group them under a few
    kill (turns off something on for everyone) 177 Each keeps an older path alive in the code. These are the ones to delete, path and all
    tune (a number with one default) 73 Keep the ones a budget needs; track A replaces many
    attempt (turns on something nobody ships) 57 Each is an unfinished decision: measure it and ship it, or delete it
    hw (unset, it follows the PC) 49 The per-GPU rules. Today they sit in about 30 places; they belong in one
    player (a menu row or the launcher's) 26 Keep
  • The reads stay where they are. The milestone first said no file but the table's would read the environment. Moving 1,200 reads would touch every line the 77 open renderer pull requests touch. A check that holds each read to the table gives the same guarantee and conflicts with none of them, so the "done when" was reworded.

  • One switch removed as the first: RX_VK_GPU_PROFILE, a second name for RX_VK_PASS_TIMING=1. The host's nine removed RX_ names moved into the table's removed rows.

  • Found while reading: seven comments beside a default name another number than the code uses (RX_VK_UPLOAD_BUDGET_MS, RX_VK_COMPACT_PCT, RX_VK_KEEP_FINALIZED_MB, RX_VK_IMAGE_BLOCK_MB, RX_VK_TEX_MAX_MB, RX_VK_ASTC_BC_MB, RX_VK_WB_MAX_KB); docs/development.md says RX_VK_PRESENT_THREAD is off by default while the device's queue for it is made on NVIDIA; RX_VK_TIMELINE is on for any value, 0 included. None is fixed here.

  • Limits: the rows were written from one reading of each switch's code and not checked by a second reader. Run in the game on Linux with an RTX 3090 only. The check was not run on the PC it was written on. The host's HOS_ switches (about 200) have no table yet.

  • Next in this track: the 49 hw rules into one place that the start logs whole; then the kill switches deleted file by file, each batch run in the game.

Track F, second piece: the kill switches (2026-11-16, #1309, WIP)

#1288, #1300 and #1302 (six table rows corrected by a second reading) are merged.

  • What it is: 93 of the 177 kill switches deleted from vk_draw.cpp, vk_texture.cpp, vk_replay.cpp and vk_memory.cpp, each with the older path it selected: about 400 fewer lines, 478 switches left.
  • How it was made: one agent a file deleted, a second agent a file checked every hunk against the old text. The reviews found no change of behaviour and one stale test needle. This worked because the files don't share the switches; the agents were told to keep a switch rather than edit another file.
  • 26 were kept: tools or the README name them, the default follows the PC, or they are the way out of a young fix. RX_VK_WB_DIFF and RX_VK_LATE_FIX were deleted and then put back at review for that last reason.
  • In the game: nine sessions against five of main on an RTX 3090 (Linux), three scenes. No difference. The Market looked 5% slower after two pairs and overlapped after five more sessions: on this PC two runs a side do not settle a difference under about 8%.
  • Not done: the 56 kill switches in the shader translation's files. They are part of the program cache's stamp and span several files, so they want their own pass. The host's 212 switches are triaged (89 diagnostics, 50 kill switches, 23 player settings, 22 tunables, 20 attempts, 8 per-PC rules) and not yet in the table.
  • Limits: 53 test files were edited by reading alone and never run. Nothing ran on Windows, AMD, Intel, an integrated GPU or a small card, which is where several of the deleted switches' paths live.

M1, first step: one frame recorded and played (2026-11-16, in work, no pull request yet)

  • The study found every call between the game and the renderer passes through host/rx_backend.c, so the recorder needs no change in gpu/vk. It estimated 15 to 30 GB a minute for a full trace (not measured), which is why the first step is one frame.
  • Measured: one Kokiri Forest frame is a 2.0 GB file: 1.9 GB for the snapshot of GPU-visible memory (489,681 pages that are not zero) and 62 MB for the frame's 56 calls. The snapshot took 2.2 s.
  • First play: the renderer started with no game code, took the snapshot, and crashed at the frame's first clear: the op stream names a render target by a pointer into the recording process's own heap. Being fixed.
  • Also seen: the frame's submits wait for events the game signals, which the player has to make; and the player did not get the synchronous replay it asked for.

Studies made before tracks A, C and F's rules (2026-11-16, from reading the code; nothing in them was measured)

Track C, the frame pipeline: why the frame is the GPU's time plus 3 to 7 ms.

  • The game limits itself: once a frame its main thread waits, with no timeout, for the GPU to finish all of the frame before, its present included.
  • The port adds three whole-frame rules: a frame's replay starts only once its present is handed over, the present waits for the main thread's signal, and one present at most is queued ahead. They exist because replaying a half-written frame drew the lit scene black.
  • With NVIDIA's driver on Linux the present call also waits for the frame's GPU work. That fits what was measured: the presenter thread alone gained nothing here, and #916's two frames ahead gained 11 to 15% on Windows, where the present does not wait.
  • Why two frames ahead made shadows flicker is written down nowhere. Three explanations are possible, each with a test.
  • "GPU time" in the log leaves out the upload command buffers and the copy to the window, so part of the 3 to 7 ms is GPU work and not waiting.
  • First change to try: the limiter waits for the part of the frame before whose results the game reads back, not for its last pixel. The game stays one frame from its results. What it can gain is the GPU time after the last pass the game reads from, which is not measured and may be nothing.
  • Before any code: several options can be bounded with switches that exist (RX_VK_FRAME_GATE=0, RX_VK_PRESENTS_AHEAD=2, RX_VK_READBACK_LATE=newest, RX_VK_PRESENT_THREAD=1), and RX_VK_LOG_RB_WRITERS=1 says where in the frame the passes the game reads from sit.

Track A, budgets.

  • The renderer holds about 25 pools. Only the texture cache answers to every signal of pressure. Most others read their limit once, at first use.
  • Nothing adds them up. The render target pool and the list of images waiting to be destroyed are outside the textures' count.
  • Never given back: retired pool records, pipelines and programs, mirrors the GPU wrote.
  • A failed allocation ends the game only through a device loss, the C++ allocator's refusal after 5 s, or the host's commit failure. Several Vulkan results are not checked, and a failed queue submit is only logged.
  • First step, in work: one vk: budget: line that adds every pool against both budgets, with what no pool reports. No decision reads it yet.

Track F, the per-PC rules.

  • 73 rules in about 40 functions of 14 files: 22 are one driver's bug, 13 a capability Vulkan could be asked for, 10 a preference measured on one card, 26 sizes by VRAM, RAM or CPU count, 2 the OS.
  • Their switches are parsed seven ways: RX_VK_FETCH_BOUNDS=on turns the fix off, RX_VK_UB_SNAPSHOT=on turns it on.
  • Two rules name a driver version, and none an upper one, so a vendor's fix never ends a workaround.
  • Seven rules test the vendor where the reason names one compiler, so they also reach Mesa's drivers.
  • Rules that look wrong today, none changed here:
    • The mirrors on a small card. Any card of 6.5 GB or less gets a third of its memory, at most 1700 MB, before the small-card rule is reached: about 1,365 MB on a 4 GB card, where mirror_budget.h argues for 256 MB beside 2.2 GB of textures. The branch came with #637, whose comment speaks of 6 GB cards. Whether 4 GB cards were meant needs its author, and a run on one.
    • "Linux and AMD" is taken as RADV with no check of the driver or its version.
    • The native float add is on for three Intel families and off for the Arc 140V, the A-series and Iris Xe, which keep the path that lost adds.
    • Three Intel rules for Windows-driver bugs are keyed on the vendor alone, so they reach Mesa's driver too.
    • Batched submits test for GCN cards a second way, which another switch can flip on every 64-lane RADV card.

Checks that cannot pass on main as they stand (found by three readers, not run): tests/test_mirror_budget.py, one assertion of tests/test_present_thread.py and one of tests/test_target_image_pool.py each look for a line that is not in the function they read.

Track F, third and fourth pieces (2026-11-16, built, not yet run in the game, no pull request yet)

  • 18 more kill switches deleted from the smaller renderer files; 18 kept. Four were put back at review: the two switches measurement runs pin their settings with, the one way to turn sparse images off, and one whose comment names the case it is for. 460 renderer switches are left of 571.
  • The host's 216 switches joined the table, read once each: 90 diagnostics, 50 that turn something off, 24 player settings, 24 numbers, 20 that turn on something nobody ships, 8 that follow the PC.
  • Not started: the 22 kill switches the shader translation reads. Any edit to those files makes every player's shaders translate again, so they go in one pull request with the translation's other pending changes.

M1, the one-frame trace: it plays (2026-11-16, #1334)

  • HOS_RX_TRACE records a frame, longshot --play-trace plays it with no game. A Kokiri Forest frame plays all 2,686 draws, none left out, 600 rounds at 24 ms each; the snapshot is 3.1 GB and 6,900 programs.
  • The played picture is not the game's. A loading screen plays exactly as live. The forest plays darker and hazier, without a button prompt and some ground detail. What earlier frames left on the GPU is not in a trace; the sky and ambient light the game renders from its time of day and keeps are the first suspect, not confirmed.
  • So today it compares two builds on one trace. It does not show how the game looks, and it does not exercise frame pacing (no game thread, renderer unthreaded).
  • It took four rounds to get here: host-heap pointers in the op stream, programs known only from their creation call, a pool table too small for the scene, and my own present numbers falling in loading screens.
  • Next step if wanted: capture the GPU-side images at the snapshot.
  • Documented in docs/development/trace-replay.md.

First steps of tracks A, D and F's rules, and two more pieces of F (2026-11-16, all WIP, each run once in the game)

Pull request What
#1325 18 more kill switches deleted
#1326 the host's 216 switches in the table
#1339 track A step 0: the vk: budget: line
#1340 track D step 1: draw_key.h, 15 pure functions, 12 checks include it
#1341 per-GPU rules step 1: device_policy.h, 67 decisions in one log block, 4 sites converted
  • First finding of the budget line: on the RTX 3090 about 426 MB of VRAM is held by something no pool reports, the same in Kokiri Forest (5.6 GB counted) and Hyrule Field (8.7 GB).
  • The per-GPU step converted 4 sites, not the study's dozen: the others sit in functions that checks cut by text.
  • None of these has been through tests/run_all.py; about 100 test files are edited or new across the stack.

Studies for tracks B and D (2026-11-16, from reading)

  • Memory sync (B). A page's state is spread over about 15 tables. Confirmed: three host writes zero memory the renderer has imported without marking it (discard_pages, FreeMemoryPages, UnmapPhysicalMemory), the writes #1034 fixes. Suspected with the render thread on: the game captures submission N+1 before N's GPU writes are recorded, so a page both wrote can sync stale. Design: one record a page with a named owner, ten steps, first a checker that is off by default.
  • Draw split (D). About 2,500 of vk_draw.cpp's 11,000 lines are the per-draw path. Descriptors are rebuilt whole for nearly every draw because reuse is all or nothing and the game rebinds a uniform buffer each draw (estimated 0.4 to 0.6 ms of 1.1 to gain); mesh programs have no fast path; every indirect mesh draw ends its pass.

Where the frame's time goes, measured (2026-11-17, RTX 3090, 1440p native, Linux)

This replaces the earlier notes' guesses about fps. Everything here was measured in the game, interleaved.

  • A frame in Kokiri Forest is 15 ms; the GPU's work is 11 ms. The other 4 ms: about 1.9 ms where the GPU waits for the frame's first draws, 0.7 ms where it waits mid-frame, the rest upload command buffers and the window copy.
  • Why the GPU waits at the frame's start. The game waits each frame, with no timeout, for the GPU to finish the frame before; only then does it signal, and nothing with draws can be recorded before that signal (doing so is what flashed). So the GPU has nothing from the end of one frame until the first part of the next is recorded.
  • Through the geometry the GPU outruns the recording; through the frame's last passes the recording outruns the GPU. A faster recording therefore only helps by the idle it removes, at most about 2.5 ms.
  • The render thread's recording is a flat profile: about 8.7 ms a frame, the largest single function 6%.
Tried Result
Parts of 240 draws, not 120 (#1354) Kokiri Forest 63.0 -> 67.9 fps, the Market 68.6 -> 70.8, Hyrule Field the same. Kept.
Frame gate off, presenter thread, two presents ahead, each alone nothing
Frame gate off with the presenter thread 3 to 5%; not shipped, the gate's reason stands
Early or late readbacks nothing: those waits overlap the game's frame wait
Answering the game's frame wait early ceiling measured 0.00 ms; removed
Three short first parts the GPU's first wait 2.4 -> 1.5 ms, the same idle appeared mid-frame; fps the same; removed
RX_VK_PARALLEL=4 (recording on four threads, as built) 10 to 23% slower
A program-pick cache in front of the lookup serves 40% of draws, almost no mesh draws; fps the same; parked, not shipped
Descriptors rebuilt by section 1,600 of 2,500 draws take the cheap path; fps the same; parked, not shipped
  • No large fps gain was found on this PC, and the measurements say why: it needs either a recording design that really runs on several threads, or not recording again what did not change, or less GPU work in the frame's last passes. Each is a project, not a switch. Slower CPUs and other drivers were not measured.
  • Two gains under 3% cannot be told from none here: the spread between sessions of one build is 3 to 8%.

Track B, memory sync (#1360, 2026-11-17)

  • Fixed: five host writes into guest memory the renderer was never told of (three zero imported pages at a free), with a check that fails on a new one. Windows now zeroes imported pages in place as Linux does.
  • Fixed: a capture's pages that a write-back wrote since are found late when the capture is taken (2,600 to 5,700 pages a session), where a sync used to copy the capture's page over them. The 32-bit generation counter, which wrapped after about 52 hours, is 64 bits.
  • RX_VK_MEM_CHECK=1 counts where the sync breaks its rules. The ordering rules hold (0 in 168,000 takes).
  • A wrong fix, caught by measuring. A sync that kept every word the CPU's copy left as it was halved the frame rate: the game sets counters the GPU fills (the exposure sums among them) back to zero every frame, and no compare of contents can see a write of the same value. It never shipped. The checker now says what it cannot tell.
  • Not shown: any visible bug fixed. Nothing here was tied to a flash or a crash report.

What is open across the plan

  • Nothing has been through tests/run_all.py: about 120 test files are new or edited across six pull requests.
  • Nothing ran on Windows, AMD, Intel, an integrated GPU or a small card.
  • Not started: track E (pipeline preparation out of process), the 22 kill switches the shader translation reads (any edit there makes every player's shaders translate again), track A beyond the accounting line, track D beyond its first header, the per-GPU rules beyond four sites, the small-card mirror budget.
  • M1's played frame is darker than the game's; the GPU-side images are not in a trace.

Later the same day (2026-11-17): the ceiling, and the next steps of tracks A, E and F

  • The ceiling for fps on this PC is about 17% in Kokiri Forest. The game's own loop needs about 12.7 ms of the 15.4 ms frame; the rest is its wait for the GPU. No renderer change can give more there.
  • Recording ahead of the game's signal, the one project with that ceiling, was measured and dropped: the frame's first part was never final before the signal (0 of 595 frames); the game writes about 57 pages just before it.
  • Recording on four threads is not slower with every core free (64.3 fps against 65.9 under the profiler). The 10 to 23% loss measured earlier came from timed runs being pinned to 6 cores. It is not faster either.
  • Every timed number in these notes is for 6 cores (12 threads), the job queue's timing mode.
Pull request Added
#1339 track A every allocator buffer counted (unaccounted VRAM 426 -> 280 MB); an arbiter that asks pools kept for reuse before textures in use are evicted, seen giving back 192 to 232 MB at a time under a 6.5 GB allowance; the mirrors' rule in one place (cards of 4.5 GB or less: 256 MB again)
#1341 track F 15 switches read by one rule; four rules test the driver their reason names, not the vendor (they change AMDVLK, RADV and ANV, none of which was run)
#1386 track E the shader preparation journals each driver compile; a supervisor restarts past a shader that crashes or hangs it and quarantines that one. Proven with forced crashes and a forced hang
  • Track E's worth, from the crash groups: about 5 of 55 reports are in the shader phase or inside a driver. Of 21 plain device-lost reports, 17 are during play. Ten more reports are VRAM-full during play, mostly AMD: track A's arbiter and the small-card mirror rule are aimed at those, and neither has run on such a card.

The shader-stamp batch (#1390, 2026-11-17)

  • 15 of the 22 kill switches the translation read are deleted; 7 kept, each for a stated reason. The per-PC rules in the stamped files read the device policy; vk_vendor.h is gone. 126 switches removed in all across the plan.
  • Merging it makes every player's shaders translate again once (about 5 minutes on this PC), so it is its own pull request: that cost is a decision of its own.
  • Run here: all shaders translated again with none failed; pictures within the difference between two sessions of the build before; fps the same. The paths that changed for AMD, Intel and cards without f16 did not run.
  • Every track of the plan now has a pull request. All nine are WIP: none has been through tests/run_all.py, and none has run on Windows, AMD, Intel, an integrated GPU or a small card.

M1 is faithful, and track D's next steps (2026-11-17, evening)

  • A played frame is now the live picture (#1334). The trace holds the 223 images the GPU wrote (828 MB) and the player puts them back each round: played against live differs by 0.009 of 1, where two live sessions differ by 0.007 to 0.018. The rounds converge over about five and are not identical from the first (the playing renderer's write-backs into guest memory are not rewound): compare from round 6 on.
  • Track D (#1340): the pipeline key is a pure function and the twelve "what is bound" variables are one struct. Keys unchanged: a second start made its 10,082 pipelines from the caches in 2.2 s, as before.
  • Where the plan stops without a decision: the draw split's next step reshapes draw() and should not be built on about 160 test files that have never run. The same holds for the later steps of memory sync. The checks need to run, here or on the forge, before more is stacked on these branches.