@driftengine/core 3.63.0 → 4.0.0

package/dist/render/shaders/gi/composeField.wgsl.d.ts

@@ -0,0 +1,56 @@
+/** Composing the world's distance field, on the device, because 707 ms is not a frame. */
+/**
+ * **This is the only version of `composeGlobalField` that can run in a frame.**
+ *
+ * The TypeScript in `gi/globalField.ts` is the reference and says so in its own header: it visits
+ * every sample of every cascade for every instance it cannot cull outright, deliberately, because
+ * a reference that was already accelerated would be a second thing to be wrong rather than the
+ * thing the first is checked by. Measured by `scripts/gi-schemes.mjs`, that costs **707 ms a
+ * frame** for 32 instances over four cascades of 65 cubed — 35 million inverse transforms and
+ * trilinear reads, which is exactly the shape a GPU is for and exactly the shape a CPU is not.
+ *
+ * **One invocation a sample, and no culling at all.** The reference culls an instance further from
+ * a cascade than that cascade's reach, and the measurement that justified it there — 19.4 ms
+ * against 150.2 — is a statement about a serial loop. Here every sample is already parallel, so
+ * what the cull would save is a branch per instance per thread and what it would cost is a
+ * divergent one. It is left out, and `scripts/gi-parity.mjs` is what proves that changes no answer:
+ * the cull cannot change a result, only the time taken to reach it, because a culled instance is
+ * one whose contribution the minimum would have discarded.
+ *
+ * **The layouts are the reference's, restated rather than shared, and that is the hazard.** A
+ * shader and a TypeScript function cannot import a struct from each other, so the eight-corner
+ * blend below and `read()` in `globalField.ts` are two spellings of one decision. `gi-parity.mjs`
+ * runs both over generated input and compares every sample, which is the arrangement
+ * `gpu-parity.mjs` established for exactly this reason.
+ */
+/** Floats per instance in the `instances` buffer. See `INSTANCE_*` below for what they are. */
+export declare const COMPOSE_INSTANCE_FLOATS = 32;
+/** Where each field of an instance record starts, in floats. */
+export declare const INSTANCE_INVERSE = 0;
+export declare const INSTANCE_SCALE = 16;
+export declare const INSTANCE_BOUNDS = 17;
+export declare const INSTANCE_DIMS = 23;
+export declare const INSTANCE_OFFSET = 26;
+/** The instance's own colour, three floats. White where a consumer declared none. */
+export declare const INSTANCE_ALBEDO = 28;
+/**
+ * Floats in the `params` buffer: cascade origin, step, dims, reach, instance count, output base.
+ *
+ * **Every cascade has its own copy, at its own 256-byte-aligned offset.** `queue.writeBuffer` is a
+ * queue operation and is not ordered against the commands of an encoder, so rewriting one params
+ * buffer between dispatches gives every dispatch the *last* write — three cascades composed with
+ * the outermost one's origin and step, which looks like a field that is simply wrong everywhere.
+ */
+export declare const COMPOSE_PARAM_FLOATS = 12;
+/** Where a cascade's samples start in the shared output, in floats. `params[9]`. */
+export declare const COMPOSE_OUTPUT_BASE = 9;
+/**
+ * Bytes between one cascade's params and the next.
+ *
+ * A storage binding's offset must be a multiple of `minStorageBufferOffsetAlignment`, which is 256
+ * on every device this targets — the same limit the GPU-driven pyramid's levels are padded to.
+ */
+export declare const COMPOSE_PARAM_STRIDE = 256;
+/** Invocations a workgroup. 64 is this backend's default everywhere else. */
+export declare const COMPOSE_WORKGROUP = 64;
+export declare const COMPOSE_FIELD_WGSL = "\nstruct Params {\n  originX: f32,\n  originY: f32,\n  originZ: f32,\n  step: f32,\n  countX: f32,\n  countY: f32,\n  countZ: f32,\n  reach: f32,\n  instances: f32,\n  padA: f32,\n  padB: f32,\n  padC: f32,\n};\n\n@group(0) @binding(0) var<storage, read> params: array<f32>;\n@group(0) @binding(1) var<storage, read> instances: array<f32>;\n@group(0) @binding(2) var<storage, read> sources: array<f32>;\n@group(0) @binding(3) var<storage, read_write> field: array<f32>;\n/* The colour of whatever won the union at each sample, three floats. See GlobalFieldCascade. */\n@group(0) @binding(4) var<storage, read_write> albedo: array<f32>;\n\n/*\n * The eight-corner blend of one object's field, at a point already in that object's space.\n *\n * Clamped at the grid's edge, exactly as the reference is: a sample past the last plane takes that\n * plane rather than extrapolating, and the index stops one short so the pair it interpolates\n * between is always inside.\n */\nfn sourceAt(base: u32, bounds0: vec3<f32>, bounds1: vec3<f32>, dims: vec3<f32>, p: vec3<f32>) -> f32 {\n  /* One step for all three axes, because an object's voxels are cubic. bakeObjectSdf is why. */\n  let step = (bounds1.x - bounds0.x) / (dims.x - 1.0);\n\n  var low = vec3<f32>(0.0, 0.0, 0.0);\n  var frac = vec3<f32>(0.0, 0.0, 0.0);\n  for (var axis = 0u; axis < 3u; axis = axis + 1u) {\n    let count = dims[axis];\n    let local = (p[axis] - bounds0[axis]) / step;\n    let clamped = clamp(local, 0.0, count - 1.0);\n    let index = min(floor(clamped), count - 2.0);\n    low[axis] = index;\n    frac[axis] = clamped - index;\n  }\n\n  let nx = u32(dims.x);\n  let ny = u32(dims.y);\n  let lx = u32(low.x);\n  let ly = u32(low.y);\n  let lz = u32(low.z);\n\n  var total = 0.0;\n  for (var cz = 0u; cz < 2u; cz = cz + 1u) {\n    let wz = select(1.0 - frac.z, frac.z, cz == 1u);\n    for (var cy = 0u; cy < 2u; cy = cy + 1u) {\n      let wy = select(1.0 - frac.y, frac.y, cy == 1u);\n      for (var cx = 0u; cx < 2u; cx = cx + 1u) {\n        let wx = select(1.0 - frac.x, frac.x, cx == 1u);\n        let at = lx + cx + nx * (ly + cy + ny * (lz + cz));\n        total = total + sources[base + at] * wx * wy * wz;\n      }\n    }\n  }\n  return total;\n}\n\n@compute @workgroup_size(64)\nfn main(@builtin(global_invocation_id) id: vec3<u32>) {\n  let countX = u32(params[4]);\n  let countY = u32(params[5]);\n  let countZ = u32(params[6]);\n  let total = countX * countY * countZ;\n  let index = id.x;\n  if (index >= total) {\n    return;\n  }\n\n  let ix = index % countX;\n  let iy = (index / countX) % countY;\n  let iz = index / (countX * countY);\n  let step = params[3];\n  let world = vec3<f32>(\n    params[0] + f32(ix) * step,\n    params[1] + f32(iy) * step,\n    params[2] + f32(iz) * step,\n  );\n\n  /* The reach, which is both the initial value and a bound on what any instance can lower it to. */\n  var best = params[7];\n  /* White, so a sample no instance reached is neutral rather than a light that vanishes. */\n  var bestAlbedo = vec3<f32>(1.0, 1.0, 1.0);\n  let instanceCount = u32(params[8]);\n\n  for (var i = 0u; i < instanceCount; i = i + 1u) {\n    let base = i * 32u;\n\n    /*\n     * The world point carried into the object's space through the **inverse**. Column-major, the\n     * order gl-matrix stores a matrix in, which is the order the reference reads it in too.\n     */\n    let object = vec3<f32>(\n      instances[base + 0u] * world.x + instances[base + 4u] * world.y + instances[base + 8u] * world.z + instances[base + 12u],\n      instances[base + 1u] * world.x + instances[base + 5u] * world.y + instances[base + 9u] * world.z + instances[base + 13u],\n      instances[base + 2u] * world.x + instances[base + 6u] * world.y + instances[base + 10u] * world.z + instances[base + 14u],\n    );\n\n    let scale = instances[base + 16u];\n    let bounds0 = vec3<f32>(\n      instances[base + 17u],\n      instances[base + 17u + 1u],\n      instances[base + 17u + 2u],\n    );\n    let bounds1 = vec3<f32>(\n      instances[base + 17u + 3u],\n      instances[base + 17u + 4u],\n      instances[base + 17u + 5u],\n    );\n\n    /*\n     * **Outside the source's box, bounded two ways and the larger taken.** The distance to the box\n     * alone is a true bound and a useless one: just outside it says zero, so a sphere trace stops\n     * on a phantom shell around every instance. d(q) >= d(c) - |q - c| by the triangle\n     * inequality, against the field's own value at the nearest point of the box, is the bound that\n     * reports the real clearance. See sampleInstance in globalField.ts.\n     */\n    let clamped = clamp(object, bounds0, bounds1);\n    let outside = length(object - clamped);\n\n    var distance = 0.0;\n    if (outside > 0.0) {\n      let dims = vec3<f32>(\n        instances[base + 23u],\n        instances[base + 23u + 1u],\n        instances[base + 23u + 2u],\n      );\n      let sourceBase = u32(instances[base + 26u]);\n      let atBox = sourceAt(sourceBase, bounds0, bounds1, dims, clamped);\n      distance = max(outside, atBox - outside) * scale;\n    } else {\n      let dims = vec3<f32>(\n        instances[base + 23u],\n        instances[base + 23u + 1u],\n        instances[base + 23u + 2u],\n      );\n      let sourceBase = u32(instances[base + 26u]);\n      distance = sourceAt(sourceBase, bounds0, bounds1, dims, object) * scale;\n    }\n\n    /*\n     * **The minimum, because the union of two solids is the nearer surface** \u2014 and the colour goes\n     * with it rather than beside it. Writing the albedo unconditionally would paint every sample\n     * with whichever instance happened to come last, which is a field of the right shape in the\n     * wrong colours and looks like a lighting bug rather than a composition one.\n     */\n    if (distance < best) {\n      best = distance;\n      bestAlbedo = vec3<f32>(\n        instances[base + 28u],\n        instances[base + 28u + 1u],\n        instances[base + 28u + 2u],\n      );\n    }\n  }\n\n  /*\n   * **Into this cascade's own region of one shared buffer.** Without the base every cascade writes\n   * the same samples and the last one wins, which reads as a field that has only its outermost\n   * level \u2014 the innermost detail simply absent, at the resolution a viewer is closest to.\n   */\n  field[u32(params[9]) + index] = best;\n  let colourAt = (u32(params[9]) + index) * 3u;\n  albedo[colourAt] = bestAlbedo.x;\n  albedo[colourAt + 1u] = bestAlbedo.y;\n  albedo[colourAt + 2u] = bestAlbedo.z;\n}\n";

