From 16721fe42fa5843bf97db997680ba0baab9aa0b1 Mon Sep 17 00:00:00 2001 From: phantoslayer21 <156617979+phantoslayer21@users.noreply.github.com> Date: Mon, 16 Nov 2026 00:15:41 -0500 Subject: [PATCH 1/4] Model K: k_approx opt-in close approximations a1 (input stage) and a2 (output stage), D3D12 only Runtime option k_approx (opt-in; nothing set stays the exact path, the default and the reference). The variants are judged by image quality against the exact path, not byte for byte. D3D12 devices only: HIP refuses the option, and an unknown tag is refused. Taking one adds a note of create and " k_approx=..." to the kernels line. - a1, the tiled input stage (kx/k_in_tiled*__a1; k_in_common.hlsli KI_HWMATH): the correctly rounded log2, 2^x and divisions (FP32 double-word arithmetic with a Ziv test and a binary64 fallback) become v_log_f32, v_exp_f32 and v_rcp_f32 times the dividend (scaled for |b| >= 2^126). Needs the exact input kernels. - a2, the output stage (k_out_color*__a2, k_out_pixel_c*__a2; k_out.hlsli KO_APPROX): the exact divisions become v_rcp_f32 times the dividend plus one correction of the quotient from its exact residual, and ko_div_axis and ko_rcp_refined drop their Newton step; ko_rcp_output_bounded and every opaque barrier stay. Excludes k_fast. Tests (test_k_runtime_d3d12.py): the refusals (HIP, unknown tag), the note, the __a1 / __a2 kernels in the launch trace, and loose closeness bounds against the exact path on the synthetic model (tone-mapped luma PSNR). Signed-off-by: phantoslayer21 <156617979+phantoslayer21@users.noreply.github.com> --- clean/dx12/kernel_sets.json | 28 +++++++++++++ clean/k/dx12/README.md | 18 ++++++++ clean/k/dx12/hlsl/k_in_common.hlsli | 22 ++++++++++ clean/k/dx12/hlsl/k_out.hlsli | 28 +++++++++++++ clean/k/dx12/kernels/k_in.hlsl | 5 +++ clean/k/dx12/kernels/k_out.hlsl | 7 ++++ clean/k/runtime/runtime_k.cpp | 42 ++++++++++++++++++- clean/k/runtime/runtime_k.h | 14 ++++++- clean/k/tests/test_k_runtime_d3d12.py | 60 +++++++++++++++++++++++++++ 9 files changed, 221 insertions(+), 3 deletions(-) diff --git a/clean/dx12/kernel_sets.json b/clean/dx12/kernel_sets.json index db66536c..07fe9ce0 100644 --- a/clean/dx12/kernel_sets.json +++ b/clean/dx12/kernel_sets.json @@ -428,10 +428,18 @@ "k_out_color", "k_io.co" ], + [ + "k_out_color__a2", + "k_io.co" + ], [ "k_out_color_direct", "k_io.co" ], + [ + "k_out_color_direct__a2", + "k_io.co" + ], [ "k_out_pixel", "k_io.co" @@ -440,10 +448,18 @@ "k_out_pixel_c", "k_io.co" ], + [ + "k_out_pixel_c__a2", + "k_io.co" + ], [ "k_out_pixel_c_direct", "k_io.co" ], + [ + "k_out_pixel_c_direct__a2", + "k_io.co" + ], [ "k_out_pixel_direct", "k_io.co" @@ -584,13 +600,25 @@ "kx/k_in_tiled", "k_io_exact.co" ], + [ + "kx/k_in_tiled__a1", + "k_io_exact.co" + ], [ "kx/k_in_tiled_direct", "k_io_exact.co" ], + [ + "kx/k_in_tiled_direct__a1", + "k_io_exact.co" + ], [ "kx/k_in_tiled_uniform", "k_io_exact.co" + ], + [ + "kx/k_in_tiled_uniform__a1", + "k_io_exact.co" ] ] } diff --git a/clean/k/dx12/README.md b/clean/k/dx12/README.md index 07cc0f4e..2bd9a7a0 100644 --- a/clean/k/dx12/README.md +++ b/clean/k/dx12/README.md @@ -112,3 +112,21 @@ identical. Known limit, shared with Model M's ports: D3D12 flushes FP32 denormals (inputs and results) to zero and HIP keeps them. `k_expo_scalars` only meets one with a pre-exposure above about 8.5e37, so the check's inputs keep clear of them. + +## Close approximations (runtime option `k_approx`, opt-in) + +Every port above is exact, and nothing set is the exact path. `k_approx` selects close approximations of two stages on +the D3D12 devices (HIP refuses the option); they are judged by image quality against the exact path, not byte for byte, +and taking one adds a note of create. + +- `a1`, the tiled input stage (`kx/k_in_tiled*__a1`, `hlsl/k_in_common.hlsli` `KI_HWMATH`): its correctly rounded log2, + 2^x and divisions (FP32 double-word arithmetic with a Ziv test and a binary64 fallback) become `v_log_f32`, + `v_exp_f32` (about 1 FP32 ulp) and `v_rcp_f32` times the dividend (scaled for |b| >= 2^126). On the port-check input + family the network input x0 differs from exact in about 1e-5 of its FP16 values, always by one FP16 ulp. +- `a2`, the output stage (`k_out_color*__a2`, `k_out_pixel_c*__a2`, `hlsl/k_out.hlsli` `KO_APPROX`): its exact divisions + become `v_rcp_f32` times the dividend plus one correction of the quotient from its exact residual, and two refined + reciprocals drop their Newton step; every opaque barrier stays. On the port-check output family (plain and + special-value inputs) every FP16 output is within one ulp of exact. + +`k_approx=a1,a2` takes both. `test_k_runtime_d3d12.py` (`test_k_approx_refusals`, `test_native_k_approx_close`) checks +the refusals, the note, that the `__a1` / `__a2` kernels run, and loose closeness bounds on the synthetic model. diff --git a/clean/k/dx12/hlsl/k_in_common.hlsli b/clean/k/dx12/hlsl/k_in_common.hlsli index 4e88f455..5e5def81 100644 --- a/clean/k/dx12/hlsl/k_in_common.hlsli +++ b/clean/k/dx12/hlsl/k_in_common.hlsli @@ -5,10 +5,32 @@ #pragma once // ---- the exact input stage's arithmetic (k_io.hip with KI_FAST = 0) -------------------------------------------------- +#ifndef KI_HWMATH +#define KI_HWMATH 0 +#endif +#if KI_HWMATH +// CLOSE-APPROXIMATION variant (opt-in, never the default): the transcendental unit instead of the correctly rounded +// sequences: v_log_f32 / v_exp_f32 (about 1 FP32 ulp), v_rcp_f32 and a product for the divisions. The results meet the +// input stage's FP16 roundings, so they differ from the exact form only where an FP32 result lies within about one +// FP32 ulp of an FP16 rounding midpoint. +float ki_log2(float x) { return log2(x); } +float ki_exp2(float x) { return exp2(x); } +float ki_rcp(float x) { return rcp(x); } +// a rcp(b), branch free. For |b| >= 2^126, 1 / b would flush to zero (e.g. the score's g / nu for a colour range near +// FLT_MAX, where the quotient is about 1/8): there b is scaled by s = 2^-64 first and the product scaled back, +// (a rcp(b s)) s, which cannot overflow (|a / b| <= 2^2 there) and flushes only where a / b itself is below 2^-126. +// s = 1 elsewhere (the same value as a rcp(b)); b = 0, +-inf and NaN give the IEEE quotient's special value. +float ki_div(float a, float b) +{ + const float s = abs(b) < 8.5070592e+37f ? 1.0f : 5.4210109e-20f; // 2^126, 2^-64 + return (a * rcp(b * s)) * s; +} +#else float ki_log2(float x) { return kf_log2(x); } float ki_exp2(float x) { return kf_exp2(x); } float ki_rcp(float x) { return kf_div(1.0f, x); } float ki_div(float a, float b) { return kf_div(a, b); } +#endif // spec 42 decode factor D(t) float ki_decode(float t) { diff --git a/clean/k/dx12/hlsl/k_out.hlsli b/clean/k/dx12/hlsl/k_out.hlsli index af105b92..5390f4f1 100644 --- a/clean/k/dx12/hlsl/k_out.hlsli +++ b/clean/k/dx12/hlsl/k_out.hlsli @@ -49,6 +49,16 @@ WG_ARGS_END // opaque zero (the launch's workgroup count is below 2^31): x ^ ko_z is x, but the D3D12 shader compiler cannot see // through it. Used where the driver was seen to regroup chains of products by a shared / uniform factor or to fuse // FP16 multiply + add (wg_math.hlsli "DRIVER EXCEPTIONS"); HIP keeps every such product as written (contract off). +#ifndef KO_APPROX +#define KO_APPROX 0 +#endif +// KO_APPROX 1: CLOSE-APPROXIMATION variant a2 (runtime option k_approx=a2; opt-in, never the default): ko_div is +// v_rcp_f32 times the dividend plus one correction of the quotient from its exact residual (q + r (a - b q), two fma) +// instead of the exact division, and ko_div_axis and ko_rcp_refined drop their Newton step. ko_rcp_output_bounded and +// every opaque barrier (kof, koh, kp_opq, the conversion input) stay: without them, measured, one-FP16-ulp differences +// of mid-range intermediates reach outputs near zero (a few at 4 ulp). Not byte-identical; measured on the port-check +// output family (6 seeds, plain and special-value inputs): every FP16 output within 1 ulp of exact, about 1e-5 of the +// values differ. #define ko_z (wg_grid_ >> 31) float kof(float x) { return asfloat(asuint(x) ^ ko_z); } double kod(double x) { uint lo, hi; asuint(x, lo, hi); return asdouble(lo ^ ko_z, hi); } @@ -139,6 +149,17 @@ half kh_mul(half a, half b) { return koh(a * b); } // scaled back by the exact power of two 2^(127 - eb); every later step is then wg_div's step times a power of two with // all values normal (quotient within 2^+-71, residuals >= 2^-82), so each rounds to the scaled bits of wg_div's result, // and wg_div's exponent reassembly gives that same value. Other operands (zero, inf, NaN, far exponents): wg_div. +#if KO_APPROX +// a2: a rcp(b), branch free (|b| >= 2^126 scaled by 2^-64 first, see k_in_common.hlsli ki_div), plus one correction of +// the quotient from its exact residual: within about half an FP32 ulp +float ko_div(float a, float b) +{ + const float s = abs(b) < 8.5070592e+37f ? 1.0f : 5.4210109e-20f; + const float bs = b * s, r = rcp(bs); + const float q = a * r; + return mad(mad(-bs, q, a), r, q) * s; +} +#else float ko_div(float a, float b) { const uint ua = asuint(a), ub = asuint(b); @@ -153,6 +174,7 @@ float ko_div(float a, float b) [branch] if (ea - 92u > 70u || eb - 92u > 70u) q = wg_div(a, b); return q; } +#endif half kh_div(half a, half b) { return kh_round(ko_div((float)a, (float)b)); } // ---- binary64 log / 2^x (k_fp.h kd_*) --------------------------------------------------------------------------------- @@ -433,6 +455,9 @@ void ko_color_tap(float4 c, out uint2 tap, out uint tT) // beta quotient of the axis coefficients (ko_div_axis: v_rcp_f32, one Newton step, residual correction) float ko_div_axis(float a, float b) { +#if KO_APPROX // a2: without the Newton step + return a * rcp(b); +#endif float r = rcp(b); r = mad(mad(-b, r, 1.0f), r, r); const float q = a * r; @@ -496,6 +521,9 @@ float ko_cubic_unit(float Am1, float A0, float A1, float A2, KoAxis a) // the IEEE division elsewhere float ko_rcp_refined(float x) { +#if KO_APPROX // a2: without the Newton step + return rcp(x); +#endif [branch] if (x >= asfloat(0x2f800000u) && x <= asfloat(0x4f800000u)) { const float r = rcp(x); return mad(mad(-x, r, 1.0f), r, r); diff --git a/clean/k/dx12/kernels/k_in.hlsl b/clean/k/dx12/kernels/k_in.hlsl index 41178a92..22147b0e 100644 --- a/clean/k/dx12/kernels/k_in.hlsl +++ b/clean/k/dx12/kernels/k_in.hlsl @@ -31,6 +31,11 @@ // @wg-kernel kx/k_in_tiled_uniform co=k_io_exact.co block=256 wave=64 args=s248:p4.b128.p5.b48 defines=K_UNIFORM=1 // @wg-kernel kx/k_in_tiled co=k_io_exact.co block=256 wave=64 args=s200:p4.b128.p5 // @wg-kernel kx/k_in_tiled_direct co=k_io_exact.co entry=k_in_tiled block=256 wave=64 args=s200:p4.b128.p5 rs=direct defines=WG_DIRECT_TEXTURES=1 +// The __a1 forms: the opt-in close approximation a1 (runtime option k_approx=a1, never the default): log2 / 2^x / +// divisions on the transcendental unit (hlsl/k_in_common.hlsli KI_HWMATH); not byte-identical to HIP. +// @wg-kernel kx/k_in_tiled_uniform__a1 co=k_io_exact.co entry=k_in_tiled_uniform block=256 wave=64 args=s248:p4.b128.p5.b48 defines=K_UNIFORM=1,KI_HWMATH=1 +// @wg-kernel kx/k_in_tiled__a1 co=k_io_exact.co entry=k_in_tiled block=256 wave=64 args=s200:p4.b128.p5 defines=KI_HWMATH=1 +// @wg-kernel kx/k_in_tiled_direct__a1 co=k_io_exact.co entry=k_in_tiled block=256 wave=64 args=s200:p4.b128.p5 rs=direct defines=WG_DIRECT_TEXTURES=1,KI_HWMATH=1 #include "wg_platform.hlsli" #ifndef K_UNIFORM #define K_UNIFORM 0 diff --git a/clean/k/dx12/kernels/k_out.hlsl b/clean/k/dx12/kernels/k_out.hlsl index da700b4b..692713bb 100644 --- a/clean/k/dx12/kernels/k_out.hlsl +++ b/clean/k/dx12/kernels/k_out.hlsl @@ -47,6 +47,13 @@ // @wg-kernel k_out_color_direct co=k_io.co entry=k_out_color block=128 wave=64 args=s312:p4.b12.x24.b52.x12.b24.x4.p4.x8.p4.b8.p2.b56 rs=direct defines=WG_DIRECT_TEXTURES=1 // @wg-kernel k_out_pixel_c_direct co=k_io.co entry=k_out_pixel_c block=128 wave=64 args=s312:p4.b12.x24.b52.x12.b24.x4.p4.x8.p4.b8.p2.b56 rs=direct defines=KO_COMPACT=1,WG_DIRECT_TEXTURES=1 // @wg-kernel k_out_pixel_direct co=k_io.co entry=k_out_pixel_c block=128 wave=64 args=s312:p4.b12.x24.b52.x12.b24.x4.p4.x8.p4.b8.p2.b56 rs=direct defines=KO_COMPACT=0,WG_DIRECT_TEXTURES=1 +// The __a2 forms: the opt-in close approximation a2 (runtime option k_approx=a2, never the default): divisions on +// v_rcp_f32 with one quotient correction, two reciprocals without their Newton step, every opaque barrier kept +// (hlsl/k_out.hlsli KO_APPROX); not byte-identical to HIP. +// @wg-kernel k_out_color__a2 co=k_io.co entry=k_out_color block=128 wave=64 args=s312:p4.b12.x24.b52.x12.b24.x4.p4.x8.p4.b8.p2.b56 defines=KO_APPROX=1 +// @wg-kernel k_out_pixel_c__a2 co=k_io.co entry=k_out_pixel_c block=128 wave=64 args=s312:p4.b12.x24.b52.x12.b24.x4.p4.x8.p4.b8.p2.b56 defines=KO_COMPACT=1,KO_APPROX=1 +// @wg-kernel k_out_color_direct__a2 co=k_io.co entry=k_out_color block=128 wave=64 args=s312:p4.b12.x24.b52.x12.b24.x4.p4.x8.p4.b8.p2.b56 rs=direct defines=WG_DIRECT_TEXTURES=1,KO_APPROX=1 +// @wg-kernel k_out_pixel_c_direct__a2 co=k_io.co entry=k_out_pixel_c block=128 wave=64 args=s312:p4.b12.x24.b52.x12.b24.x4.p4.x8.p4.b8.p2.b56 rs=direct defines=KO_COMPACT=1,WG_DIRECT_TEXTURES=1,KO_APPROX=1 #include "wg_platform.hlsli" #if defined(WG_DIRECT_TEXTURES) #include "native_direct.hlsli" diff --git a/clean/k/runtime/runtime_k.cpp b/clean/k/runtime/runtime_k.cpp index 0b7320bb..8b080ec1 100644 --- a/clean/k/runtime/runtime_k.cpp +++ b/clean/k/runtime/runtime_k.cpp @@ -472,6 +472,30 @@ bool KRuntime::create(const WgRtConfig& c, Device* dev, AllocFn alloc_fn, bool e // the exact input stage is the default (spec 09 / 49 accuracy); k_fast_in=1 (or k_in_exact=0, or k_fast=1, whose // "_f" kernels include the fast input stage) selects the fast one in_exact_ = !(fast_ || kfastin == "1" || kexact == "0"); + // k_approx (opt-in, never the default): close approximations of the D3D12 ports, judged by image quality against + // the exact path, which stays the default and the reference. "a1": the tiled input stage's log2 / 2^x / divisions + // on the transcendental unit (kernels kx/k_in_tiled*__a1; clean/k/dx12/hlsl/k_in_common.hlsli KI_HWMATH). + // "a2": the output stage's divisions on v_rcp_f32 with one quotient correction and two reciprocals without their + // Newton step (kernels k_out_color*__a2, k_out_pixel_c*__a2; clean/k/dx12/hlsl/k_out.hlsli KO_APPROX). A comma list + // selects several. D3D12 devices only (HIP refuses); taking one adds a note of create (not bit-exact). + const std::string kapprox = option(c, "k_approx"); + if (!kapprox.empty()) { + size_t at = 0; + while (at <= kapprox.size()) { + const size_t end = std::min(kapprox.find(',', at), kapprox.size()); + const std::string tag = kapprox.substr(at, end - at); + if (tag == "a1") approx_a1_ = true; + else if (tag == "a2") approx_a2_ = true; + else return fail("model K: unknown k_approx " + tag + " (a1, a2)"); + at = end + 1; + } + if (c.backend < 2) return fail("model K: k_approx runs on the D3D12 devices only"); + if (approx_a1_ && !in_exact_) return fail("model K: k_approx=a1 needs the exact input kernels (k_io_exact.co)"); + if (approx_a2_ && fast_) return fail("model K: k_approx=a2 and k_fast=1 exclude each other"); + approx_note_ = std::string("model K: close approximation k_approx=") + (approx_a1_ ? "a1" : "") + + (approx_a1_ && approx_a2_ ? "," : "") + (approx_a2_ ? "a2" : "") + + " (opt-in, not bit-exact; the default path is exact)"; + } const std::string krule = option(c, "k_expo_rule"); if (!krule.empty() && krule != "spec" && krule != "v051") return fail("model K: unknown k_expo_rule " + krule + " (spec or v051)"); @@ -632,7 +656,9 @@ bool KRuntime::create(const WgRtConfig& c, Device* dev, AllocFn alloc_fn, bool e if (c.backend == 3) for (const std::string& k : d3d12_kernels()) if (!dev_->prepare(k)) return dfail(); - return smx_select(c.backend, smx_test_); + if (!smx_select(c.backend, smx_test_)) return false; + if (!approx_note_.empty()) notes_ += (notes_.empty() ? "" : "\n") + approx_note_; + return true; } // ---- the softmax weight rounding: create-time self-check (native D3D12 device) --------------------------------------- @@ -1176,6 +1202,9 @@ bool KRuntime::frame(const WgRtFrame& fr, const FrameIo* io) { kname_buf = n; } if (native_direct_ && io_kernel) kname_buf += "_direct"; + if (approx_a1_ && kname_buf.rfind("kx/k_in_tiled", 0) == 0) kname_buf += "__a1"; + if (approx_a2_ && (kname_buf.rfind("k_out_color", 0) == 0 || kname_buf.rfind("k_out_pixel_c", 0) == 0)) + kname_buf += "__a2"; return kname_buf.c_str(); }; // backend 1 (the host emulator) has no tiled input kernels; HIP (0) and the D3D12 devices (2 hybrid, 3 native) do @@ -1348,6 +1377,14 @@ std::vector KRuntime::d3d12_kernels() const { v.push_back("k_out_color" + d); if (!native_direct_) v.push_back("kx/k_in_tiled_uniform"); // (no direct form: the direct frame uses k_in_tiled_direct) v.push_back("kx/k_in_tiled" + d); // input_uniforms_safe refusing the host uniforms + if (approx_a1_) { // k_approx=a1 (opt-in) + if (!native_direct_) v.push_back("kx/k_in_tiled_uniform__a1"); + v.push_back("kx/k_in_tiled" + d + "__a1"); + } + if (approx_a2_) { // k_approx=a2 (opt-in) + v.push_back("k_out_color" + d + "__a2"); + if (compact_head_) v.push_back("k_out_pixel_c" + d + "__a2"); + } // the legacy input kernels: a render size above 0.68 x the output (up to 1.0, native AA / DLAA), a jitter outside // [-0.5, 0.5], or input_tiled=0 (k_in_reset reads buffers only: no direct form) v.push_back("kx/k_in_color" + d); @@ -1438,7 +1475,8 @@ const char* KRuntime::kernels() { " legacy_color_launches=" + std::to_string(legacy_color_launches_) + " legacy_base_launches=" + std::to_string(legacy_base_launches_) + (fast_ ? " k_fast=1" : "") + (expo_v051_ ? " k_expo_rule=v051" : "") + - smx_note_ + " hidden=fused_d0" + std::string(" head=") + (compact_head_ ? "compact" : "full") + + smx_note_ + approx_tag() + " hidden=fused_d0" + std::string(" head=") + + (compact_head_ ? "compact" : "full") + " base=" + std::to_string(Bw_) + "x" + std::to_string(Bh_) + " hdr=" + (hdr_ ? "1" : "0") + " mv=render" + " filter_level=" + std::to_string(level_last_) + diff --git a/clean/k/runtime/runtime_k.h b/clean/k/runtime/runtime_k.h index 6f5df54b..e8ba3fd7 100644 --- a/clean/k/runtime/runtime_k.h +++ b/clean/k/runtime/runtime_k.h @@ -160,8 +160,20 @@ class KRuntime { // D3D12 latency options (create: k_color_at, k_warm, k_warm_line, k_warm_groups): the stage after which k_out_color // runs unordered (empty: before the input stage, HIP's order), the stage after which k_warm runs (empty: off) std::string color_at_, warm_at_, warm_to_; - // the softmax stages run their round-to-odd (__rodd) ports: the mix-form probe failed (native D3D12 device only) + // the softmax stages run their round-to-odd (__rodd) ports (smx_select: the mix form failed the create-time + // self-check, native D3D12 device only) bool smx_rodd_ = false; + // runtime option k_approx (opt-in, D3D12 devices; never the default): close-approximation variants by tag + // ("a1": the tiled input stage on the transcendental unit, kernels kx/k_in_tiled*__a1) + bool approx_a1_ = false; + bool approx_a2_ = false; // "a2": the output stage (k_out_color, k_out_pixel_c) with KO_APPROX, kernels *__a2 + std::string approx_note_; // the note of create when k_approx is set + // " k_approx=a1[,a2]" for the kernels line, or empty + std::string approx_tag() const { + if (!approx_a1_ && !approx_a2_) return std::string(); + return std::string(" k_approx=") + (approx_a1_ ? "a1" : "") + (approx_a1_ && approx_a2_ ? "," : "") + + (approx_a2_ ? "a2" : ""); + } std::string smx_note_; std::string smx_test_; // option k_smx_test (developer builds only) std::string notes_; // notes of create for the caller's log (notes()), one per line, or empty diff --git a/clean/k/tests/test_k_runtime_d3d12.py b/clean/k/tests/test_k_runtime_d3d12.py index a77397dd..38887f59 100644 --- a/clean/k/tests/test_k_runtime_d3d12.py +++ b/clean/k/tests/test_k_runtime_d3d12.py @@ -29,6 +29,8 @@ in both e4 / d4 shapes (1440p Quality: NG = 4; 4K Performance: NG = 2); with both forms failed, or with a corrupt stage shader (a softmax stage's __rodd port, the fixed-weight stage e0), create refuses in one line. Each create leg runs in its own process. The hook exists only in a runtime library built with clean/runner/build.py --dev-diagnostics: these tests skip on another build. +k_approx (opt-in close approximations): refused on HIP and for an unknown tag; with a1,a2 its __a1 / __a2 kernels run, one +note of create says so, and the output stays within loose bounds of the exact path's (tone-mapped luma PSNR). GPU only: WG_K_GPU_BUILD=, ROCM_PATH; run each test under the @@ -55,6 +57,19 @@ write_k_model) OUT, MAX_RENDER = (200, 120), (130, 78) +# k_approx=a1,a2 against the exact path on the synthetic model (test_native_k_approx_close): wide bounds; the random +# synthetic network (random parameters) amplifies small input differences strongly +# measured (RX 9070 XT, 3 frames at 1440p Quality): at most 17.4 % of the values differ, PSNR 54.7 .. 55.7 dB +APPROX_MAX_DIFFER, APPROX_MIN_PSNR = 0.35, 45.0 + + +def tonemapped_psnr(a, b): + """PSNR (dB) of the tone-mapped luma T = Y / (1 + Y) of two linear RGB arrays [n, 3] (the spec side's closeness + measure; Y = max(0.2126 R + 0.7152 G + 0.0722 B, 0)).""" + w = np.array([0.2126, 0.7152, 0.0722]) + ya, yb = np.maximum(a.astype(np.float64) @ w, 0), np.maximum(b.astype(np.float64) @ w, 0) + mse = float(np.mean((ya / (1 + ya) - yb / (1 + yb)) ** 2)) + return float("inf") if mse == 0 else 10 * np.log10(1 / mse) # written in full by every frame: compared raw with a sentinel before the frame (the head buffer is added per frame) WRITTEN = ["exposure.pair", "k.scalars", "k.x0", "k.S0", "k.S1", "k.S2", "k.S3", "k.S4", "k.A", "k.B", "k.ctap", "k.ctapT"] @@ -356,6 +371,51 @@ def test_native_fallback_frames_4k_performance(self): self.check_fallback_frames([(1920, 1080, True, 1.0, 1.0), (1920, 1080, False, 1.0, 1.0)], True, out=(3840, 2160), max_render=(1920, 1080)) + # ---- k_approx: the opt-in close approximations (never the default) -------------------------------------------- + def test_k_approx_refusals(self): + """k_approx runs on the D3D12 devices only (HIP refuses it) and takes only its known tags.""" + with self.assertRaises(RuntimeError) as cm: + self.make(0, True, False, "k_approx=a1", OUT, MAX_RENDER) + self.assertIn("D3D12 devices only", str(cm.exception)) + bad = self.leg("k_approx=a3") + self.assertFalse(bad["ok"], bad) + self.assertIn("unknown k_approx a3", bad["error"]) + plain = self.leg("") + self.assertEqual(plain["notes"], []) # nothing set: the exact path, no note + + def test_native_k_approx_close(self): + """k_approx=a1,a2: its __a1 / __a2 kernels run, one note of create says so, and the output stays close to the + exact path's (the bounds are wide of the measured values; the image-quality scoring is the spec side's).""" + got = self.leg("k_approx=a1,a2") + self.assertTrue(got["ok"], got) + self.assertEqual(len(got["notes"]), 1, got) + self.assertIn("close approximation k_approx=a1,a2", got["notes"][0]) + out, mr = self.QUALITY["out"], self.QUALITY["max_render"] + ex = self.make(3, True, False, "", out, mr) + ap = self.make(3, True, False, "k_approx=a1,a2", out, mr) + pos = os.path.getsize(TRACE) if os.path.exists(TRACE) else 0 + try: + for i, fr in enumerate(self.FRAMES_Q): + rw, rh, reset, E, pi = fr[:5] + x = inputs(np.random.default_rng(500 + i), rw, rh, True, reset) + x["pre_exposure"], x["E_cur"] = pi, float(np.float32(E)) + ex.frame(x, 0, half=True) + ap.frame(x, 0, half=True) + a = np.frombuffer(out_bytes(ex, True), np.float16).reshape(-1, 4)[:, :3].astype(np.float32) + b = np.frombuffer(out_bytes(ap, True), np.float16).reshape(-1, 4)[:, :3].astype(np.float32) + self.assertTrue(np.isfinite(b).all(), "frame %d: non-finite approximate output" % i) + differ = float(np.mean(a != b)) + psnr = tonemapped_psnr(a, b) + print("k_approx frame %d: differ %.4f psnr %.2f dB" % (i, differ, psnr)) + self.assertLess(differ, APPROX_MAX_DIFFER, "frame %d" % i) + self.assertGreater(psnr, APPROX_MIN_PSNR, "frame %d" % i) + lines, _ = trace_since(pos) + ran = {ln.split()[0] for ln in lines if ln.split()} + self.assertTrue(any(k.endswith("__a1") for k in ran), sorted(ran)) + self.assertTrue(any(k.endswith("__a2") for k in ran), sorted(ran)) + finally: + del ex, ap + def test_input_copy_frames_refused_on_d3d12(self): """raw_inputs (the interop's HIP input copies) has no checked D3D12 port: refused, not run unchecked.""" for backend in (2, 3): From b9b731afc4203eb6c22147d13c5c2f0ecdd2093d Mon Sep 17 00:00:00 2001 From: phantoslayer21 <156617979+phantoslayer21@users.noreply.github.com> Date: Mon, 16 Nov 2026 03:02:32 -0500 Subject: [PATCH 2/4] k_approx: prepare only the selected forms, native device only, consistent a2, one-line refusals - Native create already prepares (and digest-checks) exactly the kernels the context can select, the __a1 / __a2 forms only when selected. The D3D12 executor now skips its own warm-up for a runtime that did (runtime_prepared_kernels): that warm-up compiled every kernel of the build, so an unusable unselected approximate shader refused every default context. - k_approx runs on the native D3D12 device only; the hybrid device (backend 2) is refused as HIP is. - a2 needs the compact head: with k_head=full, k_out_pixel has no a2 form, so the combination is refused at create instead of running a mixed output stage. - An empty value (k_approx=) and an empty list item are refused; values in refusals are shown on one line (control characters as '?'). - The executor's mode line names k_approx and calls the mode an approximation. Tests: test_k_runtime_d3d12.py k_approx tests rewritten (refusals on both other devices and every malformed value, each tag's note and kernels-line field, the self-check fallback with k_approx, per-frame kernel selection with negative controls, closeness with differ > 0, a changed approximate shader selected and not); test_k_approx_executor.py (new): the interop matrix with a changed a2 shader, selected and not, and the mode line. README: the k_approx section matches (no figures without a record). Signed-off-by: phantoslayer21 <156617979+phantoslayer21@users.noreply.github.com> --- clean/k/dx12/README.md | 24 ++-- clean/k/runtime/runtime_k.cpp | 40 +++++- clean/k/runtime/runtime_k.h | 6 +- clean/k/tests/test_k_approx_executor.py | 108 ++++++++++++++++ clean/k/tests/test_k_runtime_d3d12.py | 154 ++++++++++++++++++----- clean/runtime/interop/backend.cpp | 6 +- clean/runtime/interop/executor_d3d12.cpp | 4 +- clean/runtime/runtime.cpp | 2 + clean/runtime/runtime_core.h | 3 + 9 files changed, 299 insertions(+), 48 deletions(-) create mode 100644 clean/k/tests/test_k_approx_executor.py diff --git a/clean/k/dx12/README.md b/clean/k/dx12/README.md index 2bd9a7a0..80c0dc2d 100644 --- a/clean/k/dx12/README.md +++ b/clean/k/dx12/README.md @@ -116,17 +116,23 @@ Known limit, shared with Model M's ports: D3D12 flushes FP32 denormals (inputs a ## Close approximations (runtime option `k_approx`, opt-in) Every port above is exact, and nothing set is the exact path. `k_approx` selects close approximations of two stages on -the D3D12 devices (HIP refuses the option); they are judged by image quality against the exact path, not byte for byte, -and taking one adds a note of create. +the native D3D12 device (HIP and the hybrid device refuse the option); they are judged by image quality against the +exact path, not byte for byte, and taking one adds a note of create. - `a1`, the tiled input stage (`kx/k_in_tiled*__a1`, `hlsl/k_in_common.hlsli` `KI_HWMATH`): its correctly rounded log2, 2^x and divisions (FP32 double-word arithmetic with a Ziv test and a binary64 fallback) become `v_log_f32`, - `v_exp_f32` (about 1 FP32 ulp) and `v_rcp_f32` times the dividend (scaled for |b| >= 2^126). On the port-check input - family the network input x0 differs from exact in about 1e-5 of its FP16 values, always by one FP16 ulp. + `v_exp_f32` (about 1 FP32 ulp) and `v_rcp_f32` times the dividend (scaled for |b| >= 2^126). Frames that take the + legacy input kernels (a render size above 0.68 x the output, a jitter outside [-0.5, 0.5], `input_tiled=0`) run the + exact input stage. - `a2`, the output stage (`k_out_color*__a2`, `k_out_pixel_c*__a2`, `hlsl/k_out.hlsli` `KO_APPROX`): its exact divisions become `v_rcp_f32` times the dividend plus one correction of the quotient from its exact residual, and two refined - reciprocals drop their Newton step; every opaque barrier stays. On the port-check output family (plain and - special-value inputs) every FP16 output is within one ulp of exact. - -`k_approx=a1,a2` takes both. `test_k_runtime_d3d12.py` (`test_k_approx_refusals`, `test_native_k_approx_close`) checks -the refusals, the note, that the `__a1` / `__a2` kernels run, and loose closeness bounds on the synthetic model. + reciprocals drop their Newton step; every opaque barrier stays. It needs the compact head (`k_head=compact`, the + default): the full head's `k_out_pixel` has no `a2` form. + +`k_approx=a1,a2` takes both. Create refuses, in one line, an empty value or list item, an unknown tag, `a1` without the +exact input kernels, and `a2` with `k_fast=1` or `k_head=full`. It prepares the `__a1` / `__a2` forms (and checks their +manifest digests) only when they are selected, and the D3D12 executor runs no warm-up of its own for model K, so an +unusable approximate shader cannot affect a context that does not select it. `test_k_runtime_d3d12.py` +(`test_k_approx_*`, `test_native_k_approx_frames`) checks the refusals, the notes, the per-frame kernel selection and +loose closeness bounds on the synthetic model; `test_k_approx_executor.py` checks the executor with a changed +approximate shader, selected and not. diff --git a/clean/k/runtime/runtime_k.cpp b/clean/k/runtime/runtime_k.cpp index 8b080ec1..c16e9a4d 100644 --- a/clean/k/runtime/runtime_k.cpp +++ b/clean/k/runtime/runtime_k.cpp @@ -355,6 +355,25 @@ std::string stage_kernel_base(const KStageInfo& st, bool f16, bool has_y, int nw // is refused with k_fast=1 or k_fast_in=1), k_expo_rule (spec, the default: spec 42 draft 3 section 4, E_cur = the // game's exposure or 1, E_aux = the auto-exposure value; v051: opt-in, for A/B only, the 0.5.1 rule E_cur = E_aux = // the auto-exposure value when it runs). +// whether key= appears in the runtime options or WG_RUNTIME_OPTIONS (also with an empty value) +bool option_given(const WgRtConfig& c, const std::string& key) { + const char* env = std::getenv("WG_RUNTIME_OPTIONS"); + const std::string text = std::string(c.runtime_options ? c.runtime_options : "") + ";" + (env ? env : ""); + for (size_t a = 0; a <= text.size();) { + size_t b = text.find(';', a); + if (b == std::string::npos) b = text.size(); + if (text.compare(a, key.size() + 1, key + "=") == 0) return true; + a = b + 1; + } + return false; +} +// a value for a one-line message: control characters as '?' +std::string one_line(std::string v) { + for (char& ch : v) + if ((unsigned char)ch < 32 || ch == 127) ch = '?'; + return v; +} + std::string option(const WgRtConfig& c, const std::string& key) { const char* env = std::getenv("WG_RUNTIME_OPTIONS"); const std::string text = std::string(c.runtime_options ? c.runtime_options : "") + ";" + (env ? env : ""); @@ -477,21 +496,28 @@ bool KRuntime::create(const WgRtConfig& c, Device* dev, AllocFn alloc_fn, bool e // on the transcendental unit (kernels kx/k_in_tiled*__a1; clean/k/dx12/hlsl/k_in_common.hlsli KI_HWMATH). // "a2": the output stage's divisions on v_rcp_f32 with one quotient correction and two reciprocals without their // Newton step (kernels k_out_color*__a2, k_out_pixel_c*__a2; clean/k/dx12/hlsl/k_out.hlsli KO_APPROX). A comma list - // selects several. D3D12 devices only (HIP refuses); taking one adds a note of create (not bit-exact). - const std::string kapprox = option(c, "k_approx"); - if (!kapprox.empty()) { + // selects several. The native D3D12 device only (HIP and the hybrid device refuse); taking one adds a note of create + // (not bit-exact). + if (option_given(c, "k_approx")) { + const std::string kapprox = option(c, "k_approx"); + if (kapprox.empty()) return fail("model K: k_approx is empty (a1, a2 or a1,a2)"); size_t at = 0; while (at <= kapprox.size()) { const size_t end = std::min(kapprox.find(',', at), kapprox.size()); const std::string tag = kapprox.substr(at, end - at); if (tag == "a1") approx_a1_ = true; else if (tag == "a2") approx_a2_ = true; - else return fail("model K: unknown k_approx " + tag + " (a1, a2)"); + else if (tag.empty()) return fail("model K: k_approx has an empty item: " + one_line(kapprox) + " (a1, a2)"); + else return fail("model K: unknown k_approx " + one_line(tag) + " (a1, a2)"); at = end + 1; } - if (c.backend < 2) return fail("model K: k_approx runs on the D3D12 devices only"); + // the native D3D12 device only: it prepares the selected forms at create and refuses the fast input stage; the + // hybrid device (backend 2) and HIP are refused + if (c.backend != 3) return fail("model K: k_approx runs on the native D3D12 device only"); if (approx_a1_ && !in_exact_) return fail("model K: k_approx=a1 needs the exact input kernels (k_io_exact.co)"); if (approx_a2_ && fast_) return fail("model K: k_approx=a2 and k_fast=1 exclude each other"); + // a2 has forms of k_out_color and k_out_pixel_c only: the full head's k_out_pixel would stay exact + if (approx_a2_ && !compact_head_) return fail("model K: k_approx=a2 needs the compact head (k_head=compact, the default)"); approx_note_ = std::string("model K: close approximation k_approx=") + (approx_a1_ ? "a1" : "") + (approx_a1_ && approx_a2_ ? "," : "") + (approx_a2_ ? "a2" : "") + " (opt-in, not bit-exact; the default path is exact)"; @@ -653,9 +679,11 @@ bool KRuntime::create(const WgRtConfig& c, Device* dev, AllocFn alloc_fn, bool e if (!dev_->sync()) return dfail(); // the native device prepares (loads, verifies and compiles) every kernel this context can select now: a missing or // corrupt shader fails create here, not at the first frame - if (c.backend == 3) + if (c.backend == 3) { for (const std::string& k : d3d12_kernels()) if (!dev_->prepare(k)) return dfail(); + prepared_ = true; + } if (!smx_select(c.backend, smx_test_)) return false; if (!approx_note_.empty()) notes_ += (notes_.empty() ? "" : "\n") + approx_note_; return true; diff --git a/clean/k/runtime/runtime_k.h b/clean/k/runtime/runtime_k.h index e8ba3fd7..5629e99f 100644 --- a/clean/k/runtime/runtime_k.h +++ b/clean/k/runtime/runtime_k.h @@ -83,6 +83,9 @@ class KRuntime { const std::string& err() const { return err_; } // notes of create for the caller's log (wg_rt_notes), one per line, or empty: the round-to-odd softmax ports const std::string& notes() const { return notes_; } + // true when create prepared every kernel this context can select (the native D3D12 device): the caller then + // prepares nothing more (the executor's warm_up would also compile kernels the context never runs) + bool prepared() const { return prepared_; } const std::string& model_path() const { return model_path_; } // What the timing marks 0..4 bracket (FrameIo.timing_base): "exposure", "input", "network", "output". static const char* const kTimingLabels[4]; @@ -163,7 +166,7 @@ class KRuntime { // the softmax stages run their round-to-odd (__rodd) ports (smx_select: the mix form failed the create-time // self-check, native D3D12 device only) bool smx_rodd_ = false; - // runtime option k_approx (opt-in, D3D12 devices; never the default): close-approximation variants by tag + // runtime option k_approx (opt-in, the native D3D12 device; never the default): close-approximation variants by tag // ("a1": the tiled input stage on the transcendental unit, kernels kx/k_in_tiled*__a1) bool approx_a1_ = false; bool approx_a2_ = false; // "a2": the output stage (k_out_color, k_out_pixel_c) with KO_APPROX, kernels *__a2 @@ -177,6 +180,7 @@ class KRuntime { std::string smx_note_; std::string smx_test_; // option k_smx_test (developer builds only) std::string notes_; // notes of create for the caller's log (notes()), one per line, or empty + bool prepared_ = false; // prepared() unsigned warm_line_ = 128, warm_groups_ = 64; DevPtr warm_dummy_ = 0; WgRtFrameInfo info_ = {}; diff --git a/clean/k/tests/test_k_approx_executor.py b/clean/k/tests/test_k_approx_executor.py new file mode 100644 index 00000000..02d765e5 --- /dev/null +++ b/clean/k/tests/test_k_approx_executor.py @@ -0,0 +1,108 @@ +# SPDX-License-Identifier: MIT +"""GPU/D3D12: the executor prepares only the kernels model K selected, so an opt-in form that is not selected cannot +affect a default context. + +A copy of the runtime build with one byte changed in k_out_pixel_c__a2.dxil and k_out_pixel_c_direct__a2.dxil (the +k_approx=a2 output form; the executor runs the direct one) runs +test_interop_d3d12.exe's `matrix` case at 1080p (every usual upscaler-mode ratio, HDR and LDR, both declared maximum +sizes): with nothing set every context is taken by the D3D12 executor and its frame runs (the executor's warm-up does not +compile the unselected form) and its mode line names the exact path; with k_approx=a2 every context is refused, naming +the shader. The unchanged build passes with k_approx=a2 (control: the refusal comes from the changed byte) and its mode +line names k_approx=a2 and an approximation. + +Set WG_K_GPU_BUILD (a runtime build with dx12/) and WG_K_INTEROP_EXE (test_interop_d3d12.exe); run under the shared GPU +lock. Only synthetic parameters (random_network_params). + +Run: python -m unittest clean.k.tests.test_k_approx_executor +""" +import os +from pathlib import Path +import shutil +import subprocess +import tempfile +import unittest + +from clean.k.reference.network import random_network_params +from clean.k.tests.test_k_runtime_gpu import gpu_build, write_k_model + +# the k_approx=a2 output form: the buffer form and the direct form the executor runs (textures) +VICTIMS = ("k_out_pixel_c__a2", "k_out_pixel_c_direct__a2") + + +def copy_build(src, dst): + """The runtime build's files and its dx12 folder (not its test model folders).""" + for f in os.listdir(src): + p = os.path.join(src, f) + if os.path.isfile(p): + shutil.copy2(p, dst) + shutil.copytree(os.path.join(src, "dx12"), os.path.join(dst, "dx12")) + + +def mode_lines(out): + return [ln for ln in out.splitlines() if "network model K mode:" in ln] + + +class TestKApproxExecutor(unittest.TestCase): + def setUp(self): + self.exe = os.environ.get("WG_K_INTEROP_EXE") + if not self.exe: + self.skipTest("set WG_K_INTEROP_EXE to the clean native interop test") + self.build = Path(gpu_build()).resolve() + for v in VICTIMS: + if not (self.build / "dx12" / (v + ".dxil")).exists(): + self.skipTest("no %s.dxil in WG_K_GPU_BUILD (build_dx12.py --model-k)" % v) + + def matrix(self, build, model_dir, model, modelmap, extra): + opts = ";".join(["model=K", f"kernels_dir={build}", f"model_dir={model_dir}", + f"model_k_dir={Path(model).parent}", f"model_k_map={modelmap}"] + extra) + env = os.environ.copy() + env.pop("WG_RUNTIME_OPTIONS", None) + p = subprocess.run([self.exe, str(Path(build) / "wronggpu_runtime.dll"), "matrix", opts, "1080"], + capture_output=True, text=True, timeout=900, env=env) + return p.returncode, p.stdout + p.stderr + + def run_case(self, corrupt, extra): + """One matrix run on the build (corrupt: on a copy with one byte of the victim shader changed).""" + with tempfile.TemporaryDirectory(prefix="k-approx-exe-") as td: + model, modelmap = write_k_model(os.path.join(td, "model"), random_network_params(11)) + build = str(self.build) + if corrupt: + build = os.path.join(td, "build") + os.makedirs(build) + copy_build(str(self.build), build) + for v in VICTIMS: + path = os.path.join(build, "dx12", v + ".dxil") + data = bytearray(Path(path).read_bytes()) + data[len(data) // 2] ^= 0x40 + Path(path).write_bytes(bytes(data)) + return self.matrix(build, td, model, modelmap, extra) + + def test_selected_form_runs(self): + """Control: the unchanged build takes k_approx=a2 in every context; the mode log names the approximation.""" + rc, out = self.run_case(False, ["k_approx=a2"]) + self.assertEqual(rc, 0, out) + self.assertTrue(out.rstrip().endswith("PASS"), out) + modes = mode_lines(out) + self.assertEqual(len(modes), 20, modes) + self.assertTrue(all(";k_approx=a2;" in m and "an approximation (not bit-exact)" in m for m in modes), modes) + + def test_unselected_form_is_not_prepared(self): + """The changed shader, nothing set: every context runs on the exact path (the warm-up skips the form).""" + rc, out = self.run_case(True, []) + self.assertEqual(rc, 0, out) + self.assertTrue(out.rstrip().endswith("PASS"), out) + self.assertNotIn("integrity mismatch", out) + modes = mode_lines(out) + self.assertEqual(len(modes), 20, modes) + self.assertTrue(all("k_approx" not in m and "the exact path" in m for m in modes), modes) + + def test_selected_changed_form_is_refused(self): + """The changed shader, k_approx=a2: every context is refused, naming the shader.""" + rc, out = self.run_case(True, ["k_approx=a2"]) + self.assertNotEqual(rc, 0, out) + self.assertEqual(out.count("could not take this context"), 20, out[-3000:]) + self.assertIn("integrity mismatch: " + VICTIMS[1], out) + self.assertNotIn("ready dx12 1", out) + +if __name__ == "__main__": + unittest.main() diff --git a/clean/k/tests/test_k_runtime_d3d12.py b/clean/k/tests/test_k_runtime_d3d12.py index 38887f59..ac5e285a 100644 --- a/clean/k/tests/test_k_runtime_d3d12.py +++ b/clean/k/tests/test_k_runtime_d3d12.py @@ -343,9 +343,11 @@ def test_native_softmax_refusals(self): shutil.copy2(src, tmp) shutil.copytree(os.path.join(self.build, "dx12"), os.path.join(tmp, "dx12")) path = os.path.join(tmp, "dx12", victim + ".dxil") - data = bytearray(open(path, "rb").read()) + with open(path, "rb") as f: + data = bytearray(f.read()) data[len(data) // 2] ^= 0x40 - open(path, "wb").write(bytes(data)) + with open(path, "wb") as f: + f.write(bytes(data)) bad = self.leg("", build=tmp) self.assertFalse(bad["ok"], bad) self.assertIn(victim, bad["error"]) @@ -373,23 +375,112 @@ def test_native_fallback_frames_4k_performance(self): # ---- k_approx: the opt-in close approximations (never the default) -------------------------------------------- def test_k_approx_refusals(self): - """k_approx runs on the D3D12 devices only (HIP refuses it) and takes only its known tags.""" - with self.assertRaises(RuntimeError) as cm: - self.make(0, True, False, "k_approx=a1", OUT, MAX_RENDER) - self.assertIn("D3D12 devices only", str(cm.exception)) - bad = self.leg("k_approx=a3") - self.assertFalse(bad["ok"], bad) - self.assertIn("unknown k_approx a3", bad["error"]) + """k_approx runs on the native D3D12 device only (HIP and the hybrid device refuse it), takes only its known + tags, refuses an empty value or list item and a2 with the full head; every refusal is one line. Nothing set: + a successful create on the exact path (no note, no k_approx in the kernels line).""" + for backend in (0, 2): + with self.subTest(backend=backend): + with self.assertRaises(RuntimeError) as cm: + self.make(backend, True, False, "k_approx=a1", OUT, MAX_RENDER) + self.assertIn("native D3D12 device only", str(cm.exception)) + self.assertNotIn("\n", str(cm.exception).strip()) + refusals = {"k_approx=": "k_approx is empty", "k_approx=a1,": "empty item", "k_approx=,a2": "empty item", + "k_approx=a1,,a2": "empty item", "k_approx=a3": "unknown k_approx a3", + "esc:k_approx=a\\x01b": "unknown k_approx a?b", "k_approx=a2;k_head=full": "compact head"} + for options, why in refusals.items(): + with self.subTest(options=options): + got = self.leg(options) + self.assertFalse(got["ok"], got) + self.assertIn(why, got["error"]) + self.assertNotIn("\n", got["error"].strip()) plain = self.leg("") - self.assertEqual(plain["notes"], []) # nothing set: the exact path, no note + self.assertTrue(plain["ok"], plain) + self.assertEqual((plain["smx"], plain["notes"], plain["k_approx"]), ("mix", [], "")) + + def test_k_approx_each_tag(self): + """a1, a2 and a1,a2 each create, report themselves in the kernels line and add exactly one note; with the + self-check's fallback forced the approximation still applies (two notes), and with both forms failed create + refuses.""" + for tags in ("a1", "a2", "a1,a2"): + with self.subTest(tags=tags): + got = self.leg("k_approx=" + tags) + self.assertTrue(got["ok"], got) + self.assertEqual(got["k_approx"], tags) + self.assertEqual(len(got["notes"]), 1, got) + self.assertIn("close approximation k_approx=" + tags, got["notes"][0]) + self.need_dev_build() + fb = self.leg("k_approx=a1,a2;k_smx_test=mix_fail") + self.assertTrue(fb["ok"], fb) + self.assertEqual((fb["smx"], fb["k_approx"]), ("rodd(hook)", "a1,a2")) + self.assertEqual(len(fb["notes"]), 2, fb) + bad = self.leg("k_approx=a1,a2;k_smx_test=both_fail") + self.assertFalse(bad["ok"], bad) + self.assertIn("not exact on this driver", bad["error"]) - def test_native_k_approx_close(self): - """k_approx=a1,a2: its __a1 / __a2 kernels run, one note of create says so, and the output stays close to the - exact path's (the bounds are wide of the measured values; the image-quality scoring is the spec side's).""" - got = self.leg("k_approx=a1,a2") - self.assertTrue(got["ok"], got) - self.assertEqual(len(got["notes"]), 1, got) - self.assertIn("close approximation k_approx=a1,a2", got["notes"][0]) + def test_k_approx_shaders_prepared_only_when_selected(self): + """An unusable approximate shader cannot affect the default: with nothing set create succeeds (the unselected + forms are never prepared); selecting that form refuses create in one line naming it.""" + import shutil + import tempfile + for victim, tag in (("k_out_pixel_c__a2", "a2"), ("kx__k_in_tiled__a1", "a1")): + with self.subTest(victim=victim): + tmp = tempfile.mkdtemp(prefix="k_approx_corrupt_") + try: + for f in os.listdir(self.build): + src = os.path.join(self.build, f) + if os.path.isfile(src): + shutil.copy2(src, tmp) + shutil.copytree(os.path.join(self.build, "dx12"), os.path.join(tmp, "dx12")) + path = os.path.join(tmp, "dx12", victim + ".dxil") + with open(path, "rb") as f: + data = bytearray(f.read()) + data[len(data) // 2] ^= 0x40 + with open(path, "wb") as f: + f.write(bytes(data)) + plain = self.leg("", build=tmp) + self.assertTrue(plain["ok"], plain) + self.assertEqual(plain["k_approx"], "") + sel = self.leg("k_approx=" + tag, build=tmp) + self.assertFalse(sel["ok"], sel) + self.assertIn(victim.replace("kx__", "kx/"), sel["error"]) + self.assertNotIn("\n", sel["error"].strip()) + finally: + shutil.rmtree(tmp, ignore_errors=True) + + def frame_kernels(self, rt, x, lines_from): + """One frame of rt; the kernels it launched (launch trace).""" + rt.frame(x, 0, half=True) + lines, pos = trace_since(lines_from) + return {ln.split()[0] for ln in lines if ln.split() and ln.split()[-1] == "d3d12"}, pos + + def check_variant(self, ran, approx): + """The output stage ran its a2 forms (approx) or its exact forms only; a tiled input stage its a1 form or the + exact one. Raises AssertionError otherwise.""" + tiled = [k for k in ran if k.startswith("kx/k_in_tiled")] + if approx: + self.assertIn("k_out_pixel_c__a2", ran) + self.assertNotIn("k_out_pixel_c", ran) + self.assertTrue(tiled and all(k.endswith("__a1") for k in tiled), sorted(ran)) + else: + self.assertFalse([k for k in ran if k.endswith(("__a1", "__a2"))], sorted(ran)) + self.assertIn("k_out_pixel_c", ran) + + def check_close(self, a, b): + """The approximate output differs from the exact one (it is not the exact path in disguise) and stays within + loose bounds (tone-mapped luma PSNR).""" + differ = float(np.mean(a != b)) + psnr = tonemapped_psnr(a, b) + self.assertGreater(differ, 0.0, "the approximate output is identical to the exact output") + self.assertLess(differ, APPROX_MAX_DIFFER) + self.assertGreater(psnr, APPROX_MIN_PSNR) + return differ, psnr + + def test_native_k_approx_frames(self): + """k_approx=a1,a2 against nothing set, frame by frame (1440p Quality, a reset, steady frames and a smaller + render size): every approximate frame runs the a1 tiled input and the a2 output forms and no exact one, every + default frame none of them; the approximate output differs from the exact one and stays within loose bounds. + Negative controls: the variant check fails on a default frame, the closeness check on identical outputs and on + a perturbed output.""" out, mr = self.QUALITY["out"], self.QUALITY["max_render"] ex = self.make(3, True, False, "", out, mr) ap = self.make(3, True, False, "k_approx=a1,a2", out, mr) @@ -399,20 +490,21 @@ def test_native_k_approx_close(self): rw, rh, reset, E, pi = fr[:5] x = inputs(np.random.default_rng(500 + i), rw, rh, True, reset) x["pre_exposure"], x["E_cur"] = pi, float(np.float32(E)) - ex.frame(x, 0, half=True) - ap.frame(x, 0, half=True) + ran_ex, pos = self.frame_kernels(ex, x, pos) + ran_ap, pos = self.frame_kernels(ap, x, pos) + self.check_variant(ran_ex, False) + self.check_variant(ran_ap, True) + with self.assertRaises(AssertionError): # negative control: a default frame is not an approximate one + self.check_variant(ran_ex, True) a = np.frombuffer(out_bytes(ex, True), np.float16).reshape(-1, 4)[:, :3].astype(np.float32) b = np.frombuffer(out_bytes(ap, True), np.float16).reshape(-1, 4)[:, :3].astype(np.float32) self.assertTrue(np.isfinite(b).all(), "frame %d: non-finite approximate output" % i) - differ = float(np.mean(a != b)) - psnr = tonemapped_psnr(a, b) + differ, psnr = self.check_close(a, b) print("k_approx frame %d: differ %.4f psnr %.2f dB" % (i, differ, psnr)) - self.assertLess(differ, APPROX_MAX_DIFFER, "frame %d" % i) - self.assertGreater(psnr, APPROX_MIN_PSNR, "frame %d" % i) - lines, _ = trace_since(pos) - ran = {ln.split()[0] for ln in lines if ln.split()} - self.assertTrue(any(k.endswith("__a1") for k in ran), sorted(ran)) - self.assertTrue(any(k.endswith("__a2") for k in ran), sorted(ran)) + with self.assertRaises(AssertionError): # negative controls of the closeness check + self.check_close(a, a.copy()) + with self.assertRaises(AssertionError): + self.check_close(a, a * 1.5 + 0.25) finally: del ex, ap @@ -438,17 +530,21 @@ def test_input_copy_frames_refused_on_d3d12(self): def softmax_leg(mdir, map_path, options, build): """Child of the softmax tests: one native create; prints ok, the smx field, the notes and the error as JSON.""" + if options.startswith("esc:"): # escapes for values a command line cannot carry (control characters) + options = options[4:].encode().decode("unicode_escape") try: rt = KRuntimeExt(build, mdir, map_path, OUT, MAX_RENDER, True, False, False, options, backend=3) except RuntimeError as e: - print(json.dumps({"ok": False, "smx": "", "notes": [], "error": str(e)})) + print(json.dumps({"ok": False, "smx": "", "notes": [], "k_approx": "", "error": str(e)})) return rt.lib.wg_rt_notes.argtypes = [ctypes.c_void_p] rt.lib.wg_rt_notes.restype = ctypes.c_char_p kern = rt.lib.wg_rt_kernels(rt.rt).decode().split() smx = [kv.split("=", 1)[1] for kv in kern if kv.startswith("smx=")] + approx = [kv.split("=", 1)[1] for kv in kern if kv.startswith("k_approx=")] notes = [n for n in rt.lib.wg_rt_notes(rt.rt).decode().split("\n") if n] - print(json.dumps({"ok": True, "smx": smx[0] if smx else "", "notes": notes, "error": ""})) + print(json.dumps({"ok": True, "smx": smx[0] if smx else "", "notes": notes, "k_approx": approx[0] if approx else "", + "error": ""})) if __name__ == "__main__": diff --git a/clean/runtime/interop/backend.cpp b/clean/runtime/interop/backend.cpp index ac65392d..4efe2ebe 100644 --- a/clean/runtime/interop/backend.cpp +++ b/clean/runtime/interop/backend.cpp @@ -798,9 +798,11 @@ class Context { "(model K runs its render-resolution motion variant on it)" : "")); const std::string net = option_value(n_rtopts_, "network"), fast = option_value(n_rtopts_, "k_fast"); - const bool exact = (net.empty() || net == "fused") && fast != "1"; + const std::string approx = option_value(n_rtopts_, "k_approx"); // the opt-in close approximations + const bool exact = (net.empty() || net == "fused") && fast != "1" && approx.empty(); say(WG_LOG_INFO, std::string("network model K mode: network=") + (net.empty() ? "fused" : net) + ";k_fast=" + - (fast.empty() ? "0" : fast) + ";handover=" + (staged_out_ ? "staged" : "fence") + + (fast.empty() ? "0" : fast) + (approx.empty() ? std::string() : ";k_approx=" + approx) + + ";handover=" + (staged_out_ ? "staged" : "fence") + (exact ? ", the exact path" : ", an approximation (not bit-exact)") + (k_default_ ? " (the default mode; network=fused8;k_fast=1;handover=staged selects the " "fastest mode)" diff --git a/clean/runtime/interop/executor_d3d12.cpp b/clean/runtime/interop/executor_d3d12.cpp index 0c89f668..204942e6 100644 --- a/clean/runtime/interop/executor_d3d12.cpp +++ b/clean/runtime/interop/executor_d3d12.cpp @@ -158,7 +158,9 @@ class D3d12Executor : public Executor { rt_ = wgrt::runtime_create(c, std::move(dev), err, true, true); if (!rt_) return *err = "D3D12 runtime: " + *err, false; ext_ = wgrt::d3d12_ext(wgrt::runtime_device(rt_)); - if (!ext_->warm_up(&e) || !wgrt::runtime_device(rt_)->sync()) + // model K prepared exactly the kernels its context can select at create; warm_up would also compile the others + // (unselected opt-in forms among them), so it runs only for a runtime that did not prepare its own + if (!(wgrt::runtime_prepared_kernels(rt_) || ext_->warm_up(&e)) || !wgrt::runtime_device(rt_)->sync()) return *err = "D3D12 executor: " + (e.empty() ? wgrt::runtime_device(rt_)->err() : e), false; return true; } diff --git a/clean/runtime/runtime.cpp b/clean/runtime/runtime.cpp index 8131f852..29e19ea2 100644 --- a/clean/runtime/runtime.cpp +++ b/clean/runtime/runtime.cpp @@ -3194,8 +3194,10 @@ const char* runtime_notes(Runtime* rt) { return rt->notes_text.c_str(); } uint64_t runtime_memory_bytes(Runtime* rt) { return rt->owned_bytes; } #ifdef WG_NO_MODEL_K const char* runtime_timing_info(Runtime*) { return nullptr; } +bool runtime_prepared_kernels(Runtime*) { return false; } #else const char* runtime_timing_info(Runtime* rt) { return rt->k ? KRuntime::timing_info() : nullptr; } +bool runtime_prepared_kernels(Runtime* rt) { return rt->k && rt->k->prepared(); } #endif const char* const* runtime_timing_labels(Runtime* rt) { static const char* const kM[4] = {"enc0", "Swin", "dec0", "post"}; diff --git a/clean/runtime/runtime_core.h b/clean/runtime/runtime_core.h index 86781a89..19225c46 100644 --- a/clean/runtime/runtime_core.h +++ b/clean/runtime/runtime_core.h @@ -110,6 +110,9 @@ const char* runtime_model(Runtime* rt); // exposure, input, network, output) and, for model K, a description for the log (null for model M). const char* const* runtime_timing_labels(Runtime* rt); const char* runtime_timing_info(Runtime* rt); +// Whether create already prepared every kernel this context can select (model K on the native D3D12 device): the +// executor then skips its warm_up, which would compile every kernel of the loaded code objects, the unselected ones too. +bool runtime_prepared_kernels(Runtime* rt); // Whether cfg (recon_output) or the environment (WG_RECON_SIZE=output) asks for the experimental D = O. bool recon_output_requested(const WgRtConfig& cfg); From 6723545b9df6cedef53177e7ebb19c1fe7b89723 Mon Sep 17 00:00:00 2001 From: phantoslayer21 <156617979+phantoslayer21@users.noreply.github.com> Date: Mon, 16 Nov 2026 04:28:56 -0500 Subject: [PATCH 3/4] k_approx=a1: fast-close where the stage supports it; legacy-input frames run exact, logged once per context The a1 contract: a frame on the legacy input path (a render size above 0.68 x the output, a jitter outside [-0.5, 0.5], input_tiled=0) runs the exact input stage, never refused (exact is always within quality). The first such frame of a context produces one line for the log: KRuntime::take_frame_note, runtime_take_frame_note and the C export wg_rt_take_frame_note; the D3D12 executor logs it after the frame. The option's create note, its comment, clean/k/README.md and clean/k/dx12/README.md say so. Tests: test_native_k_approx_a1_legacy_note (tiled / legacy switches over seven frames, path confirmed by the launch trace: exactly one line at the first legacy frame per a1 context, none with nothing set or a2); test_a1_legacy_line_once_per_context (interop matrix: each DLAA context logs it once, tiled contexts never). Signed-off-by: phantoslayer21 <156617979+phantoslayer21@users.noreply.github.com> --- clean/k/README.md | 5 +++ clean/k/dx12/README.md | 7 ++-- clean/k/runtime/runtime_k.cpp | 16 +++++++-- clean/k/runtime/runtime_k.h | 9 +++++ clean/k/tests/test_k_approx_executor.py | 17 +++++++++ clean/k/tests/test_k_runtime_d3d12.py | 44 ++++++++++++++++++++++++ clean/runtime/interop/executor_d3d12.cpp | 5 ++- clean/runtime/runtime.cpp | 10 ++++++ clean/runtime/runtime_core.h | 3 ++ clean/runtime/wg_runtime.h | 4 +++ 10 files changed, 114 insertions(+), 6 deletions(-) diff --git a/clean/k/README.md b/clean/k/README.md index 6aaf3146..57b33782 100644 --- a/clean/k/README.md +++ b/clean/k/README.md @@ -192,6 +192,11 @@ Model K ships in the same `wronggpu_runtime.dll` as model M; nothing changes for `k_in_exact=1` names the default; `k_in_exact=0` is the same as `k_fast_in=1`, which selects `k_io.co`'s GPU log2 / 2^x / reciprocal estimates instead (not bit-exact, test use). `k_in_exact=1` is refused with `k_fast=1` or `k_fast_in=1`. + `k_approx=a1|a2|a1,a2` (native D3D12 device only; opt-in, not bit-exact, judged by image quality against the exact + path; `clean/k/dx12/README.md`): `a1` the tiled input stage's transcendental unit forms, fast-close where the stage + supports it: a frame on the legacy input path (a render size above 0.68 x the output, a jitter outside [-0.5, 0.5], + `input_tiled=0`) runs the exact input stage, and the first such frame of a context logs one line; `a2` the output + stage's division forms (needs the compact head). Exposure (spec 42 draft 3 section 4): E_cur = the game's exposure texture or value, 1 if it passes none; the auto-exposure value (spec 07, run when the game asks for it at creation, HDR only) is E_aux and acts only through λ. `k_expo_rule=v051` (A/B only) restores the 0.5.1 rule (the measured value as E_cur and E_aux). diff --git a/clean/k/dx12/README.md b/clean/k/dx12/README.md index 80c0dc2d..a02f8a4f 100644 --- a/clean/k/dx12/README.md +++ b/clean/k/dx12/README.md @@ -121,9 +121,10 @@ exact path, not byte for byte, and taking one adds a note of create. - `a1`, the tiled input stage (`kx/k_in_tiled*__a1`, `hlsl/k_in_common.hlsli` `KI_HWMATH`): its correctly rounded log2, 2^x and divisions (FP32 double-word arithmetic with a Ziv test and a binary64 fallback) become `v_log_f32`, - `v_exp_f32` (about 1 FP32 ulp) and `v_rcp_f32` times the dividend (scaled for |b| >= 2^126). Frames that take the - legacy input kernels (a render size above 0.68 x the output, a jitter outside [-0.5, 0.5], `input_tiled=0`) run the - exact input stage. + `v_exp_f32` (about 1 FP32 ulp) and `v_rcp_f32` times the dividend (scaled for |b| >= 2^126). Fast-close where the + stage supports it: frames that take the legacy input kernels (a render size above 0.68 x the output, a jitter outside + [-0.5, 0.5], `input_tiled=0`) run the exact input stage (never refused: exact is always within quality); the first + such frame of a context logs one line (`wg_rt_take_frame_note`, logged by the D3D12 executor). - `a2`, the output stage (`k_out_color*__a2`, `k_out_pixel_c*__a2`, `hlsl/k_out.hlsli` `KO_APPROX`): its exact divisions become `v_rcp_f32` times the dividend plus one correction of the quotient from its exact residual, and two refined reciprocals drop their Newton step; every opaque barrier stays. It needs the compact head (`k_head=compact`, the diff --git a/clean/k/runtime/runtime_k.cpp b/clean/k/runtime/runtime_k.cpp index c16e9a4d..ed0d6424 100644 --- a/clean/k/runtime/runtime_k.cpp +++ b/clean/k/runtime/runtime_k.cpp @@ -493,7 +493,10 @@ bool KRuntime::create(const WgRtConfig& c, Device* dev, AllocFn alloc_fn, bool e in_exact_ = !(fast_ || kfastin == "1" || kexact == "0"); // k_approx (opt-in, never the default): close approximations of the D3D12 ports, judged by image quality against // the exact path, which stays the default and the reference. "a1": the tiled input stage's log2 / 2^x / divisions - // on the transcendental unit (kernels kx/k_in_tiled*__a1; clean/k/dx12/hlsl/k_in_common.hlsli KI_HWMATH). + // on the transcendental unit (kernels kx/k_in_tiled*__a1; clean/k/dx12/hlsl/k_in_common.hlsli KI_HWMATH): fast-close + // where the stage supports it; a frame on the legacy input path (kx/k_in_color + k_in_base / k_in_reset: a render + // size above 0.68 x the output, a jitter outside [-0.5, 0.5], input_tiled=0) runs the exact input stage, which is + // never refused (exact is always within quality) and is logged once per context (take_frame_note). // "a2": the output stage's divisions on v_rcp_f32 with one quotient correction and two reciprocals without their // Newton step (kernels k_out_color*__a2, k_out_pixel_c*__a2; clean/k/dx12/hlsl/k_out.hlsli KO_APPROX). A comma list // selects several. The native D3D12 device only (HIP and the hybrid device refuse); taking one adds a note of create @@ -520,7 +523,10 @@ bool KRuntime::create(const WgRtConfig& c, Device* dev, AllocFn alloc_fn, bool e if (approx_a2_ && !compact_head_) return fail("model K: k_approx=a2 needs the compact head (k_head=compact, the default)"); approx_note_ = std::string("model K: close approximation k_approx=") + (approx_a1_ ? "a1" : "") + (approx_a1_ && approx_a2_ ? "," : "") + (approx_a2_ ? "a2" : "") + - " (opt-in, not bit-exact; the default path is exact)"; + " (opt-in, not bit-exact; the default path is exact)" + + (approx_a1_ ? std::string("; a1 applies to the tiled input stage, frames on the legacy input path " + "run the exact input stage") + : std::string()); } const std::string krule = option(c, "k_expo_rule"); if (!krule.empty() && krule != "spec" && krule != "v051") @@ -1237,6 +1243,12 @@ bool KRuntime::frame(const WgRtFrame& fr, const FrameIo* io) { }; // backend 1 (the host emulator) has no tiled input kernels; HIP (0) and the D3D12 devices (2 hybrid, 3 native) do const bool use_tiled = tiled_input_ && cfg_.backend != 1 && fin.s == 0.5f && tiled_guard(rw, rh, fin.jx, fin.jy); + // k_approx=a1 on a legacy-input frame: the exact input stage runs (a1 has no legacy form); one line for the caller's + // log, the first time in this context (take_frame_note) + if (approx_a1_ && !use_tiled && !a1_legacy_noted_) { + a1_legacy_noted_ = true; + frame_note_ = "model K: k_approx=a1 applies to the tiled input stage only; this context's frames on the legacy input path (a render size above 0.68 x the output, a jitter outside [-0.5, 0.5], or input_tiled=0) run the exact input stage (this line once per context)"; + } // k_in_exact: the output colour taps by k_out_color (KFrame's exact plan), not by the tiled input kernel const bool use_tiled_color = use_tiled && !in_exact_ && !reset && 4LL * Bw_ >= W_ && 4LL * Bh_ >= H_; KiHost input_host = {}; diff --git a/clean/k/runtime/runtime_k.h b/clean/k/runtime/runtime_k.h index 5629e99f..f810eb4f 100644 --- a/clean/k/runtime/runtime_k.h +++ b/clean/k/runtime/runtime_k.h @@ -86,6 +86,13 @@ class KRuntime { // true when create prepared every kernel this context can select (the native D3D12 device): the caller then // prepares nothing more (the executor's warm_up would also compile kernels the context never runs) bool prepared() const { return prepared_; } + // A line for the caller's log that a frame produced (k_approx=a1 on the legacy input path: once per context), or an + // empty string; taking it clears it. + std::string take_frame_note() { + std::string n; + n.swap(frame_note_); + return n; + } const std::string& model_path() const { return model_path_; } // What the timing marks 0..4 bracket (FrameIo.timing_base): "exposure", "input", "network", "output". static const char* const kTimingLabels[4]; @@ -181,6 +188,8 @@ class KRuntime { std::string smx_test_; // option k_smx_test (developer builds only) std::string notes_; // notes of create for the caller's log (notes()), one per line, or empty bool prepared_ = false; // prepared() + std::string frame_note_; // take_frame_note() + bool a1_legacy_noted_ = false; // the k_approx=a1 legacy-input line was produced (once per context) unsigned warm_line_ = 128, warm_groups_ = 64; DevPtr warm_dummy_ = 0; WgRtFrameInfo info_ = {}; diff --git a/clean/k/tests/test_k_approx_executor.py b/clean/k/tests/test_k_approx_executor.py index 02d765e5..0d421346 100644 --- a/clean/k/tests/test_k_approx_executor.py +++ b/clean/k/tests/test_k_approx_executor.py @@ -96,6 +96,23 @@ def test_unselected_form_is_not_prepared(self): self.assertEqual(len(modes), 20, modes) self.assertTrue(all("k_approx" not in m and "the exact path" in m for m in modes), modes) + def test_a1_legacy_line_once_per_context(self): + """The a1 contract through the executor: the matrix's DLAA contexts (render size = output: the legacy input path) + log the a1 line exactly once each, and their frames run (no refusal); the other ratios (the tiled path) never.""" + rc, out = self.run_case(False, ["k_approx=a1"]) + self.assertEqual(rc, 0, out) + self.assertTrue(out.rstrip().endswith("PASS"), out) + blocks, cur = [], [] + for ln in out.splitlines(): + if ln.strip().startswith("matrix "): + blocks.append((ln.strip(), sum("k_approx=a1 applies to the tiled input stage only" in c for c in cur))) + cur = [] + else: + cur.append(ln) + self.assertEqual(len(blocks), 20, blocks) + for label, n in blocks: + self.assertEqual(n, 1 if label.startswith("matrix DLAA") else 0, (label, n)) + def test_selected_changed_form_is_refused(self): """The changed shader, k_approx=a2: every context is refused, naming the shader.""" rc, out = self.run_case(True, ["k_approx=a2"]) diff --git a/clean/k/tests/test_k_runtime_d3d12.py b/clean/k/tests/test_k_runtime_d3d12.py index ac5e285a..6070a6f4 100644 --- a/clean/k/tests/test_k_runtime_d3d12.py +++ b/clean/k/tests/test_k_runtime_d3d12.py @@ -475,6 +475,50 @@ def check_close(self, a, b): self.assertGreater(psnr, APPROX_MIN_PSNR) return differ, psnr + A1_LEGACY_NOTE = "k_approx=a1 applies to the tiled input stage only" + + def take_note(self, rt): + rt.lib.wg_rt_take_frame_note.argtypes = [ctypes.c_void_p] + rt.lib.wg_rt_take_frame_note.restype = ctypes.c_char_p + return rt.lib.wg_rt_take_frame_note(rt.rt).decode() + + def test_native_k_approx_a1_legacy_note(self): + """The a1 contract: fast-close where the stage supports it. A frame on the legacy input path (here a jitter outside + [-0.5, 0.5]) runs the exact input stage, never refused, and the first such frame of a context produces ONE line + for the log (wg_rt_take_frame_note): across tiled -> legacy -> legacy -> tiled -> legacy -> tiled -> legacy frames + exactly one line, at the first legacy frame; a second a1 context gets its own line; no line without a1 (nothing + set, k_approx=a2). The launch trace shows every frame took the path it was meant to (the check is not vacuous).""" + legacy_jitter = (0.75, -0.8) + plan = [False, True, True, False, True, False, True] # legacy? + for options, expect in (("k_approx=a1", True), ("k_approx=a1", True), ("", False), ("k_approx=a2", False)): + with self.subTest(options=options): + rt = self.make(3, True, False, options, OUT, MAX_RENDER) + pos = os.path.getsize(TRACE) if os.path.exists(TRACE) else 0 + try: + notes = [] + for i, legacy in enumerate(plan): + x = inputs(np.random.default_rng(700 + i), 130, 78, True, i == 0, + jitter=legacy_jitter if legacy else (0.25, -0.25)) + ran, pos = self.frame_kernels(rt, x, pos) + on_legacy = "kx/k_in_color" in ran + on_tiled = any(k.startswith("kx/k_in_tiled") for k in ran) + self.assertEqual((on_legacy, on_tiled), (legacy, not legacy), (i, sorted(ran))) + if legacy or "a1" not in options: + self.assertFalse([k for k in ran if k.endswith("__a1")], (i, sorted(ran))) + else: + self.assertTrue(all(k.endswith("__a1") for k in ran if k.startswith("kx/k_in_tiled")), sorted(ran)) + notes.append(self.take_note(rt)) + got = [(i, n) for i, n in enumerate(notes) if n] + if expect: + self.assertEqual(len(got), 1, got) + self.assertEqual(got[0][0], 1, got) # the first legacy frame + self.assertIn(self.A1_LEGACY_NOTE, got[0][1]) + self.assertNotIn("\n", got[0][1]) + else: + self.assertEqual(got, []) + finally: + del rt + def test_native_k_approx_frames(self): """k_approx=a1,a2 against nothing set, frame by frame (1440p Quality, a reset, steady frames and a smaller render size): every approximate frame runs the a1 tiled input and the a2 output forms and no exact one, every diff --git a/clean/runtime/interop/executor_d3d12.cpp b/clean/runtime/interop/executor_d3d12.cpp index 204942e6..63817604 100644 --- a/clean/runtime/interop/executor_d3d12.cpp +++ b/clean/runtime/interop/executor_d3d12.cpp @@ -339,7 +339,10 @@ class D3d12Executor : public Executor { &e, "dx12_input_states"); } bool timeout = false; // the bottleneck wait timeout's refusal: passed on as it is (executor_select.h) - if (ok && !wgrt::runtime_frame(rt_, job.frame, &io)) { + const bool framed = ok && wgrt::runtime_frame(rt_, job.frame, &io); + if (framed && log_) // a line the frame produced (model K: k_approx=a1 on the legacy input path, once per context) + if (const char* note = wgrt::runtime_take_frame_note(rt_)) log_(false, note); + if (ok && !framed) { ok = false; e = wgrt::runtime_error(rt_); timeout = frame_timeout_refused(e); diff --git a/clean/runtime/runtime.cpp b/clean/runtime/runtime.cpp index 29e19ea2..95c6e460 100644 --- a/clean/runtime/runtime.cpp +++ b/clean/runtime/runtime.cpp @@ -496,6 +496,7 @@ struct Runtime { std::string output_filter_opt; // the option as given ("" = none) uint32_t lz_bits[5] = {0, 0, 0, 0, 0}; // FP16 bit patterns of the weights w(-2) ... w(+2), even output index std::string notes_text; // lines for the front end's log at create (runtime_notes) + std::string frame_note_text; // runtime_take_frame_note // Motion vectors at output resolution (runtime option motion_outres=original|point; no option: frames never use // FrameIo.motion_hi and nothing is loaded for it). 1 = "original": the kernels of encoder_mo.co / post_mo_w64*.co // (spec 03 draft 4, spec 06 section 3) run on frames that bring the raw motion; 2 = "point": such frames run on the @@ -3195,9 +3196,14 @@ uint64_t runtime_memory_bytes(Runtime* rt) { return rt->owned_bytes; } #ifdef WG_NO_MODEL_K const char* runtime_timing_info(Runtime*) { return nullptr; } bool runtime_prepared_kernels(Runtime*) { return false; } +const char* runtime_take_frame_note(Runtime*) { return nullptr; } #else const char* runtime_timing_info(Runtime* rt) { return rt->k ? KRuntime::timing_info() : nullptr; } bool runtime_prepared_kernels(Runtime* rt) { return rt->k && rt->k->prepared(); } +const char* runtime_take_frame_note(Runtime* rt) { + rt->frame_note_text = rt->k ? rt->k->take_frame_note() : std::string(); + return rt->frame_note_text.empty() ? nullptr : rt->frame_note_text.c_str(); +} #endif const char* const* runtime_timing_labels(Runtime* rt) { static const char* const kM[4] = {"enc0", "Swin", "dec0", "post"}; @@ -3361,6 +3367,10 @@ WG_RT_API int wg_rt_download(void* rt, uintptr_t ptr, void* dst, size_t bytes) { } WG_RT_API const char* wg_rt_kernels(void* rt) { return ((Runtime*)rt)->kernels(); } WG_RT_API const char* wg_rt_notes(void* rt) { return ((Runtime*)rt)->notes_text.c_str(); } +WG_RT_API const char* wg_rt_take_frame_note(void* rt) { + const char* n = runtime_take_frame_note((Runtime*)rt); + return n ? n : ""; +} WG_RT_API const char* wg_rt_model_source(void* rt) { return ((Runtime*)rt)->model_source.c_str(); } WG_RT_API int wg_rt_stage_blob(void* rt, const char* stage, const void** data, size_t* bytes) { Runtime* r = (Runtime*)rt; diff --git a/clean/runtime/runtime_core.h b/clean/runtime/runtime_core.h index 19225c46..8523ffb8 100644 --- a/clean/runtime/runtime_core.h +++ b/clean/runtime/runtime_core.h @@ -113,6 +113,9 @@ const char* runtime_timing_info(Runtime* rt); // Whether create already prepared every kernel this context can select (model K on the native D3D12 device): the // executor then skips its warm_up, which would compile every kernel of the loaded code objects, the unselected ones too. bool runtime_prepared_kernels(Runtime* rt); +// A line for the caller's log produced by the last frames (model K: k_approx=a1 on the legacy input path, once per +// context), or null; taking it clears it. Valid until the next call. +const char* runtime_take_frame_note(Runtime* rt); // Whether cfg (recon_output) or the environment (WG_RECON_SIZE=output) asks for the experimental D = O. bool recon_output_requested(const WgRtConfig& cfg); diff --git a/clean/runtime/wg_runtime.h b/clean/runtime/wg_runtime.h index 353e3077..c53686a3 100644 --- a/clean/runtime/wg_runtime.h +++ b/clean/runtime/wg_runtime.h @@ -168,6 +168,10 @@ WG_RT_API const char* wg_rt_kernels(void* rt); * output_taps=model|none"); runtime option output_filter=original|analytic|quality5|quality9 selects it (default: * original when the model file has the weights, else analytic; original without them fails create). */ WG_RT_API const char* wg_rt_notes(void* rt); +/* A line for the caller's log produced by the frames since the last call, or an empty string; taking it clears it. At + present one: model K with k_approx=a1, the first frame of the context on the legacy input path (it runs the exact + input stage). Valid until the next call. */ +WG_RT_API const char* wg_rt_take_frame_note(void* rt); /* The packed weight blob of a stage (host copy), for checks. */ WG_RT_API int wg_rt_stage_blob(void* rt, const char* stage, const void** data, size_t* bytes); From d5901f3a32c6d64f02850f39d385de6f127ec501 Mon Sep 17 00:00:00 2001 From: phantoslayer21 <156617979+phantoslayer21@users.noreply.github.com> Date: Mon, 16 Nov 2026 05:14:45 -0500 Subject: [PATCH 4/4] test_k_direct_legacy: k_approx=a1 on the direct route keeps legacy frames exact With k_approx=a1 on the direct context (WG_TEST_DX12_OPTIONS), DLAA and jitter-outside-the-guard frames run the exact input stage: every output byte equals the exact reference on all 6 frames, and the context logs its one a1 line. Signed-off-by: phantoslayer21 <156617979+phantoslayer21@users.noreply.github.com> --- clean/k/tests/test_k_direct_legacy.py | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/clean/k/tests/test_k_direct_legacy.py b/clean/k/tests/test_k_direct_legacy.py index 9da1e4be..34f677e9 100644 --- a/clean/k/tests/test_k_direct_legacy.py +++ b/clean/k/tests/test_k_direct_legacy.py @@ -8,7 +8,8 @@ packed as arena offset 0, clean/runtime/struct_args.h, and the frame would overwrite the arena's first allocation). test_interop_d3d12.exe dx12same runs the same 6 frames (resets at frames 1 and 5) through executor=hip (the exact reference on the buffer route) and executor=dx12 (the native direct route: "inputs read directly 1") and compares the -raw output texture bytes: every frame must be identical. The tiled Quality case is the control. +raw output texture bytes: every frame must be identical. The tiled Quality case is the control. With k_approx=a1 on the +direct context, the legacy frames (DLAA, a jitter outside the guard) run the exact input stage: still identical. Set WG_K_GPU_BUILD (a developer runtime build: executor=hip is a diagnostic key) and WG_K_INTEROP_EXE (test_interop_d3d12.exe); run under the shared GPU lock. Only synthetic parameters (random_network_params). @@ -31,6 +32,12 @@ ("jitter outside the guard, Quality", 853, 480, 1280, 720, "", {"WG_TEST_JITTER_OUT": "1"}), ("input_tiled=0, Quality", 853, 480, 1280, 720, "input_tiled=0", {}), ("control: tiled Quality", 853, 480, 1280, 720, "", {}), + # k_approx=a1 on the direct context only (WG_TEST_DX12_OPTIONS: the HIP reference refuses k_approx): a legacy frame + # runs the EXACT input stage (a1 applies to the tiled input stage only) and a1 changes nothing else, so every output + # byte still equals the exact reference + ("k_approx=a1, DLAA", 1280, 720, 1280, 720, "", {"WG_TEST_DX12_OPTIONS": "k_approx=a1"}), + ("k_approx=a1, jitter outside the guard", 853, 480, 1280, 720, "", {"WG_TEST_JITTER_OUT": "1", + "WG_TEST_DX12_OPTIONS": "k_approx=a1"}), ] ROW = re.compile(r"frame (\d+): (\d+) of (\d+) bytes differ") @@ -73,6 +80,8 @@ def test_direct_legacy_frames_match_the_reference(self): self.assertEqual([d for _, d, _ in rows], [0] * FRAMES, "%s: output bytes differ from the exact reference" % label) self.assertNotIn("null cpre", out) + if "k_approx=a1" in env_extra.get("WG_TEST_DX12_OPTIONS", ""): # the option took effect: its one line + self.assertEqual(out.count("k_approx=a1 applies to the tiled input stage only"), 1, out[-2000:]) self.assertEqual(rc, 0, out[-2000:])