@driftengine/core 3.63.0 → 4.0.0

package/src/render/shaders/gi/probeTrace.wgsl.ts

@@ -0,0 +1,269 @@
+/**
+ * A probe's own rays, on the device: `gi/chain.ts` minus its screen level.
+ *
+ * **A probe has no use for screen space, and including it would be a defect rather than a cost.**
+ * The screen level is an accelerator for rays cast from the camera's own view, where the frame
+ * already holds the answer. A probe stands in the world and its rays go everywhere, so most of them
+ * leave the frame — and the few that do not would make a *cached* probe depend on where the camera
+ * happens to be, so a probe would change its contents as the viewer turned and every surface it
+ * lights would shimmer. So the chain is entered with a projector that answers "off screen" for
+ * every point, which makes level 0 contribute exactly nothing and levels 1 and 2 take the whole
+ * ray. The reference stays one function; this is that function with one input pinned.
+ *
+ * **What a field hit is worth comes from the probes**, which is the maintainer's answer of
+ * 2026-09-17 and the reason `GiResources.fieldRadiance` is a function rather than a texture: a
+ * probe traced against radiance that is itself probe radiance converges on several bounces over a
+ * few refreshes. The direction it is read along is back down the ray — the light leaving that
+ * surface *towards* the probe is what the probe is measuring — which the chain's own signature
+ * leaves to the caller because it takes no direction.
+ *
+ * **One core, two modules**, as `shaders/recon/resolve.wgsl.ts` and `network.wgsl.ts` are. The
+ * arithmetic reads the field and the probes through functions the including module defines, so the
+ * production module can read the renderer's own buffers and the parity check can read plain ones of
+ * the same numbers.
+ *
+ * The accessors an including module must define, before including the core:
+ *
+ * ```wgsl
+ * fn probeFieldAt(p: vec3<f32>) -> f32          // the composed field's distance at a world point
+ * fn probeFieldInside(p: vec3<f32>) -> f32      // how far inside the outermost cascade, negative outside
+ * fn probeSurfaceRadiance(p: vec3<f32>, towards: vec3<f32>) -> vec3<f32>
+ * fn probeDistantRadiance(p: vec3<f32>, towards: vec3<f32>) -> vec3<f32>
+ * ```
+ *
+ * **Two, and it used to be one.** A ray that struck a wall and a ray that left the world need
+ * different answers and the single accessor could not tell them apart: what leaves a wall is its
+ * albedo times the light reaching it, and what a ray finds having left is whatever the probe
+ * volume coarsely says is out there. Measured with one accessor, a red wall and a white wall
+ * returned the same colour — `demo/dev/bounce.html`, and `plans/2026-09-17-indirect-light.md`
+ * Task 8.
+ *
+ * and `march: ProbeMarch` as a uniform.
+ */
+
+import { GLOBAL_FIELD_BLEND } from '../../gi/globalField.ts';
+import { FIELD_MARCH, FIELD_START_VOXELS } from '../../gi/traceField.ts';
+import { SAMPLE_FIELD_WGSL } from './sampleField.wgsl.ts';
+
+/**
+ * Floats in the march block, which is sixteen because of how a uniform aligns rather than how many
+ * numbers it holds: four counts, four lengths, and two `vec3`s that each take a whole four-float row.
+ */
+export const PROBE_MARCH_FLOATS = 16;
+
+/** The workgroup a trace dispatches over: one invocation a direction. */
+export const PROBE_TRACE_WORKGROUP = 64;
+
+/** A number as WGSL always reads it as a float, so an integer constant is not an `i32`. */
+function f(value: number): string {
+  return Number.isInteger(value) ? value.toFixed(1) : String(value);
+}
+
+export const PROBE_MARCH_WGSL = /* wgsl */ `
+struct ProbeMarch {
+  /* Steps a ray may take, the cascades it may read, and how many samples a cascade is a side. */
+  steps: u32,
+  levels: u32,
+  side: u32,
+  rayCount: u32,
+  /* How far a ray may travel, how close to a surface counts as arriving, the finest voxel. */
+  reachM: f32,
+  hitEpsilonM: f32,
+  finestStep: f32,
+  coneAngle: f32,
+  /* The outermost cascade's corners, for the confidence the last level is faded by. */
+  outerLow: vec3<f32>,
+  outerHigh: vec3<f32>,
+}
+`;
+
+/**
+ * The march and the two levels, as text.
+ *
+ * Defines `probeIndirect(point, normal, direction, coneAngle) -> vec3<f32>`, which is what one of a
+ * probe's rays is worth.
+ */
+export const PROBE_TRACE_CORE_WGSL = /* wgsl */ `
+const PROBE_FIELD_START_VOXELS: f32 = ${f(FIELD_START_VOXELS)};
+const PROBE_FIELD_BLEND: f32 = ${f(GLOBAL_FIELD_BLEND)};
+
+struct ProbeFieldHit {
+  hit: bool,
+  point: vec3<f32>,
+}
+
+/* A cone's radius at a distance. Zero angle is a ray, which is what a probe's rays are. */
+fn probeConeRadius(distanceM: f32, coneAngle: f32) -> f32 {
+  return select(0.0, distanceM * tan(coneAngle), coneAngle > 0.0);
+}
+
+/*
+ * March one ray through the composed world field.
+ *
+ * **Lifted along the normal and only along the normal.** Pushing the start along the ray as well
+ * double-counts: a ray leaving along its own normal would begin two offsets out and every distance
+ * it reported would carry the second one. And it does not help the case that needs help — a tangent
+ * ray pushed along itself is still on the surface, because a surface is what tangent means.
+ */
+fn probeTraceField(
+  point: vec3<f32>,
+  normal: vec3<f32>,
+  direction: vec3<f32>,
+  coneAngle: f32,
+) -> ProbeFieldHit {
+  var out: ProbeFieldHit;
+  out.hit = false;
+  out.point = point;
+
+  /* Not named "length": a local of that name shadows the built-in and the next call to it fails. */
+  let reach = length(direction);
+  if (!(reach > 0.0)) { return out; }
+  let unit = direction / reach;
+
+  let start = PROBE_FIELD_START_VOXELS * march.finestStep;
+  let normalLength = length(normal);
+  let lifted = point + select(vec3<f32>(0.0), normal * (start / normalLength), normalLength > 0.0);
+
+  var travelled = 0.0;
+  for (var step = 0u; step < march.steps; step = step + 1u) {
+    let at = lifted + unit * travelled;
+    /*
+     * **Outside the outermost cascade the march stops rather than sampling.** There is no
+     * information out there: the sampler clamps to the edge, which is right for a sample and wrong
+     * for a march — stepping on clamped values converges on the cascade's boundary and reports a
+     * surface made of nothing.
+     */
+    if (probeFieldInside(at) <= 0.0) { return out; }
+
+    let distance = probeFieldAt(at);
+    if (distance <= probeConeRadius(travelled, coneAngle) + march.hitEpsilonM) {
+      out.hit = true;
+      out.point = at;
+      return out;
+    }
+    /*
+     * **Step by the distance, and by at least a quarter of a voxel.** A field whose value is
+     * genuinely tiny beside a surface the cone is not wide enough to accept would otherwise take
+     * ever-smaller steps and spend the whole budget arriving nowhere, which reads as a miss and
+     * costs a fallback anyway. The floor makes that case terminate quickly instead.
+     */
+    travelled = travelled + max(distance, march.finestStep * 0.25);
+    if (travelled > march.reachM) { return out; }
+  }
+  return out;
+}
+
+/*
+ * How much of a field hit is trusted, faded across the outer tenth of the outermost cascade.
+ *
+ * Every boundary in this chain moves with the camera — the cascades are centred on it — and a hard
+ * switch at a boundary that moves is a seam sweeping through the picture whenever the camera turns.
+ */
+fn probeFieldConfidence(p: vec3<f32>) -> f32 {
+  let band = PROBE_FIELD_BLEND * (march.outerHigh.x - march.outerLow.x);
+  if (band <= 0.0) { return 1.0; }
+  let gap = min(p - march.outerLow, march.outerHigh - p);
+  return clamp(min(gap.x, min(gap.y, gap.z)) / band, 0.0, 1.0);
+}
+
+/*
+ * One of a probe's rays, as radiance.
+ *
+ * Level 1 answers as much as its distance from the outermost cascade's face allows; level 2 takes
+ * whatever is left without asking, which is what "never wrong and only ever coarse" buys. There is
+ * no case where the probes decline, and no fourth level to fall to.
+ */
+fn probeIndirect(
+  point: vec3<f32>,
+  normal: vec3<f32>,
+  direction: vec3<f32>,
+  coneAngle: f32,
+) -> vec3<f32> {
+  var radiance = vec3<f32>(0.0);
+  var fieldShare = 0.0;
+
+  let hit = probeTraceField(point, normal, direction, coneAngle);
+  if (hit.hit) {
+    fieldShare = probeFieldConfidence(hit.point);
+    if (fieldShare > 0.0) {
+      /* Back down the ray: what this surface sends *towards* the probe is what the probe measures. */
+      radiance = radiance + probeSurfaceRadiance(hit.point, -direction) * fieldShare;
+    }
+  }
+
+  let probes = 1.0 - fieldShare;
+  if (probes > 0.0) {
+    radiance = radiance + probeDistantRadiance(point + direction * march.reachM, -direction) * probes;
+  }
+  return radiance;
+}
+`;
+
+/** `FIELD_MARCH`'s own numbers, so a caller fills the block from one place. */
+export const PROBE_MARCH_DEFAULTS = FIELD_MARCH;
+
+/**
+ * The parity module: the core over plain buffers, with a radiance that is a function of position.
+ *
+ * **The radiance is positional on purpose.** A march that lands a voxel away 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 radiance would check the *blend* and nothing about the march.
+ * A steep function of the hit's position turns a wrong hit into a wrong colour.
+ *
+ * `probeRadianceAt` is an accessor by design, so this check is of the march and the level blend
+ * alone; what a probe volume answers is the production module's business and `probeVolume.test.ts`
+ * is what holds that.
+ */
+export function probeTraceParityWgsl(): string {
+  return /* wgsl */ `
+@group(0) @binding(0) var<storage, read> cascades: array<f32>;
+@group(0) @binding(1) var<storage, read> fields: array<f32>;
+${PROBE_MARCH_WGSL}
+@group(0) @binding(2) var<uniform> march: ProbeMarch;
+/* Seven floats a ray: the point, the normal, the direction. The cone angle is the march's. */
+@group(0) @binding(3) var<storage, read> rays: array<f32>;
+@group(0) @binding(4) var<storage, read_write> radiance: array<f32>;
+${SAMPLE_FIELD_WGSL}
+
+fn probeFieldAt(p: vec3<f32>) -> f32 {
+  return sampleField(march.levels, march.side, p);
+}
+
+fn probeFieldInside(p: vec3<f32>) -> f32 {
+  return insideBy(march.levels - 1u, p);
+}
+
+/* The same expression the harness evaluates, and the reason it is a sine of position. */
+fn probeParityRadiance(p: vec3<f32>) -> vec3<f32> {
+  return vec3<f32>(
+    0.5 + 0.4 * sin(p.x * 1.3),
+    0.5 + 0.4 * sin(p.y * 1.7 + 1.0),
+    0.5 + 0.4 * sin(p.z * 2.3 + 2.0),
+  );
+}
+
+/* One expression for both, so this module keeps checking the march and the blend and nothing else. */
+fn probeSurfaceRadiance(p: vec3<f32>, towards: vec3<f32>) -> vec3<f32> {
+  return probeParityRadiance(p);
+}
+
+fn probeDistantRadiance(p: vec3<f32>, towards: vec3<f32>) -> vec3<f32> {
+  return probeParityRadiance(p);
+}
+${PROBE_TRACE_CORE_WGSL}
+
+@compute @workgroup_size(${PROBE_TRACE_WORKGROUP})
+fn traceMain(@builtin(global_invocation_id) id: vec3<u32>) {
+  if (id.x >= march.rayCount) { return; }
+  let at = id.x * 9u;
+  let point = vec3<f32>(rays[at], rays[at + 1u], rays[at + 2u]);
+  let normal = vec3<f32>(rays[at + 3u], rays[at + 4u], rays[at + 5u]);
+  let direction = vec3<f32>(rays[at + 6u], rays[at + 7u], rays[at + 8u]);
+  let value = probeIndirect(point, normal, direction, march.coneAngle);
+  let out = id.x * 3u;
+  radiance[out] = value.x;
+  radiance[out + 1u] = value.y;
+  radiance[out + 2u] = value.z;
+}
+`;
+}