package/dist/render/shaders/gi/composeField.wgsl.js

@@ -0,0 +1,231 @@
+/** Composing the world's distance field, on the device, because 707 ms is not a frame. */
+/**
+ * **This is the only version of `composeGlobalField` that can run in a frame.**
+ *
+ * The TypeScript in `gi/globalField.ts` is the reference and says so in its own header: it visits
+ * every sample of every cascade for every instance it cannot cull outright, deliberately, because
+ * a reference that was already accelerated would be a second thing to be wrong rather than the
+ * thing the first is checked by. Measured by `scripts/gi-schemes.mjs`, that costs **707 ms a
+ * frame** for 32 instances over four cascades of 65 cubed — 35 million inverse transforms and
+ * trilinear reads, which is exactly the shape a GPU is for and exactly the shape a CPU is not.
+ *
+ * **One invocation a sample, and no culling at all.** The reference culls an instance further from
+ * a cascade than that cascade's reach, and the measurement that justified it there — 19.4 ms
+ * against 150.2 — is a statement about a serial loop. Here every sample is already parallel, so
+ * what the cull would save is a branch per instance per thread and what it would cost is a
+ * divergent one. It is left out, and `scripts/gi-parity.mjs` is what proves that changes no answer:
+ * the cull cannot change a result, only the time taken to reach it, because a culled instance is
+ * one whose contribution the minimum would have discarded.
+ *
+ * **The layouts are the reference's, restated rather than shared, and that is the hazard.** A
+ * shader and a TypeScript function cannot import a struct from each other, so the eight-corner
+ * blend below and `read()` in `globalField.ts` are two spellings of one decision. `gi-parity.mjs`
+ * runs both over generated input and compares every sample, which is the arrangement
+ * `gpu-parity.mjs` established for exactly this reason.
+ */
+/** Floats per instance in the `instances` buffer. See `INSTANCE_*` below for what they are. */
+export const COMPOSE_INSTANCE_FLOATS = 32;
+/** Where each field of an instance record starts, in floats. */
+export const INSTANCE_INVERSE = 0;
+export const INSTANCE_SCALE = 16;
+export const INSTANCE_BOUNDS = 17;
+export const INSTANCE_DIMS = 23;
+export const INSTANCE_OFFSET = 26;
+/** The instance's own colour, three floats. White where a consumer declared none. */
+export const INSTANCE_ALBEDO = 28;
+/**
+ * Floats in the `params` buffer: cascade origin, step, dims, reach, instance count, output base.
+ *
+ * **Every cascade has its own copy, at its own 256-byte-aligned offset.** `queue.writeBuffer` is a
+ * queue operation and is not ordered against the commands of an encoder, so rewriting one params
+ * buffer between dispatches gives every dispatch the *last* write — three cascades composed with
+ * the outermost one's origin and step, which looks like a field that is simply wrong everywhere.
+ */
+export const COMPOSE_PARAM_FLOATS = 12;
+/** Where a cascade's samples start in the shared output, in floats. `params[9]`. */
+export const COMPOSE_OUTPUT_BASE = 9;
+/**
+ * Bytes between one cascade's params and the next.
+ *
+ * A storage binding's offset must be a multiple of `minStorageBufferOffsetAlignment`, which is 256
+ * on every device this targets — the same limit the GPU-driven pyramid's levels are padded to.
+ */
+export const COMPOSE_PARAM_STRIDE = 256;
+/** Invocations a workgroup. 64 is this backend's default everywhere else. */
+export const COMPOSE_WORKGROUP = 64;
+export const COMPOSE_FIELD_WGSL = /* wgsl */ `
+struct Params {
+  originX: f32,
+  originY: f32,
+  originZ: f32,
+  step: f32,
+  countX: f32,
+  countY: f32,
+  countZ: f32,
+  reach: f32,
+  instances: f32,
+  padA: f32,
+  padB: f32,
+  padC: f32,
+};
+
+@group(0) @binding(0) var<storage, read> params: array<f32>;
+@group(0) @binding(1) var<storage, read> instances: array<f32>;
+@group(0) @binding(2) var<storage, read> sources: array<f32>;
+@group(0) @binding(3) var<storage, read_write> field: array<f32>;
+/* The colour of whatever won the union at each sample, three floats. See GlobalFieldCascade. */
+@group(0) @binding(4) var<storage, read_write> albedo: array<f32>;
+
+/*
+ * The eight-corner blend of one object's field, at a point already in that object's space.
+ *
+ * Clamped at the grid's edge, exactly as the reference is: a sample past the last plane takes that
+ * plane rather than extrapolating, and the index stops one short so the pair it interpolates
+ * between is always inside.
+ */
+fn sourceAt(base: u32, bounds0: vec3<f32>, bounds1: vec3<f32>, dims: vec3<f32>, p: vec3<f32>) -> f32 {
+  /* One step for all three axes, because an object's voxels are cubic. bakeObjectSdf is why. */
+  let step = (bounds1.x - bounds0.x) / (dims.x - 1.0);
+
+  var low = vec3<f32>(0.0, 0.0, 0.0);
+  var frac = vec3<f32>(0.0, 0.0, 0.0);
+  for (var axis = 0u; axis < 3u; axis = axis + 1u) {
+    let count = dims[axis];
+    let local = (p[axis] - bounds0[axis]) / step;
+    let clamped = clamp(local, 0.0, count - 1.0);
+    let index = min(floor(clamped), count - 2.0);
+    low[axis] = index;
+    frac[axis] = clamped - index;
+  }
+
+  let nx = u32(dims.x);
+  let ny = u32(dims.y);
+  let lx = u32(low.x);
+  let ly = u32(low.y);
+  let lz = u32(low.z);
+
+  var total = 0.0;
+  for (var cz = 0u; cz < 2u; cz = cz + 1u) {
+    let wz = select(1.0 - frac.z, frac.z, cz == 1u);
+    for (var cy = 0u; cy < 2u; cy = cy + 1u) {
+      let wy = select(1.0 - frac.y, frac.y, cy == 1u);
+      for (var cx = 0u; cx < 2u; cx = cx + 1u) {
+        let wx = select(1.0 - frac.x, frac.x, cx == 1u);
+        let at = lx + cx + nx * (ly + cy + ny * (lz + cz));
+        total = total + sources[base + at] * wx * wy * wz;
+      }
+    }
+  }
+  return total;
+}
+
+@compute @workgroup_size(${COMPOSE_WORKGROUP})
+fn main(@builtin(global_invocation_id) id: vec3<u32>) {
+  let countX = u32(params[4]);
+  let countY = u32(params[5]);
+  let countZ = u32(params[6]);
+  let total = countX * countY * countZ;
+  let index = id.x;
+  if (index >= total) {
+    return;
+  }
+
+  let ix = index % countX;
+  let iy = (index / countX) % countY;
+  let iz = index / (countX * countY);
+  let step = params[3];
+  let world = vec3<f32>(
+    params[0] + f32(ix) * step,
+    params[1] + f32(iy) * step,
+    params[2] + f32(iz) * step,
+  );
+
+  /* The reach, which is both the initial value and a bound on what any instance can lower it to. */
+  var best = params[7];
+  /* White, so a sample no instance reached is neutral rather than a light that vanishes. */
+  var bestAlbedo = vec3<f32>(1.0, 1.0, 1.0);
+  let instanceCount = u32(params[8]);
+
+  for (var i = 0u; i < instanceCount; i = i + 1u) {
+    let base = i * ${COMPOSE_INSTANCE_FLOATS}u;
+
+    /*
+     * The world point carried into the object's space through the **inverse**. Column-major, the
+     * order gl-matrix stores a matrix in, which is the order the reference reads it in too.
+     */
+    let object = vec3<f32>(
+      instances[base + 0u] * world.x + instances[base + 4u] * world.y + instances[base + 8u] * world.z + instances[base + 12u],
+      instances[base + 1u] * world.x + instances[base + 5u] * world.y + instances[base + 9u] * world.z + instances[base + 13u],
+      instances[base + 2u] * world.x + instances[base + 6u] * world.y + instances[base + 10u] * world.z + instances[base + 14u],
+    );
+
+    let scale = instances[base + ${INSTANCE_SCALE}u];
+    let bounds0 = vec3<f32>(
+      instances[base + ${INSTANCE_BOUNDS}u],
+      instances[base + ${INSTANCE_BOUNDS}u + 1u],
+      instances[base + ${INSTANCE_BOUNDS}u + 2u],
+    );
+    let bounds1 = vec3<f32>(
+      instances[base + ${INSTANCE_BOUNDS}u + 3u],
+      instances[base + ${INSTANCE_BOUNDS}u + 4u],
+      instances[base + ${INSTANCE_BOUNDS}u + 5u],
+    );
+
+    /*
+     * **Outside the source's box, bounded two ways and the larger taken.** The distance to the box
+     * alone is a true bound and a useless one: just outside it says zero, so a sphere trace stops
+     * on a phantom shell around every instance. d(q) >= d(c) - |q - c| by the triangle
+     * inequality, against the field's own value at the nearest point of the box, is the bound that
+     * reports the real clearance. See sampleInstance in globalField.ts.
+     */
+    let clamped = clamp(object, bounds0, bounds1);
+    let outside = length(object - clamped);
+
+    var distance = 0.0;
+    if (outside > 0.0) {
+      let dims = vec3<f32>(
+        instances[base + 23u],
+        instances[base + 23u + 1u],
+        instances[base + 23u + 2u],
+      );
+      let sourceBase = u32(instances[base + 26u]);
+      let atBox = sourceAt(sourceBase, bounds0, bounds1, dims, clamped);
+      distance = max(outside, atBox - outside) * scale;
+    } else {
+      let dims = vec3<f32>(
+        instances[base + ${INSTANCE_DIMS}u],
+        instances[base + ${INSTANCE_DIMS}u + 1u],
+        instances[base + ${INSTANCE_DIMS}u + 2u],
+      );
+      let sourceBase = u32(instances[base + ${INSTANCE_OFFSET}u]);
+      distance = sourceAt(sourceBase, bounds0, bounds1, dims, object) * scale;
+    }
+
+    /*
+     * **The minimum, because the union of two solids is the nearer surface** — and the colour goes
+     * with it rather than beside it. Writing the albedo unconditionally would paint every sample
+     * with whichever instance happened to come last, which is a field of the right shape in the
+     * wrong colours and looks like a lighting bug rather than a composition one.
+     */
+    if (distance < best) {
+      best = distance;
+      bestAlbedo = vec3<f32>(
+        instances[base + ${INSTANCE_ALBEDO}u],
+        instances[base + ${INSTANCE_ALBEDO}u + 1u],
+        instances[base + ${INSTANCE_ALBEDO}u + 2u],
+      );
+    }
+  }
+
+  /*
+   * **Into this cascade's own region of one shared buffer.** Without the base every cascade writes
+   * the same samples and the last one wins, which reads as a field that has only its outermost
+   * level — the innermost detail simply absent, at the resolution a viewer is closest to.
+   */
+  field[u32(params[9]) + index] = best;
+  let colourAt = (u32(params[9]) + index) * 3u;
+  albedo[colourAt] = bestAlbedo.x;
+  albedo[colourAt + 1u] = bestAlbedo.y;
+  albedo[colourAt + 2u] = bestAlbedo.z;
+}
+`;

