@driftengine/core 3.62.0 → 4.0.0

package/dist/render/inference/spatialKernels.js

@@ -0,0 +1,179 @@
+/**
+ * The spatial operators on the device: convolution, its transpose, patch embedding, resizing and
+ * max pooling.
+ *
+ * **One invocation per output element, each gathering what it reads**, in the layouts of the
+ * references in `@driftengine/texture`'s `spatial.ts` — channel-major images and the upstream's
+ * weight layouts. A transposed convolution is written as a gather, not the reference's scatter, so
+ * no two invocations write one element; the two agree because each output sums the same products.
+ *
+ * **Resizing bakes the reference's conventions as constants**: the half-pixel source without aligned
+ * corners, clamped below zero for bilinear only, stepping by the node's own step where it gives one;
+ * the corner-to-corner scale with them, and zero for an output of one; and the cubic kernel at
+ * a = −0.75 with its taps clamped to the border.
+ *
+ * What it gives up: a gather per output reads its whole window from storage with no reuse between
+ * neighbours, which is the cost a tiled convolution removes. Measured against a DPT head's largest,
+ * a 3×3 of 32 channels at 518², it is 3.2 ms — 1.5 TFLOP/s where the tiled multiply reaches 4.5 on
+ * the same device (an RX 9070 XT) — so the decoder's convolutions are the second thing to tile.
+ */
+import { float, num, perElement, read, size } from './kernelKit.js';
+/* Grouped, output `o` reads the `perGroup` channels from `first`: its group's run of the input. */
+const conv2d = (request) => {
+    const [, h, w] = request.inputShapes[0];
+    const [, perGroup, kh, kw] = request.inputShapes[1];
+    const [cout, oh, ow] = request.outputShape;
+    const outPerGroup = cout / num(request.attributes, 'groups', 1);
+    const stride = num(request.attributes, 'stride', 1);
+    const padding = num(request.attributes, 'padding', 0);
+    const bias = request.inputShapes.length > 2 ? read(request, 2, 'o') : '0.0';
+    return perElement(request, size(request.outputShape), `  let o = i / ${oh * ow}u;
+  let y = i32((i / ${ow}u) % ${oh}u);
+  let x = i32(i % ${ow}u);
+  let first = (o / ${outPerGroup}u) * ${perGroup}u;
+  var sum = ${bias};
+  for (var c = 0u; c < ${perGroup}u; c = c + 1u) {
+    for (var ky = 0; ky < ${kh}; ky = ky + 1) {
+      let sy = y * ${stride} - ${padding} + ky;
+      if (sy < 0 || sy >= ${h}) { continue; }
+      for (var kx = 0; kx < ${kw}; kx = kx + 1) {
+        let sx = x * ${stride} - ${padding} + kx;
+        if (sx < 0 || sx >= ${w}) { continue; }
+        sum = sum + ${read(request, 0, `((first + c) * ${h}u + u32(sy)) * ${w}u + u32(sx)`)} * ${read(request, 1, `((o * ${perGroup}u + c) * ${kh}u + u32(ky)) * ${kw}u + u32(kx)`)};
+      }
+    }
+  }
+  output[i] = sum;`);
+};
+const convTranspose2d = (request) => {
+    const [cin, h, w] = request.inputShapes[0];
+    const [, cout, kh, kw] = request.inputShapes[1];
+    const [, oh, ow] = request.outputShape;
+    const stride = num(request.attributes, 'stride', 1);
+    const padding = num(request.attributes, 'padding', 0);
+    const bias = request.inputShapes.length > 2 ? read(request, 2, 'o') : '0.0';
+    return perElement(request, size(request.outputShape), `  let o = i / ${oh * ow}u;
+  let ty = i32((i / ${ow}u) % ${oh}u);
+  let tx = i32(i % ${ow}u);
+  var sum = ${bias};
+  for (var ky = 0; ky < ${kh}; ky = ky + 1) {
+    let sy = ty + ${padding} - ky;
+    if (sy < 0 || sy % ${stride} != 0 || sy / ${stride} >= ${h}) { continue; }
+    for (var kx = 0; kx < ${kw}; kx = kx + 1) {
+      let sx = tx + ${padding} - kx;
+      if (sx < 0 || sx % ${stride} != 0 || sx / ${stride} >= ${w}) { continue; }
+      for (var c = 0u; c < ${cin}u; c = c + 1u) {
+        sum = sum + ${read(request, 0, `(c * ${h}u + u32(sy / ${stride})) * ${w}u + u32(sx / ${stride})`)} * ${read(request, 1, `((c * ${cout}u + o) * ${kh}u + u32(ky)) * ${kw}u + u32(kx)`)};
+      }
+    }
+  }
+  output[i] = sum;`);
+};
+const patchEmbed = (request) => {
+    const [cin, h, w] = request.inputShapes[0];
+    const dim = request.inputShapes[1][0];
+    const patch = num(request.attributes, 'patch');
+    const cols = Math.floor(w / patch);
+    const bias = request.inputShapes.length > 2 ? read(request, 2, 'o') : '0.0';
+    return perElement(request, size(request.outputShape), `  let token = i / ${dim}u;
+  let o = i % ${dim}u;
+  let top = (token / ${cols}u) * ${patch}u;
+  let left = (token % ${cols}u) * ${patch}u;
+  var sum = ${bias};
+  for (var c = 0u; c < ${cin}u; c = c + 1u) {
+    for (var ky = 0u; ky < ${patch}u; ky = ky + 1u) {
+      for (var kx = 0u; kx < ${patch}u; kx = kx + 1u) {
+        sum = sum + ${read(request, 0, `(c * ${h}u + top + ky) * ${w}u + left + kx`)} * ${read(request, 1, `((o * ${cin}u + c) * ${patch}u + ky) * ${patch}u + kx`)};
+      }
+    }
+  }
+  output[i] = sum;`);
+};
+/*
+ * The source coordinate of a destination index, as a WGSL expression, in the reference's
+ * convention: `step` source pixels a destination pixel, which is the sizes' ratio unless the node
+ * gives its own, as a resize by a scale factor does upstream.
+ */
+function source(index, input, output, align, cubic, step) {
+    if (align)
+        return output <= 1 ? '0.0' : `f32(${index}) * ${float((input - 1) / (output - 1))}`;
+    const raw = `(f32(${index}) + 0.5) * ${float(step ?? input / output)} - 0.5`;
+    return cubic ? raw : `max(${raw}, 0.0)`;
+}
+/* PyTorch's `nearest`: `⌊i·scale⌋`, the product in single precision as the reference takes it. */
+const nearest = (request) => {
+    const [, h, w] = request.inputShapes[0];
+    const [, oh, ow] = request.outputShape;
+    const stepped = typeof request.attributes['stepHeight'] === 'number';
+    const scaleY = stepped ? num(request.attributes, 'stepHeight') : h / oh;
+    const scaleX = stepped ? num(request.attributes, 'stepWidth') : w / ow;
+    return perElement(request, size(request.outputShape), `  let plane = (i / ${oh * ow}u) * ${h * w}u;
+  let sy = min(u32(floor(f32((i / ${ow}u) % ${oh}u) * ${float(scaleY)})), ${h - 1}u);
+  let sx = min(u32(floor(f32(i % ${ow}u) * ${float(scaleX)})), ${w - 1}u);
+  output[i] = ${read(request, 0, `plane + sy * ${w}u + sx`)};`);
+};
+const resize = (request) => {
+    if (request.attributes['mode'] === 'nearest')
+        return nearest(request);
+    const [, h, w] = request.inputShapes[0];
+    const [, oh, ow] = request.outputShape;
+    const align = request.attributes['alignCorners'] === true;
+    const cubic = request.attributes['mode'] === 'bicubic';
+    const stepped = typeof request.attributes['stepHeight'] === 'number';
+    const stepHeight = stepped ? num(request.attributes, 'stepHeight') : undefined;
+    const stepWidth = stepped ? num(request.attributes, 'stepWidth') : undefined;
+    const at = (y, x) => read(request, 0, `plane + u32(clamp(${y}, 0, ${h - 1})) * ${w}u + u32(clamp(${x}, 0, ${w - 1}))`);
+    const sample = cubic
+        ? `  let a = -0.75;
+  let tx = sx - floor(sx);
+  let ty = sy - floor(sy);
+  let wx = array<f32, 4>(cubicFar(tx + 1.0, a), cubicNear(tx, a), cubicNear(1.0 - tx, a), cubicFar(2.0 - tx, a));
+  let wy = array<f32, 4>(cubicFar(ty + 1.0, a), cubicNear(ty, a), cubicNear(1.0 - ty, a), cubicFar(2.0 - ty, a));
+  var value = 0.0;
+  for (var j = 0; j < 4; j = j + 1) {
+    var across = 0.0;
+    for (var k = 0; k < 4; k = k + 1) { across = across + wx[k] * ${at('y0 - 1 + j', 'x0 - 1 + k')}; }
+    value = value + wy[j] * across;
+  }
+  output[i] = value;`
+        : `  let tx = sx - f32(x0);
+  let ty = sy - f32(y0);
+  let top = ${at('y0', 'x0')} * (1.0 - tx) + ${at('y0', 'x0 + 1')} * tx;
+  let bottom = ${at('y0 + 1', 'x0')} * (1.0 - tx) + ${at('y0 + 1', 'x0 + 1')} * tx;
+  output[i] = top * (1.0 - ty) + bottom * ty;`;
+    const kernel = perElement(request, size(request.outputShape), `  let plane = (i / ${oh * ow}u) * ${h * w}u;
+  let sy = ${source(`(i / ${ow}u) % ${oh}u`, h, oh, align, cubic, stepHeight)};
+  let sx = ${source(`i % ${ow}u`, w, ow, align, cubic, stepWidth)};
+  let y0 = i32(floor(sy));
+  let x0 = i32(floor(sx));
+${sample}`);
+    if (!cubic)
+        return kernel;
+    const helpers = `fn cubicNear(x: f32, a: f32) -> f32 { return ((a + 2.0) * x - (a + 3.0)) * x * x + 1.0; }
+fn cubicFar(x: f32, a: f32) -> f32 { return ((a * x - 5.0 * a) * x + 8.0 * a) * x - 4.0 * a; }`;
+    return { ...kernel, code: kernel.code.replace('\n@compute', `\n${helpers}\n\n@compute`) };
+};
+/* The largest of each window; a window always lies inside the input, since there is no padding. */
+const maxPool2d = (request) => {
+    const [, h, w] = request.inputShapes[0];
+    const [, oh, ow] = request.outputShape;
+    const kernel = num(request.attributes, 'kernel');
+    const stride = num(request.attributes, 'stride', kernel);
+    return perElement(request, size(request.outputShape), `  let plane = (i / ${oh * ow}u) * ${h * w}u;
+  let top = ((i / ${ow}u) % ${oh}u) * ${stride}u;
+  let left = (i % ${ow}u) * ${stride}u;
+  var largest = ${read(request, 0, `plane + top * ${w}u + left`)};
+  for (var ky = 0u; ky < ${kernel}u; ky = ky + 1u) {
+    for (var kx = 0u; kx < ${kernel}u; kx = kx + 1u) {
+      largest = max(largest, ${read(request, 0, `plane + (top + ky) * ${w}u + left + kx`)});
+    }
+  }
+  output[i] = largest;`);
+};
+export const SPATIAL_KERNELS = [
+    ['conv2d', conv2d],
+    ['convTranspose2d', convTranspose2d],
+    ['patchEmbed', patchEmbed],
+    ['resize', resize],
+    ['maxPool2d', maxPool2d],
+];

package/dist/render/inference/splatRaster.wgsl.d.ts

@@ -0,0 +1,75 @@
+/**
+ * A cloud of Gaussians drawn and differentiated on the device, one workgroup per tile.
+ *
+ * **Hand-authored WGSL, which the 2026-08-12 rule makes the exception for a compute shader**: there
+ * is no second copy to keep in step, because a compute shader has no WebGL2 twin, and the safety
+ * property inverts — this *is* the bottom of its own stack. What stands in for the generator's
+ * check is `scripts/gpu-parity.mjs`, which runs every one of these against
+ * `@driftengine/capture`'s reference rasteriser on the same cloud.
+ *
+ * **Why a tile and not a splat.** Splats overlap and compositing is ordered, so one invocation per
+ * splat has no way for two of them writing one pixel to agree who was in front. Turned inside out —
+ * one workgroup per tile of the frame, one invocation per pixel, each walking the list of splats
+ * that touch its tile — every pixel accumulates alone in its own registers and nothing is contended.
+ *
+ * **The backward pass reduces rather than adds atomically, and that is a determinism decision.**
+ * Many pixels contribute to one splat's gradient. WGSL has no floating-point atomic, and the usual
+ * workaround — a compare-and-swap loop over the bits — sums in whatever order the lanes happen to
+ * arrive; floating-point addition is not associative, so the same cloud would give a different
+ * gradient every run. Instead the workgroup steps through its list together, and for each splat the
+ * 256 lanes are reduced in a fixed tree into one slot of its own, which `splatTiles.ts`'s `pairOf`
+ * allocates. A second pass sums each splat's contiguous run. Same answer, every run, every device.
+ *
+ * **The frame is written premultiplied, as the reference writes it**: three channels of colour
+ * already multiplied by the light that reached them, and the coverage beside it.
+ */
+/**
+ * Numbers a splat occupies on the device: centre, screen covariance, opacity, colour, reach.
+ *
+ * **The reach is in the record because a tile is not a splat's footprint.** A workgroup walks every
+ * pixel of its tile, and a splat that touches the tile at one corner reaches only part of it — so
+ * without the same box the reference loops over, the device draws the splat at pixels the reference
+ * never evaluates. Measured before it was there: 6.7 · 10⁻³ of a channel on the worst pixel, which
+ * is not a rounding difference but a different picture. Just outside three standard deviations a
+ * Gaussian is still worth about a hundredth of its opacity, far above the faint cutoff.
+ */
+export declare const SPLAT_RASTER_FLOATS = 10;
+/** Numbers a splat's screen gradient occupies, in `@driftengine/capture`'s own order. */
+export declare const SPLAT_GRADIENT_FLOATS = 9;
+/** One workgroup covers a tile: the invocations are its pixels. */
+export declare const SPLAT_RASTER_GROUP = 16;
+/**
+ * The frame, and the light left at every pixel after the whole cloud — which the backward pass
+ * needs and cannot recover, because it walks the list the other way.
+ *
+ * Bindings: `params`, `splats`, `offsets`, `counts`, `lists`, `frame`, `light`.
+ */
+export declare const SPLAT_FORWARD_WGSL = "\n@group(0) @binding(0) var<uniform> params: Params;\n@group(0) @binding(1) var<storage, read> splats: array<f32>;\n@group(0) @binding(2) var<storage, read> offsets: array<u32>;\n@group(0) @binding(3) var<storage, read> counts: array<u32>;\n@group(0) @binding(4) var<storage, read> lists: array<u32>;\n@group(0) @binding(5) var<storage, read_write> frame: array<f32>;\n@group(0) @binding(6) var<storage, read_write> light: array<f32>;\n\nstruct Params {\n  width: u32,\n  height: u32,\n  across: u32,\n  splats: u32,\n};\n\nconst FAINT: f32 = 0.0009803921568627451;\nconst FLOATS: u32 = 10u;\nconst GRADS: u32 = 9u;\n\n\nstruct Splat {\n  centre: vec2f,\n  /* The screen covariance, [[a, b], [b, d]], the low-pass already in it. */\n  a: f32,\n  b: f32,\n  d: f32,\n  opacity: f32,\n  colour: vec3f,\n  /* Half the side of the pixel box it is drawn in, which is what bounds it. */\n  reach: f32,\n};\n\nfn readSplat(index: u32) -> Splat {\n  let at = index * FLOATS;\n  var one: Splat;\n  one.centre = vec2f(splats[at], splats[at + 1u]);\n  one.a = splats[at + 2u];\n  one.b = splats[at + 3u];\n  one.d = splats[at + 4u];\n  one.opacity = splats[at + 5u];\n  one.colour = vec3f(splats[at + 6u], splats[at + 7u], splats[at + 8u]);\n  one.reach = splats[at + 9u];\n  return one;\n}\n\n/* The pixel box the binning bins by, asked of one pixel: the rasteriser's own bound. */\nfn insideBox(one: Splat, pixel: vec2f) -> bool {\n  return pixel.x >= floor(one.centre.x - one.reach)\n    && pixel.x <= ceil(one.centre.x + one.reach)\n    && pixel.y >= floor(one.centre.y - one.reach)\n    && pixel.y <= ceil(one.centre.y + one.reach);\n}\n\n/* The inverse of the screen covariance, which is what the exponent is written in. */\nfn conicOf(one: Splat) -> vec3f {\n  let determinant = one.a * one.d - one.b * one.b;\n  return vec3f(one.d / determinant, -one.b / determinant, one.a / determinant);\n}\n\n/* How much of a splat reaches a pixel, from the pixel's own centre. */\nfn weightAt(conic: vec3f, offset: vec2f) -> f32 {\n  let power = -0.5 * (conic.x * offset.x * offset.x\n    + 2.0 * conic.y * offset.x * offset.y\n    + conic.z * offset.y * offset.y);\n  return exp(power);\n}\n\n\n@compute @workgroup_size(16, 16, 1)\nfn main(@builtin(global_invocation_id) id: vec3u, @builtin(workgroup_id) group: vec3u) {\n  if (id.x >= params.width || id.y >= params.height) { return; }\n  let tile = group.y * params.across + group.x;\n  let start = offsets[tile];\n  let held = counts[tile];\n  let centre = vec2f(f32(id.x) + 0.5, f32(id.y) + 0.5);\n\n  var transmit = 1.0;\n  var colour = vec3f(0.0);\n  var covered = 0.0;\n  for (var slot = 0u; slot < held; slot = slot + 1u) {\n    let one = readSplat(lists[start + slot]);\n    if (!insideBox(one, vec2f(f32(id.x), f32(id.y)))) { continue; }\n    let alpha = one.opacity * weightAt(conicOf(one), centre - one.centre);\n    if (alpha < FAINT) { continue; }\n    let share = alpha * transmit;\n    colour = colour + share * one.colour;\n    covered = covered + share;\n    transmit = transmit * (1.0 - alpha);\n  }\n\n  let pixel = id.y * params.width + id.x;\n  frame[pixel * 4u] = colour.x;\n  frame[pixel * 4u + 1u] = colour.y;\n  frame[pixel * 4u + 2u] = colour.z;\n  frame[pixel * 4u + 3u] = covered;\n  light[pixel] = transmit;\n}\n";
+/**
+ * The gradients of one tile's splats, each into a slot of its own.
+ *
+ * The workgroup walks its list furthest first, in step: every lane holds the light in front of the
+ * splat it has reached and the colour accumulated behind it, and after each splat the lanes are
+ * reduced in a fixed tree so the sum is the same on every device and every run.
+ *
+ * Bindings: `params`, `splats`, `offsets`, `counts`, `lists`, `pairOf`, `dPixels`, `light`,
+ * `partials`.
+ */
+export declare const SPLAT_BACKWARD_WGSL = "\n@group(0) @binding(0) var<uniform> params: Params;\n@group(0) @binding(1) var<storage, read> splats: array<f32>;\n@group(0) @binding(2) var<storage, read> offsets: array<u32>;\n@group(0) @binding(3) var<storage, read> counts: array<u32>;\n@group(0) @binding(4) var<storage, read> lists: array<u32>;\n@group(0) @binding(5) var<storage, read> pairOf: array<u32>;\n@group(0) @binding(6) var<storage, read> dPixels: array<f32>;\n@group(0) @binding(7) var<storage, read> light: array<f32>;\n@group(0) @binding(8) var<storage, read_write> partials: array<f32>;\n\nstruct Params {\n  width: u32,\n  height: u32,\n  across: u32,\n  splats: u32,\n};\n\nconst FAINT: f32 = 0.0009803921568627451;\nconst FLOATS: u32 = 10u;\nconst GRADS: u32 = 9u;\n\n\nstruct Splat {\n  centre: vec2f,\n  /* The screen covariance, [[a, b], [b, d]], the low-pass already in it. */\n  a: f32,\n  b: f32,\n  d: f32,\n  opacity: f32,\n  colour: vec3f,\n  /* Half the side of the pixel box it is drawn in, which is what bounds it. */\n  reach: f32,\n};\n\nfn readSplat(index: u32) -> Splat {\n  let at = index * FLOATS;\n  var one: Splat;\n  one.centre = vec2f(splats[at], splats[at + 1u]);\n  one.a = splats[at + 2u];\n  one.b = splats[at + 3u];\n  one.d = splats[at + 4u];\n  one.opacity = splats[at + 5u];\n  one.colour = vec3f(splats[at + 6u], splats[at + 7u], splats[at + 8u]);\n  one.reach = splats[at + 9u];\n  return one;\n}\n\n/* The pixel box the binning bins by, asked of one pixel: the rasteriser's own bound. */\nfn insideBox(one: Splat, pixel: vec2f) -> bool {\n  return pixel.x >= floor(one.centre.x - one.reach)\n    && pixel.x <= ceil(one.centre.x + one.reach)\n    && pixel.y >= floor(one.centre.y - one.reach)\n    && pixel.y <= ceil(one.centre.y + one.reach);\n}\n\n/* The inverse of the screen covariance, which is what the exponent is written in. */\nfn conicOf(one: Splat) -> vec3f {\n  let determinant = one.a * one.d - one.b * one.b;\n  return vec3f(one.d / determinant, -one.b / determinant, one.a / determinant);\n}\n\n/* How much of a splat reaches a pixel, from the pixel's own centre. */\nfn weightAt(conic: vec3f, offset: vec2f) -> f32 {\n  let power = -0.5 * (conic.x * offset.x * offset.x\n    + 2.0 * conic.y * offset.x * offset.y\n    + conic.z * offset.y * offset.y);\n  return exp(power);\n}\n\n\nconst LANES: u32 = 256u;\nvar<workgroup> gathered: array<array<f32, 9>, 256>;\n\n@compute @workgroup_size(16, 16, 1)\nfn main(\n  @builtin(global_invocation_id) id: vec3u,\n  @builtin(workgroup_id) group: vec3u,\n  @builtin(local_invocation_index) lane: u32,\n) {\n  let tile = group.y * params.across + group.x;\n  let start = offsets[tile];\n  let held = counts[tile];\n  /* Off the edge of the frame there is no pixel, and the lane still meets every barrier below. */\n  let inside = id.x < params.width && id.y < params.height;\n  let pixel = select(0u, id.y * params.width + id.x, inside);\n  let centre = vec2f(f32(id.x) + 0.5, f32(id.y) + 0.5);\n\n  var transmit = select(1.0, light[pixel], inside);\n  var behind = vec3f(0.0);\n  var behindCover = 0.0;\n  var dPixel = vec4f(0.0);\n  if (inside) {\n    dPixel = vec4f(dPixels[pixel * 4u], dPixels[pixel * 4u + 1u],\n      dPixels[pixel * 4u + 2u], dPixels[pixel * 4u + 3u]);\n  }\n\n  for (var step = 0u; step < held; step = step + 1u) {\n    let slot = held - 1u - step;\n    let index = lists[start + slot];\n    let one = readSplat(index);\n    let conic = conicOf(one);\n    let offset = centre - one.centre;\n    let weight = weightAt(conic, offset);\n    let alpha = one.opacity * weight;\n    let contributes = inside && alpha >= FAINT\n      && insideBox(one, vec2f(f32(id.x), f32(id.y)));\n\n    var mine: array<f32, GRADS>;\n    for (var k = 0u; k < GRADS; k = k + 1u) { mine[k] = 0.0; }\n    if (contributes) {\n      /* Undo this splat's own share to recover the light that reached it. */\n      /* Divided by what is left of the light, and by one where nothing is. */\n      let left = select(1.0 - alpha, 1.0, alpha == 1.0);\n      let before = transmit / left;\n      var dAlpha = 0.0;\n      for (var c = 0u; c < 3u; c = c + 1u) {\n        let grad = dPixel[c];\n        mine[6u + c] = grad * alpha * before;\n        dAlpha = dAlpha + grad * before * (one.colour[c] - behind[c]);\n      }\n      dAlpha = dAlpha + dPixel.w * before * (1.0 - behindCover);\n      mine[5u] = dAlpha * weight;\n\n      /* Through the exponent to the centre and the covariance, as the reference has it. */\n      let dPower = dAlpha * one.opacity * weight;\n      mine[0u] = dPower * (conic.x * offset.x + conic.y * offset.y);\n      mine[1u] = dPower * (conic.y * offset.x + conic.z * offset.y);\n      let dInverse = vec3f(\n        -0.5 * dPower * offset.x * offset.x,\n        -0.5 * dPower * offset.x * offset.y,\n        -0.5 * dPower * offset.y * offset.y);\n      mine[2u] = -(conic.x * dInverse.x * conic.x + 2.0 * conic.x * conic.y * dInverse.y\n        + conic.y * dInverse.z * conic.y);\n      mine[3u] = -2.0 * (conic.x * dInverse.x * conic.y + conic.y * dInverse.y * conic.y\n        + conic.x * dInverse.y * conic.z + conic.y * dInverse.z * conic.z);\n      mine[4u] = -(conic.y * dInverse.x * conic.y + 2.0 * conic.y * conic.z * dInverse.y\n        + conic.z * dInverse.z * conic.z);\n\n      /* And carry this splat into what stands behind the next one. */\n      behind = alpha * one.colour + (1.0 - alpha) * behind;\n      behindCover = alpha + (1.0 - alpha) * behindCover;\n      transmit = before;\n    }\n\n    /* The lanes, reduced in a fixed tree: the same sum in the same order on every device. */\n    for (var k = 0u; k < GRADS; k = k + 1u) { gathered[lane][k] = mine[k]; }\n    workgroupBarrier();\n    for (var half = LANES / 2u; half > 0u; half = half / 2u) {\n      if (lane < half) {\n        for (var k = 0u; k < GRADS; k = k + 1u) {\n          gathered[lane][k] = gathered[lane][k] + gathered[lane + half][k];\n        }\n      }\n      workgroupBarrier();\n    }\n    if (lane == 0u) {\n      let pair = pairOf[start + slot] * GRADS;\n      for (var k = 0u; k < GRADS; k = k + 1u) { partials[pair + k] = gathered[0][k]; }\n    }\n    workgroupBarrier();\n  }\n}\n";
+/**
+ * Each splat's own run of partial gradients, summed in index order.
+ *
+ * Bindings: `params`, `pairOffsets`, `tilesPerSplat`, `partials`, `gradients`.
+ */
+export declare const SPLAT_REDUCE_WGSL = "\n@group(0) @binding(0) var<uniform> params: Params;\n@group(0) @binding(1) var<storage, read> pairOffsets: array<u32>;\n@group(0) @binding(2) var<storage, read> tilesPerSplat: array<u32>;\n@group(0) @binding(3) var<storage, read> partials: array<f32>;\n@group(0) @binding(4) var<storage, read_write> gradients: array<f32>;\n\nstruct Params {\n  width: u32,\n  height: u32,\n  across: u32,\n  splats: u32,\n};\n\nconst FAINT: f32 = 0.0009803921568627451;\nconst FLOATS: u32 = 10u;\nconst GRADS: u32 = 9u;\n\n\n\n@compute @workgroup_size(64, 1, 1)\nfn main(@builtin(global_invocation_id) id: vec3u) {\n  let splat = id.x;\n  if (splat >= params.splats) { return; }\n  let start = pairOffsets[splat];\n  let held = tilesPerSplat[splat];\n  for (var k = 0u; k < GRADS; k = k + 1u) {\n    var total = 0.0;\n    for (var slot = 0u; slot < held; slot = slot + 1u) {\n      total = total + partials[(start + slot) * GRADS + k];\n    }\n    gradients[splat * GRADS + k] = total;\n  }\n}\n";
+/**
+ * One Adam step over one family of parameters.
+ *
+ * The bias corrections arrive already computed, because they are a running product on the host —
+ * `β₁ⁿ` raised on the device would be a second definition of the same decay and would drift from
+ * the reference's in the last bits for no gain.
+ *
+ * Bindings: `settings` (count, rate, correction1, correction2), `values`, `gradient`, `moment`,
+ * `second`.
+ */
+export declare const SPLAT_ADAM_WGSL = "\nstruct Settings {\n  count: u32,\n  rate: f32,\n  correction1: f32,\n  correction2: f32,\n};\n\nconst BETA1: f32 = 0.9;\nconst BETA2: f32 = 0.999;\nconst EPSILON: f32 = 1e-8;\n\n@group(0) @binding(0) var<uniform> settings: Settings;\n@group(0) @binding(1) var<storage, read_write> values: array<f32>;\n@group(0) @binding(2) var<storage, read> gradient: array<f32>;\n@group(0) @binding(3) var<storage, read_write> moment: array<f32>;\n@group(0) @binding(4) var<storage, read_write> second: array<f32>;\n\n@compute @workgroup_size(64, 1, 1)\nfn main(@builtin(global_invocation_id) id: vec3u) {\n  let at = id.x;\n  if (at >= settings.count) { return; }\n  let g = gradient[at];\n  let m = BETA1 * moment[at] + (1.0 - BETA1) * g;\n  let v = BETA2 * second[at] + (1.0 - BETA2) * g * g;\n  moment[at] = m;\n  second[at] = v;\n  values[at] = values[at]\n    - (settings.rate * (m / settings.correction1)) / (sqrt(v / settings.correction2) + EPSILON);\n}\n";