package/src/render/shaders/gi/probeVolume.wgsl.ts

@@ -0,0 +1,246 @@
+/**
+ * What the probe grid answers at a world point, on the device.
+ *
+ * **This is the fourth spelling of one idea and the file says so rather than hoping.**
+ * `probeGrid.ts` holds the eight-probe trilinear blend in TypeScript, `octahedral.ts` holds the
+ * mapping in TypeScript and again in GLSL, and `shaders/flat/probeGrid.ts` holds both together in
+ * the GLSL the lit pass uses. This is WGSL, because a hand-written compute shader cannot include a
+ * generated one — and `scripts/probe-bake-parity.mjs` is what holds it to the others rather than
+ * a reader's confidence that four copies of an expression say the same thing.
+ *
+ * **Why a probe reads the grid at all**: the maintainer's answer of 2026-09-17 is that what a field
+ * hit is worth comes from the probes, so a probe traced against radiance that is itself probe
+ * radiance converges on several bounces over a few refreshes. That is what makes this the multi-
+ * bounce half of Wave 4A rather than a single-bounce approximation of it.
+ *
+ * **No visibility term here, deliberately.** `visibleProbes` exists to stop light reaching a
+ * *surface* through a wall it is behind, and it is what `gridIrradiance` applies when shading. A
+ * probe asking "what is the radiance out there" is a different question with a different failure:
+ * crushing a blind probe's weight would make the bounce darker than the room, and the reference
+ * this is checked against — `indirect-parity.mjs` — enters the chain with `visibility: null` for
+ * exactly this reason.
+ *
+ * The accessor an including module must define, before including the core:
+ *
+ * ```wgsl
+ * fn probeLayerSample(layer: u32, uv: vec2<f32>) -> vec3<f32>       // at the radiance level
+ * fn probeLayerIrradiance(layer: u32, uv: vec2<f32>) -> vec3<f32>   // at the irradiance level
+ * ```
+ *
+ * and `volume: ProbeVolume` as a uniform. Production samples a texture; the parity module reads a
+ * plain buffer of the same numbers.
+ */
+
+/**
+ * Floats in the volume block, and where each field starts.
+ *
+ * Named offsets for the reason `probeBake.wgsl.ts` gives and paid for: an `f32` after a `vec3<f32>`
+ * fills the vec3's padding rather than starting a new row, so `edge` is float **11**.
+ */
+export const VOLUME_ORIGIN = 0;
+export const VOLUME_INV_SPACING = 4;
+export const VOLUME_COUNTS = 8;
+export const VOLUME_EDGE = 11;
+export const VOLUME_LEVEL = 12;
+export const VOLUME_RADIANCE_EDGE = 13;
+export const VOLUME_RADIANCE_LEVEL = 14;
+
+/** Fifty-two bytes of fields rounded up to the struct's own sixteen-byte alignment. */
+export const PROBE_VOLUME_FLOATS = 16;
+
+export const PROBE_VOLUME_STRUCT_WGSL = /* wgsl */ `
+struct ProbeVolume {
+  /* Where the grid's first probe stands, and one over the step between them. */
+  origin: vec3<f32>,
+  invSpacing: vec3<f32>,
+  /* How many probes along each axis. Whole numbers carried as floats. */
+  counts: vec3<f32>,
+  /* Texels across the level being sampled, gutter included. */
+  edge: f32,
+  /* Which mip of the probe array that level is. */
+  level: f32,
+  /* And the level that holds *radiance* rather than irradiance, with its own edge. */
+  radianceEdge: f32,
+  radianceLevel: f32,
+  padA: f32,
+}
+`;
+
+export const PROBE_VOLUME_CORE_WGSL = /* wgsl */ `
+/* The octahedral encode, matching "octEncode" in "shaders/octahedral.ts". */
+fn probeOctEncode(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 = (1.0 - abs(vec2<f32>(n.y, n.x))) *
+      vec2<f32>(select(-1.0, 1.0, n.x >= 0.0), select(-1.0, 1.0, n.y >= 0.0));
+  }
+  return p * 0.5 + 0.5;
+}
+
+/*
+ * Where to sample a direction in a map whose outer ring is a gutter.
+ *
+ * The inner region is "edge - 2" texels offset by one, so a direction at the very border of the
+ * octahedral square lands on the last real texel and the tap that interpolates past it reads the
+ * gutter — which the bake filled with the folded direction.
+ */
+fn probeOctInsetUv(d: vec3<f32>, edge: f32) -> vec2<f32> {
+  return (probeOctEncode(d) * (edge - 2.0) + 1.0) / edge;
+}
+
+/*
+ * One axis of the lookup: which probe is below the point, and how far past it the point is.
+ *
+ * **The index is integer arithmetic and the fraction is not**, which is the distinction row 139 of
+ * the resume file is about. A world position divided by a spacing is a genuine float division and
+ * its floor is a genuine floor; what must never be written in floats is a *lattice* — an index
+ * decomposed out of a layer number — because a device may implement that division as a
+ * multiplication by a reciprocal and answer 3 for 3.0 % 3.0.
+ *
+ * The lower index stops one short of the last probe so the pair "index" and "index + 1" is always
+ * inside the grid, and a single-probe axis has no pair at all — both corners are probe zero and
+ * the fraction is zero, so that axis multiplies every weight by one.
+ */
+struct ProbeCell {
+  index: u32,
+  fraction: f32,
+}
+
+fn probeCell(value: f32, origin: f32, invSpacing: f32, count: u32) -> ProbeCell {
+  var out: ProbeCell;
+  out.index = 0u;
+  out.fraction = 0.0;
+  if (count <= 1u) { return out; }
+  let local = (value - origin) * invSpacing;
+  let span = f32(count - 1u);
+  let clamped = clamp(local, 0.0, span);
+  let index = min(u32(floor(clamped)), count - 2u);
+  out.index = index;
+  out.fraction = clamped - f32(index);
+  return out;
+}
+
+/*
+ * The layer a probe at whole lattice coordinates occupies. x fastest, then y, then z.
+ *
+ * **Not clamped, and "ProbeGrid.layerAt" is** — the difference is who may call them. "layerAt" is a
+ * public method whose contract is that it accepts anything, so it clamps; this is reached from one
+ * place, under two guarantees that together make the clamp unreachable. "probeCell" returns an
+ * index no greater than "count - 2", so "index + 1" is inside; and on an axis only one probe wide
+ * it returns index 0 with fraction 0, so the far corner's weight is zero and the caller skips it
+ * before asking. A clamp here would be a line no perturbation can make fail, which this session
+ * has already had to remove twice.
+ */
+fn probeLayerAt(ix: u32, iy: u32, iz: u32, counts: vec3<u32>) -> u32 {
+  return ix + counts.x * (iy + counts.y * iz);
+}
+
+/*
+ * What has already bounced onto a surface facing the normal at a point, from the level this writes.
+ *
+ * **One shared direction, and that is right here where a per-corner one is right for radiance.**
+ * An irradiance map is indexed by the *normal of the surface being lit*, not by where the light
+ * came from, so every probe is asked the same question: what reaches a surface facing this way.
+ * Reading it at the level the bake writes is what closes the loop — the second bounce is the first
+ * one read back.
+ */
+fn probeVolumeIrradianceAt(p: vec3<f32>, n: vec3<f32>) -> vec3<f32> {
+  let counts = vec3<u32>(
+    max(1u, u32(volume.counts.x)),
+    max(1u, u32(volume.counts.y)),
+    max(1u, u32(volume.counts.z)),
+  );
+  let cx = probeCell(p.x, volume.origin.x, volume.invSpacing.x, counts.x);
+  let cy = probeCell(p.y, volume.origin.y, volume.invSpacing.y, counts.y);
+  let cz = probeCell(p.z, volume.origin.z, volume.invSpacing.z, counts.z);
+  let uv = probeOctInsetUv(n, volume.edge);
+
+  var sum = vec3<f32>(0.0);
+  for (var oz = 0u; oz < 2u; oz = oz + 1u) {
+    let wz = select(1.0 - cz.fraction, cz.fraction, oz == 1u);
+    for (var oy = 0u; oy < 2u; oy = oy + 1u) {
+      let wy = select(1.0 - cy.fraction, cy.fraction, oy == 1u);
+      for (var ox = 0u; ox < 2u; ox = ox + 1u) {
+        let wx = select(1.0 - cx.fraction, cx.fraction, ox == 1u);
+        let weight = wx * wy * wz;
+        if (weight <= 0.0) { continue; }
+        let layer = probeLayerAt(cx.index + ox, cy.index + oy, cz.index + oz, counts);
+        sum = sum + probeLayerIrradiance(layer, uv) * weight;
+      }
+    }
+  }
+  return sum;
+}
+
+/* Where a layer's probe stands, which a parallax read needs and the lattice above decides. */
+fn probeVolumeProbeAt(layer: u32, counts: vec3<u32>) -> vec3<f32> {
+  let x = layer % counts.x;
+  let y = (layer / counts.x) % counts.y;
+  let z = layer / (counts.x * counts.y);
+  let spacing = vec3<f32>(
+    select(0.0, 1.0 / volume.invSpacing.x, volume.invSpacing.x != 0.0),
+    select(0.0, 1.0 / volume.invSpacing.y, volume.invSpacing.y != 0.0),
+    select(0.0, 1.0 / volume.invSpacing.z, volume.invSpacing.z != 0.0),
+  );
+  return volume.origin + vec3<f32>(f32(x), f32(y), f32(z)) * spacing;
+}
+
+/*
+ * The radiance leaving a world point, as the grid saw it.
+ *
+ * **A ray needs radiance and the first version read irradiance**, which is what
+ * "demo/dev/bounce.html" measured as a bounce dimmer and greyer than the rasterised grid it was
+ * meant to replace. Irradiance is light *arriving* at a point, already cosine-convolved over a
+ * hemisphere; what a ray that struck a wall needs is the light *leaving* that wall towards it. The
+ * two differ by the surface's albedo — so a red wall and a white wall at the same irradiance
+ * returned the same colour, and the red never travelled.
+ *
+ * **Level 0 of the probe array is that radiance**, and it needs no albedo because it is a
+ * rasterised capture of the shaded room: the red wall is red in it. §6.4 of the design names
+ * "envProbeArray.ts" as this track's starting point and leaves how much of it to reuse to
+ * measurement, which is this.
+ *
+ * **Each corner is read along its own direction to the point**, which is what makes this a
+ * position lookup rather than a direction one. Eight probes sampled along one shared direction
+ * answer "what is over there from roughly here"; eight probes each sampled towards "p" answer
+ * "what is at "p"", and the difference is the parallax that a marched hit exists to provide. It is
+ * also why no direction is passed in: deriving it removes the reversed-direction mistake that
+ * "probe-bake-parity.mjs" records being unable to see.
+ */
+fn probeVolumeRadianceAt(p: vec3<f32>) -> vec3<f32> {
+  let counts = vec3<u32>(
+    max(1u, u32(volume.counts.x)),
+    max(1u, u32(volume.counts.y)),
+    max(1u, u32(volume.counts.z)),
+  );
+  let cx = probeCell(p.x, volume.origin.x, volume.invSpacing.x, counts.x);
+  let cy = probeCell(p.y, volume.origin.y, volume.invSpacing.y, counts.y);
+  let cz = probeCell(p.z, volume.origin.z, volume.invSpacing.z, counts.z);
+
+  var sum = vec3<f32>(0.0);
+  for (var oz = 0u; oz < 2u; oz = oz + 1u) {
+    let wz = select(1.0 - cz.fraction, cz.fraction, oz == 1u);
+    for (var oy = 0u; oy < 2u; oy = oy + 1u) {
+      let wy = select(1.0 - cy.fraction, cy.fraction, oy == 1u);
+      for (var ox = 0u; ox < 2u; ox = ox + 1u) {
+        let wx = select(1.0 - cx.fraction, cx.fraction, ox == 1u);
+        let weight = wx * wy * wz;
+        if (weight <= 0.0) { continue; }
+        let layer = probeLayerAt(cx.index + ox, cy.index + oy, cz.index + oz, counts);
+        /*
+         * From that probe towards the point, which is the parallax. A probe standing exactly on
+         * the point has no direction to offer and takes its own zeroth texel, which is as good an
+         * answer as exists for a point inside a probe.
+         */
+        let offset = p - probeVolumeProbeAt(layer, counts);
+        let reach = length(offset);
+        let towards = select(vec3<f32>(0.0, 0.0, 1.0), offset / reach, reach > 0.0);
+        let uv = probeOctInsetUv(towards, volume.radianceEdge);
+        sum = sum + probeLayerSample(layer, uv) * weight;
+      }
+    }
+  }
+  return sum;
+}
+`;