package/dist/render/shaders/gi/marchField.wgsl.d.ts

@@ -0,0 +1,30 @@
+/** The composed field, drawn — so a pass that fills one can be looked at rather than trusted. */
+/**
+ * **A visualisation, and it is the honest first consumer of the field.**
+ *
+ * What Wave 4A's chain is eventually for is indirect light in the shading path, and that is a far
+ * larger integration than a pass. What a pass can do now is prove the composition runs on a device
+ * and say what it costs — and a distance field is a thing you can *see*, by sphere-tracing it from
+ * the camera. If the geometry in the picture is the geometry in the scene, in the right places and
+ * the right sizes, the composition is right; if a cascade boundary shows as a seam, the fade is
+ * wrong. Neither is available from a number.
+ *
+ * That is what `DRAFT_SCENES` is for, and it is the same shape the GPU-driven pipeline's three rigs
+ * took: a second path drawn beside the first, measured, and kept out of the published set until
+ * what it draws is the whole material.
+ *
+ * **The march is `traceField.ts`'s, minus the cone.** Step by the field's own value, which is a
+ * distance nothing can be nearer than; stop where it falls under an epsilon; give up where the ray
+ * leaves the outermost cascade, because past that there is no information and stepping on a clamped
+ * value converges on the boundary and reports a surface made of nothing.
+ */
+/** Floats in the march's params: the inverse view-projection, the eye, and four scalars. */
+export declare const MARCH_PARAM_FLOATS = 24;
+/** Where each field starts. `INV_VIEW_PROJ` is column-major, as `gl-matrix` stores it. */
+export declare const MARCH_INV_VIEW_PROJ = 0;
+export declare const MARCH_EYE = 16;
+export declare const MARCH_LEVELS = 20;
+export declare const MARCH_SIDE = 21;
+export declare const MARCH_STEPS = 22;
+export declare const MARCH_EPSILON = 23;
+export declare const MARCH_FIELD_WGSL: string;

