DLSS kept the replay on one thread: its decisions follow the passes in replay order, its jitter and camera are noted
draw by draw, and its evaluation reads the per-object motion list the scene's draws build. Now the scan takes DLSS's
decisions on its own state (vk_dlaa_plan, split out of vk_dlaa_pass) and notes the scene camera in replay order
(vk_dlaa_scan_draw), and the copy of the lit scene and the evaluation are records of the chunk that holds the op
(vk_dlaa_exec). A chunk's draws are jittered while they come before the op the scan ended the scene at. The
evaluation waits until the chunks before it are recorded, and the chunks after it wait for it (a hold), since they
sample its output. Chunks note their draws for the per-object motion one at a time (mo_lock in vk_exec_draw.c); the
uniform overrides of a motion draw and shader_for's last-frame variant flag are per thread, as the other chunks' draws
go on meanwhile; the FXAA shader table takes concurrent lookups. fxaa = 0 runs in chunks too.
With dlaa = 1 at 4K (DLSS Quality) on 1.2.1 and an RTX 5070, replay_workers = 4 takes the frame rate from 70 to 78
fps where the CPU is the limit, with no one-frame glitch in 241 consecutive frames.
(cherry picked from commit 04f8bb1b57)
replay_workers = N (0, the default, keeps the sequential replay) records a submission of enough draws in chunks that start between passes, on N threads and in twice as many chunks, and submits them in order. In the town at 4K on an RTX 5070, 4 threads take the replay from 8.2 to 4.5 ms a frame and the frame rate from 71 to 79.
A sequential scan on the submitting thread applies only what is queue state (fixed-function and bind ops, render targets, render enable and conditions, samples-passed counting) and keeps a copy of it where each chunk starts, with how far its lists got: inline uniform updates, RENDER_COND results, contact shadow marches and the ops that drop uniform copies. A chunk takes those from the lists instead of from the chunks before it, starts with every image in GENERAL and ends with a full barrier, so its recording depends only on the copy and the lists.
Each thread records with a context of its own: the replay's memos, descriptor state, occlusion query segments and per-command-buffer state moved from file statics into VkExec and VkExecDraw, and the tables the contexts share (stand-ins, depth twins, views, mirrors, timestamps, completion callbacks, crumbs) take locks or atomics. The scan makes render targets live in replay order and notes the op (vk_texture_revive), since a chunk can sample a storage before the chunk that renders it got there or after the scan went past a later target there: a chunk's texture slots resolve as of its own op, and the chunks after a texture with no entry yet wait for the chunk that makes it. Uniform copies are dropped at the op that writes them (vk_usnap_drop_at).
Contact shadows plan their march in replay order (vk_contact_plan) and the chunk that holds its op records it; the HDR source keeps the copy that comes last in replay order. DLSS and fxaa = 0 act on the frame draw by draw and keep the replay sequential. TOTK_REPLAY_STATE_CHECK=1 compares the state after the last chunk with the scan's.
A draw or dispatch whose shaders write storage buffers drops the uniform copies they cover from its own op on, as the other GPU writes do (scan_writes). The scan still translates no shader: it reads the shaders the recording contexts translated from a table shared with them (vk_exec_draw_writes), and an op whose shader no context translated yet holds the chunks after it until it is recorded. Before, the chunk that recorded such a write dropped the copies for every position at that moment, so a later chunk recorded first bound the copy taken at the submit call: on an RX 7800 XT on RADV the grass near the camera came out dark or unshaded in some runs with 4 threads.
TOTK_TRACE=perf counts the chunks held per submission by reason and logs when each chunk of the last submission began. The settings menu has the thread count under Advanced, Scheduling, with the count this run uses under it.
The recorder thread begins, ends and submits the submission's open part (vk_rec.c rec_end_cb), so a chunk's mirror prologue stays off it: vk_sync_part waits until the recorder is idle, as the part pool allows one thread at a time, then records, ends and submits the prologue itself. Through the recorder the prologue could reach the queue before it was ended, and the GPU lost the device at the title screen.
(cherry picked from commit b94e2e9642)
On 1.4.3 the per-frame wait is the second of the two nvnSyncWait calls in f_70002db8ac (return address 0x70002db99c). Like on 1.2.1, its sync comes from a two-entry ring indexed per frame; the first call waits on one object's sync behind a mode check. wdiasjunior found the site and measured it on an RX 7800 XT (#676): about 67-70 to 81-83 fps on Great Sky Island.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Each frame the game waits in one nvnSyncWait (1.2.1 lr 0x7000b23dfc) for the frame it presented last. On the Switch
that work is long done by then; here it is still in the replay and on the GPU, and on Great Sky Island the wait is
about 4.6 ms of a 13 ms frame. With TOTK_SYNC_AHEAD=1 that one wait waits for the frame before it instead, once the
replay thread submitted the asked value, so the game builds the next frame while the GPU runs the last one.
The game then writes guest memory that GPU work still in flight reads. Shadow storage makes that safe: a shadow update
of a pool with a reader in flight is queued and copied by the GPU in the next part's prologue, in queue order, instead
of memcpy'd under that reader (TOTK_SHADOW_DEFER=1, the default with the switch; 0 makes the replay thread wait for
the reader instead). The guard is read under the shadow lock and the wait takes that lock once after raising it, so no
sync that read the old guard is still copying when the game writes again. The switch needs shadow storage (Linux and
Wine by default, TOTK_SHADOW=1 on native Windows) and the 1.2.1 call site; otherwise it stays off with a log line.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
nvnCommandBufferUpdateUniformBuffer between draws was replayed as a buffer copy at that point, which needs a barrier
against the draws that read the old bytes, and a barrier ends the open pass. The terrain and the sky islands' meshes
update before most of their draws: about 200 updates inside passes in a field submission, each a pass end, a full
barrier and a pass begin.
An update inside a pass now goes to the scratch buffer only. Later bindings of a range it covers bind the scratch
bytes (ub_bind, from ubo_info and bind_range); a binding it covers only in part, or at an offset the alignment
refuses, gets a merged copy of the snapshot or guest memory with the submission's updates on top. The copies into the
real buffers are recorded behind one barrier of their own at the next full barrier (vk_exec_ub_flush from
barrier_to). A new update of a range replaces the older overlay and pending copy of it, so the lists stay as short as
the blocks. Copies, fills and storage writes of the same bytes retire the overlays they touch, and a storage binding
over a pending copy brings the copies forward with a pass restart. bind_sig hashes the overlay each of the draw's
uniform and storage bindings reads, so a draw of an updated block binds the newest bytes and the others still skip
their descriptor build. TOTK_UB_OVERLAY=0 copies at once as before; ab alternates; TOTK_TRACE=perf prints the
counts.
1.4.3, RTX 4070 Ti, 2560x1440 DLAA, standing still on Great Sky Island, TOTK_AB=10 (tools/ab_summary.py):
17.03 ms a frame with the copies at once, 14.39 ms with the overlays (-15.5%, 58.7 to 69.5 fps); replay time on the
CPU 8.81 to 8.30 ms.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BspNcezsiV8zT8wcnXrrME
83d2302 turned it on from one measurement where the game waits for the GPU (a GTX 1650 in the Depths, #88).
Nobody checked frame pacing at the 60 fps cap with GPU headroom or on a 6-thread CPU. #659 (GTX 1660 Ti,
i5-9400F, GPU at 26 %) reports uneven motion on 0.3.7 at a steady 60 fps that 0.3.4 did not have, and this
is the only change in the frame path between the two releases that reaches that machine. Players it helped
set replay_async = 1.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Merged on top of #566. The camera motion is #594's: its blocks in camb also feed the per-object pass, and
dlaa_mv.comp stays as on main, fed the identity and the reprojection made on the CPU in double. #566's
vk_usnap_host goes, vk_usnap_bytes serves the same. #566's scaling-draw swap, camera rune guard and output-size
scaling pass stay in vk_dlaa.c. Translator patch 0012 becomes 0015 after dev's 0012-0014.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Solid scene draws whose position reads an object's own uniform blocks (bones c5, place c7, c6) are drawn a second time
with a vertex shader variant (translator patch 0012) that computes last frame's position from last frame's blocks; the
game writes those into two copies that take turns, and the uniform snapshot keeps both (vk_mvprev.c). The draws are
listed during the replay and recorded through the recorder thread with repeated state skipped. Blocks whose last-frame
copies measured wrong (c9 and c11 of walls and cliffs) keep this frame's; positions without an object block (terrain,
grass) keep the camera's motion, which measured as good.
The camera motion is reprojected in double precision on the CPU: the float inverse made noise on far surfaces and a
still camera that DLSS followed into a wobble. DLSS gets Ultra Performance (a third of the output, also in the F1 menu)
and NVIDIA's recommended preset per mode (K, M for Performance, L for Ultra Performance; TOTK_DLSS_PRESET overrides).
Test switches: TOTK_MV_CHECK measures the motion vectors and DLSS's output against the picture, TOTK_DLAA_TIMES times
DLSS and the motion passes on the GPU. A reactive mask pass for transparents is included but off (TOTK_DLSS_REACTIVE):
its mask covers sky and fog too.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
replay_async was off because no timing on our machines showed a gain. Where the game waits for the GPU
it does: a GTX 1650 in the Depths went from 450-686 frames over 50 ms a minute to 10-13, and the 1% low
from 10-12 to 13-24 fps (#88). An RTX 5090 ran slower with it off (#459). Where the replay or the game
threads bound the frame it is neutral (machines A and B, the Steam Deck in #308), and no crash report
ties to it. MacNativeGames has its translation thread on by default for TotK. It adds up to a frame of
latency; replay_async = 0 turns it off.
The fight scene on an RX 9070 with it on: 60.0 fps mean, 1% low 56.3 in the last window, no frame over
50 ms, 0 validation errors.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The settings menu offers 1920x1280, 2160x1440, 2256x1504, 2880x1920 and 3000x2000 (the 3:2 screens of Surface and
Framework laptops and tablets), and the setup builds romfs-patches-<w>x<h> for each, so the HUD moves to the top and
bottom edges as it does at 16:10 instead of being stretched.
runtime/cfg.c: the known names take both sides, the per-stick dead zones beside the shadow and
DLSS switches.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
0.2.8 turned the recorder on for every GPU (e38eaa8). The AMD device losses
and hangs came back the same day: a black screen or VK_ERROR_DEVICE_LOST at
startup on RDNA 2, 3 and 4, under AMD's Windows driver and under RADV
(#277, #283), and vk_recorder = 0 still gets past it.
The submission recorder goes back to defaulting off on vendor 0x1002;
TOTK_VK_RECORDER=1 still forces it on for an A/B run, and the log says which
path was taken. The rec_end_cb line now prints only when a part really was
recorded by the recorder, so a log no longer suggests the setting was
bypassed (#315).
The menu side is dev's: it has Simplified Chinese since #243, glyphs included. Simplified Chinese
joins the setup window as a fourth language beside Brazilian Portuguese, in the language switch,
the Windows and locale pick and the launcher; zh-Hans.json gets the nineteen texts added since
(fonts step, CPU level, base game checks, Linux checks) and the {game_exe} placeholder.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The sampler keeps both the DLSS mip bias and pull request #321's anisotropic level; DLAA's pass hook runs after the
contact shadows'; the extension arrays grow for NGX's extensions beside HDR's and the calibrated timestamps.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Reverts dafc35f: free_cores = 1 in totk.ini lifts the virtual core gate again, as in 0.2.8. The mode stays as an
experiment, and every place a player meets it says the game crashes: totk.ini.example, a WARNING line in the start log,
and a line under every crash report and FATAL while the gate is off (kern_free_cores_note), so a log from #212 names
the cause at once.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Earlier settings menus wrote free_cores = 1 under the label "Virtual core gate", which promised the gate. Without it a
thread that holds no virtual core reports its ideal core to GetCurrentProcessorNumber, so the game's job workers all
report core 0 and run its per-core code at once. On 1.2.1 two of them add the same per-core NVN control memory, which
retires the command handle the other just recorded, and its CallCommands fails at start (#212); on 1.4.3 the game
corrupts a heap in main+0x82e00 or hangs at the title menu. A player with such a totk.ini crashed at every start and
the menu no longer shows the row.
free_cores is no longer a setting: only TOTK_FREE_CORES in the environment lifts the gate, and a free_cores value in
totk.ini is logged as ignored. The kernel probe asks the kernel whether the gate is on.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
With hdr = 1 the game's tonemap shader is replaced by one that keeps highlights up to the display's peak, the present
reads the float picture the game copies into its 8-bit window texture, and a compute pass encodes it as PQ in Rec. 2020
for an HDR10 swapchain. Peak, paper white and HUD brightness are live settings in the menu and totk.ini. The approach
follows the RenoDX TotK mod by souperman9 and Musa; no code was copied.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Conflicts: the known-key and section lists in cfg.c keep both sides; vk_backend.c, vk_device.c and vk_exec_draw.c include platform.h and vk_dlaa.h; create_instance takes the window's instance extensions from gfx_window_vk_extensions as on main, in a 12-entry array for NGX's.
patches-v121.txt takes the aspect set at upstream's 1.2.1 sites (game_patches.c aspect_install): the same two camera
loads and two viewport divisions as 1.4.3, with the same original words and the same replacement from page +56. The
installer now builds the romfs-patches-<w>x<h> overlays for 1.2.1 too; ultrawide_layout.py passes on its
Common.Product.110 at all ten sizes. Checked in game at 3440x1440 (camera 2.3889) and 1920x1200 (1.6000): wider or
taller view, HUD at the corners or edges, no validation errors.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
ultrawide_layout.py handled canvases wider than 16:9 only, so the Steam Deck's 1280x800 got the 16:10 camera with
the 16:9 HUD stretched 11% over it. A narrower canvas now scales each layout's root pane in y by the aspect over 16/9,
stretches full-screen backgrounds back and moves the HUD to the top and bottom edges. The pane list and distances are
the TALL table of tools/aspect_layouts.py from pull request #60, in the format of the wide edits; the minimap,
discovery banner and dragon's tears keys are found by walking the animation's curves. Every value is checked against
the shipped one before it is written: 1.4.3's Common.Product.140 and 1.2.1's Common.Product.110 pass at 1280x800 and
1920x1200, and the 3440x1440 overlay is byte-identical to the one before.
The settings menu offers 1280x800, 1680x1050, 1920x1200 and 2560x1600, and the installer builds their overlays with the
21:9 and 32:9 ones.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The setup window gets installer/text/zh-Hans.json, a full copy of the English catalog, and a third entry in its
language switch. A Windows display language of zh-CN or zh-SG picks it; zh-TW, zh-HK and zh-MO write Traditional
Chinese and stay on English. A Chinese window still starts with English as the game language, because Chinese game
text needs the Switch shared fonts the installer does not extract. The launcher's message box and
make_release.py's launcher_text.h carry the Chinese strings too.
The menu and the performance overlay get a text_zh_hans table for every menu id, and TOTK_MENU_LANG takes zh-Hans.
Left unset, the menu follows the system UI language with the same Simplified Chinese regions. The font atlas merges
in every glyph of the menu language's text from the system font (Microsoft YaHei, else SimSun) and is built again
when the menu language changes. ov_probe checks that every menu id has Chinese text, that the printf formats keep
the English conversions, and how system language tags map to menu languages; installer_gui_test checks the new
catalog the same way as the Russian one.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DcYzeu7eb2tXZMU4bRVcGh
tools/ultrawide_layout.py computes every edit from the canvas aspect, so 32:9 needs no new layout data: the installer now builds romfs-patches-3840x1080 and -5120x1440 beside the four 21:9 sizes, and the menu lists both. Before, a 32:9 output_res got the wide camera with the 16:9 HUD stretched over it (issue #181).
The menu had English and Russian. pt-BR gets its own row with every menu id, a Português (Brasil) entry in the menu language list (TOTK_MENU_LANG = pt-BR), and is picked automatically when the Windows display language is pt-BR. The game language pt-BR now maps to this row instead of Portugal's pt, so the software keyboard shows Brazilian text too; pt keeps its row and the English menu. probe_menu_text checks the row is complete, keeps its overlay formats and follows the setting.
Wide sizes other than the four the installer prepares get the wide camera with a 16:9 HUD stretched over it. aspect = fit letterboxes a 16:9 game in a wider window where it used to stretch. Ultrawide is 1.4.3 only.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
AMD driver 26.10.1 on RDNA2 cards wrote past the end of a 3D BC4 volume made
BLOCK_TEXEL_VIEW_COMPATIBLE and 2D_ARRAY_COMPATIBLE, which lost the device at the
logo (issue #5). 3D BC textures no longer get block views: draws into a level go
to an uncompressed 2D array stand-in that is copied back at the pass end
(TOTK_BLOCK_VIEWS_3D=1 restores the old path).
Parts the recorder thread recorded and the submitting thread ended turned the
scene green, then white, on the same driver once a submission was split. The
recorder now writes the closing breadcrumb and ends the part itself
(TOTK_REC_END=0 restores the old split). The recorder stays off on AMD by default.
Based on the patch Pelipooper posted in issue #5; stand-ins extended to every
mip level.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
DLAA runs DLSS at the scene's own size on the R11G11B10F light target, right before the bloom chain's first pass,
so bloom, post and HUD read the anti-aliased picture. NGX is loaded from the driver's NGX core at run time; no NVIDIA
SDK code is compiled in, and nvngx_dlss.dll goes next to totk.exe. The scene's draws get a Halton(2,3) viewport
jitter that steps after each DLAA run; camera motion vectors come from the scene depth reprojected through this and
last frame's view-projection of the scene camera block (c4), read from the uniform snapshot. One DLSS feature per
scene size keeps dynamic resolution from stalling. dlaa and fxaa switch live from the settings menu; fxaa skips the
draw of the game's FXAA pass.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The README is a front page now: a general status, a short feature list, install steps from a release, credits as a
list of links that points to THIRD_PARTY_NOTICES.md, the build steps last. The licence table moved into the notices.
The build steps take the game version as <ver>; 1.4.3 is the primary version in the architecture doc, which also
gains the zstd host decoder, the settings table and menu, spin gates, the uniform snapshot and the resolution patches.
Controls list F1, F10, F11 and the menu keys; the tester guide and CONTRIBUTING point to logs\totk.log.
THIRD_PARTY_NOTICES.md: the four code rows that sat in the installer table move to the main table, the zstd rows
cover ov_zstd.c and the release package, the MacNativeGames resolution commit is given in full, the NVN proc list and
the compiler runtime of a source build are listed.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Every lifted instruction read and wrote c->x[n] and c->sp, so each register passed from one guest instruction to the
next went through a store and a load, and clang could not keep it in a host register across a guest store.
recomp/regs.py now copies the six most used X registers and SP of a function into locals at its entry. A forward pass
over the function's flow tracks which locals changed since the last sync, and only those are stored back before a
call, an SVC, a trap, a return or a tail exit. After an SVC every local reloads; after a call only X0-X18 and X30,
since AAPCS64 has the callee preserve X19-X29 and SP. TotK does not break that: main and subsdk0 import neither
longjmp nor the unwinder, sdk's have no direct callers, and the runtime writes no register above X3 except X30.
gen.py --no-callee-saved-trust reloads them too, --reg-locals sets the count. Functions with an unresolved computed br
keep their registers in the Cpu, as they keep NZCV.
All registers in locals was slower than none: clang spills them to the stack and the syncs stay. Over 300 hot
functions, 4-6 locals gave the fewest instructions and memory operands.
1.4.3 .text 299 -> 266 MiB. Fight bench (bench-fight2-2026-10-27b, frames 5400-7500, uncapped): 11.30 and 11.92 ms vs
13.5-13.9 on main; frames 2400-5300 11.24 and 11.36 vs 13.25. Without the callee-saved trust 12.58 ms.
tests/diff/func.py: 0 failing on 1.4.3 (889 functions, 583 with calls) and 1.2.1 (810); a plan with no spills fails
at once. Probes kernel, vkexec, nvn-tex and shader pass in both versions.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
docs/building.md merges the two toolchain docs and the README build steps, and lists the developer checks. The
Maxwell reference moves to docs/maxwell.md. architecture.md loses the milestone table, controls.md describes timed
script lines and input recording, and the tester guide includes shader preparation.
The agent skills, hooks, playbook, backlog and the study notes on upstream projects are the maintainer's local setup:
.claude/, notes/ and CLAUDE.local.md are ignored now, and tools/worktree.py links them into task worktrees. AGENTS.md
keeps the project rules.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The README now names the three test machines, the installer, remapping and the mouse camera, and lists the open bugs. The backlog drops the dated diary, finished steps and local paths and keeps every open item with its evidence. Citations into our code name functions instead of line numbers that had drifted, build/ notes are no longer cited, and the toolchain doc lists opus and libvpx.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
