@driftengine/core 3.62.0 → 4.0.0

package/dist/render/shaders/gpudriven/decode.wgsl.js

@@ -0,0 +1,349 @@
+/** A DriftTexture decode program, interpreted on the device. */
+/**
+ * **`@driftengine/texture`'s `decodeCpu`, as WGSL — the half that package's README has listed as
+ * missing since Wave 2B.** The reference is the specification and this is checked against it by
+ * `scripts/gpu-parity.mjs`, over generated programs and a real texture array.
+ *
+ * **Core does not import that package**, so its vocabulary is written again here and
+ * `decode.wgsl.test.ts` asserts the two are equal.
+ *
+ * **The tables are uniforms because the shading pass is at eight storage buffers**, which is
+ * WebGPU's default per stage. A uniform binding is at most 65,536 bytes, so the tables have fixed
+ * capacities, and `decodeTables.ts` refuses a set that does not fit rather than truncating it.
+ *
+ * **Its networks are evaluated by `../network.wgsl.ts`**, the one evaluator the device has, which
+ * reads their weights through `decodeNetWeight` here. Until 2026-09-17 this module carried its own
+ * copy of the loop.
+ */
+import { networkWgsl } from '../network.wgsl.js';
+export const DECODE_REGISTERS = 16;
+export const DECODE_OPS = {
+    SAMPLE_LATENT: 0,
+    EVAL_NETWORK: 1,
+    SAMPLE_BLOCK: 2,
+    PROCEDURAL_FBM: 3,
+    FLIPBOOK_INDEX: 4,
+    LATENT_LERP: 5,
+    REMAP_CHANNEL: 6,
+    COMPOSITE: 7,
+    CONSTANT: 8,
+};
+/** Lattice clamp, lattice wrap, centre clamp, centre wrap. `ADDRESS_MODE` in the reference. */
+export const DECODE_ADDRESS_MODES = 4;
+/** The order `REMAP_CHANNEL` packs a semantic in, which is `REMAP_SEMANTICS`'. */
+export const DECODE_SEMANTICS = [
+    'albedo-srgb',
+    'albedo-linear',
+    'normal-tangent-yup',
+    'normal-tangent-ydown',
+    'roughness-linear',
+    'gloss-linear',
+    'metallic-linear',
+    'occlusion-linear',
+    'height-linear',
+    'emissive-srgb',
+    'mask-linear',
+];
+/**
+ * **Four in and four out are not a choice**: `EVAL_NETWORK` reads one four-lane register and
+ * writes one. The hidden limit holds a small refinement network, which the bake does not make yet.
+ */
+export const DECODE_NETWORK_INPUTS = 4;
+export const DECODE_NETWORK_OUTPUTS = 4;
+export const DECODE_NETWORK_HIDDEN_LAYERS = 2;
+export const DECODE_NETWORK_WIDTH = 16;
+/** `PROCEDURAL_FBM`'s octave count is a loop bound on the device, so it has one. */
+export const DECODE_FBM_OCTAVES = 16;
+/** Sixty-four material slots, three programs each. */
+export const DECODE_PROGRAM_CAPACITY = 192;
+export const DECODE_NETWORK_CAPACITY = 256;
+export const DECODE_NODE_CAPACITY = 3200;
+/** Blocks of four floats, so fifteen thousand three hundred and sixty weights. */
+export const DECODE_WEIGHT_BLOCKS = 3840;
+export const DECODE_CONSTANT_CAPACITY = 256;
+export const DECODE_NODES_BYTES = (DECODE_PROGRAM_CAPACITY + DECODE_NETWORK_CAPACITY * 2 + DECODE_NODE_CAPACITY) * 16;
+export const DECODE_WEIGHTS_BYTES = (DECODE_WEIGHT_BLOCKS + DECODE_CONSTANT_CAPACITY) * 16;
+/** What a material's program lane holds when it has no program there. */
+export const DECODE_NO_PROGRAM = 0xffffffff;
+/**
+ * The declarations, at the bindings the including module chooses.
+ *
+ * The including module also defines `fn decodeLatentSize() -> f32`, the edge of level 0 in texels,
+ * because where that number lives is the including module's business.
+ */
+export function decodeResourcesWgsl(b) {
+    return /* wgsl */ `
+struct DecodeNodes {
+  programs: array<vec4<u32>, ${DECODE_PROGRAM_CAPACITY}>,
+  networks: array<vec4<u32>, ${DECODE_NETWORK_CAPACITY * 2}>,
+  nodes: array<vec4<u32>, ${DECODE_NODE_CAPACITY}>,
+}
+
+struct DecodeWeights {
+  values: array<vec4<f32>, ${DECODE_WEIGHT_BLOCKS}>,
+  constants: array<vec4<f32>, ${DECODE_CONSTANT_CAPACITY}>,
+}
+
+@group(${b.group}) @binding(${b.nodes}) var<uniform> decodeNodes: DecodeNodes;
+@group(${b.group}) @binding(${b.weights}) var<uniform> decodeWeights: DecodeWeights;
+@group(${b.group}) @binding(${b.latents}) var decodeLatents: texture_2d_array<f32>;
+@group(${b.group}) @binding(${b.clampSampler}) var decodeClampSampler: sampler;
+@group(${b.group}) @binding(${b.repeatSampler}) var decodeRepeatSampler: sampler;
+`;
+}
+/**
+ * The interpreter. Every function is the reference's, operation for operation; where a line looks
+ * odd, `decodeCpu.ts` is why.
+ *
+ * - **Registers are a fresh function-scope array**, zeros, one per call. The reference reuses the
+ *   caller's registers, so its parity check hands it fresh ones per case.
+ * - **`PROCEDURAL_FBM`'s hash is `u32` arithmetic with wrapping multiplies**, which is exactly what
+ *   `Math.imul` computes; only its final division is float, so that operation is compared at a
+ *   stated tolerance.
+ * - **Component-wise aliasing is safe**: the reference reads component `c` of a source before it
+ *   writes component `c` of a destination, so reading whole vectors first gives the same answer
+ *   when a node writes the register it reads.
+ * - **Every index into a table is clamped**, because a uniform array read past its end is clamped
+ *   by the language anyway and saying so is cheaper than finding out.
+ */
+export const DECODE_WGSL = /* wgsl */ `
+fn decodeWeight(index: u32) -> f32 {
+  let block = min(index / 4u, ${DECODE_WEIGHT_BLOCKS - 1}u);
+  return decodeWeights.values[block][index % 4u];
+}
+
+/* The exact sRGB curve, as semantics.ts has it, not the 2.2 power. */
+fn decodeSrgbToLinear(value: f32) -> f32 {
+  if (value <= 0.04045) {
+    return value / 12.92;
+  }
+  return pow((value + 0.055) / 1.055, 2.4);
+}
+
+fn decodeHash(x: i32, y: i32, seed: u32) -> f32 {
+  var h = (bitcast<u32>(x) * 0x27d4eb2du) ^ (bitcast<u32>(y) * 0x165667b1u) ^ (seed * 0x9e3779b1u);
+  h = (h ^ (h >> 15u)) * 0x2c1b3c6du;
+  h = (h ^ (h >> 12u)) * 0x297a2d39u;
+  return f32(h ^ (h >> 15u)) / 4294967295.0;
+}
+
+fn decodeValueNoise(u: f32, v: f32, seed: u32) -> f32 {
+  let x0 = floor(u);
+  let y0 = floor(v);
+  let fx = u - x0;
+  let fy = v - y0;
+  let sx = fx * fx * (3.0 - 2.0 * fx);
+  let sy = fy * fy * (3.0 - 2.0 * fy);
+  let ix = i32(x0);
+  let iy = i32(y0);
+  let a = decodeHash(ix, iy, seed);
+  let b = decodeHash(ix + 1, iy, seed);
+  let c = decodeHash(ix, iy + 1, seed);
+  let d = decodeHash(ix + 1, iy + 1, seed);
+  return (a * (1.0 - sx) + b * sx) * (1.0 - sy) + (c * (1.0 - sx) + d * sx) * sy;
+}
+
+fn decodeFbm(uv: vec2<f32>, seed: u32, octaves: u32) -> f32 {
+  var total = 0.0;
+  var amplitude = 0.5;
+  var frequency = 1.0;
+  let count = clamp(octaves, 1u, ${DECODE_FBM_OCTAVES}u);
+  for (var o = 0u; o < count; o = o + 1u) {
+    total = total + decodeValueNoise(uv.x * frequency * 8.0, uv.y * frequency * 8.0, seed) * amplitude;
+    amplitude = amplitude * 0.5;
+    frequency = frequency * 2.0;
+  }
+  return total;
+}
+
+/*
+ * timeNodes.ts flipbookFrame with loop true: a modulo that stays non-negative, in integers.
+ *
+ * Not raw - count * floor(raw / count). On the device that wrote this check, a float 144 / 12 came
+ * back 11.999999 and floored to 11, so every frame index that was an exact multiple of the frame
+ * count read as the count itself. Integer remainder is what the reference computes, and it has
+ * no rounding to disagree about.
+ */
+fn decodeFlipbook(t: f32, frames: u32, fps: u32) -> f32 {
+  if (frames == 0u) {
+    return 0.0;
+  }
+  let raw = i32(floor(t * f32(fps)));
+  let count = i32(min(frames, 2147483647u));
+  return f32(((raw % count) + count) % count);
+}
+
+fn decodeRemap(value: vec4<f32>, packed: u32) -> vec4<f32> {
+  var dst = value;
+  let semantic = packed >> 4u;
+  let component = packed & 15u;
+  if (component >= 4u) {
+    return dst;
+  }
+  let raw = value[component];
+  var mapped = raw;
+  /* albedo-srgb and emissive-srgb decode; normal-tangent-ydown and gloss-linear flip. */
+  if (semantic == 0u || semantic == 9u) {
+    mapped = decodeSrgbToLinear(raw);
+  } else if (semantic == 3u || semantic == 5u) {
+    mapped = 1.0 - raw;
+  }
+  dst[component] = mapped;
+  return dst;
+}
+
+/* The networks are the engine's one evaluator, reading its weights out of the uniform table. */
+fn decodeNetWeight(index: u32) -> f32 {
+  return decodeWeight(index);
+}
+${networkWgsl({
+    name: 'decodeNet',
+    scalar: 'f32',
+    width: DECODE_NETWORK_WIDTH,
+    hidden: DECODE_NETWORK_HIDDEN_LAYERS,
+})}
+fn decodeNetwork(network: u32, input: vec4<f32>) -> vec4<f32> {
+  let slot = min(network, ${DECODE_NETWORK_CAPACITY - 1}u) * 2u;
+  let header = decodeNodes.networks[slot];
+  let widths = decodeNodes.networks[slot + 1u];
+  var values: array<f32, ${DECODE_NETWORK_WIDTH}>;
+  for (var i = 0u; i < 4u; i = i + 1u) {
+    values[i] = input[i];
+  }
+  let result = decodeNetEval(
+    header.x,
+    min(header.y, ${DECODE_NETWORK_INPUTS}u),
+    header.w,
+    array<u32, ${DECODE_NETWORK_HIDDEN_LAYERS}>(widths.x, widths.y),
+    min(header.z, ${DECODE_NETWORK_OUTPUTS}u),
+    values,
+  );
+  return vec4<f32>(result[0], result[1], result[2], result[3]);
+}
+
+/* One whole level of a lattice-addressed latent: bilinear by hand, exactly as decodeCpu does it. */
+fn decodeLatticeLevel(layer: u32, uv: vec2<f32>, level: i32, mode: u32) -> vec4<f32> {
+  let size = max(i32(decodeLatentSize()) >> u32(level), 1);
+  let edge = f32(size);
+  var a = clamp(uv, vec2<f32>(0.0), vec2<f32>(1.0));
+  if (mode == 1u) {
+    a = uv - floor(uv);
+  }
+  let s = a * (edge - 1.0);
+  let base = floor(s);
+  let f = s - base;
+  let x0 = clamp(i32(base.x), 0, size - 1);
+  let x1 = clamp(i32(base.x) + 1, 0, size - 1);
+  let y0 = clamp(i32(base.y), 0, size - 1);
+  let y1 = clamp(i32(base.y) + 1, 0, size - 1);
+  let index = i32(layer);
+  let t00 = textureLoad(decodeLatents, vec2<i32>(x0, y0), index, level);
+  let t10 = textureLoad(decodeLatents, vec2<i32>(x1, y0), index, level);
+  let t01 = textureLoad(decodeLatents, vec2<i32>(x0, y1), index, level);
+  let t11 = textureLoad(decodeLatents, vec2<i32>(x1, y1), index, level);
+  let top = t00 * (1.0 - f.x) + t10 * f.x;
+  let bottom = t01 * (1.0 - f.x) + t11 * f.x;
+  return top * (1.0 - f.y) + bottom * f.y;
+}
+
+fn decodeLatentSample(layer: u32, uv: vec2<f32>, lod: f32, mode: u32) -> vec4<f32> {
+  let top = f32(textureNumLevels(decodeLatents)) - 1.0;
+  /* Negative and not-a-number read level 0, as the reference's lod > 0 test does. */
+  let level = min(select(0.0, lod, lod > 0.0), top);
+  if (mode == 3u) {
+    return textureSampleLevel(decodeLatents, decodeRepeatSampler, uv, layer, level);
+  }
+  if (mode == 2u) {
+    return textureSampleLevel(decodeLatents, decodeClampSampler, uv, layer, level);
+  }
+  let lower = floor(level);
+  let upper = min(lower + 1.0, top);
+  let blend = level - lower;
+  let near = decodeLatticeLevel(layer, uv, i32(lower), mode);
+  let far = decodeLatticeLevel(layer, uv, i32(upper), mode);
+  return near * (1.0 - blend) + far * blend;
+}
+
+fn decodeProgram(program: u32, uv: vec2<f32>, lod: f32, t: f32) -> vec4<f32> {
+  var r: array<vec4<f32>, ${DECODE_REGISTERS}>;
+  if (program >= ${DECODE_PROGRAM_CAPACITY}u) {
+    return r[0];
+  }
+  let header = decodeNodes.programs[program];
+  let first = header.x;
+  let count = min(header.y, ${DECODE_NODE_CAPACITY}u);
+  let mode = header.w;
+  for (var i = 0u; i < count; i = i + 1u) {
+    let node = decodeNodes.nodes[min(first + i, ${DECODE_NODE_CAPACITY - 1}u)];
+    let a = node.y;
+    let b = node.z;
+    let dst = min(node.w, ${DECODE_REGISTERS - 1}u);
+    let ra = r[min(a, ${DECODE_REGISTERS - 1}u)];
+    let rb = r[min(b, ${DECODE_REGISTERS - 1}u)];
+    switch (node.x) {
+      case 0u, 2u: {
+        r[dst] = decodeLatentSample(a, uv, lod, mode);
+      }
+      case 1u: {
+        r[dst] = decodeNetwork(b, ra);
+      }
+      case 3u: {
+        let n = decodeFbm(uv, a, b);
+        r[dst] = vec4<f32>(n, n, n, 1.0);
+      }
+      case 4u: {
+        r[dst] = vec4<f32>(decodeFlipbook(t, a, b), 0.0, 0.0, 1.0);
+      }
+      case 5u: {
+        let m = t - floor(t);
+        r[dst] = ra * (1.0 - m) + rb * m;
+      }
+      case 6u: {
+        r[dst] = decodeRemap(ra, b);
+      }
+      case 7u: {
+        let alpha = ra.w;
+        r[dst] = vec4<f32>(ra.xyz * alpha + rb.xyz * (1.0 - alpha), alpha + rb.w * (1.0 - alpha));
+      }
+      case 8u: {
+        r[dst] = decodeWeights.constants[min(a, ${DECODE_CONSTANT_CAPACITY - 1}u)];
+      }
+      default: {
+      }
+    }
+  }
+  return r[min(header.z, ${DECODE_REGISTERS - 1}u)];
+}
+`;
+/** Floats a case of the device check: program, u, v, lod, t. */
+export const DECODE_CASE_FLOATS = 5;
+export const DECODE_PARITY_WGSL = /* wgsl */ `
+@group(0) @binding(0) var<storage, read> params: array<f32>;
+@group(0) @binding(1) var<storage, read> cases: array<f32>;
+@group(0) @binding(7) var<storage, read_write> results: array<f32>;
+${decodeResourcesWgsl({ group: 0, nodes: 2, weights: 3, latents: 4, clampSampler: 5, repeatSampler: 6 })}
+
+fn decodeLatentSize() -> f32 {
+  return params[1];
+}
+
+${DECODE_WGSL}
+
+@compute @workgroup_size(64)
+fn main(@builtin(global_invocation_id) id: vec3<u32>) {
+  if (id.x >= u32(params[0])) {
+    return;
+  }
+  let at = id.x * ${DECODE_CASE_FLOATS}u;
+  let value = decodeProgram(
+    u32(cases[at]),
+    vec2<f32>(cases[at + 1u], cases[at + 2u]),
+    cases[at + 3u],
+    cases[at + 4u],
+  );
+  results[id.x * 4u] = value.x;
+  results[id.x * 4u + 1u] = value.y;
+  results[id.x * 4u + 2u] = value.z;
+  results[id.x * 4u + 3u] = value.w;
+}
+`;