package/dist/render/shaders/gi/marchField.wgsl.js

@@ -0,0 +1,141 @@
+/** The composed field, drawn — so a pass that fills one can be looked at rather than trusted. */
+import { SAMPLE_FIELD_WGSL } from './sampleField.wgsl.js';
+/**
+ * **A visualisation, and it is the honest first consumer of the field.**
+ *
+ * What Wave 4A's chain is eventually for is indirect light in the shading path, and that is a far
+ * larger integration than a pass. What a pass can do now is prove the composition runs on a device
+ * and say what it costs — and a distance field is a thing you can *see*, by sphere-tracing it from
+ * the camera. If the geometry in the picture is the geometry in the scene, in the right places and
+ * the right sizes, the composition is right; if a cascade boundary shows as a seam, the fade is
+ * wrong. Neither is available from a number.
+ *
+ * That is what `DRAFT_SCENES` is for, and it is the same shape the GPU-driven pipeline's three rigs
+ * took: a second path drawn beside the first, measured, and kept out of the published set until
+ * what it draws is the whole material.
+ *
+ * **The march is `traceField.ts`'s, minus the cone.** Step by the field's own value, which is a
+ * distance nothing can be nearer than; stop where it falls under an epsilon; give up where the ray
+ * leaves the outermost cascade, because past that there is no information and stepping on a clamped
+ * value converges on the boundary and reports a surface made of nothing.
+ */
+/** Floats in the march's params: the inverse view-projection, the eye, and four scalars. */
+export const MARCH_PARAM_FLOATS = 24;
+/** Where each field starts. `INV_VIEW_PROJ` is column-major, as `gl-matrix` stores it. */
+export const MARCH_INV_VIEW_PROJ = 0;
+export const MARCH_EYE = 16;
+export const MARCH_LEVELS = 20;
+export const MARCH_SIDE = 21;
+export const MARCH_STEPS = 22;
+export const MARCH_EPSILON = 23;
+export const MARCH_FIELD_WGSL = /* wgsl */ `
+@group(0) @binding(0) var<storage, read> params: array<f32>;
+@group(0) @binding(1) var<storage, read> cascades: array<f32>;
+@group(0) @binding(2) var<storage, read> fields: array<f32>;
+
+${SAMPLE_FIELD_WGSL}
+
+struct Varying {
+  @builtin(position) position: vec4<f32>,
+  @location(0) uv: vec2<f32>,
+};
+
+/*
+ * One triangle covering the frame, which is one fewer than two and has no diagonal for a
+ * derivative to straddle. Clip y of +1 is the top of the image on both backends — see
+ * CLIP_CORRECTION's own note, which spent months saying otherwise — so uv.y counts down from it.
+ */
+@vertex
+fn vertexMain(@builtin(vertex_index) index: u32) -> Varying {
+  var out: Varying;
+  let x = f32(i32(index) / 2) * 4.0 - 1.0;
+  let y = f32(i32(index) & 1) * 4.0 - 1.0;
+  out.position = vec4<f32>(x, y, 0.0, 1.0);
+  out.uv = vec2<f32>(x * 0.5 + 0.5, 0.5 - y * 0.5);
+  return out;
+}
+
+fn unproject(ndc: vec2<f32>) -> vec3<f32> {
+  let m = ${MARCH_INV_VIEW_PROJ}u;
+  let clip = vec4<f32>(ndc.x, ndc.y, 0.5, 1.0);
+  /*
+   * Column-major, so column c is params[c * 4 .. c * 4 + 3]. Any depth gives the same ray from the
+   * eye, which is why the z above is a half rather than a near or a far plane — this is the one
+   * place the depth convention does not have to be known.
+   */
+  var world = vec4<f32>(0.0, 0.0, 0.0, 0.0);
+  for (var row = 0u; row < 4u; row = row + 1u) {
+    world[row] =
+      params[m + row] * clip.x +
+      params[m + 4u + row] * clip.y +
+      params[m + 8u + row] * clip.z +
+      params[m + 12u + row] * clip.w;
+  }
+  return world.xyz / world.w;
+}
+
+/** The field's gradient, which for a distance field is the surface normal. */
+fn normalAt(levels: u32, side: u32, p: vec3<f32>, h: f32) -> vec3<f32> {
+  let dx = sampleField(levels, side, p + vec3<f32>(h, 0.0, 0.0)) - sampleField(levels, side, p - vec3<f32>(h, 0.0, 0.0));
+  let dy = sampleField(levels, side, p + vec3<f32>(0.0, h, 0.0)) - sampleField(levels, side, p - vec3<f32>(0.0, h, 0.0));
+  let dz = sampleField(levels, side, p + vec3<f32>(0.0, 0.0, h)) - sampleField(levels, side, p - vec3<f32>(0.0, 0.0, h));
+  let g = vec3<f32>(dx, dy, dz);
+  let length2 = dot(g, g);
+  return select(vec3<f32>(0.0, 1.0, 0.0), g * inverseSqrt(length2), length2 > 1e-12);
+}
+
+/** Whether a point is still inside the outermost cascade, which is all the field knows about. */
+fn withinField(levels: u32, p: vec3<f32>) -> bool {
+  let base = (levels - 1u) * 8u;
+  let low = vec3<f32>(cascades[base], cascades[base + 1u], cascades[base + 2u]);
+  let high = vec3<f32>(cascades[base + 3u], cascades[base + 4u], cascades[base + 5u]);
+  return all(p >= low) && all(p <= high);
+}
+
+@fragment
+fn fragmentMain(vary: Varying) -> @location(0) vec4<f32> {
+  let levels = u32(params[${MARCH_LEVELS}]);
+  let side = u32(params[${MARCH_SIDE}]);
+  let steps = u32(params[${MARCH_STEPS}]);
+  let epsilon = params[${MARCH_EPSILON}];
+  let eye = vec3<f32>(
+    params[${MARCH_EYE}],
+    params[${MARCH_EYE} + 1u],
+    params[${MARCH_EYE} + 2u],
+  );
+
+  let ndc = vec2<f32>(vary.uv.x * 2.0 - 1.0, 1.0 - vary.uv.y * 2.0);
+  let direction = normalize(unproject(ndc) - eye);
+
+  /* The finest cascade's step, which is the smallest move worth making. */
+  let floorStep = cascades[6] * 0.25;
+  var travelled = 0.0;
+  var hit = false;
+  var at = eye;
+  for (var i = 0u; i < steps; i = i + 1u) {
+    at = eye + direction * travelled;
+    if (!withinField(levels, at)) {
+      break;
+    }
+    let distance = sampleField(levels, side, at);
+    if (distance <= epsilon) {
+      hit = true;
+      break;
+    }
+    travelled = travelled + max(distance, floorStep);
+  }
+
+  if (!hit) {
+    /* Nothing here, so the frame keeps whatever drew before this. */
+    discard;
+  }
+
+  let normal = normalAt(levels, side, at, cascades[6] * 0.5);
+  let sun = normalize(vec3<f32>(0.4, 0.8, 0.45));
+  let lambert = max(dot(normal, sun), 0.0);
+  /* A hemispheric fill under it, so a face turned away is readable rather than black. */
+  let ambient = 0.18 + 0.12 * (normal.y * 0.5 + 0.5);
+  let shade = vec3<f32>(0.62, 0.66, 0.72) * (lambert * 0.85 + ambient);
+  return vec4<f32>(shade, 1.0);
+}
+`;

