[oliverames]

What and why

DKB can change its rendering path after the last MetalFX size message. A scaler-creation log alone cannot show returns to cached sizes or establish whether later submissions still use MetalFX.

This adds successful size-transition logging and an opt-in DM_NVN_MFX_TRACE=1 diagnostic gated by selected passdump frames. The trace records named upscaler decisions, refusal reasons and dimensions from the exact resolved bindings, with at most 64 detailed records per submission. Submission-owned summaries include calls, named attempts, substitution decisions and early exits. They record observed start/end frames and flag boundary crossings. A zero count describes one submission, not a complete game frame; calls rejected before shader lookup cannot be classified by name.

The diagnostic leaves the existing scaler decisions and pacing policy unchanged.

@seedds This supports the Switch 2 games running on iPhone investigation. The DKB iPhone 17 Pro Max evidence comes from an older combined build: one frame has 1676×943 AA targets, while a later frame has 2304×1296 geometry and AA attachments, with 2346×1320 drawable captures. Those observations do not establish why the path changed, continued MetalFX dispatch on every frame, a pacing improvement, or a fur-shimmer fix. The diagnostic may help other titles with named game upscalers, but that benefit has not been measured on those games.

Full production classifier coverage, hosted CI and exact-head physical iPhone execution remain outstanding.

Checked

• Tests: Nov 12, main 0c23e0b59 merged in (head aa10929c): check_t_upscaler_mfx in game mode passes its 15 checks, the encoding-thread variants weren't rerun; test_docs, test_env_switches, test_gfx_tests_makefile and the iOS compile check (263 files) pass. Before that, at head 64be2a6, the Mac fixture passes 95 checks with the encoding thread off, 95 with it on, and 15 in game mode. Coverage includes exact resolved dimensions/serials, an empty-submission summary, refusal classification, and a presentation boundary during an active submission. All 12 documentation/environment tests and diff whitespace checks pass. Full production classifier coverage and hosted CI are outstanding.
• Games run, with title ID and version: no game was run for this head. The original description cites DKB evidence from an older combined build (no title version stated; the game note path uses title ID 040074A01BF12000) and says it does not establish why the path changed.
• Devices and OS: the DKB observations came from an iPhone 17 Pro Max (OS not stated). The Mac fixture's hardware and macOS version are not stated. Exact-head physical iPhone execution is outstanding.
• scripts/regress.py line: not stated.
• Measurements before and after: not stated. The description says the benefit to other titles has not been measured. The only figures are the older-build DKB dimensions quoted above: 1676×943 AA targets in one frame, 2304×1296 geometry and AA attachments in a later frame, and 2346×1320 drawable captures.

Front ends

None: no front end has to act on this.

Docs

• The diagnostic is described in its game note and in a Diagnostic line added to an existing docs/reference/rendering.md entry (both are in the diff; docs/agents/04-graphics.md and docs/env_switches.tsv also change). The description does not say python3 dm/tools/docs_symptoms.py was run, and docs/agents/symptoms.md is not in the diff, so the symptom index step is unconfirmed.
• A chain tool changed: dmsh_chain.py --header was run and dm/gfx/nvn/dmsh_chain.h is part of the change. Not applicable: no chain tool changed.
• No game files, keys or data extracted from a game in the change or the attachments (source, a test, and docs only).

Rebased onto main ab41d6a (2026-11-10), and before that onto dbf8499 (2026-11-09); conflict resolved in dm/gfx/nvn/nvn_mtl.m, where main's ndve_engine_dispatch early return now runs before the traced MetalFX decision in dispatch() and main's threadgroup spill block after it.

[oliverames]

@seedds, this small diagnostic comes from Switch 2 games running on iPhone, specifically checking DKB's 1676×943 scene → 2304×1296 MetalFX output on iPhone 17 Pro Max. It logs successful size-pair transitions, including a return to cached scaler dimensions that creation logs miss. Existing Mac MetalFX tests and docs pass; the line does not prove GPU completion or drawable size, and per-frame size changes can add logging overhead. Exact-head physical gameplay remains pending. It may help other titles using the same MetalFX path; no pacing or visual-quality improvement is claimed.

[oliverames]

@seedds Updated this Switch 2 / iPhone diagnostic to 0d6edee9, merging current upstream repairs and #1164's remaining fixture guards. The earlier clang-tidy failure was in the inherited allocation/fixture/filesystem findings, not the seven-line size-transition log. Relative to prerequisite 4bb147e6, the change remains the three diagnostic/documentation files.

Verified locally: targeted renderer LLVM 23.1.4 ratchet has zero file/check pairs above or below the baseline; MetalFX fixture passes 74 checks with encoding thread off and 74 with it on, plus 5 game-path checks; 11 documentation tests and whitespace checks pass. New hosted CI is pending.

A fresh combined DKB diagnostic run on iPhone 17 Pro Max retained 1676×943 scene → 2304×1296 MetalFX → 2346×1320 drawable. That app is an adapted combined baseline, not this exact PR head. Its raw AA capture incurred dropped/discarded frames, so it is not evidence of pacing improvement. Cached-size-return log behavior and exact-head phone gameplay remain verification gaps; keeping this draft. The log remains useful for correlating resolution transitions across titles without treating allocation pools as resolution controls.

[oliverames]

@seedds Head 1978d68 resolves the rendering-documentation conflict while preserving upstream's new MetalFX color handling. The size-transition diagnostic remains unchanged. The focused Mac tests pass: 91 MetalFX checks in each encoding mode, 12 game-path checks, and 11 documentation tests. This remains draft pending hosted checks and exact-head phone verification.

The ongoing Switch 2 games running on iPhone investigation found a useful limit of these logs: the DKB iPhone 17 Pro Max run last logged 1676×943 to 2304×1296, but a later captured frame used 2304×1296 AA targets. A last-seen size log does not establish that scaling continued on every subsequent frame. I am investigating that render-path change before making a sustained-resolution claim.

[oliverames]

@seedds Head 4fcc352 adds bounded dispatch-path evidence for the Switch 2 games running on iPhone work. Review caught a real accounting race between presentation and replay; the counters now belong to submission replay, with explicit start/end frame labels and a boundary-crossing flag. Zero means no dispatch in that submission, not proof about a whole game frame.

The focused Mac runs pass 95/95 MetalFX checks and 15 game-mode checks, plus 12 docs/environment tests. This remains draft: hosted CI, full production classifier coverage and exact-head iPhone testing are pending. No pacing or shimmer fix is claimed. The next DKB iPhone 17 Pro Max run will use this evidence to distinguish native-size rendering from scaler substitution or fallback.

[oliverames]

@seedds, new physical-phone evidence for Switch 2 games running on iPhone: DKB completed a 70-second gameplay route on the iPhone 17 Pro Max with this dispatch trace adapted onto the existing combined test build. The trace recorded MetalFX substitution in frames 4728–4730, with resolved 1676×943 input and 2304×1296 output. Both route drawable captures were 2346×1320.

One recorded decision:

[pass] F4728 MFX submission=16863 dispatch key=7629d857a0a93833_b kind=direct bindings_resolved=1 input=50666/ser35335/1676x943 rect_valid=1 rect=0,0,1676,943 output=1767/ser4624/2304x1296 rect_valid=1 rect=0,0,2304,1296 outcome=metalfx reason=none

Fresh log.txt and memstat.tsv were pulled after stopping the game. Executable SHA-256: edee6e822508c949ed194a78324ddd4a427b808da05dbfe90ca572b27c70c9a5. Launch used DM_LAUNCHER=0, DM_UPSCALER=metalfx, and DM_NVN_MFX_TRACE=1, followed by three selected pass-dump frames during gameplay. No FPS or memory-pool override.

This verifies a nonzero diagnostic path on the phone. It does not verify the exact PR head, sustained warm stability, a shimmer fix, or the later full-resolution render path. The PR remains draft. The dispatch decisions and refusal reasons may also help diagnose other titles that use the MetalFX substitution path.

[oliverames]

The clang-tidy (ratchet) failure on this head is not from this diff. It ran at 08:07 UTC against main 13da1c5, which had the same three clang-analyzer-security.ArrayBound findings in nvn_mtl.m (S.stream, g_red_once, g_mrb; main run 41795029384). Main fixed it in 5ccbedd and was green again at 41798477391.

I checked this head merged with current main (aafe01d) locally with clang-tidy 23.1.4: nvn_mtl.m has 47 findings, the same as main, and t_upscaler_mfx.m, t_cpu_storage.m, t_pool_chunks.m and t_sparse_tiles.m have 0.

A fresh run will still fail for a reason on main: lint-c on main is red since 0b8e0dc (run 41819072419), with four file/check pairs above the baseline in files this PR does not touch (dm/gfx/vk/hle_vk.m NullDereference, dm/host/hle_jit.c suspicious-realloc-usage, dm/host/hle_oe.c StdCLibraryFunctions, dm/host/web_apple.m NullablePassedToNonnull). No commit to dm/host or dm/gfx has landed on main since.

[oliverames]

@seedds Flagging from my open-PR index of my 32 open PRs here: this one stays draft pending hosted CI and exact-head physical iPhone execution. The description above is still the full picture, nothing new from me. Happy to rebase, split or retitle whenever review suits.

[oliverames]

@seedds Marking this ready for review now, so it stops waiting in draft on me. The remaining item from the description is still open: hosted CI and exact-head physical iPhone execution. It can carry on alongside a review instead of ahead of it. The description stays the source of truth; happy to rebase, split or retitle whenever review suits.

[oliverames]

Rebased onto current main: one conflict in mtl_sub_begin (kept main's line without the removed g_rc_npend/g_rc_skip reset, plus mfx_trace_sub_begin). make GAME=040074A01BF12000 check_t_upscaler_mfx: 15 checks, 0 failed; test_docs.py OK.