[PromethOps]

What and why

Engines place their transient render targets over each other in a CPU_NO_ACCESS pool, as a frame graph does: NVN gives them that pool's memory, whatever their number. The host makes a private Metal texture for each (pool, offset, description), so every description takes memory of its own. Ocarina of Time's note on main lists the case that remains as open:

render targets that move in the game's pool and change size with its dynamic resolution (1580 → 1579 → 1578 …) get a new Metal texture each time, about 2 GB added to the residency set per 300 frames.

pool_heap_texture (nvn_mtl.m) gives each CPU_NO_ACCESS pool, up to 1 GB, one placement heap. Each of the pool's render targets (COMPRESSIBLE, not sparse, linear or display) is placed at its pool offset scaled by 1.25, since a Metal texture can be a little larger than NVN's layout of it.

• Ranges apart in the pool stay apart in the heap; ranges that overlap there may overlap here, as the memory is one on NVN. Memory then stays bounded by about 1.25 times the pool, however many sizes the targets take.
• A texture that does not fit its scaled range keeps an allocation of its own.
• Heap memory no texture has covered yet takes the texture's initial content (tex_init_fill, or zeros). Over memory another texture has covered, a new texture inherits what is there and nothing is written, as on NVN.
• An image placed there is never taken as a resolution family's heap by image_texture (pool_heap flag, jonpage0's fix from the review).
• DM_NVN_POOL_HEAP=0 turns it off; restop prints the heaps.

Measured

	Pool heap	Before main's Ocarina changes	On main 75c1a8c, fixed scene
CPU_NO_ACCESS render targets	—	3,001 MB in 804 MB of pools	3 placed, in 3 heaps of 480 MB
residency set	off	8–10 GB	5,201–5,247 MB
residency set	on	6–7 GB (62 heaps, 671 MB)	5,158–5,187 MB

Main's own Ocarina changes have since removed most of what this saved: on main, in a fixed Kokiri Forest scene, the gain is about 1 %. PucaVaz's runs on main (M4, 24 GB) found the same, with no errors. The case it is still meant for, the targets that resize with the dynamic resolution, was not exercised by these scenes (the resolution stayed put), so it is not demonstrated here. I am leaving it to the maintainer whether the general change is worth carrying for that case and for other engines' frame graphs.

Checked