package/dist/render/shaders/gi/probeBake.wgsl.d.ts

@@ -0,0 +1,113 @@
+/**
+ * A probe's own bake, on the device: trace a sphere of rays, convolve them into an octahedral map.
+ *
+ * **Two dispatches rather than one, and the split is what makes it affordable.** A probe's texel
+ * is a cosine-weighted sum over every direction, so one invocation a texel that also traced would
+ * trace the same `PROBE_DIRECTIONS` rays once per texel — 256 rays becoming 256 × edge², which for
+ * an edge of 16 is sixty-five thousand marches for a probe that needs 256. So `traceMain` casts
+ * the rays once and writes them down, and `convolveMain` reads them back.
+ *
+ * **The octahedral mapping is a third spelling and that is a hazard this file states rather than
+ * hides.** `octahedral.ts` holds it in TypeScript and in GLSL; this is WGSL, because a hand-written
+ * compute shader cannot include the generated one. `scripts/probe-bake-parity.mjs` is what holds
+ * the three together, over the texels and the directions both.
+ *
+ * **A probe's normal is its ray's own direction, which is right here and wrong on a surface.**
+ * `probeTraceField` lifts the start along the normal to keep a ray from immediately hitting the
+ * surface it left, and its header says lifting along the ray as well double-counts — for a *surface*
+ * sample, where the normal and the ray are different things. A probe stands in open space and has
+ * no surface and no normal, so the only thing to lift along is the ray, and what it buys is a probe
+ * that has come to rest inside a wall casting rays that leave it rather than all reporting a hit at
+ * zero distance.
+ *
+ * The accessors an including module must define, before including the core, are `probeIndirect`'s
+ * — see `probeTrace.wgsl.ts` — plus `bake: ProbeBake` as a uniform.
+ */
+/**
+ * Floats in the bake block, and where each field of it starts.
+ *
+ * **A `vec3<f32>` is sixteen-byte *aligned* and twelve bytes *long*, and an `f32` after one fills
+ * the gap rather than starting a new row.** So `counts` occupies floats 8 to 10 and `edge` is float
+ * **11**, not 12 — which cost an afternoon: written at 12, the shader read `edge` as `frame` and
+ * every direction came back rotated by the difference, at exactly the right radius. The radius
+ * matching is what said it was the angle and not the set.
+ *
+ * Exported as named offsets for that reason. A caller that counts rows gets this wrong; a caller
+ * that names the field cannot.
+ */
+export declare const BAKE_ORIGIN = 0;
+export declare const BAKE_SPACING = 4;
+export declare const BAKE_COUNTS = 8;
+export declare const BAKE_EDGE = 11;
+export declare const BAKE_FRAME = 12;
+export declare const BAKE_SCHEDULED = 13;
+/** The sun, which the trace evaluates itself so a light that moves changes the bounce. */
+export declare const BAKE_SUN_DIR = 16;
+export declare const BAKE_SUN_COLOUR = 20;
+/** What a ray that left the world finds. The frame's ambient, so nothing rasterised is read. */
+export declare const BAKE_SKY_COLOUR = 24;
+/** Rounded up to the struct's own sixteen-byte alignment, with two vec3 rows for the sun. */
+export declare const PROBE_BAKE_FLOATS = 28;
+/** Invocations a workgroup, for both entry points. 64 is this backend's default everywhere. */
+export declare const PROBE_BAKE_WORKGROUP = 64;
+/** Floats a ray's radiance takes in the intermediate buffer. */
+export declare const PROBE_RAY_FLOATS = 3;
+/** Floats a baked texel takes. Three and not four: the alpha of an irradiance map means nothing. */
+export declare const PROBE_TEXEL_FLOATS = 3;
+export declare const PROBE_BAKE_STRUCT_WGSL = "\nstruct ProbeBake {\n  /* Where the grid's first probe stands, and how far apart they are. */\n  origin: vec3<f32>,\n  spacing: vec3<f32>,\n  /* How many probes along each axis. Whole numbers carried as floats, as every block here does. */\n  counts: vec3<f32>,\n  /* Texels across one probe's map, gutter included. */\n  edge: f32,\n  /* Which frame this is, which turns the direction set so a probe converges rather than repeats. */\n  frame: f32,\n  /* How many probes this dispatch bakes. The schedule says which. */\n  scheduled: f32,\n  pad: f32,\n  /* Towards the sun, and what colour it is. The trace shades what it hits rather than reading a\n     capture, which is what lets a bounce follow a light that moved. */\n  sunDir: vec3<f32>,\n  sunColour: vec3<f32>,\n  /* And what is outside, for a ray that left. See probeDistantRadiance. */\n  skyColour: vec3<f32>,\n}\n";
+/**
+ * The octahedral mapping and the probe lattice, as text.
+ *
+ * Defines `bakeOctInsetDir(u, v, edge)` and `bakeProbePosition(layer)`.
+ */
+export declare const PROBE_BAKE_CORE_WGSL: string;
+/**
+ * The parity module: the bake over plain buffers, with a radiance that is a function of position.
+ *
+ * **The radiance is positional for the reason `probeTraceParityWgsl` gives**: a march that landed a
+ * voxel from where the reference landed would return almost the right answer from a smooth field
+ * and exactly the right one from a constant, so a constant would check the convolution and nothing
+ * about the trace.
+ *
+ * What this check is *for*, over and above `indirect-parity.mjs`, is the three pieces of arithmetic
+ * that only exist in this file: the octahedral texel-to-direction fold, the layer-to-position
+ * lattice, and the Fibonacci direction set. Each is a second spelling of something `octahedral.ts`,
+ * `probeGrid.ts` and `probeTrace.ts` already hold, and a second spelling is what this repository
+ * has learned to check rather than trust.
+ */
+export declare function probeBakeParityWgsl(): string;
+/**
+ * The production module: the same core, reading the renderer's composed field and probe array.
+ *
+ * **`probeRadianceAt` is the probe volume here and a sine of position in the parity module**, which
+ * is the whole reason the core takes it as an accessor. A probe traced against radiance that is
+ * itself probe radiance converges on several bounces over a few refreshes — the maintainer's answer
+ * of 2026-09-17 — and that is a property of what is bound rather than of the arithmetic.
+ *
+ * **The probe array is sampled while a later pass writes a mip of it, and that is legal.** WebGPU
+ * forbids a texture being read and written inside one pass, not across two on one encoder: the
+ * dispatches here read the array as it stood, and the blit that follows writes the levels the next
+ * frame's dispatches will read. What that costs is a frame of latency in the bounce, which is what
+ * a probe volume has anyway because it accumulates.
+ */
+export declare function probeBakeWgsl(): string;
+/** Bytes between one blit's parameters and the next. A dynamic offset must be 256-aligned. */
+export declare const PROBE_BLIT_STRIDE = 256;
+/** Floats a blit's parameters hold: the slot, the map's edge, and the target level's edge. */
+export declare const PROBE_BLIT_FLOATS = 4;
+/**
+ * Carrying a baked map into the probe array the shading already samples.
+ *
+ * **A render pass rather than a storage write, because the probe array is not a storage texture.**
+ * It is created with `RENDER_ATTACHMENT | TEXTURE_BINDING` and its format is the surface's, which
+ * needs a device feature before it can be written from compute. Rendering into one mip of one layer
+ * needs neither, and the array already carries the usage for it.
+ *
+ * **The target edge is a parameter because not every level is the irradiance level.** A layer the
+ * scene has never rasterised holds undefined contents in its roughness chain, and a fragment
+ * sampling that is worse than a fragment sampling a flat colour. So a layer being filled for the
+ * first time has every level written from the same map — blocky at level 0, which is the honest
+ * thing a diffuse solution can say about a mirror — and every frame after that writes only the
+ * irradiance level.
+ */
+export declare const PROBE_BLIT_WGSL: string;