[PromethOps]

What and why

The Legend of Zelda: Ocarina of Time (Switch 2, 0400486024DEC000 v131072) upscales 1536x864 to 2048x1152 with agl's NDSR network from agl_ndsr_vr.pck: f8965bffbdf51d78, fa3033d05c0a41d6 and the other variants. It has two siblings, agl_ndsr.pck and agl_ndsr_vr_light.pck. DM_UPSCALER=metalfx (the launcher's "Game's upscaler: MetalFX") is meant to draw that network with MetalFX's spatial scaler instead. On this game it did nothing, for two reasons:

• UPSCALER_SOURCE in dm/games/game.py matched only /agl_ndsr.pck#, so the profile named none of the shaders the game runs. It now also matches agl_ndsr_vr.pck and agl_ndsr_vr_light.pck.
• Once listed, every variant was refused as "neither of the colour shapes MetalFX draws". Their code holds no sRGB curve: they neither encode nor decode, R11G11B10F in and out.

A variant whose code has no curve constant and no MUFU.EX2 / MUFU.LG2 (up_mfx_has_pow) is now drawn as the linear shape. Every curve takes a power, whichever buffer its constants come from, so the power check covers curves whose constants are not in the code. Such a variant converts nothing, so its input and output are in one colour space, whichever it is. The linear shape converts nothing either, so the colour passes as it is. The washed-out picture of An upscaler's colour read from its code came from a decode the shader does and the swap did not; there is none here. Code with a power but no curve constant still runs the game's shader.

With the change the option works on this game: the log reads upscaler f8965bffbdf51d78_b: input and output in one colour space …, then first dispatch of fa3033d05c0a41d6_b drawn by MetalFX, 1536x864 … → 2048x1152.

