Skip to content

An argument block whose only change is a uniform buffer is patched instead of encoded again - #1611

Closed
Esteban-V wants to merge 2 commits into
seedds:mainfrom
Esteban-V:perf/args-cbuf-patch
Closed

Esteban-V wants to merge 2 commits into
seedds:mainfrom
Esteban-V:perf/args-cbuf-patch

Conversation

@Esteban-V

@Esteban-V Esteban-V commented Nov 7, 2026 •

Copy link
Copy Markdown
Contributor

What and why

Binding a uniform buffer marked the stage's arguments dirty. The next draw then encoded the whole argument block again: every texture, sampler, image and storage slot, though only the CBUF slots had moved. Games that rebind a uniform buffer between most draws spend that time on the submit thread. Donkey Kong Bananza does about 7,100 full encodes a frame.

 OP_BIND_UBO
-  g_args_dirty[stage] = 1
+  g_args_ubo[stage] = 1           // its own flag

 encode_args_
   if block reusable and no UBO change   -> bind the old block (as before)
+  if block reusable and args_cbuf_only  -> copy the old block to a new arena slot,
+                                           write only its CBUF slots again (cbuf_slot), bind it
   otherwise                             -> full encode (CBUF slot code moved to cbuf_slot, shared)

args_cbuf_only holds for a shader whose block has CBUF slots and otherwise only bindings that do not depend on the bound buffers. A shader with any other binding kind keeps the full path, as do the resource check, a pass dump and stage 5. The per-frame TSV gains @args_patch.

The reuse idea and its first measurement come from #1290.

Checked

  • Tests:
    • make -C dm/host/tests GAME=040074A01BF12000 run: passes.
    • dm/gfx/tests (Metal): 108 of the run list pass, plus test_dmsh_pull and test_tbdr_budget.
    • t_nvn and t_gfx_suspend do not link (_dm_vi_frame_queued undefined; their rules omit t_host_stubs.c). Current main (822f724) fails the same way, so this change is not the cause, but those two tests did not run.
  • Games run: Donkey Kong Bananza 040074A01BF12000 v458752 (Switch 2 / NVN2).
    • scripts/bench.py with main and this branch as variants, 3 runs each, 80 s of a recorded route (mining tunnel, early game) from a fixed save, with a warm pipeline archive.
    • No [RED] lines; the screenshots are alike.
  • Devices and OS: M3 Pro, macOS 27.0.1.
  • regress.py impact main..HEAD names Breath of the Wild, Tears of the Kingdom and Pokémon Scarlet. I don't have those games, so regress.py check has not been run. Help from their owners would be welcome; that is why this PR is a draft.
  • lint_c.py not run yet.
  • Measurements, per frame (median over 3 runs):
main this branch
full argument encodes 7,094 1,489 (5,645 patched)
submit-thread instructions per draw 14.4k 13.6k (−6%)
submit-thread CPU per draw 1.18 µs 1.10 µs (−7%; the run ranges overlap)
GPU time p50 / p95 9.8 / 14.0 ms 9.3 / 12.0 ms
frame rate 60 60 (the game caps itself; this route holds 60 on both)

The gain should show in heavier scenes where the submit thread is the limit. I have not measured that yet.

Also measured, not part of this PR: enc_thread on for this game on the Mac lowers submit-thread CPU (−25%), but in 3 of 6 runs it gave stretches of 33 ms frames. Leaving it off on the Mac stays right.

Merge danger

Door: two-way. It changes no saved data and no front end; reverting the commit restores the old path.

Blast radius: every NVN game's draws. A mistake in the patched path would show as wrong uniform data in a draw (flicker, wrong materials). The full path remains for anything outside the allow-list.

@github-actions github-actions Bot added the nvn NVN on Metal and its tests (dm/gfx/nvn, dm/gfx/tests) label Nov 7, 2026
@Esteban-V
Esteban-V marked this pull request as ready for review November 7, 2026 02:53
@Esteban-V
Esteban-V force-pushed the perf/args-cbuf-patch branch 2 times, most recently from be68a6d to 0ebcd4a Compare November 7, 2026 18:14
@github-actions github-actions Bot added docs Documentation game: 040074A01BF12000 Donkey Kong Bananza labels Nov 7, 2026
cfryerdev pushed a commit to cfryerdev/nxnative that referenced this pull request Nov 8, 2026
…stead of encoded again (seedds#1611)

Binding a uniform buffer marked the stage's arguments dirty, so the next
draw re-encoded every texture, sampler, image and storage slot though
only the CBUF slots had moved. OP_BIND_UBO now sets its own flag, and
encode_args_ copies the reusable block to a new arena slot and writes
only its CBUF slots when nothing else about the block changed. Games
that rebind a uniform buffer between most draws spend that time on the
submit thread: Donkey Kong Bananza does about 7,100 full encodes a frame.
…stead of encoded again

Binding a uniform buffer marked the stage's arguments dirty, so the next draw encoded the whole argument block again: every texture, sampler, image and storage
slot, though only the CBUF slots had moved. Games that rebind a uniform buffer between most draws (Donkey Kong Bananza: about 7,100 full encodes a frame) spent
that on the submit thread. OP_BIND_UBO now sets its own flag (g_args_ubo). When nothing else is dirty and the shader's block reads nothing but plain CBUF slots
besides bindings that do not depend on the bound buffers (args_cbuf_only), the last block of the same pass is copied to a new arena slot and only its CBUF slots
are written again (cbuf_slot, shared with the full encode). A shader with any other binding kind, the resource check, a pass dump and stage 5 keep the full path.
The per-frame TSV gains @args_patch.

Measured with scripts/bench.py on Donkey Kong Bananza (040074A01BF12000, v458752), M3 Pro, 3 runs each, 80 s of a recorded route: full encodes 7,094 -> 1,489
a frame (5,645 patched), submit-thread instructions per draw 14.4k -> 13.6k (-6%), CPU per draw 1.18 -> 1.10 us, GPU p95 14.0 -> 12.0 ms, frame rate unchanged
(the game holds 60), no [RED] lines, screenshots alike. The reuse idea was measured first in issue seedds#1290.
…ffer moved

The mechanism the previous commit fixes, in docs/reference/frame-rate.md (Symptom, Cause, Fix, Found on), its line under Donkey Kong Bananza's Found on this game, and the symptom index from dm/tools/docs_symptoms.py.
@Esteban-V
Esteban-V force-pushed the perf/args-cbuf-patch branch from 6f13f1c to 72a0c68 Compare November 9, 2026 14:36
Fasen24-AI added a commit to Fasen24-AI/swordboiMacNative that referenced this pull request Nov 10, 2026
…uffer is patched instead of encoded again

Upstream pull requests applied in this commit (their authors' work, brought onto this tree with a three-way merge; the description is in each PR):
- seedds#1611 by Esteban-V (open): An argument block whose only change is a uniform buffer is patched instead of encoded again
Fasen24-AI added a commit to Fasen24-AI/swordboiMacNative that referenced this pull request Nov 10, 2026
seedds#1901 seedds#1459 seedds#1928 seedds#1942 seedds#1940 seedds#1952 seedds#1611 seedds#2065 seedds#2083 seedds#2008 seedds#2079 seedds#2022 seedds#2075 seedds#2077 seedds#2020 seedds#2021 onto main 04811a6

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014eD437mxrMnW2UwLZhpwc7

Upstream pull requests applied in this commit (their authors' work, brought onto this tree with a three-way merge; the description is in each PR):
- seedds#1459 by PromethOps (open): DM_UPSCALER=metalfx takes agl's agl_ndsr_vr.pck networks too, and a variant with no curve and no power is drawn as one colour space: Ocarina of Time's upscaler is MetalFX's
- seedds#1611 by Esteban-V (open): An argument block whose only change is a uniform buffer is patched instead of encoded again
- seedds#1774 by uncraftablexd (closed): Compute threads that exit before a barrier keep arriving at it, and every shader loop has a cap (GPU hang defences), chain change
- seedds#1824 by cocoman93 (open): Clamp texel fetches past a sampled 2D texture's edge: no hard edge in Ocarina of Time's mist
- seedds#1901 by FifteenPen (open): The game's compute dispatches with no game barrier between them run side by side (profile key dispatch_overlap, on for Ocarina of Time): Kokiri Forest GPU p50 15.63 → 14.76 ms
- seedds#1928 by FeReuss (open): Ocarina of Time: enc_thread on, the replay encodes on a thread of its own
- seedds#1929 by FeReuss (open): Unused border corrections are compiled out of pipelines that bind no sampler with a twin (function constant DMSH_BORDER_FC)
- seedds#1930 by FeReuss (open): A float add to storage memory with no result read is one native atomic add instead of a compare-and-swap loop
- seedds#1940 by uncraftablexd (open): A prewarm list's lines after its #@after_first_frame line are built after the first frame, in the background, instead of in the prepare step (issue seedds#1747)
- seedds#1942 by uncraftablexd (open): Frame step: late frames with the GPU idle do not step up, and a longer hold the GPU does not explain is probed
- seedds#1952 by AdyaGMD (open): Compute moves ahead of scene passes past occlusion queries and conditional rendering; clears wait across dispatches
- seedds#2008 by bquilty25 (open): nvn: reactive memory watchdog, 16-way view cache, and texture upload batching
- seedds#2020 by padsiwono (open): Ocarina of Time v131072: Output Native draws the full output size instead of the game's 80 % frame (`DM_OUTPUT`)
- seedds#2021 by padsiwono (open): Ocarina of Time v131072 renders at the launcher's Resolution (`DM_RENDER_SIZE`), docked
- seedds#2022 by sleepyeyedjoe (closed): Ocarina of Time: large models no longer go black for one frame twice, 4–5 frames apart, when the game streams new textures into them (a texture ID a shader has read keeps its read mark when it gets another texture)
- seedds#2030 by humanperzeus (open): A NaN colour at alpha 0 is returned as 0, as NVIDIA's blender takes a zero factor: Ocarina of Time's white clouds over the ferns are gone
- seedds#2035 by Know-It-All-Brother (open): The shader build runs as worker processes, and no shader waits for a batch (Ocarina of Time's cold Mac map: 3,002 s to 1,298 s)
- seedds#2065 by Raymon82777 (closed): A vertex library with layer entry points of its own gets bases for its main0 pairs: Ocarina of Time's 230 ms camera-turn hitch in Hyrule Field goes to 39 ms
- seedds#2075 by sleepyeyedjoe (closed): Ocarina of Time: a patch of scenery no longer draws dark for one frame when the game gives it a sharper texture (a pool texture the walk does not make holds a stand-in of its own colours until its first read)
- seedds#2077 by roandegraaf (closed): Ocarina of Time: fix the "plaid" terrain / missing texture tiles (GPU-drawn textures now reach the storage the game copies)
- seedds#2079 by uncraftablexd (open): Render pipelines that share a vertex function are taken from the archive or compiled one at a time: the AGX driver crashes in createVertexProgramVariant's completion block
- seedds#2083 by FifteenPen (closed): Ocarina of Time's prewarm list gets 41 more task / mesh pipelines from later play
Fasen24-AI added a commit to Fasen24-AI/swordboiMacNative that referenced this pull request Nov 10, 2026
… tree (issue seedds#2066)

The guard (26062f9) answers Paper Mario TTYD's read past a 16-byte binding. Ocarina of Time ran without it (prova 21);
with it every read of c3-c16 carries a compare (Bananza +20 % GPU, an Ocarina data point on an M1 in the issue) and shaders
with a cbsize binding lose the uniform-only argument patch (seedds#1611). Binaries, lock and chain header follow in the next commit.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014eD437mxrMnW2UwLZhpwc7

Upstream pull requests applied in this commit (their authors' work, brought onto this tree with a three-way merge; the description is in each PR):
- seedds#1611 by Esteban-V (open): An argument block whose only change is a uniform buffer is patched instead of encoded again
seedds added a commit that referenced this pull request Nov 10, 2026
…t is patched instead of encoded again: a uniform binding, or an inline update deferred over one, rewrites the uniform slots and their size table in a copy of the shader's block, and every texture, sampler, image and storage slot stays as it was (PR #1611)

- OP_BIND_UBO and ubd_dirty (a deferred inline update overlapping a bound uniform buffer, whose draws then read a shadow) set g_args_ubo instead of g_args_dirty. A reusable block of a shader that reads its uniform buffers only as uniforms (args_cbuf_only, an allow-list of binding kinds decided once per shader; handles or addresses read out of a uniform buffer keep the full encode) is copied to a new arena slot with only its uniform slots and size table written again. The resource check, a pass dump and stage 5 keep the full encode. The per-frame TSV gains @args_patch
- cbuf_slot is the one place a uniform slot's address comes from, for the full encode and the patch: the binding, a deferred update's shadow, ub_padded's zero-padded copy of a binding shorter than the shader's fixed-offset reads, or the zero bank. cbsize_table makes the slots' size table for both. So a patched block is the block a full encode would write, short bindings included (issue #1860, issue #2066)
- docs/reference/frame-rate.md: Argument blocks encoded again when only a uniform buffer moved; the Bananza note; symptom index regenerated

The PR's form (binding changes only, no size table) on Donkey Kong Bananza, M3 Pro, bench.py 3 runs each, an early-game route the submit thread does not limit: full argument encodes 7,094 -> 1,489 a frame (5,645 patched), submit-thread instructions per draw 14.4k -> 13.6k, 60 fps on both; the reuse was first measured in issue #1290. This form is not measured on Bananza, nor on Breath of the Wild, where the deferred updates matter most. Host builds with no new warnings; lint_c.py tidy has nothing above the baseline; test_docs passes. Regression (quick, against 7335436): NieR:Automata, same shaders, frames reached on both, no new RED; its 100 s screenshot differs (dHash 15, RGB 6.28) in the comm panel's animation frame and the clouds, the route's run-to-run noise. No route here binds a uniform slot shorter than its shader reads, so the padded path has not run in a game.

Co-authored-by: Esteban <31489995+Esteban-V@users.noreply.github.com>
@seedds

seedds commented Nov 10, 2026

Copy link
Copy Markdown
Owner

Thanks: landed as adaff73, with you as co-author. Your design and most of the code are there; the differences:

Checked: host build, lint_c.py tidy, test_docs, and a quick regression on NieR:Automata (same shaders and frames, no new red lines). Not measured: this form on Bananza. If you can, @args_enc / @args_patch and instructions per draw on a heavier scene (the Freezer Layer, where #2066 shows the submit thread at 10-12 ms a frame) would tell how much it brings, and whether the full encodes left are mostly texture rebinds.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

docs Documentation game: 040074A01BF12000 Donkey Kong Bananza nvn NVN on Metal and its tests (dm/gfx/nvn, dm/gfx/tests)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants