Skip to content

Input encoder: opt-in E1b (runtime option e1b=on, default off) - #271

Draft
phantoslayer21 wants to merge 2 commits into
mainfrom
encoder-e1b-optin
Draft

phantoslayer21 wants to merge 2 commits into
mainfrom
encoder-e1b-optin

Conversation

@phantoslayer21

@phantoslayer21 phantoslayer21 commented Nov 17, 2026 •

Copy link
Copy Markdown
Owner

Opt-in E1b for Model M's input encoder: runtime option e1b=on (runtime_options, also WG_RUNTIME_OPTIONS), default off. With the option off, nothing changes: the default warm-up compiles the same kernels as before and every default kernel is unchanged.

With e1b=on, Model M on the native D3D12 executor runs the encoder forms e1b/input_encoder[_direct] (clean/dx12/kernels/encoder.hlsl, ENC_E1 == 2). Each wave issues the loads of its four history taps first. Then, per tap, one wave-wide test (WaveActiveAllTrue) checks whether every lane's near / far tap position equals its centre tap position. Where it does, that tap's values are copied from the centre tap instead of being computed again. On the validated driver (below) the output is byte for byte the default encoder's.

The gain depends on camera motion: a still or evenly panning view saves the most, and strong parallax gains nothing and can be slightly slower. That is why it is opt-in and not the default.

  • runtime: the e1b key is read once at create, before Model K's create returns (clean/runtime/e1b_option.h), and resolved once (e1b_resolve). E1b runs only for Model M on the native D3D12 executor without motion at output resolution, and only when the form for the context's route (direct or buffer) prepares: shader, digest, pipeline. Otherwise the default encoder runs, and the kernel line of the log says e1b=off (<reason>): Model L, Model K, not the native D3D12 executor, motion at output resolution, not in the manifest, or could not be prepared. With E1b running it says e1b=on. The kernel report only reads the choice made at create; the launch follows it from the first frame.
  • An invalid value (e1b=1, a typo) does not fail create: E1b stays off and the log gets one line, e1b: unknown value '1', using off.
  • device (native D3D12): the default warm-up skips the opt-in forms (optional_kernel), so a missing or failing E1b shader cannot fail a create; only the selected form is prepared, and only with e1b=on.
  • kernels: e1b/input_encoder and e1b/input_encoder_direct in the model M set (VGPR limit 128). ENC_E1 == 1, the same test without the early loads, stays in the source as the reference form and is not declared. manifest_kernels() moves out of the Model L guard (builds without Model L check the manifest).
  • tests: clean/runtime/tests/test_e1b_option.py (CPU): value parse, options scan and report item (test_e1b_option.cpp), and source checks of the wiring.
  • test harness: WG_TEST_MOTION_PATTERN = ramp (default, unchanged) | zero | pan | parallax, and WG_TEST_RESET_AT=<frame>[,...] (mid-stream resets).
  • clean/FORMATS.md: the option.