package/dist/render/shaders/gpudriven/environment.wgsl.d.ts

@@ -0,0 +1,44 @@
+/** Reading a baked probe from a compute stage: the mapping, the levels, and the two lookups. */
+/**
+ * **`flat/probeGrid.ts` for one probe, and the "one" is the whole of the difference.**
+ *
+ * That file blends eight probes for the diffuse term and two for the reflection, because a grid is
+ * what a large world wants and a single probe pops as a surface crosses a cell boundary. The
+ * second pipeline reads **layer 0** and says so: it owns a fixed cluster set and its rigs are a few
+ * metres across, which is one probe's worth of world. A pass handed a grid of more than one reads
+ * the first of them, which is wrong in the way a single probe is always wrong — a smooth surface
+ * crossing a cell shows the wrong room rather than a blend of two — and `PassEnvironment.layers`
+ * is what a caller checks before deciding this pipeline suits their scene.
+ *
+ * **The mapping is not written again.** `shaders/octahedral.ts` carries `octEncode` and `octInsetUv`
+ * in GLSL and in TypeScript with a test, and this is the third spelling rather than a second
+ * design — `gpu-parity.mjs` runs it against that TypeScript over generated directions, which is
+ * the only thing that keeps three copies of one mapping honest.
+ *
+ * **The texture read belongs to the including module**, as `shadow.wgsl.ts` does the same thing for
+ * the same reason: the parity entry point reads a storage buffer, because that is what a compute
+ * harness can be handed, and the shading pass reads a `texture_2d_array`. What must not differ is
+ * the arithmetic around the read, so the arithmetic is here and the read is not.
+ */
+export declare const ENVIRONMENT_WGSL = "\n/* shaders/octahedral.ts, transcribed. The direction need not be normalised: the L1 divide is. */\nfn octEncode(d: vec3<f32>) -> vec2<f32> {\n  let n = d / (abs(d.x) + abs(d.y) + abs(d.z));\n  var p = n.xy;\n  if (n.z < 0.0) {\n    p = vec2<f32>(\n      (1.0 - abs(n.y)) * select(-1.0, 1.0, n.x >= 0.0),\n      (1.0 - abs(n.x)) * select(-1.0, 1.0, n.y >= 0.0),\n    );\n  }\n  return p * 0.5 + 0.5;\n}\n\n/*\n * Where a direction lands in a map that is edge texels across and whose outer ring is a gutter.\n *\n * The inner region is edge - 2 texels offset by one, so a direction at the border of the\n * octahedral square lands on the last real texel and a bilinear tap past it reads the gutter \u2014\n * which the bake filled with the folded direction rather than the other side of the map.\n */\nfn octInsetUv(d: vec3<f32>, edge: f32) -> vec2<f32> {\n  return (octEncode(d) * (edge - 2.0) + 1.0) / edge;\n}\n\n/*\n * A level's own edge, which is not the map's.\n *\n * The gutter is one texel at every level, so its share of the map doubles as the chain coarsens\n * and the inset has to be computed per level. Floored at four, which is where the chain stops.\n */\nfn probeLevelEdge(edge: f32, level: f32) -> f32 {\n  return max(edge / exp2(level), 4.0);\n}\n\n/* The diffuse half: the cosine convolution, which lives at one fixed level of the chain. */\nfn probeIrradianceAt(dir: vec3<f32>, edge: f32, irradianceLevel: f32) -> vec3<f32> {\n  let uv = octInsetUv(dir, probeLevelEdge(edge, irradianceLevel));\n  return environmentSample(uv, irradianceLevel);\n}\n\n/*\n * The reflection at a roughness, as two levels mixed by hand.\n *\n * **By hand, and flat/probeGrid.ts records why**: a level's inset differs between levels, and\n * hardware trilinear applies one coordinate to both \u2014 so one of the two would be read at the wrong\n * inset, by a thirty-second of the map at the top of the chain, which is a visible slide in a\n * reflection as roughness rises. Two fetches at their own insets is the price of the fold.\n */\nfn probeRadianceAt(dir: vec3<f32>, edge: f32, lod: f32, maxLod: f32) -> vec3<f32> {\n  let lo = clamp(floor(lod), 0.0, maxLod);\n  let hi = min(lo + 1.0, maxLod);\n  let coarse = environmentSample(octInsetUv(dir, probeLevelEdge(edge, hi)), hi);\n  let fine = environmentSample(octInsetUv(dir, probeLevelEdge(edge, lo)), lo);\n  return mix(fine, coarse, clamp(lod - lo, 0.0, 1.0));\n}\n";
+/** Floats a case of the environment check: a direction, then the edge, the lod and the max. */
+export declare const ENVIRONMENT_CASE_FLOATS = 6;
+/**
+ * Texels a side of the synthetic chain the check reads, and how many levels it holds.
+ *
+ * **A chain whose levels are constants, one value each**, so what comes back names the level it
+ * was read from. That is what makes the two-level mix checkable without a texture: a result of
+ * 3.25 is level 3 and level 4 mixed a quarter of the way, and no bilinear filter can produce it by
+ * accident.
+ */
+export declare const ENVIRONMENT_CHECK_EDGE = 16;
+export declare const ENVIRONMENT_CHECK_LEVELS = 4;
+/**
+ * The mapping and the level arithmetic alone, as a dispatch.
+ *
+ * `environmentSample` reads a flat array of levels rather than a texture, and returns the level's
+ * own constant — so the uv it is handed is reported back as well, which is what lets one check
+ * cover both halves: that a direction lands where `octahedral.ts` says, and that a roughness
+ * reads the two levels either side of it in the right proportion.
+ */
+export declare const ENVIRONMENT_PARITY_WGSL = "\n@group(0) @binding(0) var<storage, read> params: array<f32>;\n@group(0) @binding(1) var<storage, read> cases: array<f32>;\n@group(0) @binding(2) var<storage, read> levels: array<f32>;\n@group(0) @binding(3) var<storage, read_write> results: array<f32>;\n\n/* The level's own constant, and the coordinate it was asked for, so both can be compared. */\nvar<private> lastUv: vec2<f32>;\n\nfn environmentSample(uv: vec2<f32>, level: f32) -> vec3<f32> {\n  lastUv = uv;\n  let index = u32(clamp(level, 0.0, 4.0 - 1.0));\n  return vec3<f32>(levels[index], levels[index], levels[index]);\n}\n\n\n/* shaders/octahedral.ts, transcribed. The direction need not be normalised: the L1 divide is. */\nfn octEncode(d: vec3<f32>) -> vec2<f32> {\n  let n = d / (abs(d.x) + abs(d.y) + abs(d.z));\n  var p = n.xy;\n  if (n.z < 0.0) {\n    p = vec2<f32>(\n      (1.0 - abs(n.y)) * select(-1.0, 1.0, n.x >= 0.0),\n      (1.0 - abs(n.x)) * select(-1.0, 1.0, n.y >= 0.0),\n    );\n  }\n  return p * 0.5 + 0.5;\n}\n\n/*\n * Where a direction lands in a map that is edge texels across and whose outer ring is a gutter.\n *\n * The inner region is edge - 2 texels offset by one, so a direction at the border of the\n * octahedral square lands on the last real texel and a bilinear tap past it reads the gutter \u2014\n * which the bake filled with the folded direction rather than the other side of the map.\n */\nfn octInsetUv(d: vec3<f32>, edge: f32) -> vec2<f32> {\n  return (octEncode(d) * (edge - 2.0) + 1.0) / edge;\n}\n\n/*\n * A level's own edge, which is not the map's.\n *\n * The gutter is one texel at every level, so its share of the map doubles as the chain coarsens\n * and the inset has to be computed per level. Floored at four, which is where the chain stops.\n */\nfn probeLevelEdge(edge: f32, level: f32) -> f32 {\n  return max(edge / exp2(level), 4.0);\n}\n\n/* The diffuse half: the cosine convolution, which lives at one fixed level of the chain. */\nfn probeIrradianceAt(dir: vec3<f32>, edge: f32, irradianceLevel: f32) -> vec3<f32> {\n  let uv = octInsetUv(dir, probeLevelEdge(edge, irradianceLevel));\n  return environmentSample(uv, irradianceLevel);\n}\n\n/*\n * The reflection at a roughness, as two levels mixed by hand.\n *\n * **By hand, and flat/probeGrid.ts records why**: a level's inset differs between levels, and\n * hardware trilinear applies one coordinate to both \u2014 so one of the two would be read at the wrong\n * inset, by a thirty-second of the map at the top of the chain, which is a visible slide in a\n * reflection as roughness rises. Two fetches at their own insets is the price of the fold.\n */\nfn probeRadianceAt(dir: vec3<f32>, edge: f32, lod: f32, maxLod: f32) -> vec3<f32> {\n  let lo = clamp(floor(lod), 0.0, maxLod);\n  let hi = min(lo + 1.0, maxLod);\n  let coarse = environmentSample(octInsetUv(dir, probeLevelEdge(edge, hi)), hi);\n  let fine = environmentSample(octInsetUv(dir, probeLevelEdge(edge, lo)), lo);\n  return mix(fine, coarse, clamp(lod - lo, 0.0, 1.0));\n}\n\n\n@compute @workgroup_size(64)\nfn main(@builtin(global_invocation_id) id: vec3<u32>) {\n  if (id.x >= u32(params[0])) {\n    return;\n  }\n  let at = id.x * 6u;\n  let dir = vec3<f32>(cases[at], cases[at + 1u], cases[at + 2u]);\n  let edge = cases[at + 3u];\n  let lod = cases[at + 4u];\n  let maxLod = cases[at + 5u];\n\n  let uv = octInsetUv(dir, edge);\n  let radiance = probeRadianceAt(dir, edge, lod, maxLod);\n  let out = id.x * 4u;\n  results[out] = uv.x;\n  results[out + 1u] = uv.y;\n  results[out + 2u] = radiance.x;\n  /* The last coordinate the mix asked for, which is the finer level's and carries its own inset. */\n  results[out + 3u] = lastUv.x;\n}\n";

