@photivra/engine 2.20.0 → 2.22.0

package/dist/gpu/wgsl-display-view-quality-kernel.js

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
  * WGSL kernels of the display view's Quality path on the GPU (#479): the exact area mean with diffraction kernels, the
- * anti-aliasing filter's spots, the AHD candidates and the low-signal correction, in three passes over one band of display
+ * anti-aliasing filter's spots and the AHD candidates, in three passes over one band of display
  * rows (docs/WEBGPU.md, "Display view (Quality) on the GPU"; the float64 reference is `renderDisplayView` with
  * `createDisplayViewExpectedSignal`, facade/display-view.ts and facade/expected-signal.ts):
  *
@@ -21,9 +21,7 @@
  *    camera-channel covariance), white balance and the highlight clip, the colour matrix, the tone curve and the clip to
  *    [0, 1] with the skewness term, the candidates' average, the Stein covariance with the closed-form B_c, the independent
  *    residual, AHD's choice variance ¼·Var(H − V), the flag for AHD's choice on the noise-free mosaic, which the reference takes and
- *    the kernel does not (#457), and the low-signal correction interpolated trilinearly between the grid
- *    states of a table the host uploaded (the states themselves are computed on the host, #447; the kernel records every
- *    grid key it needs in a bitmap and flags a display pixel whose state the table lacks).
+ *    the kernel does not (#457). 2.22.0: there is no low-signal correction (docs/DISPLAY_VIEW.md, "AHD at low signal").
  *
  * **Highlights (#533).** The site pass records whether each site is certainly below white, certainly at or above it, or
  * undecided (`clip_state`, from the site's mean and variance and their running bounds: certain only beyond twice the reference's
@@ -50,10 +48,13 @@
  * trigonometric built-in).
  */
 import { DISPLAY_VIEW_CLIP_MEAN_U, DISPLAY_VIEW_CLIP_VARIANCE_U, DISPLAY_VIEW_REINHARD_MEAN_U, DISPLAY_VIEW_REINHARD_VARIANCE_U } from "./wgsl-display-view-speed-kernel.js";
-import { AHD_KEY_FLOOR, AHD_KEY_LEVELS, AHD_KEY_OCTAVES, AHD_KEY_STEPS } from "../facade/display-view.js";
+import { EXACT_SUM_WGSL } from "./wgsl-exact-sum.js";
+import { DISPLAY_VIEW_COUPLED_STUB_WGSL } from "./wgsl-display-view-coupled-stub.js";
 export const DISPLAY_VIEW_QUALITY_WORKGROUP_SIZE = 64;
 /** Largest footprint per axis (real pixels), as the Speed kernel. */
 export const DISPLAY_VIEW_QUALITY_MAXIMUM_PIXELS_PER_AXIS = 6;
+/** Most spectral nodes the site passes integrate per site (2.21.0: the per-node partials are private arrays of this length). */
+export const DISPLAY_VIEW_QUALITY_MAXIMUM_NODES = 96;
 /** Uniform parameter words (see `Params`): 56 words, 224 bytes. */
 export const DISPLAY_VIEW_QUALITY_PARAM_WORDS = 56;
 /** Words per lattice-group record: lx0, ly0, lw, lh, lbase, first tap (the blocked site pass, #492), cu (f32), cv (f32). */
@@ -89,12 +90,7 @@ export const DISPLAY_VIEW_QUALITY_FLAG = /* @__PURE__ */ Object.freeze({
     materialUncertain: 1,
     /** A site the pixel read lies outside the band's site window (a host geometry error; recompute). */
     siteOutsideWindow: 2,
-    /** The correction needed a grid state the table does not hold (recompute, or compute the state and dispatch again). */
-    stateMissing: 4,
-    /** A sample's pixel variance lies within its bound of the correction threshold (recompute). */
-    thresholdTie: 8,
-    /** Informational: the pixel's expected value includes the low-signal correction. */
-    corrected: 16,
+    // Bits 4, 8 and 16 (the low-signal correction's state, threshold and applied flags) are unused since 2.22.0.
     /**
      * #457: the reference takes AHD's choice on the noise-free mosaic (one candidate, or their average on a tie), which the kernel
      * does not compute; it renders the average. The pixel is flagged (recompute) when Σ_j a_j·½|h(H) − h(V)| of some component
@@ -104,7 +100,7 @@ export const DISPLAY_VIEW_QUALITY_FLAG = /* @__PURE__ */ Object.freeze({
     /** #533: a real pixel's saturation is undecided (the host computes the display pixel's count with the reference; its samples stay). */
     highlightUndecided: 64,
     /** The bits that require the host's recomputation. */
-    recompute: 47
+    recompute: 35
 });
 /** #533: flag words per display pixel: the flags, then the 36-bit mask of saturated real pixels. */
 export const DISPLAY_VIEW_QUALITY_FLAG_WORDS = 3;
@@ -114,8 +110,6 @@ export const DISPLAY_VIEW_QUALITY_FLAG_WORDS = 3;
  * design tolerance, not a measurement: 2^-10 σ is a tenth of the 0.01 σ to which the float32 tests hold the GPU to the reference.
  */
 export const DISPLAY_VIEW_QUALITY_CHOICE_SIGMA = 2 ** -10;
-/** Words of the grid-key bitmap: one bit per grid key (AHD_KEY_LEVELS³ keys). */
-export const DISPLAY_VIEW_QUALITY_BITMAP_WORDS = Math.ceil(AHD_KEY_LEVELS ** 3 / 32);
 /**
  * A site whose uncertain lattice points (the material module's flag) could move its electrons by more than this fraction of
  * their value is flagged for host recomputation; a smaller uncertainty enters the site's bound instead (the tap weights times
@@ -133,7 +127,7 @@ const literal = (value) => {
     return /[.e]/u.test(text) ? text : `${text}.0`;
 };
 /** The parameter struct and the bound helpers shared by the three passes. */
-const COMMON_WGSL = /* wgsl */ `
+export const DISPLAY_VIEW_QUALITY_COMMON_WGSL = /* wgsl */ `
 const E: f32 = ${E_LITERAL};
 const SLACK: f32 = 1e-14;
 const CLIP_REACH: f32 = 8.5;
@@ -153,16 +147,16 @@ count: u32, row0: u32, region_w: u32, region_x: u32,
 region_y: u32, margin: u32, native_w: u32, native_h: u32,
 columns: u32, tone: u32, reach: u32, candidates: u32,
 site_x0: i32, site_y0: i32, site_w: u32, site_h: u32,
-correction: u32, state_count: u32, taps: u32, groups: u32,
+unused_16: u32, unused_17: u32, taps: u32, groups: u32,
 lattice_total: u32, gain_at_clip0: u32, gain_at_clip1: u32, gain_at_clip2: u32,
 k0: f32, k1: f32, k2: f32, reach2: f32,
 dark0: f32, dark1: f32, dark2: f32, clip_level: f32,
-c0_0: f32, c0_1: f32, c0_2: f32, threshold: f32,
+c0_0: f32, c0_1: f32, c0_2: f32, unused_35: f32,
 g0: f32, g1: f32, g2: f32, scale_u: f32,
 m00: f32, m01: f32, m02: f32, m10: f32,
 m11: f32, m12: f32, m20: f32, m21: f32,
 m22: f32, scale_v: f32, site_gamma: f32, site_first: u32,
-site_tiny: f32, pad_f: f32, pad_g: f32, pad_h: f32,
+site_tiny: f32, nodes: u32, pad_g: f32, pad_h: f32,
 };
 @group(0) @binding(0) var<uniform> params: Params;
 
@@ -344,7 +338,7 @@ return out;
  * records hold each group's lattice window (lx0, ly0, lw, lh), its first index in the lattice buffer and the point constants
  * c_u = 0.5 + f_x − W/2 and c_v = 0.5 + f_y − H/2 (exact in float32, checked by the host).
  */
-export const DISPLAY_VIEW_QUALITY_LATTICE_WGSL = /* wgsl */ `${COMMON_WGSL}
+export const DISPLAY_VIEW_QUALITY_LATTICE_WGSL = /* wgsl */ `${DISPLAY_VIEW_QUALITY_COMMON_WGSL}
 @group(0) @binding(1) var<storage, read> groups: array<u32>;
 @group(0) @binding(2) var<storage, read_write> lattice_out: array<u32>;
 @compute @workgroup_size(${DISPLAY_VIEW_QUALITY_WORKGROUP_SIZE})
@@ -371,7 +365,7 @@ lattice_out[i] = m | select(0u, 0x80000000u, material_uncertain);
  * The end of pass 2, shared by both site passes: from the site's electrons e and their absolute bound de, the readout moments
  * (mean k·e, variance k²e + c₀, third cumulant k³e), the clip at the white level and their bounds, written to site i.
  */
-const SITE_TAIL_WGSL = /* wgsl */ `
+export const DISPLAY_VIEW_QUALITY_SITE_TAIL_WGSL = /* wgsl */ `
 fn write_site(i: u32, c: u32, e: f32, de: f32, flag: u32) {
 let kc = k_of(c);
 let mean = kc * e;
@@ -404,16 +398,38 @@ const siteBindingsWgsl = (tapRecords) => /* wgsl */ `
 @group(0) @binding(4) var<storage, read> lattice: array<u32>;
 @group(0) @binding(5) var<storage, read_write> sites: array<f32>;
 @group(0) @binding(6) var<storage, read> spread: array<f32>;
+${EXACT_SUM_WGSL}
+alias Nodes = array<f32, ${DISPLAY_VIEW_QUALITY_MAXIMUM_NODES}>;
+fn add_tap(p: ptr<function, Nodes>, c: u32, t: u32, m: u32) {
+let N = params.nodes;
+for (var n = 0u; n < N; n = n + 1u) { (*p)[n] = (*p)[n] + table[(c * params.taps + t) * N + n] * table[(3u * params.taps + m) * N + n]; }
+}
+fn add_nodes(p: ptr<function, Nodes>, q: ptr<function, Nodes>) { for (var n = 0u; n < params.nodes; n = n + 1u) { (*p)[n] = (*p)[n] + (*q)[n]; (*q)[n] = 0.0; } }
+fn node_total(p: ptr<function, Nodes>, dark: f32) -> f32 {
+var anchor = exact_exponent(dark);
+for (var k = 0u; k < params.nodes; k = k + 1u) { if ((*p)[k] > 0.0) { anchor = max(anchor, exact_exponent((*p)[k])); } }
+var sum: ExactSum;
+sum.anchor = anchor;
+for (var k = 0u; k < params.nodes; k = k + 1u) { exact_add(&sum, (*p)[k]); }
+exact_add(&sum, dark);
+return exact_round(&sum);
+}
 `;
 /**
  * Pass 2: the expected electrons, readout moments and white clip of every native site of the band's window, with their bounds.
- * The site's electrons are Σ_t table[(m_t·3 + c)·T + t] + dark_c, every term non-negative and rounded once on the host, so the
- * sum carries (T + 3)·E relative (`params.site_gamma`, the host's value). An uncertain lattice point adds the tap's value spread
+ * 2.21.0 (signals integrated from the material spectrum per site): the site's electrons are Σ_t Σ_n C_c(t, n)·L_{m_t}(λ_n) +
+ * dark_c, from the channel's per-node kernel values and the spectrum of the material each tap reads (`table`: C at
+ * (c·T + t)·N + n, the spectra from 3·T·N), accumulated per node over the taps, then the node partials and the dark electrons
+ * summed in integer arithmetic and rounded once (EXACT_SUM_WGSL). Every term is non-negative and carries two host roundings (E/2
+ * each), its product (E) and at most T − 1 additions, then the final rounding (E), and the dark electrons their host rounding
+ * (E/2), so the sum carries at most (T + 2.5)·E, inside (T + 3)·E
+ * (`params.site_gamma`),
+ * plus `params.site_tiny`, the host's absolute bound on what a device that flushes below the float32 normal range can drop. An uncertain lattice point adds the tap's value spread
  * over the materials (`spread`, host float64) to the site's uncertainty, which enters its bounds, or flags the site when it
  * exceeds UNCERTAINTY_LIMIT of the electrons. One dispatch covers the `params.count` sites from `params.site_first` (#492: the
  * host splits a band's sites over several dispatches so that no dispatch gathers more than its tap budget).
  */
-export const DISPLAY_VIEW_QUALITY_SITES_WGSL = /* wgsl */ `${COMMON_WGSL}${siteBindingsWgsl(true)}${SITE_TAIL_WGSL}
+export const DISPLAY_VIEW_QUALITY_SITES_WGSL = /* wgsl */ `${DISPLAY_VIEW_QUALITY_COMMON_WGSL}${siteBindingsWgsl(true)}${DISPLAY_VIEW_QUALITY_SITE_TAIL_WGSL}
 @compute @workgroup_size(${DISPLAY_VIEW_QUALITY_WORKGROUP_SIZE})
 fn main(@builtin(global_invocation_id) gid: vec3<u32>, @builtin(num_workgroups) wg: vec3<u32>) {
   let local = gid.x + gid.y * wg.x * ${DISPLAY_VIEW_QUALITY_WORKGROUP_SIZE}u;
@@ -424,44 +440,42 @@ let jj = i / params.site_w;
 let x = params.site_x0 + i32(ii);
 let y = params.site_y0 + i32(jj);
 let c = channel_of(x, y);
-var sum = 0.0;
 var uncertainty = 0.0;
 let T = params.taps;
+var partial: Nodes;
 for (var t = 0u; t < T; t = t + 1u) {
 let tb = t * TAP;
 let g = taps[tb] * GROUP;
 let index = groups[g + 4u] + (jj + taps[tb + 2u]) * groups[g + 2u] + ii + taps[tb + 1u];
 let raw = lattice[index];
 if ((raw >> 31u) != 0u) { uncertainty = uncertainty + spread[c * T + t]; }
-sum = sum + table[((raw & 0x7fffffffu) * 3u + c) * T + t];
+add_tap(&partial, c, t, raw & 0x7fffffffu);
 }
-let e = sum + dark_of(c);
+let e = node_total(&partial, dark_of(c));
 let flag = select(0u, 1u, uncertainty > UNCERTAINTY_LIMIT * e);
-let de = params.site_gamma * e + uncertainty;
+let de = params.site_gamma * e + uncertainty + params.site_tiny;
 write_site(i, c, e, de, flag);
 }
 `;
 /**
- * Pass 2 with the defocus disc (#492): the same site electrons from a factored table, summed in blocks.
+ * Pass 2 with the defocus disc (#492): the same site electrons, summed in blocks.
  *
- * - **Factored table.** A neutral material's value is its reflectance times the white's combined kernel (the reference forms it
- *   so: reflectance[m]·neutral_c(t)), so the table holds one neutral row per channel and one row per spectral material, and
- *   `materials` holds per material its row (0 for neutral, 1 + s for spectral material s) and its reflectance as float32 bits
- *   (1 for a spectral material, an exact product). A scene of thousands of neutral materials (#491's composite: 4 143) then
- *   needs 3·T values instead of 3·T per material.
+ * - **Spectral table.** The pass reads the tap-list pass's table (2.21.0): the channel's per-node kernel values C_c(t, n) and each
+ *   material's spectrum, so the signal of each tap is integrated from its material's spectrum when the site is read.
  * - **Blocked sum.** Every group's taps form a dense cw × ch rectangle (the combined kernel's window, row-major from the group's
- *   first tap, `groups[g + 5]`), so a site sums each row of a group into a row partial, the rows into a group partial and the
- *   groups into the total. No tap records are read: the tap's lattice offset within its group is its (dx, dy).
+ *   first tap, `groups[g + 5]`), so a site sums each row of a group into a row partial per node, the rows into a group partial
+ *   and the groups into the total, then the nodes in integer arithmetic. No tap records are read: the tap's lattice offset
+ *   within its group is its (dx, dy).
  *
- * Every term is non-negative and carries two host roundings (u each, u = E/2: the row value and the reflectance), one product
- * (E) and at most cw + ch + G additions, plus the dark electrons' addition, so the electrons carry (cw_max + ch_max + G + 3)·E
- * relative (`params.site_gamma`; recursive summation of the up to 4·(2·96 + 2)² = 150 544 taps of a combined radius of 96 would
- * carry (T + 3)·E ≈ 1.8 % instead). The uncertainty, summed the same way, is scaled by 1 + site_gamma, and `params.site_tiny`
- * (host float64, rounded up) bounds the terms below the float32 normal range, which a device may flush to zero.
+ * Every term is non-negative and carries two host roundings (u each, u = E/2: the kernel value and the spectrum), one product
+ * (E) and at most cw − 1 + ch − 1 + G − 1 inexact additions, then the integer sum of the node partials and the dark electrons,
+ * rounded once (E), and the dark electrons' host rounding (E/2), so the electrons carry at most (cw_max + ch_max + G + 0.5)·E, inside (cw_max + ch_max + G + 3)·E (`params.site_gamma`;
+ * recursive summation of the up to 4·(2·96 + 2)² = 150 544 taps of a combined radius of 96 would carry (T + 3)·E ≈ 1.8 %
+ * instead). The uncertainty, summed the same way, is scaled by 1 + site_gamma, and `params.site_tiny` (host float64, rounded up)
+ * bounds what a device that flushes results below the float32 normal range can drop (the tap-list pass adds it too).
  */
-export const DISPLAY_VIEW_QUALITY_SITES_BLOCKED_WGSL = /* wgsl */ `${COMMON_WGSL}${siteBindingsWgsl(false)}
-@group(0) @binding(7) var<storage, read> materials: array<u32>;
-${SITE_TAIL_WGSL}
+export const DISPLAY_VIEW_QUALITY_SITES_BLOCKED_WGSL = /* wgsl */ `${DISPLAY_VIEW_QUALITY_COMMON_WGSL}${siteBindingsWgsl(false)}
+${DISPLAY_VIEW_QUALITY_SITE_TAIL_WGSL}
 @compute @workgroup_size(${DISPLAY_VIEW_QUALITY_WORKGROUP_SIZE})
 fn main(@builtin(global_invocation_id) gid: vec3<u32>, @builtin(num_workgroups) wg: vec3<u32>) {
   let local = gid.x + gid.y * wg.x * ${DISPLAY_VIEW_QUALITY_WORKGROUP_SIZE}u;
@@ -473,7 +487,9 @@ let x = params.site_x0 + i32(ii);
 let y = params.site_y0 + i32(jj);
 let c = channel_of(x, y);
 let T = params.taps;
-var sum = 0.0;
+var total: Nodes;
+var group_sum: Nodes;
+var row_sum: Nodes;
 var uncertainty = 0.0;
 for (var k = 0u; k < params.groups; k = k + 1u) {
 let g = k * GROUP;
@@ -482,57 +498,50 @@ let cw = lw - params.site_w + 1u;
 let ch = groups[g + 3u] - params.site_h + 1u;
 let lattice0 = groups[g + 4u] + jj * lw + ii;
 let tap0 = groups[g + 5u];
-var group_sum = 0.0;
 var group_uncertainty = 0.0;
 for (var dy = 0u; dy < ch; dy = dy + 1u) {
 let row = lattice0 + dy * lw;
 let row_tap = tap0 + dy * cw;
-var row_sum = 0.0;
 var row_uncertainty = 0.0;
 for (var dx = 0u; dx < cw; dx = dx + 1u) {
 let raw = lattice[row + dx];
 let t = row_tap + dx;
-let m = 2u * (raw & 0x7fffffffu);
 if ((raw >> 31u) != 0u) { row_uncertainty = row_uncertainty + spread[c * T + t]; }
-row_sum = row_sum + bitcast<f32>(materials[m + 1u]) * table[(materials[m] * 3u + c) * T + t];
+add_tap(&row_sum, c, t, raw & 0x7fffffffu);
 }
-group_sum = group_sum + row_sum;
+add_nodes(&group_sum, &row_sum);
 group_uncertainty = group_uncertainty + row_uncertainty;
 }
-sum = sum + group_sum;
+add_nodes(&total, &group_sum);
 uncertainty = uncertainty + group_uncertainty;
 }
-let e = sum + dark_of(c);
+let e = node_total(&total, dark_of(c));
 let flag = select(0u, 1u, uncertainty > UNCERTAINTY_LIMIT * e);
 let de = params.site_gamma * e + uncertainty * (1.0 + params.site_gamma) + params.site_tiny;
 write_site(i, c, e, de, flag);
 }
 `;
 /** Pass 3: the display pixels (see the module comment). */
-export const DISPLAY_VIEW_QUALITY_PIXELS_WGSL = /* wgsl */ `${COMMON_WGSL}
-const KEY_LEVELS: u32 = ${AHD_KEY_LEVELS}u;
-const KEY_STEPS: f32 = ${literal(AHD_KEY_STEPS)};
-const KEY_OCTAVES: f32 = ${literal(AHD_KEY_OCTAVES)};
-const KEY_FLOOR: f32 = ${literal(AHD_KEY_FLOOR)};
-const KEY_TOP: u32 = ${AHD_KEY_OCTAVES * AHD_KEY_STEPS - 1}u;
+/*
+ * 2.22.0: in the luminance branch the nested loops read the colour matrix rows from one local array (`mm`) instead of calling
+ * `m_of` (a `switch`): SwiftShader's compiler ended the GPU process on the `switch` inside those loops (after about 44 s). The
+ * values are the same (docs/WEBGPU.md, "Coupled rendering steps").
+ */
+export const DISPLAY_VIEW_QUALITY_PIXELS_BODY_WGSL = /* wgsl */ `${DISPLAY_VIEW_QUALITY_COMMON_WGSL}
 const CAND_BASE: u32 = ${DISPLAY_VIEW_QUALITY_AUX.candidates}u;
 const CAND_STRIDE: u32 = ${CANDIDATE_PHASE_STRIDE}u;
 const FLAG_UNCERTAIN: u32 = ${DISPLAY_VIEW_QUALITY_FLAG.materialUncertain}u;
 const FLAG_OUTSIDE: u32 = ${DISPLAY_VIEW_QUALITY_FLAG.siteOutsideWindow}u;
-const FLAG_STATE: u32 = ${DISPLAY_VIEW_QUALITY_FLAG.stateMissing}u;
-const FLAG_TIE: u32 = ${DISPLAY_VIEW_QUALITY_FLAG.thresholdTie}u;
-const FLAG_CORRECTED: u32 = ${DISPLAY_VIEW_QUALITY_FLAG.corrected}u;
 const FLAG_CHOICE: u32 = ${DISPLAY_VIEW_QUALITY_FLAG.ahdChoice}u;
 const FLAG_HIGHLIGHT: u32 = ${DISPLAY_VIEW_QUALITY_FLAG.highlightUndecided}u;
 const CHOICE_SIGMA: f32 = ${literal(DISPLAY_VIEW_QUALITY_CHOICE_SIGMA)};
 @group(0) @binding(1) var<storage, read> aux: array<f32>;
 @group(0) @binding(2) var<storage, read> geometry: array<f32>;
 @group(0) @binding(3) var<storage, read> sites: array<f32>;
-@group(0) @binding(4) var<storage, read> state_keys: array<i32>;
-@group(0) @binding(5) var<storage, read> state_values: array<f32>;
-@group(0) @binding(6) var<storage, read_write> bitmap: array<atomic<u32>>;
-@group(0) @binding(7) var<storage, read_write> out: array<f32>;
-@group(0) @binding(8) var<storage, read_write> flags: array<u32>;
+@group(0) @binding(4) var<storage, read_write> out: array<f32>;
+@group(0) @binding(5) var<storage, read_write> flags: array<u32>;
+
+fn cp_k(i: u32) -> f32 { return aux[${DISPLAY_VIEW_QUALITY_AUX.size}u + i]; }
 
 var<private> pixel_flags: u32;
 ${REINHARD_WGSL}
@@ -549,66 +558,6 @@ return o;
 }
 
 fn clip_bits(o: u32) -> u32 { return (bitcast<u32>(sites[o + 6u]) >> 1u) & 3u; }
-
-fn find_state(key: i32) -> u32 {
-var lo = 0u; var hi = params.state_count;
-while (lo < hi) {
-let mid = (lo + hi) / 2u;
-if (state_keys[mid] < key) { lo = mid + 1u; } else { hi = mid; }
-}
-if (lo < params.state_count && state_keys[lo] == key) { return lo; }
-return params.state_count;
-}
-
-
-
-fn flat_correction(m0: vec2<f32>, m1: vec2<f32>, m2: vec2<f32>, corr: ptr<function, array<vec2<f32>, 3>>) {
-var base: array<u32, 3>; var frac: array<f32, 3>; var dg: array<f32, 3>;
-for (var i = 0u; i < 3u; i = i + 1u) {
-var mi = m0; if (i == 1u) { mi = m1; } if (i == 2u) { mi = m2; }
-let clamped = clamp(mi.x, KEY_FLOOR, 1.0);
-let g = (log2(clamped) + KEY_OCTAVES) * KEY_STEPS;
-let b = min(u32(max(floor(g), 0.0)), KEY_TOP);
-base[i] = b; frac[i] = g - f32(b);
-
-var slope = 0.0; if (mi.x > KEY_FLOOR && mi.x < 1.0) { slope = 1.4426950408889634 * mi.y / clamped; }
-dg[i] = KEY_STEPS * (slope + 4.76837158203125e-7 + 36.0 * E) + 2.0 * E * (g + 1.0);
-}
-var values: array<f32, 24>;
-var missing = false;
-for (var corner = 0u; corner < 8u; corner = corner + 1u) {
-let i0 = base[0] + (corner & 1u); let i1 = base[1] + ((corner >> 1u) & 1u); let i2 = base[2] + ((corner >> 2u) & 1u);
-let key = i32((i0 * KEY_LEVELS + i1) * KEY_LEVELS + i2);
-var weight = 1.0;
-for (var i = 0u; i < 3u; i = i + 1u) { weight = weight * select(1.0 - frac[i], frac[i], ((corner >> i) & 1u) == 1u); }
-if (weight == 0.0) { for (var c = 0u; c < 3u; c = c + 1u) { values[corner * 3u + c] = 0.0; } continue; }
-atomicOr(&bitmap[u32(key) / 32u], 1u << (u32(key) % 32u));
-let at = find_state(key);
-if (at >= params.state_count) { missing = true; continue; }
-for (var c = 0u; c < 3u; c = c + 1u) { values[corner * 3u + c] = state_values[at * 3u + c]; }
-}
-if (missing) { pixel_flags = pixel_flags | FLAG_STATE; for (var c = 0u; c < 3u; c = c + 1u) { (*corr)[c] = vec2<f32>(0.0, 0.0); } return; }
-for (var c = 0u; c < 3u; c = c + 1u) {
-var sum = 0.0; var mag = 0.0;
-for (var corner = 0u; corner < 8u; corner = corner + 1u) {
-var weight = 1.0;
-for (var i = 0u; i < 3u; i = i + 1u) { weight = weight * select(1.0 - frac[i], frac[i], ((corner >> i) & 1u) == 1u); }
-sum = sum + weight * values[corner * 3u + c];
-mag = mag + abs(weight * values[corner * 3u + c]);
-}
-
-var slope_term = 0.0;
-for (var i = 0u; i < 3u; i = i + 1u) {
-var largest = 0.0;
-for (var corner = 0u; corner < 8u; corner = corner + 1u) {
-if (((corner >> i) & 1u) == 1u) { continue; }
-largest = max(largest, abs(values[(corner | (1u << i)) * 3u + c] - values[corner * 3u + c]));
-}
-slope_term = slope_term + dg[i] * largest;
-}
-(*corr)[c] = vec2<f32>(sum, slope_term + 12.0 * E * mag);
-}
-}
 @compute @workgroup_size(${DISPLAY_VIEW_QUALITY_WORKGROUP_SIZE})
 fn main(@builtin(global_invocation_id) gid: vec3<u32>, @builtin(num_workgroups) wg: vec3<u32>) {
   let i = gid.x + gid.y * wg.x * ${DISPLAY_VIEW_QUALITY_WORKGROUP_SIZE}u;
@@ -625,6 +574,9 @@ let ny = bitcast<u32>(geometry[row + 1u]);
 let margin = i32(params.margin);
 let reinhard = params.tone == 1u;
 let count = params.candidates;
+
+var cp_used = false;
+var cp_a: array<vec2<f32>, 9>;
 let share = select(1.0, 0.5, count == 2u);
 
 let xb_even = geometry[col + 8u]; let xb_odd = geometry[col + 9u];
@@ -689,8 +641,6 @@ let bit = j * nx + ii;
 if (bit < 32u) { mask0 = mask0 | (1u << bit); } else { mask1 = mask1 | (1u << (bit - 32u)); }
 } else if ((clip_any & 2u) != 0u) { undecided = true; }
 var e_mean = array<vec2<f32>, 3>(vec2<f32>(0.0), vec2<f32>(0.0), vec2<f32>(0.0));
-var cm_average = array<vec2<f32>, 3>(vec2<f32>(0.0), vec2<f32>(0.0), vec2<f32>(0.0));
-var pixel_variance = vec2<f32>(0.0, 0.0);
 var bs: array<vec2<f32>, 3>; var hs: array<vec2<f32>, 3>;
 var hv: array<vec2<f32>, 3>;
 
@@ -717,17 +667,26 @@ cm[0] = b_add(cm[0], b_scale(sm, w0)); cm[1] = b_add(cm[1], b_scale(sm, w1)); cm
 C[0] = b_add(C[0], b_scale(sv, w0 * w0)); C[1] = b_add(C[1], b_scale(sv, w0 * w1)); C[2] = b_add(C[2], b_scale(sv, w0 * w2));
 C[3] = b_add(C[3], b_scale(sv, w1 * w1)); C[4] = b_add(C[4], b_scale(sv, w1 * w2)); C[5] = b_add(C[5], b_scale(sv, w2 * w2));
 }
-for (var c = 0u; c < 3u; c = c + 1u) { if (exact[c]) { cm[c].y = 0.0; } cm_average[c] = b_add(cm_average[c], b_scale(cm[c], share)); }
+for (var c = 0u; c < 3u; c = c + 1u) { if (exact[c]) { cm[c].y = 0.0; } }
+
+
+var cp_chain_run = false;
+if (cp_on() && cp_reconstruct()) {
+let reach = cp_reconstruct_reach(vec3<f32>(cm[0].x, cm[1].x, cm[2].x), vec3<f32>(C[0].x, C[3].x, C[5].x));
+if (reach == 2u) { pixel_flags = pixel_flags | FLAG_UNCERTAIN; }
+cp_chain_run = reach >= 1u;
+}
+let cp_unclipped = cp_on() && cp_reconstruct();
 
 
 var bm: array<vec2<f32>, 3>; var bv: array<vec2<f32>, 3>;
 for (var c = 0u; c < 3u; c = c + 1u) {
 let gc = b_rounded(g_of(c));
 var um = b_mul(gc, cm[c]);
-if (exact[c] && cm[c].x == 1.0 && gain_at_clip(c)) { um = vec2<f32>(params.clip_level, 0.0); }
+if (exact[c] && cm[c].x == 1.0 && gain_at_clip(c) && !cp_unclipped) { um = vec2<f32>(params.clip_level, 0.0); }
 let uv = b_mul(b_mul(gc, gc), C[select(select(0u, 3u, c == 1u), 5u, c == 2u)]);
 let gap = params.clip_level - um.x;
-if (gap > 0.0 && gap * gap > params.reach2 * uv.x) { bm[c] = um; bv[c] = uv; bs[c] = gc; }
+if (cp_unclipped || (gap > 0.0 && gap * gap > params.reach2 * uv.x)) { bm[c] = um; bv[c] = uv; bs[c] = gc; }
 else { let clipped = upper_clip(um, uv, params.clip_level); bm[c] = clipped.mean; bv[c] = clipped.variance; bs[c] = b_mul(gc, clipped.slope); }
 }
 
@@ -763,16 +722,75 @@ if (variance.x > 0.0) { skew = b_div(third, b_mul(variance, b_sqrt(variance)));
 moments = unit_clip(mean, variance, skew);
 }
 hm[comp] = moments.mean; hv[comp] = moments.variance; hs[comp] = moments.slope;
-h_cand[d * 3u + comp] = moments.mean;
-e_mean[comp] = b_add(e_mean[comp], b_scale(moments.mean, share));
-pixel_variance = vec2<f32>(max(pixel_variance.x, moments.variance.x), max(pixel_variance.y, moments.variance.y));
 }
 
 var an: array<vec2<f32>, 9>;
+cp_used = false;
+if (cp_on()) {
+if (!cp_chain_run && cp_luminance()) {
+var mu = vec3<f32>(0.0); var dmu = vec3<f32>(0.0); var dsv = vec3<f32>(0.0);
+var srow = array<vec3<f32>, 3>(vec3<f32>(0.0), vec3<f32>(0.0), vec3<f32>(0.0));
+var cc = array<f32, 9>(C[0].x, C[1].x, C[2].x, C[1].x, C[3].x, C[4].x, C[2].x, C[4].x, C[5].x);
+var mm = array<vec3<f32>, 3>(vec3<f32>(params.m00, params.m01, params.m02), vec3<f32>(params.m10, params.m11, params.m12), vec3<f32>(params.m20, params.m21, params.m22));
+for (var r = 0u; r < 3u; r = r + 1u) {
+mu[r] = mm[r][0] * bm[0].x + mm[r][1] * bm[1].x + mm[r][2] * bm[2].x;
+dmu[r] = abs(mm[r][0]) * bm[0].y + abs(mm[r][1]) * bm[1].y + abs(mm[r][2]) * bm[2].y;
+dsv[r] = mm[r][0] * mm[r][0] * bv[0].y + mm[r][1] * mm[r][1] * bv[1].y + mm[r][2] * mm[r][2] * bv[2].y;
+for (var q = 0u; q < 3u; q = q + 1u) {
+var v = 0.0;
+for (var a = 0u; a < 3u; a = a + 1u) { for (var b = 0u; b < 3u; b = b + 1u) {
+var bab = bv[a].x; if (a != b) { bab = bs[a].x * bs[b].x * cc[a * 3u + b]; }
+v = v + mm[r][a] * mm[q][b] * bab;
+} }
+srow[r][q] = v;
+}
+}
+let t = cp_tone(mu, srow[0], srow[1], srow[2], dmu, dsv);
+if (t.flag) { pixel_flags = pixel_flags | FLAG_UNCERTAIN; }
+if (cp_desaturate() && t.top) { cp_chain_run = true; }
+else {
+let rows = array<vec3<f32>, 3>(t.a0, t.a1, t.a2);
+for (var comp = 0u; comp < 3u; comp = comp + 1u) {
+hm[comp] = vec2<f32>(t.hm[comp], t.bm[comp]); hv[comp] = vec2<f32>(t.hv[comp], t.bv[comp]);
 for (var c = 0u; c < 3u; c = c + 1u) {
+let jmc = rows[comp].x * m_of(0u, c) + rows[comp].y * m_of(1u, c) + rows[comp].z * m_of(2u, c);
+let ajm = abs(rows[comp].x * m_of(0u, c)) + abs(rows[comp].y * m_of(1u, c)) + abs(rows[comp].z * m_of(2u, c));
+let value = jmc * bs[c].x;
+an[comp * 3u + c] = vec2<f32>(value, ajm * bs[c].y + abs(value) * (t.ju + 4.0 * E));
+}
+}
+cp_used = true;
+}
+} else if (!cp_chain_run && cp_desaturate() && !reinhard) {
+for (var comp = 0u; comp < 3u; comp = comp + 1u) {
+let top = hm[comp].x + CLIP_REACH * sqrt(hv[comp].x);
+if (hm[comp].x > 0.0 && top >= 0.999) { cp_chain_run = true; }
+if (hm[comp].x > 0.0 && hm[comp].x - 2.0 * hm[comp].y < 0.999 && abs(top - 0.999) <= 2.0 * (hm[comp].y + CLIP_REACH * min(sqrt(hv[comp].y), hv[comp].y / (2.0 * sqrt(hv[comp].x)))) + 64.0 * E) { pixel_flags = pixel_flags | FLAG_UNCERTAIN; }
+}
+}
+if (cp_chain_run) {
+let t = cp_chain(vec3<f32>(cm[0].x, cm[1].x, cm[2].x), C[0].x, C[1].x, C[2].x, C[3].x, C[4].x, C[5].x, vec3<f32>(cm[0].y, cm[1].y, cm[2].y), vec3<f32>(C[0].y, C[3].y, C[5].y));
+if (t.flag) { pixel_flags = pixel_flags | FLAG_UNCERTAIN; }
+let rows = array<vec3<f32>, 3>(t.a0, t.a1, t.a2);
+for (var comp = 0u; comp < 3u; comp = comp + 1u) {
+hm[comp] = vec2<f32>(t.hm[comp], t.bm[comp]); hv[comp] = vec2<f32>(t.hv[comp], t.bv[comp]);
+for (var c = 0u; c < 3u; c = c + 1u) { an[comp * 3u + c] = vec2<f32>(rows[comp][c], abs(rows[comp][c]) * t.ju); }
+}
+cp_used = true;
+}
+if (cp_used) { for (var k = 0u; k < 9u; k = k + 1u) { cp_a[k] = an[k]; } }
+}
+for (var comp = 0u; comp < 3u; comp = comp + 1u) {
+h_cand[d * 3u + comp] = hm[comp];
+e_mean[comp] = b_add(e_mean[comp], b_scale(hm[comp], share));
+}
+
+for (var c = 0u; c < 3u; c = c + 1u) {
+if (!cp_used) {
 an[c] = b_mul(b_mul(hs[0], b_rounded(m_of(0u, c))), bs[c]);
 an[3u + c] = b_mul(b_mul(hs[1], b_rounded(m_of(1u, c))), bs[c]);
 an[6u + c] = b_mul(b_mul(hs[2], b_rounded(m_of(2u, c))), bs[c]);
+}
 var bc = b0; if (c == 1u) { bc = b1; } if (c == 2u) { bc = b2; }
 let wgt = b_mul(b_mul(b_scale(aj, share), b_rounded(bc)), csv[c]);
 cov[0] = b_add(cov[0], b_mul(b_mul(wgt, an[c]), an[c])); cov[1] = b_add(cov[1], b_mul(b_mul(wgt, an[c]), an[3u + c])); cov[2] = b_add(cov[2], b_mul(b_mul(wgt, an[c]), an[6u + c]));
@@ -813,24 +831,21 @@ let d0 = b_scale(bs[0], aux[eb + 2u] - aux[eb + 5u]);
 let d1 = b_scale(bs[1], aux[eb + 3u] - aux[eb + 6u]);
 let d2 = b_scale(bs[2], aux[eb + 4u] - aux[eb + 7u]);
 let sv = vec2<f32>(sites[o + 1u], sites[o + 4u]);
-let a = b_mul(hs[0], b_add(b_add(b_mul(b_rounded(params.m00), d0), b_mul(b_rounded(params.m01), d1)), b_mul(b_rounded(params.m02), d2)));
-let b = b_mul(hs[1], b_add(b_add(b_mul(b_rounded(params.m10), d0), b_mul(b_rounded(params.m11), d1)), b_mul(b_rounded(params.m12), d2)));
-let c = b_mul(hs[2], b_add(b_add(b_mul(b_rounded(params.m20), d0), b_mul(b_rounded(params.m21), d1)), b_mul(b_rounded(params.m22), d2)));
+var a = b_mul(hs[0], b_add(b_add(b_mul(b_rounded(params.m00), d0), b_mul(b_rounded(params.m01), d1)), b_mul(b_rounded(params.m02), d2)));
+var b = b_mul(hs[1], b_add(b_add(b_mul(b_rounded(params.m10), d0), b_mul(b_rounded(params.m11), d1)), b_mul(b_rounded(params.m12), d2)));
+var c = b_mul(hs[2], b_add(b_add(b_mul(b_rounded(params.m20), d0), b_mul(b_rounded(params.m21), d1)), b_mul(b_rounded(params.m22), d2)));
+if (cp_used) {
+
+let e0 = aux[eb + 2u] - aux[eb + 5u]; let e1 = aux[eb + 3u] - aux[eb + 6u]; let e2 = aux[eb + 4u] - aux[eb + 7u];
+a = b_add(b_add(b_scale(cp_a[0], e0), b_scale(cp_a[1], e1)), b_scale(cp_a[2], e2));
+b = b_add(b_add(b_scale(cp_a[3], e0), b_scale(cp_a[4], e1)), b_scale(cp_a[5], e2));
+c = b_add(b_add(b_scale(cp_a[6], e0), b_scale(cp_a[7], e1)), b_scale(cp_a[8], e2));
+}
 x0 = b_add(x0, b_mul(b_mul(a, a), sv)); x1 = b_add(x1, b_mul(b_mul(b, b), sv)); x2 = b_add(x2, b_mul(b_mul(c, c), sv));
 }
 let ajaj = b_mul(aj, aj);
 res[0] = b_add(res[0], b_mul(ajaj, b_scale(x0, 0.25))); res[1] = b_add(res[1], b_mul(ajaj, b_scale(x1, 0.25))); res[2] = b_add(res[2], b_mul(ajaj, b_scale(x2, 0.25)));
 }
-if (params.correction == 1u) {
-
-if (abs(pixel_variance.x - params.threshold) <= pixel_variance.y) { pixel_flags = pixel_flags | FLAG_TIE; }
-if (pixel_variance.x > params.threshold) {
-var corr: array<vec2<f32>, 3>;
-flat_correction(cm_average[0], cm_average[1], cm_average[2], &corr);
-for (var comp = 0u; comp < 3u; comp = comp + 1u) { s[comp] = b_add(s[comp], b_mul(aj, corr[comp])); }
-pixel_flags = pixel_flags | FLAG_CORRECTED;
-}
-}
 }
 }
 
@@ -847,6 +862,11 @@ flags[3u * i + 1u] = mask0;
 flags[3u * i + 2u] = mask1;
 }
 `;
+/** The pixel pass (`DISPLAY_VIEW_QUALITY_PIXELS_BODY_WGSL`) with the coupled steps' text: the stub by default, the coupled steps on demand (#593). */
+export function assembleDisplayViewQualityPixelsWgsl(coupledWgsl = DISPLAY_VIEW_COUPLED_STUB_WGSL) {
+    return DISPLAY_VIEW_QUALITY_PIXELS_BODY_WGSL + "\n" + coupledWgsl;
+}
+export const DISPLAY_VIEW_QUALITY_PIXELS_WGSL = /* @__PURE__ */ assembleDisplayViewQualityPixelsWgsl();
 /** The lattice pass with a material module appended (`fn material_at(p: vec2<f32>) -> u32`, `var<private> material_uncertain: bool`). */
 export function assembleDisplayViewQualityLatticeWgsl(materialModuleWgsl) {
     return DISPLAY_VIEW_QUALITY_LATTICE_WGSL + "\n" + materialModuleWgsl + "\n";