An earlier version of this description presented MetalFX as the cure for dotted horizontal lines the network's output showed in fog and light shafts. Main's dead-code removal fix, which covers two NDSR variants, removed them at their source: on main the game's own upscaler draws the same scene clean. This PR only makes the player's MetalFX choice work on these packs.

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 (and A GPU-only pool's render targets share one placement heap: Ocarina of Time's 3 GB of render targets fit in 0.7 GB #1453, 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). Kokiri Forest in fog and light shafts, a fixed scene, DM_UPSCALER=metalfx against the game's upscaler, compared on screenshots and log lines. The player confirmed the picture with both of their MetalFX launchers.
• Devices and OS: MacBook Pro M5 Pro, 24 GB, macOS 27.2.
• t_upscaler_mfx with Donkey Kong Bananza's (040074A01BF12000) and Splatoon Raiders' (0400380020056000) profiles, DM_UPSCALER game and metalfx, both encoding modes: 15 and 94 checks. One expectation changed: no curve and no power is now one colour space, not "the shader runs". New checks:
  • no curve constant but a power (EX2, LG2): the shader runs;
  • a MUFU that is no power (RCP) does not count.
• test_docs.py, docs_symptoms.py. The failing checks (host unit tests, tool tests, sanitizers, clang-tidy) fail the same way on main 75c1a8c; the build check passes.
• Not checked: scripts/regress.py check --games. Bananza's and Splatoon Raiders' variants have curve constants, so their classification is unchanged.

Docs

• The finding is in its docs/reference/rendering.md entries (the upscaler variants, and the no-curve shape), 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

[dinadur]

Tested this PR on top of main 0c7e88b (chain 844bf1a5ea8f) with The Legend of Zelda: Ocarina of Time (0400486024DEC000, v131072), Mac app, Mac Studio M5 Ultra, macOS 27.2.

With DM_UPSCALER=metalfx, the dotted horizontal lines from #1537 are gone, apart from a little flicker. But the picture is clearly too bright and washed out in Kokiri Forest: low contrast and pale, as if the colours went through one conversion too many. With DM_UPSCALER=game the colours are right, but the faint lines come back.

The log classifies every variant as linear and runs MetalFX in HDR mode:

[nvn-mtl] upscaler (DM_UPSCALER): metalfx, the game's upscaler shaders (59, from the shader map) are drawn by MetalFX's spatial scaler
[nvn-mtl] upscaler f8965bffbdf51d78_b: input and output in one colour space (linear, or no sRGB curve in the code), MetalFX in HDR mode
[nvn-mtl] upscaler fa3033d05c0a41d6_b: input and output in one colour space (linear, or no sRGB curve in the code), MetalFX in HDR mode
(same for 04135bb812a0d66e_b, a335c1db6270c355_b, aad7ea7e5c02f41d_b, b106afba1a18faa9_b, d17eefaff4f0bc23_b)
[nvn-mtl] upscaler: MetalFX spatial scaler (HDR) 1195x672 → 2048x1152, 0.7 ms

DM_PRESENT_UPSCALE=metalfx was also on. Screenshot attached below.

[PromethOps]

Thanks @dinadur, reproduced here (M5 Pro) and fixed in d715366.

Cause: these networks have no sRGB curve, but they aren't in one colour space either. A small pass before them square-roots the scene colour (gamma 2, into RGB9E5F), and the network writes its result squared with its sign kept, x * |x| (FMUL in agl_ndsr_vr.pck, HMUL2 in agl_ndsr_vr_light.pck). So their input is root-encoded and their output is linear. MetalFX left the result root-encoded, which gave about the square root of the right picture. On the same frame, the picture's mean was 146/255 against 92 with the game's upscaler, and the darkest 5 % sat at 63 against 10.

Fix: the host now detects that square in the shader's code, an FMUL or HMUL2 of a register by itself with |x| on one side. It needs 8 of them; the real variants have 32 to 108. It then squares the input on its copy into the scaler's RGBA16F texture, so MetalFX runs in HDR mode on linear colour and values above 1 keep their range. On the same scene, the result is within 1.3/255 of the game's upscaler on every channel, and the darkest 5 % is at 9.7 against 10. t_upscaler_mfx covers the classifier and a square-rooted input end to end.

The log now says square-rooted input, linear output (the shader squares): squared into linear, then MetalFX in HDR mode and MetalFX spatial scaler (HDR, input squared).

[bryanjeal]

This branch's game.py regex covers the _vr packs but its test change stops at agl_ndsr.pck's rows; test_game_profile.py still pins DM_GAME_UPSCALER_KEYS at 2 keys, so nothing would catch a VR-pack row dropping out again. One row fixes that, and it happens to be the pack Ocarina of Time's own upscaler key lives in:

'cs_other.bin\t6\tcompute\tfa3033d05c0a41d6\t/Lib/agl/agl_resource.Nin_Ounce_NVN2.release.sarc.zs/agl_ndsr_vr_light.pck#NDSR@0x84900\n'

after the agl_common.sharcb row in the MAP fixture, and the expectation becomes

self.assertEqual(macros(MAP), ['#define DM_GAME_UPSCALER_KEYS "7629d857a0a93833,c56db3d5a0f1b5af,fa3033d05c0a41d6"', '#define DM_GAME_UPSCALER_N 3'])

Defined outside MAP the fixture's escape could bite: horizontal tab and newline as above, and the file treats MAP as one string split on 'cs_other.bin' elsewhere, so a new key in a pixel row or a source outside the three packs would break the split. Without the regex line this row turns the fixture green only while main's UPSCALER_SOURCE still holds, which is why it rides on this branch rather than standing alone (PR #1559 has it as a standalone; if this PR takes it I will close that).

[PromethOps]

Thanks @bryanjeal, taken as you wrote it: the agl_ndsr_vr_light.pck row now sits after the agl_common.sharcb row in MAP, and the expectation is 3 keys. test_game_profile.py passes. #1559 can be closed if this lands.

[FifteenPen]

From Ocarina of Time on our tree, where MetalFX's spatial scaler replaced the agl_ndsr_vr chain:

• Speed: Kokiri Forest 24.5 → 22.5 ms docked (Peak8D's MetalFX path, ported to our tree).
• Picture: the grass shimmered with hard, aliased blade edges in Hyrule Field (handheld, render scale 0.80); the game's own network anti-aliases them. We went back to the game's network as the default and kept MetalFX as a choice.
• Networks by ratio: the network the game picks depends on the render-to-output ratio (we saw five keys, among them 1.1x, 1.33x and 2x). A replacement that follows the chain's dispatches has to take whichever one is used.

[dpadr]

Tested on Ocarina of Time (0400486024DEC000, v131072) on a 16 GB M2 MacBook Air, macOS 27, applied on top of a current main-based host (7f50222 plus a few host PRs). Host only: no shader rebuild needed, chain unchanged.

• Before: DM_UPSCALER=metalfx drew nothing. No "drawn by MetalFX" line appeared, and metalfx and game measured the same.
• With this PR:
  • 59 upscaler keys, up from 22.
  • Takeover logged: fa3033d05c0a41d6_b 1440x810 → 1920x1080, squared into RGBA16F. The agl_ndsr_vr_light.pck variants are read as square-rooted input.
• Handheld, scripted Kokiri Forest route, 2 runs each, submit thread at about 3 GHz:
  • Upscale span (from the upscaler's segment to the UI pass, including MetalFX's encoder): 2.50 ms → 1.31 / 1.38 ms.
  • Frame p50: 27.5–28.2 ms → 25.5–26.7 ms. GPU span: 24.9–25.8 ms → 23.4–24.1 ms.
• Colour matches the game's own network in screenshots, with no wash-out. Edges are slightly softer, as expected from the spatial scaler.
• No hangs, GPU faults or red lines.
• t_upscaler_mfx: 20 checks OK. test_game_profile: OK.

Details and the comparison table: #1911.

[PromethOps]

Thanks @FifteenPen and @dpadr.

@FifteenPen: the game's network stays the default. DM_UPSCALER is game unless the player picks MetalFX in the launcher, so the harder grass edges you saw are a trade the player opts into, as you chose on your tree. On ratios: the profile now takes every pack the game's networks come from (agl_ndsr.pck, agl_ndsr_vr.pck, agl_ndsr_vr_light.pck, 59 keys), and each takeover reads its input and output sizes from the dispatch it replaces. In one Ocarina of Time session on an M2 Pro (16 GB), four of them were drawn by MetalFX: fa3033d05c0a41d6 (square-rooted input, 1536x864 → 2048x1152), f8965bffbdf51d78, a335c1db6270c355 and d17eefaff4f0bc23. If a key stays on the game's network with this branch, its log line would help.

@dpadr: thank you for the measurements and for #1911, which describes the cause this branch fixes.