Repository navigation
Model K: k_approx opt-in (A1 + A2) - #257
Merged
Merged
Conversation
… (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>
…tent 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>
phantoslayer21
force-pushed
the
clean/k-approx
branch
from
November 16, 2026 08:05
700e268 to
f9b45ad
Compare
phantoslayer21
force-pushed
the
clean/k-mix-softmax
branch
from
November 16, 2026 08:33
8fdcdb4 to
b518f4e
Compare
phantoslayer21
force-pushed
the
clean/k-approx
branch
from
November 16, 2026 08:37
f9b45ad to
fc94b81
Compare
…mes 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>
phantoslayer21
force-pushed
the
clean/k-approx
branch
from
November 16, 2026 09:36
fc94b81 to
e03131e
Compare
…ames 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>
phantoslayer21
force-pushed
the
clean/k-approx
branch
from
November 16, 2026 10:17
e03131e to
d5901f3
Compare
phantoslayer21
marked this pull request as ready for review
November 16, 2026 10:26
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Based on main after #254 (25429c5) and #264 (32ed000, the direct route's legacy input intermediates).
What
A runtime option for Model K,
k_approx. It is opt-in: nothing set stays the exact path, which remains the default and the reference. It selects close approximations of two stages on the native D3D12 device. They are judged by image quality against the exact path, not byte for byte.a1, the tiled input stage (kx/k_in_tiled*__a1,k_in_common.hlsliKI_HWMATH): the correctly rounded log2, 2^x and divisions (FP32 double-word arithmetic with a Ziv test and a binary64 fallback) becomev_log_f32,v_exp_f32andv_rcp_f32times 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], orinput_tiled=0) run the exact input stage. That is never refused (exact is always within quality); the first such frame of a context logs one line ("k_approx=a1 applies to the tiled input stage only; ...", throughwg_rt_take_frame_noteand the D3D12 executor's log), and the option's create note andclean/k/README.mdsay so.a2, the output stage (k_out_color*__a2,k_out_pixel_c*__a2,k_out.hlsliKO_APPROX): the exact divisions becomev_rcp_f32times the dividend plus one correction of the quotient from its exact residual, andko_div_axisandko_rcp_refineddrop their Newton step.ko_rcp_output_boundedand every opaque barrier stay.Taking one adds one note of create (logged by the executor),
k_approx=...in the kernels line, and;k_approx=...with "an approximation (not bit-exact)" in the executor's mode line.Refused at create, each in one line: HIP and the hybrid D3D12 device (
k_approxruns on the native D3D12 device only); an empty value (k_approx=), an empty list item (a1,,,a2,a1,,a2) and an unknown tag (control characters shown as?);a1without the exact input kernels;a2withk_fast=1;a2withk_head=full(the full head'sk_out_pixelhas noa2form, so every accepted combination runs the same kernels on every frame).Prepared only when selected: native create prepares exactly the kernels the context can select, the
__a1/__a2forms only when they are selected, and checks each shader against the manifest digest. The D3D12 executor no longer runs its own warm-up for model K (that warm-up compiled every kernel of the build, the unselected forms too), so an unusable approximate shader cannot affect a context that does not select it; one that is selected refuses create, naming it.Speed
Model K, 1440p Quality, harness direct route, interleaved 4+4, rt-k3 build (K-MIX): frame 1.5815 -> 1.3685 ms with k_approx=a1,a2 (main 1.5955)
k_approx=a1,a2Record:
k-approx-speed.jsonin the lane folder; runsk3t-*.The seven
__a1/__a2shaders rebuilt from this branch are byte-identical (DXIL SHA-256) to those of the build that was timed and scored. Record:k-approx-dxil-257.json.Image quality (spec side's scoring, Q11-C metrics; two sets of the game's frames)
The test sets are S1 (40 frames) and S2 (thin lines, 64 frames). The bars are a tenth of the Q11-C band against exact, and no worse than exact against the RTX 3060 natives.
There is no drift over 64 frames: the vs-exact PSNR rises from the first window to the last, and the variant − exact ΔPSNR vs native stays within 0.02 dB in the last window. The spec side's verdict for both is "very very close: every bar met on S1 and S2, no drift".
Tests
test_k_runtime_d3d12.pyandtest_k_approx_executor.py, 35 / 35 on a developer build, each create in its own process; synthetic model only:test_k_approx_refusals: HIP and the hybrid device refused; the empty value, empty items, an unknown tag, a control-character tag anda2;k_head=fullrefused, each in one line; nothing set: no note, nok_approxin the kernels line.test_k_approx_each_tag:a1,a2anda1,a2each create with one note and their kernels-line field; with the self-check's fallback forced,a1,a2still applies (two notes); with both softmax forms failed, create refuses.test_k_approx_shaders_prepared_only_when_selected: a copy of the build with one byte changed ink_out_pixel_c__a2orkx/k_in_tiled__a1: nothing set creates; selecting that form refuses, naming it.test_native_k_approx_a1_legacy_note: tiled, legacy, legacy, tiled, legacy, tiled, legacy frames (legacy = a jitter outside the guard; the launch trace confirms each frame's path): withk_approx=a1exactly one line, at the first legacy frame, and a seconda1context gets its own; no line with nothing set ork_approx=a2. Legacy frames run no__a1kernel.test_native_k_approx_frames: frame by frame at 1440p Quality (a reset, a steady frame, a smaller render size): every approximate frame launches the__a1tiled input andk_out_pixel_c__a2and no exact counterpart, every default frame none of them; the approximate output differs from exact and stays within loose bounds (at most 35 % of values differ, tone-mapped luma PSNR above 45 dB; measured 1.3 / 12.2 / 17.4 % and 55.7 / 55.5 / 54.7 dB). Negative controls: the variant check fails on a default frame, the closeness check on identical and on perturbed outputs.test_k_direct_legacy.py(from #264) gains two cases:k_approx=a1on the direct context (DLAA, and a jitter outside the guard) keeps every legacy frame byte-identical to the exact reference on all 6 frames (the input stage runs exact), and the context logs its one a1 line.test_k_approx_executor.py(new;test_interop_d3d12.exe matrixat 1080p, 20 contexts each):test_selected_form_runs: the unchanged build takesk_approx=a2in every context, and each mode line names it.test_unselected_form_is_not_prepared: with one byte changed in bothk_out_pixel_c__a2forms and nothing set, every context runs the exact path. Negative control: the same test against a build with the executor's warm-up restored fails, 20 of 20 contexts refused with "shader integrity mismatch: k_out_pixel_c__a2" (recordexecutor-negctl-257.json).test_a1_legacy_line_once_per_context:k_approx=a1: each DLAA context (render size = output: the legacy input path) logs the line exactly once and its frame runs; the 16 other contexts (tiled) never log it.test_selected_changed_form_is_refused: the same copy withk_approx=a2: every context refused, namingk_out_pixel_c_direct__a2.