• Games run, with title ID and version: The Legend of Zelda: Ocarina of Time (Switch 2, 0400486024DEC000, update v131072, SDK 22.2.8), on main 75c1a8c with this PR, Shared textures no live object resolves to are retired when GPU memory runs short: Ocarina of Time no longer freezes after the talk with Saria #1455 and 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 #1459: Kokiri Forest fixed scene, heap on and off, restop at frames 1500 and 2400; earlier sessions of 5 to 15 minutes (Saria, the Great Deku Tree in and out) on the pre-main branch. No GPU errors, no visual difference on screenshots.
• Devices and OS: MacBook Pro M5 Pro, 24 GB, macOS 27.2.
• make -C dm/gfx/tests GAME=<id> check_t_pool_heap: 24 checks with direct and deferred encoding, 3 with DM_NVN_POOL_HEAP=0. It covers:
  • descriptions over one storage share the heap;
  • storage apart stays apart, and its writes do not reach each other;
  • a texture made over used memory leaves another's pixels as they are;
  • a late image description keeps its scaled offset (jonpage0's case);
  • textures without COMPRESSIBLE, sparse textures and CPU-visible pools stay apart;
  • the heap leaves the residency set with the pool.
• t_image_alias (329). Every gfx test builds. The failing checks (host unit tests, tool tests, sanitizers, clang-tidy) fail the same way on main 75c1a8c.
• Not checked: scripts/regress.py check --games on other games; only Ocarina of Time was available here.

Docs

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

[jonpage0]

Applied this on today's main (671c68e) for an Ocarina of Time rebase; the seven files apply as they are. One interaction with main's image-family heaps showed up in a unit test, so passing it on with the fix I used:

image_texture's same-storage lookup (g_alias entries with the same pool, offset and format, owner from g_image_heap_owner_key) takes any owner whose heap is big enough as the family heap. An NvPoolHeap is an NvImageHeap whose heap is the whole pool (up to 1 GB), so once a COMPRESSIBLE|IMAGE texture has been placed in the pool heap, a later description over the same storage is taken as a member of an offset-zero family and lands at heap offset 0, over whatever the pool placed there. The fix: a pool_heap flag on NvImageHeap, set when an NvPoolHeap is made, and image_texture returns to the pool-placement path when the lookup finds a pool-heap owner, so the later description keeps its scaled pool offset:

@interface NvImageHeap : NSObject { @public id<MTLHeap> heap; int pool_heap; } @end
…
        NvImageHeap *o = objc_getAssociatedObject(other, &g_image_heap_owner_key);
        // Once this storage is placed in the pool heap, later descriptions must keep its scaled offset.
        if (o && o->pool_heap) { pthread_mutex_unlock(&g_smu); return nil; }
…
        if (heap) { h = [NvPoolHeap new]; h->heap = heap; h->pool_heap = 1; …

The case in t_pool_heap.m (a 512² COMPRESSIBLE|IMAGE at pool offset 24 MB, then a 256² description over the same storage): before the fix 23 checks, 2 failed ("late image descriptions retain their scaled pool offset", "late image writes do not reach separate pool storage"); after it 24 checks, 0 failed, and the PR's own checks are unchanged. With and without DM_NVN_POOL_HEAP the rest of the gfx tests pass here (t_image_alias 329, t_image_usage 44, t_cpu_tex 59, t_cpu_storage 38, t_pool_chunks 102, t_feedback 159, with and without DM_NVN_ENC_THREAD=1). Not yet run in the game; I will report the Kokiri walk when the rebuilt app is up. Diff available as a commit if you want it on the branch.

[PucaVaz]

Tested on main 75c1a8c, with #1455, #1332 and #1446 also applied, on an M4 MacBook with 24 GB, from a Kokiri Forest save at Link's house (handheld, upscale 2.0), in two scripted runs: 10 minutes in the house; and from a fresh load, out of the door, Saria's greeting and 10 minutes of walking around the house.

• 3 GPU-only pool heaps, 480 MB in all (64, 288 and 32 MB pools), 3 render targets placed, 0 kept apart.
• No GPU errors. The [RED] lines were the title movie's AV1 decoder, the partial library's notes and one texture type mismatch in the walk, which also appears with the heap off; none came from the pool heaps. Screenshots of the house, the door, Saria's greeting and the walk show nothing missing or garbled.
• Same binary with DM_NVN_POOL_HEAP=0 DM_NVN_ALIAS_RETIRE=0, one run on the same route: house frame p50 21.9 ms (22.1 with the heap), walk p50 24.7 ms (23.9), footprint up to 11.0 GB (11.5). On this Mac and route the render targets in GPU-only pools are a small part of the scene's memory (the residency set held 4.9 GB in the house, 1.9 GB of it textures, and 5.4 GB right after leaving it), so I see no memory difference from it here. One run each, no repeats.
• With jonpage0's pool_heap fix on top (t_pool_heap 19/19 in both encoding modes and 3/3 off, t_image_alias 329/329), a 9.5-minute run on the same save (60 s in the house, Saria's greeting, 3 minutes of walking): no GPU error, house 44.1 fps (frame p50 22.2 ms), walk 36.1 fps (p50 24.2 ms), footprint up to 11.6 GB.

[PromethOps]

Thank you both.

@jonpage0: your pool_heap fix is in (85be790), with your case added to t_pool_heap.m: a 512x512 COMPRESSIBLE|IMAGE at 24 MB, then a 256x256 description over it, checked for its scaled offset and for writes that stay out of separate storage. 24/24 checks in both encoding modes, 3/3 with DM_NVN_POOL_HEAP=0, t_image_alias 329/329, and every gfx test builds.

@PucaVaz: thanks for the runs. On today's main your residency set stays around 5 GB, and only 3 render targets were placed in 480 MB of pool heaps, so the gain I measured is not there in your scene. My numbers (3,001 MB of CPU_NO_ACCESS render targets in 804 MB of pools, residency 8–10 → 6–7 GB) were taken before main's Ocarina changes. On main the case left is the note's open item: render targets that move and resize with the dynamic resolution, each getting a new Metal texture. I will re-measure on main with the dynamic resolution moving before claiming more, and update the description with the result.

The failing checks (host unit tests, tool tests, sanitizers, clang-tidy) fail the same way on main 75c1a8c; the build check passes.

[seedds]

Closing this one. Thank you, @PromethOps, and everyone who measured it. The analysis here is what settled the design that landed for #1831.

Your finding explains why mirroring the pool can't work for Ocarina's 305 MB pool: the game keeps live targets in the part of the full-size scene target that its current resolution leaves unused, which only works with NVN's own memory layout. The virtual pool is exactly where the churn is: since 04419bc the resolution moves, and on an M6 that pool made 3,468 new textures in about 1,000 village frames. Without that pool, this PR's gain on main was about 1% (yours, PucaVaz's and enjoyerofslop's runs).

What landed instead, in 7f50222, keeps each texture's own layout and recycles only memory the host has already let go. Each render target in a GPU-only pool gets a placement heap of its own. When the texture is freed, the heap stays resident for the next target of about the same size. With the switch alternating every 300 frames on an M6, the target site added 455-521 MB to the residency set per 300 frames off and 27-37 MB on. That also covers the non-virtual GPU-only pools this PR placed, so the two would compete for the same textures.

The live targets' steady total (about 2 GB in the village) stays open in the game note. Your numbers are linked from the reference entry ("Render targets that move with the dynamic resolution get new Metal memory each time" in docs/reference/rendering.md).