package/dist/render/shaders/gpudriven/environment.wgsl.js

@@ -0,0 +1,137 @@
+/** Reading a baked probe from a compute stage: the mapping, the levels, and the two lookups. */
+/**
+ * **`flat/probeGrid.ts` for one probe, and the "one" is the whole of the difference.**
+ *
+ * That file blends eight probes for the diffuse term and two for the reflection, because a grid is
+ * what a large world wants and a single probe pops as a surface crosses a cell boundary. The
+ * second pipeline reads **layer 0** and says so: it owns a fixed cluster set and its rigs are a few
+ * metres across, which is one probe's worth of world. A pass handed a grid of more than one reads
+ * the first of them, which is wrong in the way a single probe is always wrong — a smooth surface
+ * crossing a cell shows the wrong room rather than a blend of two — and `PassEnvironment.layers`
+ * is what a caller checks before deciding this pipeline suits their scene.
+ *
+ * **The mapping is not written again.** `shaders/octahedral.ts` carries `octEncode` and `octInsetUv`
+ * in GLSL and in TypeScript with a test, and this is the third spelling rather than a second
+ * design — `gpu-parity.mjs` runs it against that TypeScript over generated directions, which is
+ * the only thing that keeps three copies of one mapping honest.
+ *
+ * **The texture read belongs to the including module**, as `shadow.wgsl.ts` does the same thing for
+ * the same reason: the parity entry point reads a storage buffer, because that is what a compute
+ * harness can be handed, and the shading pass reads a `texture_2d_array`. What must not differ is
+ * the arithmetic around the read, so the arithmetic is here and the read is not.
+ */
+export const ENVIRONMENT_WGSL = /* wgsl */ `
+/* shaders/octahedral.ts, transcribed. The direction need not be normalised: the L1 divide is. */
+fn octEncode(d: vec3<f32>) -> vec2<f32> {
+  let n = d / (abs(d.x) + abs(d.y) + abs(d.z));
+  var p = n.xy;
+  if (n.z < 0.0) {
+    p = vec2<f32>(
+      (1.0 - abs(n.y)) * select(-1.0, 1.0, n.x >= 0.0),
+      (1.0 - abs(n.x)) * select(-1.0, 1.0, n.y >= 0.0),
+    );
+  }
+  return p * 0.5 + 0.5;
+}
+
+/*
+ * Where a direction lands in a map that is edge texels across and whose outer ring is a gutter.
+ *
+ * The inner region is edge - 2 texels offset by one, so a direction at the border of the
+ * octahedral square lands on the last real texel and a bilinear tap past it reads the gutter —
+ * which the bake filled with the folded direction rather than the other side of the map.
+ */
+fn octInsetUv(d: vec3<f32>, edge: f32) -> vec2<f32> {
+  return (octEncode(d) * (edge - 2.0) + 1.0) / edge;
+}
+
+/*
+ * A level's own edge, which is not the map's.
+ *
+ * The gutter is one texel at every level, so its share of the map doubles as the chain coarsens
+ * and the inset has to be computed per level. Floored at four, which is where the chain stops.
+ */
+fn probeLevelEdge(edge: f32, level: f32) -> f32 {
+  return max(edge / exp2(level), 4.0);
+}
+
+/* The diffuse half: the cosine convolution, which lives at one fixed level of the chain. */
+fn probeIrradianceAt(dir: vec3<f32>, edge: f32, irradianceLevel: f32) -> vec3<f32> {
+  let uv = octInsetUv(dir, probeLevelEdge(edge, irradianceLevel));
+  return environmentSample(uv, irradianceLevel);
+}
+
+/*
+ * The reflection at a roughness, as two levels mixed by hand.
+ *
+ * **By hand, and flat/probeGrid.ts records why**: a level's inset differs between levels, and
+ * hardware trilinear applies one coordinate to both — so one of the two would be read at the wrong
+ * inset, by a thirty-second of the map at the top of the chain, which is a visible slide in a
+ * reflection as roughness rises. Two fetches at their own insets is the price of the fold.
+ */
+fn probeRadianceAt(dir: vec3<f32>, edge: f32, lod: f32, maxLod: f32) -> vec3<f32> {
+  let lo = clamp(floor(lod), 0.0, maxLod);
+  let hi = min(lo + 1.0, maxLod);
+  let coarse = environmentSample(octInsetUv(dir, probeLevelEdge(edge, hi)), hi);
+  let fine = environmentSample(octInsetUv(dir, probeLevelEdge(edge, lo)), lo);
+  return mix(fine, coarse, clamp(lod - lo, 0.0, 1.0));
+}
+`;
+/** Floats a case of the environment check: a direction, then the edge, the lod and the max. */
+export const ENVIRONMENT_CASE_FLOATS = 6;
+/**
+ * Texels a side of the synthetic chain the check reads, and how many levels it holds.
+ *
+ * **A chain whose levels are constants, one value each**, so what comes back names the level it
+ * was read from. That is what makes the two-level mix checkable without a texture: a result of
+ * 3.25 is level 3 and level 4 mixed a quarter of the way, and no bilinear filter can produce it by
+ * accident.
+ */
+export const ENVIRONMENT_CHECK_EDGE = 16;
+export const ENVIRONMENT_CHECK_LEVELS = 4;
+/**
+ * The mapping and the level arithmetic alone, as a dispatch.
+ *
+ * `environmentSample` reads a flat array of levels rather than a texture, and returns the level's
+ * own constant — so the uv it is handed is reported back as well, which is what lets one check
+ * cover both halves: that a direction lands where `octahedral.ts` says, and that a roughness
+ * reads the two levels either side of it in the right proportion.
+ */
+export const ENVIRONMENT_PARITY_WGSL = /* wgsl */ `
+@group(0) @binding(0) var<storage, read> params: array<f32>;
+@group(0) @binding(1) var<storage, read> cases: array<f32>;
+@group(0) @binding(2) var<storage, read> levels: array<f32>;
+@group(0) @binding(3) var<storage, read_write> results: array<f32>;
+
+/* The level's own constant, and the coordinate it was asked for, so both can be compared. */
+var<private> lastUv: vec2<f32>;
+
+fn environmentSample(uv: vec2<f32>, level: f32) -> vec3<f32> {
+  lastUv = uv;
+  let index = u32(clamp(level, 0.0, ${ENVIRONMENT_CHECK_LEVELS}.0 - 1.0));
+  return vec3<f32>(levels[index], levels[index], levels[index]);
+}
+
+${ENVIRONMENT_WGSL}
+
+@compute @workgroup_size(64)
+fn main(@builtin(global_invocation_id) id: vec3<u32>) {
+  if (id.x >= u32(params[0])) {
+    return;
+  }
+  let at = id.x * ${ENVIRONMENT_CASE_FLOATS}u;
+  let dir = vec3<f32>(cases[at], cases[at + 1u], cases[at + 2u]);
+  let edge = cases[at + 3u];
+  let lod = cases[at + 4u];
+  let maxLod = cases[at + 5u];
+
+  let uv = octInsetUv(dir, edge);
+  let radiance = probeRadianceAt(dir, edge, lod, maxLod);
+  let out = id.x * 4u;
+  results[out] = uv.x;
+  results[out + 1u] = uv.y;
+  results[out + 2u] = radiance.x;
+  /* The last coordinate the mix asked for, which is the finer level's and carries its own inset. */
+  results[out + 3u] = lastUv.x;
+}
+`;

