@photivra/engine 2.20.0 → 2.22.0

package/dist/gpu/wgsl-display-view-quality-kernel.d.ts

@@ -1,6 +1,8 @@
 export declare const DISPLAY_VIEW_QUALITY_WORKGROUP_SIZE = 64;
 /** Largest footprint per axis (real pixels), as the Speed kernel. */
 export declare 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 declare const DISPLAY_VIEW_QUALITY_MAXIMUM_NODES = 96;
 /** Uniform parameter words (see `Params`): 56 words, 224 bytes. */
 export declare 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). */
@@ -35,12 +37,6 @@ export declare const DISPLAY_VIEW_QUALITY_FLAG: Readonly<{
     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;
     /**
      * #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
@@ -50,7 +46,7 @@ export declare const DISPLAY_VIEW_QUALITY_FLAG: Readonly<{
     /** #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 declare const DISPLAY_VIEW_QUALITY_FLAG_WORDS = 3;
@@ -60,8 +56,6 @@ export declare 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 declare const DISPLAY_VIEW_QUALITY_CHOICE_SIGMA: number;
-/** Words of the grid-key bitmap: one bit per grid key (AHD_KEY_LEVELS³ keys). */
-export declare const DISPLAY_VIEW_QUALITY_BITMAP_WORDS: number;
 /**
  * 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
@@ -70,6 +64,8 @@ export declare const DISPLAY_VIEW_QUALITY_BITMAP_WORDS: number;
 export declare const DISPLAY_VIEW_QUALITY_UNCERTAINTY_LIMIT: number;
 /** Bound constant of a clipped-normal slope Φ(z) (in units of E): z's 8E through φ·|z| ≤ 0.24 plus the Abramowitz–Stegun 147E. */
 export declare const DISPLAY_VIEW_QUALITY_SLOPE_U = 200;
+/** The parameter struct and the bound helpers shared by the three passes. */
+export declare const DISPLAY_VIEW_QUALITY_COMMON_WGSL: string;
 /**
  * Pass 1: the material of every lattice point of every group (the module's `material_at`, its uncertainty in bit 31; the output
  * is `lattice_out`, since a material module may declare its own `lattice`, as #491's composite module does). The group
@@ -77,35 +73,48 @@ export declare const DISPLAY_VIEW_QUALITY_SLOPE_U = 200;
  * 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 declare const DISPLAY_VIEW_QUALITY_LATTICE_WGSL: string;
+/**
+ * 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.
+ */
+export declare const DISPLAY_VIEW_QUALITY_SITE_TAIL_WGSL = "\nfn write_site(i: u32, c: u32, e: f32, de: f32, flag: u32) {\n  let kc = k_of(c);\n  let mean = kc * e;\n  let variance = kc * kc * e + c0_of(c);\n  let third = kc * kc * kc * e;\n  var m = vec2<f32>(mean, kc * de + 2.0 * E * mean);\n  var v = vec2<f32>(variance, kc * kc * de + 4.0 * E * variance);\n  let gap = 1.0 - mean;\n  // #533: bits 1 (certainly clipped) and 2 (undecided) of the flag word.\n  let state = clip_state(m.x, m.y, v.x, v.y);\n  let bits = flag | select(0u, 2u, state == 1u) | select(0u, 4u, state == 2u);\n  if (!(gap > 0.0 && gap * gap > params.reach2 * variance)) {\n    let clipped = upper_clip(m, v, 1.0);\n    m = clipped.mean; v = clipped.variance;\n  }\n  let o = i * SITE;\n  sites[o] = m.x; sites[o + 1u] = v.x; sites[o + 2u] = third;\n  sites[o + 3u] = m.y; sites[o + 4u] = v.y; sites[o + 5u] = kc * kc * kc * de + 5.0 * E * third;\n  sites[o + 6u] = bitcast<f32>(bits); sites[o + 7u] = e;\n}\n";
 /**
  * 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 declare const DISPLAY_VIEW_QUALITY_SITES_WGSL: string;
 /**
- * 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 declare const DISPLAY_VIEW_QUALITY_SITES_BLOCKED_WGSL: string;
 /** Pass 3: the display pixels (see the module comment). */
+export declare const DISPLAY_VIEW_QUALITY_PIXELS_BODY_WGSL: string;
+/** 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 declare function assembleDisplayViewQualityPixelsWgsl(coupledWgsl?: string): string;
 export declare const DISPLAY_VIEW_QUALITY_PIXELS_WGSL: string;
 /** The lattice pass with a material module appended (`fn material_at(p: vec2<f32>) -> u32`, `var<private> material_uncertain: bool`). */
 export declare function assembleDisplayViewQualityLatticeWgsl(materialModuleWgsl: string): string;