Based on: own design (the encoder's tap positions, spec 03 and the existing encoder.hlsl).

Measured

Interleaved timing: fresh process per run, order reversed on odd rounds, 3 rounds, 1500 frames per run, synthetic Model M, direct route, D3D12 timestamps. Frame time, paired median of (e1b on) - (default), per synthetic motion pattern. The gain depends on camera motion.

motion pattern 1080p Quality 1440p Quality
zero (still camera) -4.0 us -6.5 us
pan (one constant vector) -3.5 us -8.5 us
parallax (every neighbour differs) +2.0 us +2.0 us
ramp (the harness default; 1 round) +3.5 us +3.5 us

Every timing run's 1500-frame output hash is identical between e1b on and the default. The timing was measured with E1b selected through a development switch; the two E1b kernels of this branch are sha256-identical to the ones timed.

Tested

RX 9070 XT, AMD driver 32.0.32015.7029, synthetic Model M, the direct route (the route of every shipped configuration). Each run is its own process; "launch trace" counts the encoder launches per run.

  • Option off: every default D3D12 kernel (47 DXIL files) and every HIP code object (44) is sha256-identical to the same build of main. The final-output hash over 1500 frames equals main's: 1440p Quality 4032aeefd33ef6e4, 1080p Quality 096e28df06b8af96. Launch trace: the default encoder in every frame, no E1b launch, no e1b item in the log.

  • Option on (e1b=on): the 1500-frame output hash equals the option-off run for every motion pattern at both shapes, and the launch trace shows the E1b kernel in all 1500 frames and the default encoder in none (log: e1b=on):

    motion pattern 1080p Quality 1440p Quality
    ramp 096e28df06b8af96 4032aeefd33ef6e4
    zero 27ed43e328910df1 9fb5697a11743fab
    pan fbe19d2cd8099a16 888af40bbc40131b
    parallax d272c4f74344e922 30a2b49361b75c7c
  • Odd size, 1001x563 -> 1501x845, 600 frames: option off equals main (5f0fdf4d31a766f8); option on equals off with the ramp (5f0fdf4d31a766f8) and zero (01be5ec391ce5e88) patterns, E1b in all 600 frames.

  • Mid-stream resets on frames 350, 351, 420 and 599, 600 frames, 1440p Quality: on equals off with the zero (fa3feca957453372) and parallax (5c3742b498e010e3) patterns, E1b in all 600 frames, the reset frames included. Without the resets the zero run gives eadd3a1e7f71e625, so the resets took effect.

  • Fallbacks, 1440p Quality: e1b=1 creates, logs e1b: unknown value '1', using off, runs the default encoder and gives the default bytes. With both E1b shaders corrupted on disk, a default create succeeds with the default bytes, and e1b=on creates, logs e1b=off (e1b/input_encoder_direct could not be prepared: native D3D12 shader integrity mismatch: ...) and gives the default bytes. Motion at output resolution with e1b=on: e1b=off (motion at output resolution runs its own encoder), no E1b launch.

  • RGA (gfx1201), default vs E1b: the same floating-point arithmetic instructions in the same numbers on both routes (direct 2614 = 2614, buffer 2516 = 2516; FMA, multiply, add, subtract, min / max and conversions each equal after merging the dual-issue and constant-operand encodings). e1b/input_encoder_direct: 89 VGPRs, no spills.

  • clean/runtime/tests/test_e1b_option.py (CPU) passes.

  • public_gates.py: the must-pass gates pass. The leak scan of the changed files has 0 hits, and the whole-tree leak and number lists are the same as main's.

Not tested

  • Other drivers or GPUs: the byte identity is shown for the driver above.
  • The buffer route on the GPU: no shipped configuration uses it (native D3D12 external I/O requires the direct route); its E1b form compiles to the same arithmetic as its default form (above).
  • Model L, Model K and the HIP executor with e1b=on on the GPU: the code reports e1b=off (Model L) / (Model K) / (not the native D3D12 executor) and runs their own encoders; not run here (the synthetic model set has Model M only).
  • Non-finite and very large motion values, and history values at quantisation boundaries: positions that are NaN compare unequal (no copy), equal positions give equal validity, but no dedicated adversarial input was run.
  • In-game timing and real camera paths. A per-wave skip counter for an in-game walk exists only in a developer build and is not part of this PR.

Records: e1b-summary.json (timing), e1bev-runs.jsonl (the legs above), e1b-isa-fpops.json (the instruction comparison); team records.

With e1b=on, Model M on the native D3D12 executor runs the encoder forms e1b/input_encoder[_direct]
(encoder.hlsl, ENC_E1 == 2). Each wave issues the loads of its four history taps first. Then, per tap,
one wave-wide test checks whether every lane's near / far tap position equals its centre tap position;
where it does, that tap's values are copied from the centre tap instead of being computed again. The
output is byte for byte the default encoder's. The gain depends on camera motion: still and evenly
panning views save the most, strong parallax can be slightly slower.

- runtime: runtime_options key e1b=on|off (also WG_RUNTIME_OPTIONS), default off; the kernel line in
  the log shows e1b=on, or e1b=off (...) when the model, executor or manifest cannot run it (the
  default encoder then runs). manifest_kernels() moves out of the Model L guard so that builds
  without Model L can check the manifest.
- kernels: e1b/input_encoder and e1b/input_encoder_direct in the model M set (VGPR limit 128).
  ENC_E1 == 1 (the same test without the early loads) stays in the source as the reference form and
  is not declared.
- test harness: WG_TEST_MOTION_PATTERN = ramp (default) | zero | pan | parallax for the timing legs.
- FORMATS.md: the option.

Option off: every default kernel unchanged.

Signed-off-by: phantoslayer21 <156617979+phantoslayer21@users.noreply.github.com>
…l create

- device (native D3D12): the default warm-up skips the opt-in forms (optional_kernel: e1b/*), so a missing or
  failing E1b shader cannot fail a default create, and a default create compiles exactly what it did before.
- runtime: the e1b key is read once at create, before Model K's create returns (e1b_option.h e1b_scan), and
  resolved once (e1b_resolve): E1b runs only for Model M on the native D3D12 executor without motion at output
  resolution, and only when the route's own form (direct or buffer) prepares. Otherwise the default encoder runs
  and the reason is kept: Model L, Model K, not the native D3D12 executor, motion at output resolution, not in the
  manifest, or could not be prepared. The kernel report only reads it (no side effects); the launch follows the
  create-time route from the first frame.
- an invalid value (e.g. e1b=1 or a typo) no longer fails create: E1b stays off and the log gets one line,
  "e1b: unknown value '1', using off".
- tests: clean/runtime/tests/test_e1b_option.py (CPU): the value parse, the options scan and the report item
  (test_e1b_option.cpp, MSVC), and source checks of the wiring (read and resolved at create, side-effect-free
  report, no opt-in form in the default warm-up).
- test harness: WG_TEST_RESET_AT=<frame>[,...] for mid-stream resets in the byte legs.
- FORMATS.md: the create-time choice, the reasons, the fallback, and the byte-identity scope.

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