[dpadr]

What and why

Symptom. Creating texture views (newTextureViewWithPixelFormat) was the largest single cost on Ocarina of Time's (Switch 2) submit thread. The view cache hit, yet the game made about 330 views a frame in Kokiri Forest, and about 310 of them were the same views made again.

Cause. The view cache (vc_get / vc_put, Texture views cached by texture and view parameters) kept views only for live textures.

• A texture finalized while one of its IDs is still registered resolves through g_ghost.
• vc_set_for refused that texture's set, because nothing would have dropped it later.
• So every submission that read the ID made a transient view, which treg_finish_submission released at the end of the submission, and the next submission made it again.
• OoT has about 37 submissions a frame.

Change.

• A finalized texture that g_ghost still holds keeps its view set, marked as a finalized texture's.
• Once a frame, vc_ghost_sweep, called from tex_by_id's slow path under g_rmu, drops the sets of serials that g_ghost has let go.
  • The owner evicts idle ghost entries under g_smu (own_ghost_trim), which can't take g_rmu, so the eviction itself can't drop the set.
  • Both checks look at the ghost table through a new owner function, own_ghost_has / own_ghost_has_locked: a look that is not a use, so a cached view never keeps its serial in the table (Finalized textures in use stay in their table: no 100–490 ms frames at a streamed transition on 0400486024DEC000 #2389 keeps entries by use). Every tex_by_id lookup still resolves the ID's texture, which is a use, so a finalized texture the game reads stays, and its set with it.
  • The views hold their texture only as long as g_ghost already does, plus up to a frame.
• DM_NVN_VC_KEEP: on by default; 0 turns it off, and ab alternates it with the DM_AB phases for an in-run A/B.

Why on by default. This is general host code. It changes no translated output, only whether an identical Metal view is made again. Each kept set lives no longer than its ghost entry (plus up to a frame), and all sets together are bounded by VC_MAX, and each set is dropped by the same paths as before (the texture's pool finalized, VC_MAX) plus the sweep. With 4 slots per texture as before, OoT showed no evictions (0.0 a frame), so the slot count is unchanged.

Relationship to #2260 (open, roandegraaf: views cached by the Metal texture, behind this cache). The two fix different misses of the same cache, and they are complementary:

• nvn/views: cache texture views by Metal texture behind the serial cache #2260: render targets made on new texture objects every frame over storage that stays. The serial changes, so the cache by texture object never hits. Measured there: 77 views a frame in a Hyrule Field view on an M4 Pro.
• This change: a finalized texture that a still-registered ID resolves through g_ghost. Its serial is stable, but vc_set_for refused to keep its set, so a transient view was made every submission. Measured here: about 310 of the 330 views a frame in Kokiri Forest.
• Where they overlap: nvn/views: cache texture views by Metal texture behind the serial cache #2260's second cache would also catch this case for textures the GPU writes. It doesn't cover textures uploaded from guest memory (view_pkg), which this change does, because nvn/views: cache texture views by Metal texture behind the serial cache #2260 leaves those out on purpose. This change also fixes the cause where it lies, the first cache's refusal, rather than adding a second lookup and lock per view.
• With both merged: this cache answers first, and nvn/views: cache texture views by Metal texture behind the serial cache #2260's catches new texture objects. Our cut8 line carries the two together this way (vc_get, then vb_get when !view_pkg; vb_put after vc_put). In code they merge without conflict: nvn/views: cache texture views by Metal texture behind the serial cache #2260 onto this branch conflicts only in dm/gfx/tests/Makefile, as it does onto main itself.
• Not measured: how much of this change's −1.72 M cycles remains on top of nvn/views: cache texture views by Metal texture behind the serial cache #2260. That needs an A/B of this switch (DM_NVN_VC_KEEP=ab) on a host with nvn/views: cache texture views by Metal texture behind the serial cache #2260. It will be reported here when our cut8 line runs it.

Reference entry: Texture views re-made for finalized textures every submission; symptom index regenerated; a line under OoT's "Found on this game".

Checked

• Measurement: in-run A/B on Ocarina of Time (0400486024DEC000, v131072, Switch 2).

  • Setup:

    • the Kokiri Forest route, replayed from a pinned save, to frame 12,000;
    • DM_AB=240, so phases of 240 frames alternating off and on; 21 + 21 phases from frame 1,800;
    • handheld full resolution (1440×810), 60 fps target;
    • each on-phase compared with the mean of its two off-neighbours: 20 pairs, median with a bootstrap 95 % interval.

  • Host: the same change on our cut4 line (these numbers were measured before the rebases onto main b21eb3f and then 0c23e0b, where the serial tables moved to nvn_owner.m and Finalized textures in use stay in their table: no 100–490 ms frames at a streamed transition on 0400486024DEC000 #2389 changed how long the ghost table keeps entries; the view-cache logic is the same. A fresh in-run A/B on current main follows once our main reference build reaches that chain). Its other switch, 16 slots a texture, never came into play: 0.0 evictions a frame with the switch off.

  • Results:

    	off → on	B − A [95 %]
    submit-thread cycles a frame	27.89 → 25.83 M	−1.72 M [−1.91, −1.49] (−6 %)
    submit-thread instructions a frame	61.77 → 56.59 M	−5.37 M [−5.65, −5.06]
    views made a frame	328–347 → 38.4–38.9 (about 290–310 of them for finalized textures)
    views reused a frame	87 → 366–414
    one view	about 15,400 instructions, 5,600–9,000 cycles
    frame time p50		−0.17 ms [−0.46, +0.02] (noise)
    GPU p50		+0.28 ms [+0.16, +0.43]
    attachment traffic and passes		unchanged

    The views made with the change on (about 37 a frame) are new textures' first views, which no cache can avoid.

  • Frame time: the A/B ran mostly GPU-bound, with the CPU clock varying from 1.6 to 2.6 GHz over the run, so frame p50 moved within noise. The result is stated in cycles and instructions, which don't depend on the clock.

  • Why the cycles still matter. Burn controls on the same Mac and route added a fixed amount of submit-thread work (3 M cycles spun at each frame's first submission, in alternating DM_AB phases):

    • at about 3 GHz, about 95 % of the extra work is hidden behind the GPU;
    • at about 2.1 GHz (background load, or heat on a fanless M2) it lands in full, at about +0.57 ms a frame per M cycles.

    The M2 Air spends long stretches of play at that lower clock, so −1.72 M cycles is about −1 ms a frame there.

  • GPU p50: the +0.28 ms is small and has no identified cause. The change encodes the same views and the same draws, and per-pass GPU times (DM_NVN_GPUPROF) are within noise.

• Device: MacBook Air M2, 16 GB, macOS 27.0.
• regress.py impact origin/main..HEAD (3fd81cd0 on main 0c23e0b):
  • affected: Breath of the Wild, Pokémon Scarlet, Tears of the Kingdom (texture finalize / register / pool paths);
  • not affected: Hades;
  • no usage manifest: 159 profiles, OoT among them.
  • None of the three affected games is on this machine.
• regress.py check --games: not run. The local NVN games with Mac builds (Animal Well 010020D01AD24000, Mina 0100DCD01F306000) have shader packages split before packages carried their shader keys, and main's f7a5452 (Ocarina of Time (0400486024DEC000) black screen with sound on c78d7375 / chain 89f44f9b6bb0: the present pass pairs VS a5b1bd74e47458d7 (writes loc0 only) with FS 29e3c9dd92b8a571 (reads loc1/loc2) #1841) refuses them, so the check stopped before any comparison, on the baseline and this branch alike. No regression check was done for this change.
• Tests:
  • On 3fd81cd0 (main 0c23e0b; M2, macOS 27.0). The PR head 4e5750d is rebased onto main 596d719: it adds the switch's row to docs/env_switches.tsv and keeps nvn-mtl: write image buffer textures below 16-byte alignment through a shadow #1399's new tbv fields in the view-set struct beside the ghost flag. On 4e5750d: make dmhost, t_nvn 311 checks and t_serial_owner 176, 0 failed. The full run: t_nvn 311 checks, 0 failed (also with DM_NVN_VC_KEEP=0); t_serial_owner 176/0; t_rt_lifetime 9/0; t_queue_lifetime 38/0; t_cpu_tex 105/0; t_pool_notes 91/0; t_readback 218 cases, 0 failed.
  • dm/tools/tests/test_docs.py (6 tests) and test_env_switches.py OK on 600d3c7 (run with python3 -m unittest).
• Not checked:
  • iPhone;
  • Breath of the Wild, Tears of the Kingdom and Pokémon Scarlet (no local game files);
  • a long session for memory: the kept sets follow the ghost table's entries and VC_MAX, as above.

Docs

• The finding is in its docs/reference/rendering.md entry and OoT's note, and python3 dm/tools/docs_symptoms.py was run (the symptom index)
• A chain tool changed: no chain change
• No game files, keys or data extracted from a game in the change or the attachments

🤖 Generated with Claude Code

[seedds]

Landed on main as 9339e55, with you as co-author. Thank you: the diagnosis was right, and so was fixing it in the view cache.

What changed from this branch:

• Rebased onto current main. Main had dropped the tbv field from the view set.
• Texture-buffer rows stay out of a finalized texture's set. tbuf_as_2d also stores through vc_set_for, and with the branch as it was, a finalized texture's rows would have gone into that texture's own set instead of g_tb2_gone. g_tb2_gone is keyed by the memory the rows view, so Unreal Engine 5.4's descriptors over the same memory share one view (Yoshi and the Mysterious Book made one per bind before it). vc_set_for now takes a ghost_ok flag, and the rows path passes 0.
• The sweep runs at the commit. It ran on tex_by_id's slow path, so a frame where every ID took the fast path never swept, and a static scene could keep textures alive after the ghost table let them go. It now runs at the first submission commit of each frame, right after own_ghost_trim, and drops every released set in one pass (no cap of 64).
• The cost comment says 5,600–9,000 cycles a view, from your measurement, rather than "about 30 us".
• The view-cache log line now counts the finalized textures' sets.
• A new test, t_vc_ghost, covers views kept across submissions, the switch's 0 mode, rows kept out of the set, the sweep dropping and keeping sets, and finalizing the pool.

Checks: the gfx tests above, plus t_nvn, t_serial_owner, t_cpu_tex, t_pool_notes, t_tbuf2d and the lifetime and alias tests, all pass. regress.py check on Bastion and Return of the Obra Dinn showed no change in fps or frame times. Obra Dinn reaches this path (4 finalized textures' sets kept). Its intermittent GPU hang showed up on the baseline and the candidate alike over three runs each.

Not measured again: the OoT gain on current main. There are no OoT shader libraries on this Mac right now. Your DM_NVN_VC_KEEP=ab A/B on a current host, with or without #2260, would be welcome here.

[seedds]

A correction to my reply above: keeping a finalized texture's texture-buffer rows out of its set was wrong, and your branch had it right.

Measured on Yoshi and the Mysterious Book (M6, from an empty save to the opening dialogue): its menus read finalized textures' rows only, and g_tb2_gone misses on about a third of those binds. With the rows in the finalized texture's set, as you had them, the menus made 12 rows views instead of about 40,000.

Main has since moved to the cache keyed by Metal texture (#2542), which kept the live-only rule. 8d003e1 removes it, so a finalized texture's rows stay with it while the owner holds it. To frame 5,100, 114,091 binds made 40,308 rows views before; with the change, 169,774 made 788. You're credited as co-author there too.