[ksolenk38ze]

Follow-up to #1444, rebased cleanly onto main (b2d46b86).

Most of the early bring-up from #1444 (EventFd, IAudioInManager, nn::ndve movie networks, BNSH task/mesh shaders, float atomics, ATOMG.CAS, textureGatherOffsets, RGBA8 image atomics, mem_map_limit on, tex_flush_upload / tex_dirty_upload, and the shader_map.tsv / shader_seen.tsv profiles) is now on main through recent commits. This PR carries the remaining renderer fixes from #1444 together with the fixes found while playing The Legend of Zelda: Ocarina of Time (0400486024DEC000, Switch 2 v131072) through all three child dungeons (Great Deku Tree, Dodongo's Cavern, Inside Jabu-Jabu's Belly), Hyrule Field, Market, Hyrule Castle, Kakariko Village, Death Mountain Trail, Zora's River / Domain / Fountain, the Temple of Time (adult timeline transition), the Graveyard, and completion of the first adult dungeon (Forest Temple, including the Poe Sisters and Phantom Ganon).

Picture fixes

• Mesh stage attribute layout (dm/gfx/tools/dmsh_meshstage.py, dm/gfx/nvn/dmsh_chain.h): Ampere mesh shaders store all vertex attribute blocks (v_blocks = ceil(max_v / 32) blocks of 32 vertices) first in stage memory, followed by all primitive attribute blocks (p_blocks = ceil(max_p / 32) blocks of 32 primitives). dmsh_meshstage.py previously interleaved one 32-vertex block and one 32-primitive block per block = idx >> 5, so whenever max_v > 32 (v_blocks > 1), primitive attributes (attr >= p_first) read and wrote vertex block 1 (v[32..63]). In the Forest Temple, the Poe Sisters and Phantom Ganon painting shaders (ee4ef51a4fddc28e and 83c0dbc51c5481e3, max_v = 128, max_p = 64) carry per-primitive brush-stroke colors in p0..p2; reading vertex block 1's screen-space positions as p0 produced solid green/magenta paintings. dmsh_meshstage.py now places all v_blocks before p_blocks, accounts for sph[0x35] bit 3 (PointSize) in v_slots, and handles ctl[0x5f] point (1) and line (2) topologies. Fixed and verified with unit tests (test_dmsh_meshstage.py, 28 tests) right after completing the Forest Temple; to be visually re-checked in the painting rooms on a revisit.
• Depth-read render pass split (dm/gfx/nvn/nvn_mtl.m): In fb_prepare, when a draw samples the currently attached depth target (R.rt.depth) in a fragment shader (prog_uses_tid) and an earlier draw in the same Metal render pass wrote depth (g_fb_dwrite), end the current pass before binding the draw. Without a pass boundary on Apple Silicon TBDR, translucent surfaces that sample scene depth for soft-depth fades (the Zora's Sapphire pedestal in Jabu-Jabu's Belly, translucent interior walls) read un-flushed tile depth and flickered with black blocks.
• Format-view image upgrades and NvImageHeap alias rebinding (dm/gfx/nvn/nvn_mtl.m): image_prepare now persists NVN_TEXTURE_FLAGS_IMAGE on g_treg[tid].t.d.flags when an image binding upgrades a texture and calls tex_upgrade_pfv before the render pass starts when an image view binds a format view (R32Uint over RGBA8Unorm_sRGB in agl_ndsr_vr). tex_upgrade also preserves NvImageHeap ownership on placement textures and rebinds matching g_by_serial, g_ghost, and g_alias views (tex_upgrade_alias_rebind) so dynamic-resolution scaling and volcanic rock / lava shaders do not sample stale textures or leave blocky mosaic tiles.
• BC1 / BC4 render-target redirection (dm/gfx/nvn/nvn_mtl.m): agl bakes sky and water reflection cubemap faces by attaching RGB_DXT1 (0x42) and RGTC1_UNORM (0x49) textures (flags 0x8 COMPRESSIBLE) as color targets. Since Metal cannot render directly into BC-compressed pixel formats, bcrt_attach redirects those attachments to an RGBA8Unorm / R8Unorm shadow texture and encodes the rendered blocks back into the guest pool / BC texture on rp_end (bc_encode_bc1, bc_encode_bc4).
• Mesh-to-fragment varying padding (dm/gfx/nvn/nvn_geometry.inc, dm/gfx/tools/shader_split.py): When a fragment shader reads a locnN input that its paired mesh shader (3a6340a04bf09797_b, a203347bb7bdbd03_b) omits, mtk_pad_mesh_fn and var_pairs pad the missing varying with float4(0, 0, 0, 1) so MTL4Compiler does not abort pipeline compilation.
• Bordered terrain tile detection (dm/gfx/nvn/nvn_mtl.m): tera allocates 260x260 (256 + 2*2 border) and 68x68 (64 + 2*2 border) R16Unorm, RGBA8Unorm, and R8Unorm terrain heightmap, normal, and blend-weight tiles in the same 2.43 GB pool as GPU render targets. Guarding attach()'s g_pool_gpu mark with g_in_rt_attach and recognizing 260x260 / 68x68 bordered tiles in tex_cpu_content preserves CPU terrain uploads across Kakariko Village and Death Mountain.