package/dist/render/inference/splatRaster.wgsl.js

@@ -0,0 +1,337 @@
+/**
+ * A cloud of Gaussians drawn and differentiated on the device, one workgroup per tile.
+ *
+ * **Hand-authored WGSL, which the 2026-08-12 rule makes the exception for a compute shader**: there
+ * is no second copy to keep in step, because a compute shader has no WebGL2 twin, and the safety
+ * property inverts — this *is* the bottom of its own stack. What stands in for the generator's
+ * check is `scripts/gpu-parity.mjs`, which runs every one of these against
+ * `@driftengine/capture`'s reference rasteriser on the same cloud.
+ *
+ * **Why a tile and not a splat.** Splats overlap and compositing is ordered, so one invocation per
+ * splat has no way for two of them writing one pixel to agree who was in front. Turned inside out —
+ * one workgroup per tile of the frame, one invocation per pixel, each walking the list of splats
+ * that touch its tile — every pixel accumulates alone in its own registers and nothing is contended.
+ *
+ * **The backward pass reduces rather than adds atomically, and that is a determinism decision.**
+ * Many pixels contribute to one splat's gradient. WGSL has no floating-point atomic, and the usual
+ * workaround — a compare-and-swap loop over the bits — sums in whatever order the lanes happen to
+ * arrive; floating-point addition is not associative, so the same cloud would give a different
+ * gradient every run. Instead the workgroup steps through its list together, and for each splat the
+ * 256 lanes are reduced in a fixed tree into one slot of its own, which `splatTiles.ts`'s `pairOf`
+ * allocates. A second pass sums each splat's contiguous run. Same answer, every run, every device.
+ *
+ * **The frame is written premultiplied, as the reference writes it**: three channels of colour
+ * already multiplied by the light that reached them, and the coverage beside it.
+ */
+/**
+ * Numbers a splat occupies on the device: centre, screen covariance, opacity, colour, reach.
+ *
+ * **The reach is in the record because a tile is not a splat's footprint.** A workgroup walks every
+ * pixel of its tile, and a splat that touches the tile at one corner reaches only part of it — so
+ * without the same box the reference loops over, the device draws the splat at pixels the reference
+ * never evaluates. Measured before it was there: 6.7 · 10⁻³ of a channel on the worst pixel, which
+ * is not a rounding difference but a different picture. Just outside three standard deviations a
+ * Gaussian is still worth about a hundredth of its opacity, far above the faint cutoff.
+ */
+export const SPLAT_RASTER_FLOATS = 10;
+/** Numbers a splat's screen gradient occupies, in `@driftengine/capture`'s own order. */
+export const SPLAT_GRADIENT_FLOATS = 9;
+/** One workgroup covers a tile: the invocations are its pixels. */
+export const SPLAT_RASTER_GROUP = 16;
+/** Below this a splat contributes less than a quarter of a value of an eight-bit channel. */
+const FAINT = '0.0009803921568627451';
+/** What every pass needs: the frame's shape and the two record widths. */
+const SHARED = /* wgsl */ `
+struct Params {
+  width: u32,
+  height: u32,
+  across: u32,
+  splats: u32,
+};
+
+const FAINT: f32 = ${FAINT};
+const FLOATS: u32 = ${SPLAT_RASTER_FLOATS}u;
+const GRADS: u32 = ${SPLAT_GRADIENT_FLOATS}u;
+
+`;
+/** Reading a splat and evaluating it, for the two passes that touch the cloud itself. */
+const SPLAT_READER = /* wgsl */ `
+struct Splat {
+  centre: vec2f,
+  /* The screen covariance, [[a, b], [b, d]], the low-pass already in it. */
+  a: f32,
+  b: f32,
+  d: f32,
+  opacity: f32,
+  colour: vec3f,
+  /* Half the side of the pixel box it is drawn in, which is what bounds it. */
+  reach: f32,
+};
+
+fn readSplat(index: u32) -> Splat {
+  let at = index * FLOATS;
+  var one: Splat;
+  one.centre = vec2f(splats[at], splats[at + 1u]);
+  one.a = splats[at + 2u];
+  one.b = splats[at + 3u];
+  one.d = splats[at + 4u];
+  one.opacity = splats[at + 5u];
+  one.colour = vec3f(splats[at + 6u], splats[at + 7u], splats[at + 8u]);
+  one.reach = splats[at + 9u];
+  return one;
+}
+
+/* The pixel box the binning bins by, asked of one pixel: the rasteriser's own bound. */
+fn insideBox(one: Splat, pixel: vec2f) -> bool {
+  return pixel.x >= floor(one.centre.x - one.reach)
+    && pixel.x <= ceil(one.centre.x + one.reach)
+    && pixel.y >= floor(one.centre.y - one.reach)
+    && pixel.y <= ceil(one.centre.y + one.reach);
+}
+
+/* The inverse of the screen covariance, which is what the exponent is written in. */
+fn conicOf(one: Splat) -> vec3f {
+  let determinant = one.a * one.d - one.b * one.b;
+  return vec3f(one.d / determinant, -one.b / determinant, one.a / determinant);
+}
+
+/* How much of a splat reaches a pixel, from the pixel's own centre. */
+fn weightAt(conic: vec3f, offset: vec2f) -> f32 {
+  let power = -0.5 * (conic.x * offset.x * offset.x
+    + 2.0 * conic.y * offset.x * offset.y
+    + conic.z * offset.y * offset.y);
+  return exp(power);
+}
+`;
+/** The two together, which is what the tiled passes include. */
+const COMMON = SHARED + SPLAT_READER;
+/**
+ * The frame, and the light left at every pixel after the whole cloud — which the backward pass
+ * needs and cannot recover, because it walks the list the other way.
+ *
+ * Bindings: `params`, `splats`, `offsets`, `counts`, `lists`, `frame`, `light`.
+ */
+export const SPLAT_FORWARD_WGSL = /* wgsl */ `
+@group(0) @binding(0) var<uniform> params: Params;
+@group(0) @binding(1) var<storage, read> splats: array<f32>;
+@group(0) @binding(2) var<storage, read> offsets: array<u32>;
+@group(0) @binding(3) var<storage, read> counts: array<u32>;
+@group(0) @binding(4) var<storage, read> lists: array<u32>;
+@group(0) @binding(5) var<storage, read_write> frame: array<f32>;
+@group(0) @binding(6) var<storage, read_write> light: array<f32>;
+${COMMON}
+
+@compute @workgroup_size(${SPLAT_RASTER_GROUP}, ${SPLAT_RASTER_GROUP}, 1)
+fn main(@builtin(global_invocation_id) id: vec3u, @builtin(workgroup_id) group: vec3u) {
+  if (id.x >= params.width || id.y >= params.height) { return; }
+  let tile = group.y * params.across + group.x;
+  let start = offsets[tile];
+  let held = counts[tile];
+  let centre = vec2f(f32(id.x) + 0.5, f32(id.y) + 0.5);
+
+  var transmit = 1.0;
+  var colour = vec3f(0.0);
+  var covered = 0.0;
+  for (var slot = 0u; slot < held; slot = slot + 1u) {
+    let one = readSplat(lists[start + slot]);
+    if (!insideBox(one, vec2f(f32(id.x), f32(id.y)))) { continue; }
+    let alpha = one.opacity * weightAt(conicOf(one), centre - one.centre);
+    if (alpha < FAINT) { continue; }
+    let share = alpha * transmit;
+    colour = colour + share * one.colour;
+    covered = covered + share;
+    transmit = transmit * (1.0 - alpha);
+  }
+
+  let pixel = id.y * params.width + id.x;
+  frame[pixel * 4u] = colour.x;
+  frame[pixel * 4u + 1u] = colour.y;
+  frame[pixel * 4u + 2u] = colour.z;
+  frame[pixel * 4u + 3u] = covered;
+  light[pixel] = transmit;
+}
+`;
+/**
+ * The gradients of one tile's splats, each into a slot of its own.
+ *
+ * The workgroup walks its list furthest first, in step: every lane holds the light in front of the
+ * splat it has reached and the colour accumulated behind it, and after each splat the lanes are
+ * reduced in a fixed tree so the sum is the same on every device and every run.
+ *
+ * Bindings: `params`, `splats`, `offsets`, `counts`, `lists`, `pairOf`, `dPixels`, `light`,
+ * `partials`.
+ */
+export const SPLAT_BACKWARD_WGSL = /* wgsl */ `
+@group(0) @binding(0) var<uniform> params: Params;
+@group(0) @binding(1) var<storage, read> splats: array<f32>;
+@group(0) @binding(2) var<storage, read> offsets: array<u32>;
+@group(0) @binding(3) var<storage, read> counts: array<u32>;
+@group(0) @binding(4) var<storage, read> lists: array<u32>;
+@group(0) @binding(5) var<storage, read> pairOf: array<u32>;
+@group(0) @binding(6) var<storage, read> dPixels: array<f32>;
+@group(0) @binding(7) var<storage, read> light: array<f32>;
+@group(0) @binding(8) var<storage, read_write> partials: array<f32>;
+${COMMON}
+
+const LANES: u32 = ${SPLAT_RASTER_GROUP * SPLAT_RASTER_GROUP}u;
+var<workgroup> gathered: array<array<f32, ${SPLAT_GRADIENT_FLOATS}>, ${SPLAT_RASTER_GROUP * SPLAT_RASTER_GROUP}>;
+
+@compute @workgroup_size(${SPLAT_RASTER_GROUP}, ${SPLAT_RASTER_GROUP}, 1)
+fn main(
+  @builtin(global_invocation_id) id: vec3u,
+  @builtin(workgroup_id) group: vec3u,
+  @builtin(local_invocation_index) lane: u32,
+) {
+  let tile = group.y * params.across + group.x;
+  let start = offsets[tile];
+  let held = counts[tile];
+  /* Off the edge of the frame there is no pixel, and the lane still meets every barrier below. */
+  let inside = id.x < params.width && id.y < params.height;
+  let pixel = select(0u, id.y * params.width + id.x, inside);
+  let centre = vec2f(f32(id.x) + 0.5, f32(id.y) + 0.5);
+
+  var transmit = select(1.0, light[pixel], inside);
+  var behind = vec3f(0.0);
+  var behindCover = 0.0;
+  var dPixel = vec4f(0.0);
+  if (inside) {
+    dPixel = vec4f(dPixels[pixel * 4u], dPixels[pixel * 4u + 1u],
+      dPixels[pixel * 4u + 2u], dPixels[pixel * 4u + 3u]);
+  }
+
+  for (var step = 0u; step < held; step = step + 1u) {
+    let slot = held - 1u - step;
+    let index = lists[start + slot];
+    let one = readSplat(index);
+    let conic = conicOf(one);
+    let offset = centre - one.centre;
+    let weight = weightAt(conic, offset);
+    let alpha = one.opacity * weight;
+    let contributes = inside && alpha >= FAINT
+      && insideBox(one, vec2f(f32(id.x), f32(id.y)));
+
+    var mine: array<f32, GRADS>;
+    for (var k = 0u; k < GRADS; k = k + 1u) { mine[k] = 0.0; }
+    if (contributes) {
+      /* Undo this splat's own share to recover the light that reached it. */
+      /* Divided by what is left of the light, and by one where nothing is. */
+      let left = select(1.0 - alpha, 1.0, alpha == 1.0);
+      let before = transmit / left;
+      var dAlpha = 0.0;
+      for (var c = 0u; c < 3u; c = c + 1u) {
+        let grad = dPixel[c];
+        mine[6u + c] = grad * alpha * before;
+        dAlpha = dAlpha + grad * before * (one.colour[c] - behind[c]);
+      }
+      dAlpha = dAlpha + dPixel.w * before * (1.0 - behindCover);
+      mine[5u] = dAlpha * weight;
+
+      /* Through the exponent to the centre and the covariance, as the reference has it. */
+      let dPower = dAlpha * one.opacity * weight;
+      mine[0u] = dPower * (conic.x * offset.x + conic.y * offset.y);
+      mine[1u] = dPower * (conic.y * offset.x + conic.z * offset.y);
+      let dInverse = vec3f(
+        -0.5 * dPower * offset.x * offset.x,
+        -0.5 * dPower * offset.x * offset.y,
+        -0.5 * dPower * offset.y * offset.y);
+      mine[2u] = -(conic.x * dInverse.x * conic.x + 2.0 * conic.x * conic.y * dInverse.y
+        + conic.y * dInverse.z * conic.y);
+      mine[3u] = -2.0 * (conic.x * dInverse.x * conic.y + conic.y * dInverse.y * conic.y
+        + conic.x * dInverse.y * conic.z + conic.y * dInverse.z * conic.z);
+      mine[4u] = -(conic.y * dInverse.x * conic.y + 2.0 * conic.y * conic.z * dInverse.y
+        + conic.z * dInverse.z * conic.z);
+
+      /* And carry this splat into what stands behind the next one. */
+      behind = alpha * one.colour + (1.0 - alpha) * behind;
+      behindCover = alpha + (1.0 - alpha) * behindCover;
+      transmit = before;
+    }
+
+    /* The lanes, reduced in a fixed tree: the same sum in the same order on every device. */
+    for (var k = 0u; k < GRADS; k = k + 1u) { gathered[lane][k] = mine[k]; }
+    workgroupBarrier();
+    for (var half = LANES / 2u; half > 0u; half = half / 2u) {
+      if (lane < half) {
+        for (var k = 0u; k < GRADS; k = k + 1u) {
+          gathered[lane][k] = gathered[lane][k] + gathered[lane + half][k];
+        }
+      }
+      workgroupBarrier();
+    }
+    if (lane == 0u) {
+      let pair = pairOf[start + slot] * GRADS;
+      for (var k = 0u; k < GRADS; k = k + 1u) { partials[pair + k] = gathered[0][k]; }
+    }
+    workgroupBarrier();
+  }
+}
+`;
+/**
+ * Each splat's own run of partial gradients, summed in index order.
+ *
+ * Bindings: `params`, `pairOffsets`, `tilesPerSplat`, `partials`, `gradients`.
+ */
+export const SPLAT_REDUCE_WGSL = /* wgsl */ `
+@group(0) @binding(0) var<uniform> params: Params;
+@group(0) @binding(1) var<storage, read> pairOffsets: array<u32>;
+@group(0) @binding(2) var<storage, read> tilesPerSplat: array<u32>;
+@group(0) @binding(3) var<storage, read> partials: array<f32>;
+@group(0) @binding(4) var<storage, read_write> gradients: array<f32>;
+${SHARED}
+
+@compute @workgroup_size(64, 1, 1)
+fn main(@builtin(global_invocation_id) id: vec3u) {
+  let splat = id.x;
+  if (splat >= params.splats) { return; }
+  let start = pairOffsets[splat];
+  let held = tilesPerSplat[splat];
+  for (var k = 0u; k < GRADS; k = k + 1u) {
+    var total = 0.0;
+    for (var slot = 0u; slot < held; slot = slot + 1u) {
+      total = total + partials[(start + slot) * GRADS + k];
+    }
+    gradients[splat * GRADS + k] = total;
+  }
+}
+`;
+/**
+ * One Adam step over one family of parameters.
+ *
+ * The bias corrections arrive already computed, because they are a running product on the host —
+ * `β₁ⁿ` raised on the device would be a second definition of the same decay and would drift from
+ * the reference's in the last bits for no gain.
+ *
+ * Bindings: `settings` (count, rate, correction1, correction2), `values`, `gradient`, `moment`,
+ * `second`.
+ */
+export const SPLAT_ADAM_WGSL = /* wgsl */ `
+struct Settings {
+  count: u32,
+  rate: f32,
+  correction1: f32,
+  correction2: f32,
+};
+
+const BETA1: f32 = 0.9;
+const BETA2: f32 = 0.999;
+const EPSILON: f32 = 1e-8;
+
+@group(0) @binding(0) var<uniform> settings: Settings;
+@group(0) @binding(1) var<storage, read_write> values: array<f32>;
+@group(0) @binding(2) var<storage, read> gradient: array<f32>;
+@group(0) @binding(3) var<storage, read_write> moment: array<f32>;
+@group(0) @binding(4) var<storage, read_write> second: array<f32>;
+
+@compute @workgroup_size(64, 1, 1)
+fn main(@builtin(global_invocation_id) id: vec3u) {
+  let at = id.x;
+  if (at >= settings.count) { return; }
+  let g = gradient[at];
+  let m = BETA1 * moment[at] + (1.0 - BETA1) * g;
+  let v = BETA2 * second[at] + (1.0 - BETA2) * g * g;
+  moment[at] = m;
+  second[at] = v;
+  values[at] = values[at]
+    - (settings.rate * (m / settings.correction1)) / (sqrt(v / settings.correction2) + EPSILON);
+}
+`;