package/src/render/shaders/gi/sampleField.wgsl.ts

@@ -0,0 +1,140 @@
+/** Reading the composed field on the device, the way `sampleGlobalField` reads it on the CPU. */
+
+import { GLOBAL_FIELD_BLEND } from '../../gi/globalField.ts';
+
+/**
+ * **One function, included by everything that reads the field, because two spellings drift.**
+ *
+ * `globalField.ts`'s `sampleGlobalField` is the reference: the finest cascade that holds a point
+ * answers, faded into the one outside it across the outer tenth of its extent, and a point past
+ * every cascade takes the outermost clamped at its edge. Every one of those three is a decision a
+ * second implementation would get subtly differently, so this is text rather than a copy — the
+ * march includes it, the parity entry point below includes it, and anything else that needs the
+ * field includes it too.
+ *
+ * **`GLOBAL_FIELD_BLEND` is interpolated in rather than restated**, which is the 2026-08-13 rule
+ * about one number in one place: a fade that is a tenth here and a twelfth there is a seam that
+ * moves with the camera and nothing in either file looks wrong.
+ */
+
+/** Floats a cascade in the `cascades` buffer: six bounds, the step, and a pad to keep it aligned. */
+export const CASCADE_FLOATS = 8;
+
+/**
+ * The sampler, as WGSL text to include.
+ *
+ * Expects `cascades: array<f32>` and `fields: array<f32>` in scope, and takes the cascade count and
+ * the samples a side as arguments rather than reading them from a third buffer — a function that
+ * reads a global it was not given is one that cannot be moved.
+ */
+export const SAMPLE_FIELD_WGSL = /* wgsl */ `
+/* Trilinear read of one cascade, clamped at its own edge. The layout is x fastest, then y, then z. */
+fn cascadeAt(level: u32, side: u32, p: vec3<f32>) -> f32 {
+  let base = level * ${CASCADE_FLOATS}u;
+  let low = vec3<f32>(cascades[base], cascades[base + 1u], cascades[base + 2u]);
+  let step = cascades[base + 6u];
+  let count = f32(side);
+
+  var corner = 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 local = (p[axis] - low[axis]) / step;
+    let clamped = clamp(local, 0.0, count - 1.0);
+    /*
+     * **The same line guards different things on the two sides, and only one of them shows.**
+     * Stopping one plane short keeps the pair this interpolates between inside the cascade. Drop it
+     * and the corner at count carries weight zero, so the *value* is identical here — WGSL clamps
+     * an out-of-range storage read and zero times anything is zero — while the TypeScript reads
+     * \`undefined\` out of a \`Float32Array\` past its end and \`undefined * 0\` is NaN. Perturbing it
+     * fails \`globalField.test.ts\` and passes \`gi-parity.mjs\`. It stays because it is what keeps
+     * the read inside this cascade rather than in the next one's samples, which share the buffer.
+     */
+    let index = min(floor(clamped), count - 2.0);
+    corner[axis] = index;
+    frac[axis] = clamped - index;
+  }
+
+  let offset = level * side * side * side;
+  let lx = u32(corner.x);
+  let ly = u32(corner.y);
+  let lz = u32(corner.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 + side * (ly + cy + side * (lz + cz));
+        total = total + fields[offset + at] * wx * wy * wz;
+      }
+    }
+  }
+  return total;
+}
+
+/* How far inside a cascade a point is, measured to the nearest face. Negative means outside. */
+fn insideBy(level: u32, p: vec3<f32>) -> f32 {
+  let base = level * ${CASCADE_FLOATS}u;
+  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]);
+  let gap = min(p - low, high - p);
+  return min(gap.x, min(gap.y, gap.z));
+}
+
+/*
+ * The field at a world point, from the finest cascade that holds it.
+ *
+ * Faded into the cascade outside across the outer tenth of the extent, because every boundary here
+ * moves with the camera — the cascades are centred on it — and a hard switch at a boundary that
+ * moves is a seam sweeping through the picture whenever the camera turns.
+ */
+fn sampleField(levels: u32, side: u32, p: vec3<f32>) -> f32 {
+  let last = levels - 1u;
+  for (var level = 0u; level <= last; level = level + 1u) {
+    let inside = insideBy(level, p);
+    if (inside <= 0.0) {
+      continue;
+    }
+    let value = cascadeAt(level, side, p);
+    if (level == last) {
+      return value;
+    }
+    let base = level * ${CASCADE_FLOATS}u;
+    let band = ${GLOBAL_FIELD_BLEND.toFixed(6)} * (cascades[base + 3u] - cascades[base]);
+    if (inside >= band) {
+      return value;
+    }
+    let outer = cascadeAt(level + 1u, side, p);
+    return mix(outer, value, inside / band);
+  }
+  return cascadeAt(last, side, p);
+}
+`;
+
+/** Floats in the sampler parity entry point's params: cascade count, samples a side, point count. */
+export const SAMPLE_PARAM_FLOATS = 4;
+
+/**
+ * A compute entry point that does nothing but sample, so `gi-parity.mjs` can compare the function
+ * above against `sampleGlobalField` directly rather than through whatever is using it.
+ */
+export const SAMPLE_FIELD_PARITY_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>;
+@group(0) @binding(3) var<storage, read> points: array<f32>;
+@group(0) @binding(4) var<storage, read_write> out: array<f32>;
+
+${SAMPLE_FIELD_WGSL}
+
+@compute @workgroup_size(64)
+fn main(@builtin(global_invocation_id) id: vec3<u32>) {
+  let count = u32(params[2]);
+  if (id.x >= count) {
+    return;
+  }
+  let p = vec3<f32>(points[id.x * 3u], points[id.x * 3u + 1u], points[id.x * 3u + 2u]);
+  out[id.x] = sampleField(u32(params[0]), u32(params[1]), p);
+}
+`;