Frame rate, pipeline archives, and memory

• Separate ArchEpoch flush states for pulling vs vertex-layout bases (dm/gfx/nvn/nvn_mtl.m): pso_save_base shared a single g_base_epoch between pulling bases (vd == 0, intended for p%05d.mtl4a) and vertex-layout bases (vd != 0, %05d.mtl4a). Whichever type hit the 32-pipeline batch threshold or 2-second timer flushed both into one file, so pulling bases landed in %05d.mtl4a and were discarded whenever pso_compact_dir compacted %05d.mtl4a with include_pull = NO. Splitting g_base_epoch and g_pull_epoch (ep->kind) keeps every pulling base in p%05d.mtl4a. pso_prebuild also probes up to 8 entries from prebuilt.tsv against g_pull_arch4 (PRE_PROBE) so an older pso_archive whose pulling bases were compacted away automatically rebuilds them on launch.
• Compacted archive ordering and validation (dm/gfx/nvn/nvn_mtl.m): pso4_init places compacted shards (>= 256 MB) at the head of g_arch4 and keeps them out of g_compact_files so they are checked first and not re-copied on every compaction pass, and arch_entries_ok checks _MTL4Archive internal entry offsets before loading an archive.
• Sub-command-buffer (OP_CALL) lookahead and pulling-base caching (dm/gfx/nvn/nvn_mtl.m): shader_prefetch_rest and pso_predict_rest_ now copy the OP_CALL return stack (cur.ret / cur.rdepth) when starting lookahead from inside a called sub-list so prefetch and PSO prediction continue across sub-list returns into the rest of the frame. hybrid_get_ex also caches the reusable vd == 0 pulling base when compiling a specialized vd != 0 pipeline on an uncached miss, and mtk_pso builds task/mesh pipelines on QOS_CLASS_USER_INITIATED.
• Retired texture descriptors and bindless pool stability (dm/gfx/nvn/nvn_mtl.m, dm/gfx/nvn/nvn_dirty.h): treg_tex and tex_mtl_ skip materializing or ghosting an unread retired GPU texture when a live alias already owns its (pool, off) range (alias_overlaps), and alias_take_over indexes g_by_serial by (pool, page) and marks retired g_treg slots over taken storage gone. This avoids a cascade of pool_gpu bindless table rebuilds and res_commit spikes in Hyrule Field, Market, and Kakariko Village.
• Batched sparse-texture uploads and 16 MB upload buffer cache (dm/gfx/nvn/nvn_mtl.m): pkg_upload_ gathers sparse-pool textures (< 64 MB) into a batch-retained MTLBuffer for the batched GPU deswizzle path instead of forcing synchronous up_flush() mid-cutscene, and up_big_src caches up to four 16 MB (BIG_S) upload buffers in g_up_big_src.
• Static pool_gpu patch arrays (dm/gfx/nvn/nvn_mtl.m): pool_gpu's patch scratch arrays (ids, ser_list, vals, 1.96 MB total) are now static under g_rmu instead of living on the 1 MB dm_bigstack.
• Game profile and manifest (dm/games/0400486024DEC000/): Increased mem_alias to 0x400000000 (16 GB) for multi-dungeon virtual pool churn, added the v0 base build entry in game.tsv, bridged nn::hid::IsOunceVibrationDeviceMounted in hle_hid.c (called when playing Ocarina notes), and updated pso_manifest.tsv to 40,154 observed (vs, fs, rt) triplets through the Forest Temple and Phantom Ganon.

Upgrade / cache note for existing users

• DMSH_CHAIN is bumped to 8b11d946d5b4 for the mesh stage layout fix, so existing shader caches rebuild the 8 affected mesh shaders automatically.
• Existing pso_archive directories do not need to be deleted manually: pso_prebuild now probes prebuilt.tsv against g_pull_arch4 (PRE_PROBE) and automatically regenerates p*.mtl4a if an older compaction run had dropped the pulling bases.

Open observations for follow-up

• At night in Hyrule Field and Kakariko Village, scene lighting looks brighter than expected (making night and day harder to tell apart), and a thin dark outline can appear on certain silhouettes at night (such as Link's shield) alongside softer texture filtering. We will investigate the night-time environment / filter pass next.

Verification

• In-game playthrough on macOS (Apple M5 Pro, v131072) through Kokiri Forest, Great Deku Tree, Hyrule Field, Market, Hyrule Castle, Kakariko Village, Death Mountain Trail, Dodongo's Cavern, Zora's River / Domain / Fountain, Inside Jabu-Jabu's Belly, Temple of Time, Graveyard, and the Forest Temple (Poe Sisters & Phantom Ganon).
• Python lint and unit tests: lint_python.py --against origin/main (0 findings), all 30 test suites in dm/gfx/tests/test_*.py (including test_dmsh_meshstage.py 28/28), dm/tools/tests/test_*.py (test_docs.py, test_game_profile.py, test_env_switches.py, test_image_atomic_bounds.py, test_txq_type.py).
• C / Metal and host tests: make -C dm/host/tests GAME=010015100B514000 run, GAME=010015100B514000 python3 dm/ios/tools/compile_check.py (261 files, 0 failed), and dm/gfx/tests (t_nvn 243, t_gfx_suspend, t_cpu_tex --metal 68, t_upgrade_alias 14, t_feedback 194, t_lookahead_bindless 22, t_pool_notes 81, t_pso_pending 52, t_pso_skey, t_refl 43).

[bettterlabs]

Built this on a Mac mini (M4, 16 GB, macOS 27.2) from a v131072 NUP: b2d46b86 + #1590 with #1544, #1390, #1543, #1557, #1556, #1575 and #1522. Two things that come from #1590 itself:

1. The NSP script stops at the shader table check

[RED] the split shader tables differ from game profile 0400486024DEC000's:
shader_pairs.tsv: 0 row(s) only in the profile, 1,284 only in the split

• Cause: var_pairs in shader_split.py now also pairs mesh keys with pixel keys, but dm/games/0400486024DEC000/shader_pairs.tsv was not split again. The Legend of Zelda: Ocarina of Time (0400486024DEC000): renderer, shader and pipeline archive fixes through the Forest Temple #1590's commit is the only change to shader_split.py in that tree.
• All 1,284 extra rows start with a mesh-stage key, and no row is removed.
• shader_map.tsv, shader_facts.tsv and pso_pairs.tsv split identical to the profile's, so these are the files the profile registers.
• With the split's shader_pairs.tsv committed to the profile, the build gets past the check (✓ shader split (2:21): 42,848 shaders).

2. t_pso_bundle: 2 of 58 checks fail on the PR head (4e6d5419) alone

make -C dm/gfx/tests GAME=0400486024DEC000 t_pso_bundle:

other pairs: two bases from the bundle: expected 2, got 3
other pairs: one compiled: expected 1, got 0

It's not in the PR's test list. On b2d46b86 + #1544, #1390 and #1543 the same test passes 58/58.

If #1390 lands too

tera_tile in tex_cpu_content makes two of #1390's t_cpu_tex checks fail: "the one over it is not" and "a write elsewhere in the pool leaves it taken". It takes a 260×260 texture as CPU content even over storage the GPU wrote. Leaving the exception out and keeping #1390's per-range rule passes t_cpu_tex 77/77.

Tests on the whole stack: t_nvn 243/0, t_cpu_tex --metal 77/0, t_pso_archive 102/0, t_pso_warm 99/0, t_upgrade_alias 20/0, t_image_alias 332/0, t_copy_alias 126/0. Python: test_dmsh_meshstage.py (with #1575's memory rule combined), test_pso_offline.py, test_docs.py and test_game_profile.py OK.

Not checked: the cause of the t_pso_bundle failures; t_pso_bundle on bare b2d46b86; the game itself on this build (the shaders are still building).

[seedds]

A note for this PR: e2b76d4 (from #1604) takes uncompressed textures from their storage unless the GPU wrote that storage, decided by address range rather than by pool. That covers Ocarina of Time's 260x260 and 68x68 terrain textures for any size and any game, so this PR's size rule for them is no longer needed. Please drop it when you rebase.

[ksolenk38ze]

Thank you for the detailed code review and for landing #1604!

All three review items have been addressed, and the branch has been rebased onto main (e2b76d4e) with tera_tile dropped in favor of the per-range mtl_tex_gpu_written tracking from #1604 (85599141 + 708f16ef):

1. pso_offline.py (dm/gfx/tools/pso_offline.py)

   • Simplified the two-stage library cache (by_msl) so the pulling and plain variants live side by side in the same dictionary (by_msl[(vs, fs, pulling)]), compiled on demand by get_pair(vs, fs, pulling).
   • Kept the base archive copy only between the two rounds of a row that mixes pulling (vc > 0) and vertexless (vc == 0) variants (need_base_copy = bool(pull_rows and plain_rows)), removing the redundant copy and second serialize_archive pass when all rows of a shader pair take the same path.
   • Added unit coverage in dm/gfx/tests/t_pso_bundle.m (mixed vc > 0 + vc == 0 rows for the same (vs, fs) pair sharing a vertex-pulling vs in pso_offline.py --append).

2. nvn_refl.m (dm/gfx/nvn/nvn_refl.m)

   • Replaced the two separate const char *has_pull / const char *has_root scans with a single line-by-line scan over the MSL source (refl_msl_flags) that matches actual identifier tokens (_pull followed by ( or [, dm_root followed by () while skipping // comments.

3. hle_nvn.c (dm/gfx/nvn/hle_nvn.c)

   • Fixed the indentation in nvnMemoryPoolFinalize (dm/gfx/nvn/hle_nvn.c:266).

[seedds]

The mesh stage attribute layout from this PR landed as 3ccb7da (chain 8900605baef9), with you as co-author. Thank you.

What I checked. The guest's own address arithmetic confirms it. In ee4ef51a4fddc28e, vertex v is written at (v/32)*768 + (v%32)*4 and primitive p at 3072 + (p/32)*512 + (p%32)*4: all the vertex blocks first, then the primitive blocks. The point mesh 3a6340a04bf09797 writes its point size at component 0 and its position at components 1 to 4. Ocarina's 5 mesh shaders with control +0x5f = 1 are exactly the 5 that write a point size. All 500 of Ocarina's mesh shaders build on the new chain. I haven't seen the paintings in the game myself.

One difference. The index area keeps #1575's rule, reserved for every primitive block: 4 + verts * ceil(max_p/32) * 32. This PR's verts * max_p would have brought back the overflow #1575 fixed.

The rest of this PR. It can't land as one change. The description and the code differ: the BC1/BC4 encoding, the alias rebinding in tex_upgrade and the 16 MB upload cache are described but not in the code. Meanwhile the code has changes the description doesn't mention (a GPU watchdog that is on by default, an indirect dispatch clamp for PRAGMATA, DM_SHADER_CHAIN, pkg_copy_absorb, null guards in the nvnBuffer* getters). Please send the remaining fixes as separate PRs on current main, each with its symptom and a measurement:

• Depth read after a depth write in the same pass: a good general fix. Please explain why reads through the texture pool are left out of the split, and give its cost in g_fb_split. I may take this one next.
• Missing mesh varyings (mtk_pad_mesh_fn): don't pad. The two foliage mesh shaders it was found on draw points and output no generic attribute at all. Their pixel shader (2a7c48d595feaaeb) uses locn5.xy as a texture coordinate into an alpha mask and discards on it. So padding with (0,0,0,1) would give every fragment the same texel. This looks like point-sprite coordinate replacement (a generic attribute replaced by the point coordinate), which the host doesn't implement yet. That's the fix to find, offline rather than by retrying on Metal's error text.
• Pipeline archive epochs, compaction ordering, OP_CALL lookahead, pulling-base caching, retired-texture alias_overlaps, batched sparse uploads: these need numbers (before and after) and a rebase over Uncompressed textures are taken from their storage unless the GPU wrote that storage, not their pool: Ocarina of Time's ground no longer opens in holes after walking a distance #1604, GPU copies into a pool chunk get lost if its pages were write-protected (LEGO Star Wars text garbled) #1591 and Compute pipelines in the pipeline archives: compiled offline for every compute shader of the map, and captured into the device's archive when the bundle lacks one #1307.
• pool_gpu arrays moved off the stack: if 1.96 MB was really on a 1 MB stack, a crash log would show it.
• GPU watchdog, dispatch clamp, DM_SHADER_CHAIN, null guards: not in this form. The watchdog changes behaviour for every game (see Ocarina of Time (0400486024DEC000 v131072, Mac): GPU hang about 10 minutes into play takes WindowServer down #1326). The clamp hides bad counts whose cause is still open. DM_SHADER_CHAIN bypasses the rule that the host loads only its own chain's libraries.
• Profile: mem_alias 16 GB needs the log that shows the alias region running out. The v0 build row needs a v0 bring-up. The pso_manifest.tsv update is welcome once it's regenerated on current main.

[seedds]

A correction to my last comment: padding the missing mesh varyings is the right fix, and it landed as 5e344a8 (chain 5616dbb62ec3), with you as co-author. I was wrong to suggest point-sprite coordinate replacement:

• The pixel shaders' input maps read generic attribute 5, not a fixed-function texture coordinate (the only kind point-sprite replacement covers) and not the point coordinate (0x2e0).
• NVN has no point-sprite function, only nvnCommandBufferSetPointSize.
• The same foliage file's triangle mesh shaders also leave locations 2, 8 and 9 unwritten that their pixel shaders read.

So it's the same case as vs_pad: the console gives an unwritten input a default (0,0,0,1), and Metal needs an explicit output.

How it landed. Your var_pairs change is in, with Ocarina's shader_pairs.tsv split again (the same 1,284 rows). The padding happens offline in dmsh_meshstage.to_stage, from the pixel partners' inputs, instead of at run time on Metal's error text. Both pipeline prebuilds (pso_offline.plan and the host's pre_desc) skip mesh pairs, which are built at the draw.

Results. Of the 1,284 mesh pairs, 31 needed padding, and Metal now builds 1,283 of the pipelines. The one left is 626fbf48041cb82b + c5eb985e769e317f: 160 vertices of 14 outputs is 35,840 bytes, over Metal's 32 KB mesh limit. I haven't checked the foliage in the game.

[seedds]

Follow-up: the last refused foliage pair (626fbf48041cb82b + c5eb985e769e317f, over Metal's 32 KB mesh size) builds now, as of d777f0a (chain 3ee493b2c3a4).

Cause. Mesh outputs were declared as a full float4 for every attribute, but this mesh shader writes only 26 components per vertex.

Fix. Each output is now declared only as wide as its paired pixel shaders can see: the components the mesh writes, plus a w they read but it doesn't write. On the GPU, Metal fills a narrower output's missing components with 0, which is the console's default for x, y and z, so the pixel shaders read the same values. That mesh comes to 28,160 bytes, and all 1,284 of Ocarina's mesh pairs build their pipelines.

[ksolenk38ze]

Thank you @seedds for landing the mesh stage attribute layout (3ccb7da0), the mesh output padding (5e344a87), and the narrowed mesh output layout (d777f0a3)!

As requested, we have rebased onto current main (bd979ced), dropped the items covered by main or excluded in your review, and split the remaining changes into focused PRs:

• nvn: implement nvnCommandBufferWaitEvent and per-queue command parking #1728: nvn: implement nvnCommandBufferWaitEvent and per-queue command parking
• nvn: pre-pass indirect draw conversion and indirect dispatch/mesh clamp #1729: nvn: pre-pass indirect draw conversion and indirect dispatch/mesh clamp
• nvn: merge contiguous gmem pool runs and harden MTL4Archive pipeline loading #1730: nvn: merge contiguous gmem pool runs and harden MTL4Archive pipeline loading
• nvn: preserve texture upgrades, BC render targets, and retired descriptor bounds #1731: nvn: preserve texture upgrades, BC render targets, and retired descriptor bounds
• games/0400486024DEC000: update Ocarina of Time pso_manifest.tsv, shader_seen.tsv and notes #1732: games/0400486024DEC000: update Ocarina of Time pso_manifest.tsv and notes

Closing #1590 in favor of the split PRs above.