From 5d99fdd5399cd705278dfc6731c8606ecff252d7 Mon Sep 17 00:00:00 2001 From: Ralph Kuepper Date: Fri, 11 Sep 2026 04:33:43 +0200 Subject: [PATCH] Sample the sheen lookup at explicit level zero for FXC --- docs/evidence/windows-fxc-layered-lut-v1.md | 57 +++++++++++++++++++++ docs/evidence/windows-warp-compiler-v1.md | 12 ++++- docs/windows-engine-plan.md | 22 ++++++-- native/shared/shaders/layered_pbr_v3.wgsl | 6 ++- 4 files changed, 89 insertions(+), 8 deletions(-) create mode 100644 docs/evidence/windows-fxc-layered-lut-v1.md diff --git a/docs/evidence/windows-fxc-layered-lut-v1.md b/docs/evidence/windows-fxc-layered-lut-v1.md new file mode 100644 index 00000000..13b8ba34 --- /dev/null +++ b/docs/evidence/windows-fxc-layered-lut-v1.md @@ -0,0 +1,57 @@ +# FXC layered-material lookup sampling + +The expanded physical Radeon DX12/FXC run on #164 passes 89 rendering goldens +and fails four during `scene_layered_pbr_pipeline` compilation: + +- clearcoat-normal minification and motion; +- explicit mirrored-tangent anisotropy; +- anisotropy under negative model scale; +- layered materials across opaque, sorted, reactive and weighted paths. + +FXC reports X3570 for a gradient instruction in a varying loop, followed by +X3511 when it cannot unroll the loop. The shader, scene specialization, core +shader, test definitions and golden helper are byte-identical between #163 and +#164. The source-equivalence receipt distinguishes that comparison from a +separately executed parent full-suite run. These are compiler failures before +image assertions, and their original logs remain in the #164 evidence. + +## Correction + +`layered_sheen_directional_albedo` used an implicit-derivative texture sample. +The helper is called from varying direct-light loops. Its R16Float lookup table +has exactly one mip, so explicitly sample level zero with the same texture, +sampler and lookup coordinates. This removes the implicit gradient requirement +that forced FXC to unroll the surrounding loop. No additional binding, texture, +allocation, feature requirement or compiler fallback is introduced. + +The change applies to the shared layered-material helper, including its scene, +transparency and visibility uses. The existing sampler policy remains intact; +the successful image assertions below are the evidence for rendering behavior, +not an assumption that compiler outputs are byte-identical. + +## Validation + +The complete local DX12/FXC shared component passes: 489 library tests, device +negotiation, all 93 goldens and the remaining integration checks. All four +previously failing tests now create their pipelines and pass their original +rendering assertions. Existing one ignored library test, four ignored goldens +and two ignored documentation examples remain unchanged. + +Raster goldens require and identify the Radeon 760M/DX12 adapter. Ordinary +pipelines use explicit FXC; the ray-query golden helper deliberately requires +DXC. Older library helpers can explicitly select software adapters. The full +FXC component takes 1,073.406 seconds including compilation, shader creation and +tests; this is test duration, not an FPS or GPU-budget measurement. + +DX12/DXC and Vulkan each pass all 93 goldens with four existing ignored tests. +Strict Clippy, formatting and repository contracts also pass. The test driver +records the exact candidate shader patch against `f96af2e`; only report updates +followed these runs. Hosted validation is pending. +The WARP/DXIL concurrent compiler crash documented with #164 remains a separate +open defect. This change does not qualify unavailable named hardware or wider +performance, starter, packaging or engine-plan acceptance. + +Source patches, the original failure log and source-equivalence receipts, +commands and complete results are retained under +`tools/quality/out/windows-engine-plan/fxc-layered-lut/` and +`tools/quality/out/windows-engine-plan/windows-shared-crash/`. diff --git a/docs/evidence/windows-warp-compiler-v1.md b/docs/evidence/windows-warp-compiler-v1.md index 105b06a1..63f6864c 100644 --- a/docs/evidence/windows-warp-compiler-v1.md +++ b/docs/evidence/windows-warp-compiler-v1.md @@ -37,8 +37,16 @@ The ray-query golden helper retains its deliberate DXC requirement. This is a software-renderer CI workaround. The WARP/DXIL access violation remains open, and physical DX12/DXC qualification remains required. The ordinary Windows engine compiler policy is unchanged. The candidate's library suite passes with -four threads and explicit FXC (489 passed, one ignored). Complete local shared -components and hosted validation are still running. +four threads and explicit FXC (489 passed, one ignored). Complete local +DX12/DXC and Vulkan shared components pass, including all 93 goldens. + +At source `f96af2e`, hosted Tests run 34552411807 passes all 22 jobs, including +actual Windows shared execution, the native engine build and all 20 example +links. Hosted Windows goldens skip its CPU adapter and do not qualify physical +images. The [published report](https://github.com/Bloom-Engine/engine/releases/tag/quality-evidence-warp-compiler-20260911) +retains the skips and all original crashes. The expanded physical FXC run also +exposes four [layered-material compiler failures](windows-fxc-layered-lut-v1.md); +that separate correction preserves the original rendering assertions. Diagnostic commands, logs, debugger stacks, executable hashes and results are retained in `tools/quality/out/windows-engine-plan/windows-shared-crash/`. diff --git a/docs/windows-engine-plan.md b/docs/windows-engine-plan.md index f119e055..38d57290 100644 --- a/docs/windows-engine-plan.md +++ b/docs/windows-engine-plan.md @@ -17,9 +17,9 @@ first nine-scene Radeon evidence are in draft PR #154. Follow-up work starts at | #127 Vulkan PT correctness | Three deterministic progressive and motion runs, both negative controls, finite intermediates, reset/lighting/rigid-motion checks, retained report | Canonical hardware gate, all four focused temporal tests, and CPU reference sanity check pass on Radeon/Vulkan; [report](evidence/issue-127-windows-vulkan-v1.md) and [raw evidence](https://github.com/Bloom-Engine/engine/releases/tag/quality-evidence-155-windows-vulkan-20260910) published | | #128 Windows image discrepancies | Identify the first incorrect stage or document a reviewed backend-specific baseline decision; rerun the full strict corpus and reproducibility checks | Cutout and surface corrections pass all nine Radeon images. At #159 source `d610d6a`, full runs 2 and 3 pass every configured check and reproduce 257 artifacts byte-identically with matching metadata and timing differences inside existing noise bounds. Earlier invalid runs retain their failures; named hardware acceptance remains separate | | #135 / #149 temporal reconstruction | Enforced motion/producer/quality-preset corpus, representative scenes, fractional/native and frozen A/B timing, memory/resize checks, platform evidence | Device/resource, stationary SSGI, and profiler fixes are retained. The surface correction passes original HD startup limits and 154,720 analytic receiver checks on Vulkan, DX12, and hosted Metal; 93 local goldens pass, including lighting recovery. The full Radeon corpus passes twice. Wider representative scenes, frozen A/B performance, memory/resize, and platform acceptance remain open | -| #140 integration gates | Same required local/hosted lanes pass on exact source; release package startup and all-example evidence | #160 fixes silent Windows CI non-execution and MSVC PATH ordering. #161 passes the actual native engine build and all 20 native links locally and in hosted CI; [evidence](https://github.com/Bloom-Engine/engine/releases/tag/quality-evidence-windows-examples-20260911) is published. Draft #162 corrects the two focused DX12 GPU failures and passes the complete Vulkan shared component. Hosted Windows still crashes with an access violation; the expanded local DX12 goldens expose a separate camera-history reset defect. Release startup/install acceptance remains open | +| #140 integration gates | Same required local/hosted lanes pass on exact source; release package startup and all-example evidence | #160 fixes silent Windows CI non-execution and MSVC PATH ordering. #161 passes the actual native engine build and all 20 native links locally and in hosted CI. #162 fixes the focused DX12 failures; #163 fixes camera-history reset. #164 passes all 22 hosted Tests jobs using an explicit FXC Windows lane. The underlying WARP/DXIL crash remains open. A separate layered-material correction passes the full local FXC shared suite and all 93 DXC/Vulkan goldens. Release startup/install acceptance remains open | | #138 capability fallback | Actual constrained-adapter startup and relevant forced-tier corpus, truthful capability outputs | Existing implementation/evidence preserved; physical constrained-limit acceptance still needs proof | -| PR integration | Reviewable changes, passing required checks, full issue evidence, merge-ready rendering branch | #147 and the stacked fixes #154–#159 remain drafts; no merge performed | +| PR integration | Reviewable changes, passing required checks, full issue evidence, merge-ready rendering branch | #147 and the stacked fixes #154–#164 remain drafts; no merge performed | ## Engine work retained in scope @@ -67,14 +67,26 @@ audit are saved in `tools/quality/out/windows-engine-plan/plan-requirements.json goldens and the expanded cut check; its [evidence is published](https://github.com/Bloom-Engine/engine/releases/tag/quality-evidence-camera-history-20260911). The Windows library crash reproduces locally inside WARP's DXIL shader optimizer during concurrent traversal tests. An [explicit FXC hosted lane](evidence/windows-warp-compiler-v1.md) - and consistent test compiler selection are being validated. The underlying - WARP/DXIL defect and physical DX12/DXC acceptance remain separate. + and consistent test compiler selection pass all 22 hosted Tests jobs at #164, + with [published evidence](https://github.com/Bloom-Engine/engine/releases/tag/quality-evidence-warp-compiler-20260911). + Hosted Windows goldens skip its CPU adapter; complete physical Radeon DX12/DXC + and Vulkan shared runs pass all 93 goldens. The expanded physical FXC run + exposed four layered-material compiler failures. A [level-zero LUT correction](evidence/windows-fxc-layered-lut-v1.md) + restores the complete local FXC shared component, including all 93 goldens; + all 93 DXC and Vulkan regression goldens also pass. Hosted checks for that + correction are pending. The underlying WARP/DXIL + defect remains open. 2. Finish all-example native linking, real starter/example startup, and clean Windows installation. The [native example gate](evidence/windows-example-gate-v1.md) passes all 20 links locally using Perry 0.5.1220 and one matching source-built runtime profile. It adds required full-lane Windows PR compilation and rejects missing or stale executable outputs. Hosted example validation also passes at `59244b9`; actual startup and clean - package installation remain required. + package installation remain required. Packing and installing the actual + package succeeds in a clean project, but its installed `bloom-web --help` + command fails on Windows because npm's shim tries `/bin/bash`. A bounded + starter compiles to WASM from that installed package; runtime rendering is + not yet proven. The next implementation work is portable command execution + and native/browser startup acceptance. 3. Complete the wider temporal/geometry, performance, memory, resize, and capability corpus. The [HD surface correction](evidence/windows-ssgi-surface-v1.md) and two valid diff --git a/native/shared/shaders/layered_pbr_v3.wgsl b/native/shared/shaders/layered_pbr_v3.wgsl index 853bf2e1..cb53fc1e 100644 --- a/native/shared/shaders/layered_pbr_v3.wgsl +++ b/native/shared/shaders/layered_pbr_v3.wgsl @@ -403,10 +403,14 @@ fn layered_sheen_visibility( } fn layered_sheen_directional_albedo(n_dot: f32, roughness: f32) -> f32 { - return textureSample( + // This lookup table has one mip. Direct-light loops can have varying + // iteration counts, so avoid the implicit derivatives that force FXC to + // unroll those loops when sampling it. + return textureSampleLevel( layered_sheen_albedo_tex, layered_sampler, vec2(clamp(n_dot, 0.0, 1.0), clamp(roughness, 0.0, 1.0)), + 0.0, ).r; }