package/dist/render/shaders/gpudriven/fog.wgsl.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The medium between the camera and a GPU-driven surface, as WGSL.
+ *
+ * **`render/fog.ts` is the reference and this is checked against it**, over generated cases on a
+ * device by `scripts/gpu-parity.mjs` — the pattern `gpudriven/lit.ts` and `gpudriven/alphaTest.ts`
+ * are both written under, and for the reason this file exists at all: the forward path's fog is
+ * GLSL, so the two pipelines cannot share text and can only be held to one another by measurement.
+ *
+ * **Two shaders include this, and neither restates it.** The shading pass fogs an opaque surface
+ * and the blended raster fogs a pane, and a pane at the render edge that did not take the haze
+ * would stand out of it. The previous wave found the weighted-transparency weight written twice
+ * after its gate had been watching the copy, so this one starts shared.
+ *
+ * The including module declares the `fog` block — `frameBlock.wgsl.ts` does, so both readers get
+ * one layout — and every guard and constant below is `render/fog.ts`'s, which is `shaders/fog.ts`'s.
+ */
+export declare const FOG_WGSL = "\n/** What distance converges toward: the day's haze, or the water column. */\nfn mediumColour() -> vec3<f32> {\n  return mix(frame.fogColour.xyz, frame.fogUnderwater.xyz, frame.fogUnderwater.w);\n}\n\n/**\n * How much of a surface at \"pointY\", \"dist\" metres away, is lost to the medium between.\n * 0 is perfectly clear, 1 is the medium's own colour.\n */\nfn mediumFog(dist: f32, pointY: f32) -> f32 {\n  let underwaterFactor = frame.fogUnderwater.w;\n  if (frame.fogRange.z == 1.0) {\n    /*\n     * A consumer asking for a hard cut writes far == near, and the guard is why that is a cut and\n     * not a NaN at the one distance where the quotient is zero over zero.\n     *\n     * **This copy of it is not observable on the machine this was written on**, and the perturbation\n     * says so: removing it changes nothing the parity check can see, because WGSL does not require\n     * NaN to be supported and this device answers 0 for 0.0/0.0 rather than NaN. The guard stays\n     * because render/fog.ts needs it \u2014 its own test fails without it \u2014 and because a device that\n     * does propagate NaN would paint the fog colour along the cut. The alpha test found the same\n     * shape from the other direction on 2026-09-18: a device may assume NaN never arrives.\n     */\n    let span = max(frame.fogRange.y - frame.fogRange.x, 1e-4);\n    let ramp = clamp((dist - frame.fogRange.x) / span, 0.0, 1.0);\n    if (underwaterFactor <= 0.0) { return ramp; }\n    let wetLinear = frame.fogRange.w * dist;\n    return mix(ramp, 1.0 - exp2(-wetLinear * wetLinear * 1.442695), underwaterFactor);\n  }\n\n  let t = (pointY - frame.fogColour.w) * frame.fogHeight.x;\n  /* (1 - e^-t)/t, which tends to 1 as the ray levels out. Guarded rather than branched: at t = 0\n     the quotient is 0/0, and 1e-4 of a scale height is 8 mm. */\n  var denom = t;\n  if (abs(t) < 1e-4) { denom = 1e-4; }\n  let air = 1.0 - exp(-frame.fogHeight.y * dist * (1.0 - exp(-denom)) / denom);\n  if (underwaterFactor <= 0.0) { return air; }\n  /* Water is its own medium and keeps its own curve, so crossing the surface changes nothing\n     about how the water column reads. */\n  let wet = frame.fogRange.w * dist;\n  return mix(air, 1.0 - exp2(-wet * wet * 1.442695), underwaterFactor);\n}\n";
+/** Floats a case of the fog check: distance, height, and the ten options. */
+export declare const FOG_CASE_FLOATS = 16;
+/**
+ * An entry point that does nothing but fog, so `gpu-parity.mjs` can compare the expression above
+ * with `render/fog.ts` directly rather than through a shading pass that writes to a texture.
+ *
+ * **It declares its own `frame` and fills it from the case**, rather than restating the arithmetic:
+ * the whole point is that the function under test is the one the frame draws with, and a second
+ * copy here is a gate watching a copy of what it guards.
+ */
+export declare const FOG_PARITY_WGSL = "\nstruct Frame {\n  /** rgb is the haze's colour, w is the eye's height. */\n  fogColour: vec4<f32>,\n  /** rgb is the water's colour, w is how far under it the camera is. */\n  fogUnderwater: vec4<f32>,\n  /** Reciprocal scale height, extinction per metre at the eye, and two spare. */\n  fogHeight: vec4<f32>,\n  /** Linear near and far, the mode, and the water's own density. */\n  fogRange: vec4<f32>,\n}\n\n@group(0) @binding(0) var<storage, read> cases: array<f32>;\n@group(0) @binding(1) var<storage, read_write> results: array<f32>;\n\nvar<private> frame: Frame;\n\n/** What distance converges toward: the day's haze, or the water column. */\nfn mediumColour() -> vec3<f32> {\n  return mix(frame.fogColour.xyz, frame.fogUnderwater.xyz, frame.fogUnderwater.w);\n}\n\n/**\n * How much of a surface at \"pointY\", \"dist\" metres away, is lost to the medium between.\n * 0 is perfectly clear, 1 is the medium's own colour.\n */\nfn mediumFog(dist: f32, pointY: f32) -> f32 {\n  let underwaterFactor = frame.fogUnderwater.w;\n  if (frame.fogRange.z == 1.0) {\n    /*\n     * A consumer asking for a hard cut writes far == near, and the guard is why that is a cut and\n     * not a NaN at the one distance where the quotient is zero over zero.\n     *\n     * **This copy of it is not observable on the machine this was written on**, and the perturbation\n     * says so: removing it changes nothing the parity check can see, because WGSL does not require\n     * NaN to be supported and this device answers 0 for 0.0/0.0 rather than NaN. The guard stays\n     * because render/fog.ts needs it \u2014 its own test fails without it \u2014 and because a device that\n     * does propagate NaN would paint the fog colour along the cut. The alpha test found the same\n     * shape from the other direction on 2026-09-18: a device may assume NaN never arrives.\n     */\n    let span = max(frame.fogRange.y - frame.fogRange.x, 1e-4);\n    let ramp = clamp((dist - frame.fogRange.x) / span, 0.0, 1.0);\n    if (underwaterFactor <= 0.0) { return ramp; }\n    let wetLinear = frame.fogRange.w * dist;\n    return mix(ramp, 1.0 - exp2(-wetLinear * wetLinear * 1.442695), underwaterFactor);\n  }\n\n  let t = (pointY - frame.fogColour.w) * frame.fogHeight.x;\n  /* (1 - e^-t)/t, which tends to 1 as the ray levels out. Guarded rather than branched: at t = 0\n     the quotient is 0/0, and 1e-4 of a scale height is 8 mm. */\n  var denom = t;\n  if (abs(t) < 1e-4) { denom = 1e-4; }\n  let air = 1.0 - exp(-frame.fogHeight.y * dist * (1.0 - exp(-denom)) / denom);\n  if (underwaterFactor <= 0.0) { return air; }\n  /* Water is its own medium and keeps its own curve, so crossing the surface changes nothing\n     about how the water column reads. */\n  let wet = frame.fogRange.w * dist;\n  return mix(air, 1.0 - exp2(-wet * wet * 1.442695), underwaterFactor);\n}\n\n@compute @workgroup_size(64)\nfn main(@builtin(global_invocation_id) id: vec3<u32>) {\n  let at = id.x * 16u;\n  if (at + 15u >= arrayLength(&cases)) { return; }\n  let dist = cases[at];\n  let pointY = cases[at + 1u];\n  frame.fogColour = vec4<f32>(cases[at + 2u], cases[at + 3u], cases[at + 4u], cases[at + 5u]);\n  frame.fogUnderwater = vec4<f32>(cases[at + 6u], cases[at + 7u], cases[at + 8u], cases[at + 9u]);\n  frame.fogHeight = vec4<f32>(cases[at + 10u], cases[at + 11u], 0.0, 0.0);\n  frame.fogRange = vec4<f32>(cases[at + 12u], cases[at + 13u], cases[at + 14u], cases[at + 15u]);\n\n  let out = id.x * 4u;\n  results[out] = mediumFog(dist, pointY);\n  let colour = mediumColour();\n  results[out + 1u] = colour.x;\n  results[out + 2u] = colour.y;\n  results[out + 3u] = colour.z;\n}\n";