Skip to content

B8: a refused frame always has an explicit result; front end tested against the real backend - #228

Draft
phantoslayer21 wants to merge 6 commits into
mainfrom
b8/refused-frame-contract
Draft

phantoslayer21 wants to merge 6 commits into
mainfrom
b8/refused-frame-contract

Conversation

@phantoslayer21

@phantoslayer21 phantoslayer21 commented Nov 15, 2026 •

Copy link
Copy Markdown
Owner

Refs #15 (0.6.5 item B8, from the #215 review). Based on main. No public header change, no ABI change.

The front end's refused-frame path (a frame WrongGPU's upscaler answers WG_ERROR_UNSUPPORTED for) is shared by every model since 0.6.0. When AMD's FSR and the stand-in both failed it ended in an error with a log line per frame (or, after a takeover, with no line at all). This PR makes that result explicit and bounded, and tests the path against the real backend.

What changes

  • The contract (clean/fsr/src/frontend.cpp, frontend.h): when AMD's FSR (missing, not created, or its dispatch failed) and the stand-in (not made, or its dispatch failed) have both failed for a frame, the error goes back to the game with one line naming both failures, once per context, also after an earlier success or after a takeover; the count is logged when the context is destroyed. Nothing else about the result changes: the answer is the same error as before, and the frames AMD or the stand-in can take keep being taken. In OptiScaler's custom slot the error goes back to its host as before.
  • AMD takeover that fails: the first refused frame hands the context to AMD; if AMD's dispatch fails (for that frame or later ones, also at the 30-frame bad-frame threshold and after a split-blocked takeover), the stand-in takes the frame, and if that fails too it is the one line above. Before, AMD's error went back with no attempt of the stand-in.
  • Non-linear (sRGB / PQ) frames keep their guard on every path: such a frame is AMD's alone and never reaches the stand-in: AMD missing, AMD failing from the start, the takeover at the bad-frame threshold, and a context already handed to AMD whose AMD dispatch starts failing (the flags of the descriptor are read before the stand-in is considered). Ordinary frames of the same context still get the stand-in.
  • Logs are bounded: AMD's failures are logged once per context (the first) and counted; AMD's per-frame context create for a bad frame is retried at the 1st, 2nd, 3rd, 10th, 100th ... frame (it used to log two lines every frame); the one "no upscaler could take this frame" line replaces the per-frame lines. A 300-frame run stays under 60 log lines.
  • Test executor for the real backend (executor.h, executor_test.cpp, backend.cpp, executor_select.h): executor=dx12-test is an executor on the D3D12 route (records into the game's list, no slots, no fences) scripted frame by frame (test_script=orrro...: o taken, r refused with the D3D12 executor's "frame not taken (nothing recorded)" error, f a failure inside the network; the last character repeats). It stands in for the default D3D12 executor in the backend's own refused-frame code (dispatch_record, refused_frame_action), which therefore runs unchanged. It is selectable only by that option name. The runtime DLL also exports wgDiagHipExecutorsMade (how many HIP executors the process's contexts made), for the release check below; it is not in any public header.
  • Docs: clean/fsr/README.md ("Frames the upscaler does not take").
  • An earlier revision of this PR added a last resort (a raw copy, then the backend's bilinear pass with a WG_FRAME_BILINEAR frame flag). Both are gone: no frame flag, no new backend flag, no change to wronggpu_upscaler.h.

Tested

  • test_frontend.cpp (8984 checks, 0 failures; built with clang++ here, ctest in CI) and test_fsr30.cpp (185 checks): for models M, K and L, each of: no AMD with the stand-in failing at create, failing at dispatch; AMD that cannot be created with the stand-in working and failing; AMD's dispatch failing with the stand-in working, failing at create, failing at dispatch; a custom slot. Each runs 300 refused frames and checks the answer for every frame (the stand-in's frame, or the error), that the one line names both failures exactly once, that AMD's failure is one line, that the count is logged at the end and that the log stays small. Also: a success followed by a failure (reported although earlier frames succeeded), and sRGB and PQ frames on four paths (AMD missing; AMD failing from the start, 40 frames, which includes the takeover threshold; a taken-over context whose AMD starts failing, with an ordinary frame after it that still gets the stand-in): the stand-in is never used for them. One older case changed on purpose: AMD's dispatch failing after the upscaler failed is now a stand-in frame (it was an error).
  • test_refusal_integration.cpp (119 checks, 0 failures; WARP, no GPU needed): the front end with the REAL backend (the runtime DLL's Context, built from this tree) and the scripted executor, a real D3D12 device and real textures, for model K and the M control, three scenarios each: AMD available (the first refusal hands the context to AMD, the rest are AMD's); no AMD with the stand-in working (five refusals in a row, each a stand-in frame, then the taken frames are the backend's again: no counter, the context stays usable); no AMD with the stand-in unavailable (the refused frames return the error with the one line, the frames the backend takes afterwards are fine). In every scenario the refusal comes from the backend's code (one line, K's and M's own), wgDiagHipExecutorsMade stays 0 (no HIP executor constructed), no HIP runtime line is logged and no amdhip64 module is loaded.
  • The runtime builds from this tree; public_gates.py must-pass gates pass, LOOK counts equal main's.

Where the real check lives and how it is built

clean/fsr/tests/test_refusal_integration.cpp is a release check, not a CI test: it needs the runtime DLL of a build (CI has none) and a D3D12 device (WARP is enough). The release script under tools/release (the release lead's) builds it from that source and runs it with the DLL of the build; the build command is in the file's header (the front end's core sources, -ld3d12 -ldxgi; the registry header generated with clean/wgshared/tools/gen_registry.py), and the DLL comes from clean/runner/build.py --runtime-only. Run without a DLL it exits 2 (a gate that runs it cannot pass by skipping; --skip-if-missing is for a developer's loop). It does not check pixels: no path of this contract writes pixels of its own any more.

Not tested

  • The integration check is not in the CI (see above).
  • hip_switch=on for models M and L (an explicit option that moves a context to HIP) is not driven here.
  • The Windows front end's build in CI is the check for the frontend.cpp / frontend.h edits on that platform (they are plain C++ and were built and tested here).

…ested against the real backend

The front end's refused-frame contract (clean/fsr/src/frontend.cpp) is explicit for every model: WrongGPU's upscaler, then
the stand-in, then AMD's FSR, and last, when none of them could upscale the frame (the stand-in cannot be made or fails, AMD's
FSR is missing or its dispatch fails, including for a context WrongGPU already handed to AMD), the game's own colour is copied
into the output unscaled (new passthrough_d3d12.cpp, Platform::passThrough) with one warning line, and the game gets
FFX_API_RETURN_OK instead of an error with no output. When that is impossible too the error goes back with one line saying why,
as before; an OptiScaler custom slot keeps getting the error (its host upscales).

Tests: test_frontend.cpp covers each failure case for models M, K and L. New test_refusal_integration.cpp drives refused frames
through the REAL network backend (the runtime DLL's Context) and the real front end on a D3D12 device, with a scripted
executor (executor=dx12-test, executor_test.cpp) standing in for the D3D12 executor: K and the M control, with and without
AMD's FSR, repeated refusals, the stand-in working and not, the real pass-through checked on the output's pixels, and no
HIP runtime ever loaded.

Signed-off-by: phantoslayer21 <156617979+phantoslayer21@users.noreply.github.com>
@phantoslayer21
phantoslayer21 marked this pull request as draft November 15, 2026 02:36
…y (REVIEW-228)

Drop the raw CopyTextureRegion pass-through (it wrote only the render-sized corner, transitioned unrelated subresources and
copied bits between format families). When the stand-in and AMD's FSR could not upscale a frame, the front end now asks the
upscaler for its existing bilinear output pass: WgFrame::flags WG_FRAME_BILINEAR (the backend says it answers it with
WG_BACKEND_BILINEAR_FRAME), and the runtime records the Converter's fallback pass (format aware, the full output size, its own
barrier handling, no HIP). The game gets OK with one warning line per context; the counts are logged at destroy. When that is
impossible too, the error goes back and the reason is logged for the first such frame, also after earlier successes.

AMD's failures are logged once per context and counted, however long the run; AMD's per-frame context create is retried at 1, 2,
3, 10, 100 ... A frame flagged non-linear (sRGB / PQ) is mapped before the AMD-only fallback, so it gets the same last resort.

Tests: test_frontend.cpp (every failure case for models M, K and L over 300 frames, log size bounded, success then an invalid
output, AMD create failing, non-linear frames). test_refusal_integration.cpp (the real backend, the scripted executor) checks every
pixel of the backend's bilinear output for consecutive frames after a sentinel fill, with a negative control, that model K's
alpha follows the colour's alpha and M's is 1, that wgDiagHipExecutorsMade stays 0, and fails without the runtime DLL.

Signed-off-by: phantoslayer21 <156617979+phantoslayer21@users.noreply.github.com>
Signed-off-by: phantoslayer21 <156617979+phantoslayer21@users.noreply.github.com>
@phantoslayer21
phantoslayer21 marked this pull request as ready for review November 15, 2026 03:06
@phantoslayer21
phantoslayer21 marked this pull request as draft November 15, 2026 03:10
…ne; no ABI change (REVIEW-228b)

Drop the frame flag, the backend flag and the bilinear last resort: no change to wronggpu_upscaler.h, none of the backend's frame
path. The contract that stays: when AMD's FSR and the stand-in have both failed for a frame, the error goes back with ONE line
naming both failures per context (also after an earlier success or a takeover) and a count at the context's end. A failing AMD
takeover now tries the stand-in before the error. A non-linear (sRGB / PQ) frame never reaches the stand-in on any path, the
takeover and a context already handed to AMD included. AMD's failures are logged once per context; AMD's per-frame create is
retried at the 1st, 2nd, 3rd, 10th ... frame.

Tests: test_frontend.cpp (every failure case for models M, K and L over 300 frames, success then failure, sRGB and PQ on four
paths). test_refusal_integration.cpp, a release check built from source by the release script, drives the real backend through the
scripted executor=dx12-test; the runtime DLL's wgDiagHipExecutorsMade (not in a public header) stays 0.

Signed-off-by: phantoslayer21 <156617979+phantoslayer21@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant