@driftengine/core 3.63.0 → 4.1.0

package/src/render/gi/probeTrace.ts

@@ -0,0 +1,143 @@
+/**
+ * What a probe asks the indirect chain, and what it does with the answers.
+ *
+ * **A probe's measurement is an octahedral irradiance map**, because that is what the shading
+ * already samples: `gridIrradiance` in `shaders/flat/probeGrid.ts` blends eight probes and reads
+ * each through `probeIrradiance(dir, layer)`. So nothing downstream of a probe changes — only where
+ * the numbers in that map came from. Today they come from six rasterised faces of the world;
+ * `chain.ts` is what they come from once this is wired up, and the difference is a second bounce
+ * and radiance from surfaces that were never in frame.
+ *
+ * **Why a spherical Fibonacci spiral and not random directions.** At a few hundred samples a random
+ * set leaves holes and pairs, and a probe with a hole in its sphere has looked at part of its world
+ * and reports all of it — as a dark patch in a direction nothing happened to be traced along. The
+ * spiral's points are as far from each other as the count allows, and its cost is one sine and one
+ * cosine a direction.
+ *
+ * **And the set turns every frame, which is what makes a probe converge.** A fixed set measures the
+ * same few hundred directions for ever, so whatever it misses it misses permanently. Rotating it by
+ * an irrational fraction of a turn each refresh means successive refreshes sample different
+ * directions, and the accumulation over a few refreshes is a denser set than any one of them.
+ */
+
+import { octInsetDir } from '../shaders/octahedral.ts';
+
+/**
+ * Why a scene is not lit by what bounces on WebGL2, in words, so both backends read one sentence.
+ *
+ * **A probe is a few hundred rays and that is a compute dispatch.** This backend has no compute
+ * stage, and the alternatives are both worse than saying so: tracing on the processor is a
+ * main-thread cost proportional to the grid, and approximating with more frequent cube bakes means
+ * the two backends light one scene differently — which is the disagreement every published scene's
+ * pixel gate exists to prevent.
+ *
+ * Written here rather than in either renderer for the reason `OIT_MULTISAMPLE_REFUSAL` is written
+ * outside both: it is a decision the two share, so it belongs where neither owns it.
+ */
+export const INDIRECT_LIGHT_WEBGL2_REFUSAL =
+  'driftengine: indirect light traces a few hundred rays a probe, which is a compute dispatch, ' +
+  'and WebGL2 has no compute stage — so `quality.indirectLight` lights nothing on this backend ' +
+  'and the probe grid keeps the bake it has always had. It is WebGPU only, as reconstruction is.';
+
+/**
+ * Directions a probe traces per refresh.
+ *
+ * **A few hundred, and the number is a cost rather than a quality.** A refresh is this many rays
+ * down a three-level chain, and `probeUpdateSchedule` decides how many probes pay it a frame. The
+ * convergence comes from the rotation between refreshes, not from this count, so it is set where a
+ * single refresh is already recognisable rather than where one refresh is final.
+ */
+export const PROBE_DIRECTIONS = 256;
+
+/**
+ * The golden angle, which is what spaces a spiral's points as far apart as a count allows.
+ *
+ * Exported because `shaders/gi/probeBake.wgsl.ts` interpolates it: a shader cannot import a
+ * constant, so the choice is one value written here and pasted in, or two literals kept in step by
+ * hand. `probe-bake-parity.mjs` checks the result either way, but only one of them can be right by
+ * construction.
+ */
+export const GOLDEN_ANGLE = Math.PI * (3 - Math.sqrt(5));
+
+/**
+ * How far the set turns between one refresh and the next, in turns.
+ *
+ * The golden ratio's fractional part: successive frames land their offsets as far from each other
+ * as the sequence allows, for the same reason the spiral's own points do, and it never repeats.
+ */
+export const FRAME_TURN = 0.618033988749895;
+
+/**
+ * Direction `index` of the set this `frame` traces, into `out`.
+ *
+ * The spiral runs `z` from near `+1` to near `-1` in equal steps and turns by the golden angle at
+ * each, which is the construction whose points are evenly spread on a sphere; the frame's own
+ * rotation is added to that turn.
+ */
+export function probeDirection(index: number, frame: number, out: Float32Array): void {
+  const i = ((index % PROBE_DIRECTIONS) + PROBE_DIRECTIONS) % PROBE_DIRECTIONS;
+  /* Offset by a half step at each end, so no direction lands exactly on a pole — where the turn
+     has no effect and two frames would trace the same ray. */
+  const z = 1 - (2 * i + 1) / PROBE_DIRECTIONS;
+  const radius = Math.sqrt(Math.max(0, 1 - z * z));
+  const angle = i * GOLDEN_ANGLE + frame * FRAME_TURN * Math.PI * 2;
+  out[0] = Math.cos(angle) * radius;
+  out[1] = Math.sin(angle) * radius;
+  out[2] = z;
+}
+
+const TEXEL_DIR = new Float32Array(3);
+
+/**
+ * The cosine convolution of `count` radiance samples into an octahedral map of `edge` texels.
+ *
+ * Each texel's direction is the normal of a surface facing that way, and its value is the
+ * irradiance such a surface receives: every sample weighted by how much of its hemisphere it
+ * occupies, which for a cosine lobe is `max(0, dot(normal, direction))`.
+ *
+ * **Normalised by the weights that were actually used, and that is the whole of the white-furnace
+ * property.** Dividing by an analytic constant — pi, or the sample count — is right only in the
+ * limit and wrong for any finite set, so a uniformly white sphere would convolve to something
+ * slightly other than white and a room would brighten or darken a little at every refresh. Dividing
+ * by the sum of the weights is exact for any set, and it is what makes a constant come back
+ * constant to the last place a float holds.
+ */
+export function convolveProbe(
+  samples: Float32Array,
+  directions: Float32Array,
+  count: number,
+  edge: number,
+  out: Float32Array,
+): void {
+  const texels = Math.max(1, Math.floor(edge));
+  for (let v = 0; v < texels; v += 1) {
+    for (let u = 0; u < texels; u += 1) {
+      octInsetDir((u + 0.5) / texels, (v + 0.5) / texels, texels, TEXEL_DIR as unknown as never);
+      const nx = TEXEL_DIR[0] as number;
+      const ny = TEXEL_DIR[1] as number;
+      const nz = TEXEL_DIR[2] as number;
+      let weights = 0;
+      let r = 0;
+      let g = 0;
+      let b = 0;
+      for (let i = 0; i < count; i += 1) {
+        const weight =
+          nx * (directions[i * 3] as number) +
+          ny * (directions[i * 3 + 1] as number) +
+          nz * (directions[i * 3 + 2] as number);
+        if (weight <= 0) continue;
+        weights += weight;
+        r += (samples[i * 3] as number) * weight;
+        g += (samples[i * 3 + 1] as number) * weight;
+        b += (samples[i * 3 + 2] as number) * weight;
+      }
+      const at = (v * texels + u) * 3;
+      /* No weight at all is a texel no sample faced, which a set this dense does not produce —
+         and answering zero rather than dividing is what keeps it from being a hole if it ever does. */
+      const scale = weights > 0 ? 1 / weights : 0;
+      out[at] = Math.max(0, r * scale);
+      out[at + 1] = Math.max(0, g * scale);
+      out[at + 2] = Math.max(0, b * scale);
+    }
+  }
+}

package/src/render/gi/probeVolume.ts

@@ -0,0 +1,288 @@
+/** The last level of the chain: a probe volume that knows where the walls are. */
+
+import { nearestProbes } from '../probeGrid.ts';
+import { octInsetDir, octInsetUv } from '../shaders/octahedral.ts';
+
+import type { vec2, vec3 } from 'gl-matrix';
+import type { Vec3 } from '../../math/color.ts';
+import type { ProbeBlend, ProbeGrid } from '../probeGrid.ts';
+
+/**
+ * **A probe volume is never wrong and only ever coarse, and that is what it is for.**
+ *
+ * It is the level the chain falls back to when the screen could not answer and the world field
+ * could not either, so it has nothing behind it and must always answer. What makes that safe is
+ * that it is an interpolation between measurements rather than a trace: no ray to escape, no frame
+ * to leave, no resolution to run out of. The cost is that it is smooth where the world is not.
+ *
+ * **The one way it *is* wrong is the wall, and every implementation of this has shipped it.**
+ * `probeGrid.ts`'s blend is eight corners and three lerps — it reads the lattice and the point and
+ * nothing else — so a point in a dark room takes a trilinear share of a probe standing in the lit
+ * room next door. Light comes out of solid walls, and no amount of probe density fixes it: halving
+ * the spacing halves the width of the glow and leaves it exactly as bright.
+ *
+ * That is not a defect in `probeGrid.ts`. Its header argues for a bare lattice at length and the
+ * argument is about *uniform pressure* — free placement wants a position and an extent per probe
+ * against a flat shader already 1.7x over WebGL2's guaranteed `MAX_FRAGMENT_UNIFORM_VECTORS`. This
+ * adds the term that was missing without touching any of that: a second array beside the radiance
+ * one, holding what each probe could see, and a weight computed from it.
+ *
+ * **Passing `null` for the visibility is the whole of the off switch**, and it lands on
+ * `nearestProbes` itself rather than on a path that reproduces it — so a scene with no visibility
+ * volume renders exactly the frame it rendered before this file existed.
+ */
+
+/**
+ * What each probe could see, as one octahedral map of depth moments per probe.
+ *
+ * **Two moments and not one distance.** A single distance gives a binary answer — in front of the
+ * wall or behind it — and a binary answer aliases along every edge in the scene, because the probe
+ * that can see a point and the probe that cannot are adjacent. The mean and the mean of squares
+ * give a *variance*, and a Chebyshev bound on that variance is a soft weight: confident where the
+ * geometry is flat, uncertain where it is not, which is exactly where a hard answer would be wrong.
+ * It is the same arithmetic a variance shadow map uses, for the same reason.
+ *
+ * Octahedral rather than a cube, matching `EnvProbeArray`: one layer a probe, no faces to seam, and
+ * no sampler per probe. `octInsetUv` is the mapping, so a direction lands in the same texel here as
+ * it does in the radiance map.
+ */
+export interface ProbeVisibility {
+  /** Two floats a texel: mean distance, then mean of squares. One map a probe, layer-major. */
+  readonly moments: Float32Array;
+  /** Texels a side, the outer ring being the gutter `octInsetUv` insets past. */
+  readonly edge: number;
+  readonly layers: number;
+}
+
+/**
+ * The least variance a texel is treated as having, in square metres.
+ *
+ * **Without it the falloff is a step**, because a probe looking at a flat wall records the same
+ * distance in every direction of the cone and the variance is exactly zero — so the Chebyshev
+ * bound is zero everywhere past the wall and one everywhere in front of it, and the seam between
+ * them is a hard line that crawls as the probes are rebaked. Two hundredths of a square metre is
+ * about fourteen centimetres of slop, which is below a probe spacing anybody would choose and
+ * above the depth error of a bake.
+ */
+export const PROBE_VISIBILITY_VARIANCE_FLOOR = 0.02;
+
+/**
+ * How sharply the Chebyshev bound is turned into a weight.
+ *
+ * The bound is generous by construction — it is an inequality, not a measurement — so a probe that
+ * is mostly occluded still scores a third of a fully visible one. Cubing it turns that third into
+ * a twenty-seventh, which is the difference between a wall that reads as a wall and one that reads
+ * as a curtain. Three is what the technique this follows uses, and it is here as a constant so the
+ * next person can see it is a choice.
+ */
+export const PROBE_VISIBILITY_SHARPNESS = 3;
+
+/**
+ * Below this share, a probe is treated as contributing nothing at all.
+ *
+ * **A weight that is merely very small is not the same as zero, and the difference is the last
+ * percent of the leak.** A probe on the far side of a wall scores about four ten-thousandths here;
+ * kept, it puts that fraction of the lit room into the dark one, which is faint and is visible
+ * because the eye reads a gradient in a dark room extremely well. Crushed, the wall is a wall.
+ *
+ * It is applied to the *product* of the trilinear weight and the visibility, because that is what a
+ * probe actually contributes, and it is applied in `visibleProbes` rather than in
+ * `probeVisibilityWeight` — the raw bound stays continuous, which is what lets it be tested as a
+ * falloff rather than as a switch.
+ */
+export const PROBE_VISIBILITY_CRUSH = 1e-2;
+
+export function createProbeVisibility(edge: number, layers: number): ProbeVisibility {
+  const side = Math.trunc(edge);
+  if (!(side >= 4)) {
+    throw new Error(
+      `createProbeVisibility: edge is ${String(edge)} and the minimum is 4. The outer ring is a ` +
+        'gutter, so anything smaller is two real texels a side.',
+    );
+  }
+  const count = Math.max(1, Math.trunc(layers));
+  return { moments: new Float32Array(side * side * 2 * count), edge: side, layers: count };
+}
+
+/** Scratch, so neither baking nor sampling allocates. */
+const UV: vec2 = [0, 0] as unknown as vec2;
+const DIR: vec3 = [0, 0, 0] as unknown as vec3;
+const PROBE_AT: Vec3 = [0, 0, 0];
+
+/**
+ * Fill one probe's map from what it can see.
+ *
+ * `distanceInDirection` is the bake: how far the geometry is from this probe along a direction.
+ * Given as a callback because how that is measured is the caller's business — a `traceField` march
+ * offline, a depth cube read back, or a closed form in a test.
+ */
+export function bakeProbeVisibility(
+  visibility: ProbeVisibility,
+  layer: number,
+  distanceInDirection: (x: number, y: number, z: number) => number,
+): void {
+  const { edge, moments } = visibility;
+  const base = layer * edge * edge * 2;
+  for (let ty = 0; ty < edge; ty++) {
+    for (let tx = 0; tx < edge; tx++) {
+      octInsetDir((tx + 0.5) / edge, (ty + 0.5) / edge, edge, DIR);
+      const distance = distanceInDirection(DIR[0], DIR[1], DIR[2]);
+      const at = base + (tx + ty * edge) * 2;
+      moments[at] = distance;
+      moments[at + 1] = distance * distance;
+    }
+  }
+}
+
+/** The moments one probe recorded in one direction, as a two-element read. */
+function momentsAt(
+  visibility: ProbeVisibility,
+  layer: number,
+  x: number,
+  y: number,
+  z: number,
+): { mean: number; meanSquare: number } {
+  const { edge, moments } = visibility;
+  octInsetUv(x, y, z, edge, UV);
+  const tx = clampTexel(Math.floor(UV[0] * edge), edge);
+  const ty = clampTexel(Math.floor(UV[1] * edge), edge);
+  const at = layer * edge * edge * 2 + (tx + ty * edge) * 2;
+  return { mean: moments[at] as number, meanSquare: moments[at + 1] as number };
+}
+
+function clampTexel(value: number, edge: number): number {
+  return value < 0 ? 0 : value > edge - 1 ? edge - 1 : value;
+}
+
+/**
+ * How much a probe's answer is trusted at a point this far away in this direction.
+ *
+ * One in front of what the probe saw; a Chebyshev bound on the depth variance behind it, cubed.
+ * Continuous everywhere, which is what `visibleProbes` then crushes rather than this.
+ */
+export function probeVisibilityWeight(
+  visibility: ProbeVisibility,
+  layer: number,
+  x: number,
+  y: number,
+  z: number,
+  distanceM: number,
+): number {
+  const { mean, meanSquare } = momentsAt(visibility, layer, x, y, z);
+  if (distanceM <= mean) return 1;
+  const variance = Math.max(Math.abs(mean * mean - meanSquare), PROBE_VISIBILITY_VARIANCE_FLOOR);
+  const beyond = distanceM - mean;
+  const chebyshev = variance / (variance + beyond * beyond);
+  return chebyshev ** PROBE_VISIBILITY_SHARPNESS;
+}
+
+/**
+ * The eight probes around a point, weighted by what each of them can actually see.
+ *
+ * With `visibility` null this is `nearestProbes` and nothing else — see the module header for why
+ * that matters. With one, each corner's trilinear weight is multiplied by its visibility, the
+ * result is crushed and the eight are renormalised so they still sum to one. **Renormalising is
+ * what keeps the blend from losing energy**, which is the property the white furnace in Task 10
+ * rests on: a solution that quietly drops a share of its probes darkens every bounce.
+ *
+ * **A point every probe is blind to still gets an answer**, because this is the last level of the
+ * chain and there is nothing behind it. When every weight crushes to zero — a point inside a solid,
+ * or a sealed void with a probe on each side of a wall — the nearest probe by distance takes the
+ * whole weight. That is the coarse answer this level exists to always have.
+ */
+export function visibleProbes(
+  grid: ProbeGrid,
+  visibility: ProbeVisibility | null,
+  x: number,
+  y: number,
+  z: number,
+  out: ProbeBlend,
+): ProbeBlend {
+  nearestProbes(grid, x, y, z, out);
+  if (visibility === null) return out;
+
+  let total = 0;
+  let nearest = 0;
+  let nearestDistance = Infinity;
+  for (let slot = 0; slot < out.layers.length; slot++) {
+    const layer = out.layers[slot] as number;
+    grid.positionOf(layer, PROBE_AT);
+    const dx = x - PROBE_AT[0];
+    const dy = y - PROBE_AT[1];
+    const dz = z - PROBE_AT[2];
+    const distance = Math.hypot(dx, dy, dz);
+    if (distance < nearestDistance) {
+      nearestDistance = distance;
+      nearest = slot;
+    }
+    /* A point standing exactly on a probe is seen by it, and has no direction to ask about. */
+    const seen = distance > 0 ? probeVisibilityWeight(visibility, layer, dx, dy, dz, distance) : 1;
+    const weight = (out.weights[slot] as number) * seen;
+    const kept = weight < PROBE_VISIBILITY_CRUSH ? 0 : weight;
+    out.weights[slot] = kept;
+    total += kept;
+  }
+
+  if (total > 0) {
+    for (let slot = 0; slot < out.weights.length; slot++) {
+      out.weights[slot] = (out.weights[slot] as number) / total;
+    }
+    return out;
+  }
+
+  out.weights.fill(0);
+  out.weights[nearest] = 1;
+  return out;
+}
+
+/**
+ * Blend what the probes carry, `channels` floats each, into a target the caller owns.
+ *
+ * Channel count rather than a fixed three, because what a probe carries is the caller's decision:
+ * three for an ambient colour, nine for a spherical-harmonic band, a whole octahedral map for a
+ * directional one. The blend is the same arithmetic whatever it is, and writing it once is what
+ * stops two of them disagreeing about what the weights mean.
+ */
+export function sampleProbeVolume(
+  blend: ProbeBlend,
+  values: Float32Array,
+  channels: number,
+  out: Float32Array,
+): Float32Array {
+  for (let channel = 0; channel < channels; channel++) out[channel] = 0;
+  for (let slot = 0; slot < blend.layers.length; slot++) {
+    const weight = blend.weights[slot] as number;
+    if (weight === 0) continue;
+    const base = (blend.layers[slot] as number) * channels;
+    for (let channel = 0; channel < channels; channel++) {
+      out[channel] = (out[channel] as number) + (values[base + channel] as number) * weight;
+    }
+  }
+  return out;
+}
+
+/**
+ * Which probes to rebake on this frame.
+ *
+ * **A grid rebaked in one frame is six draws of the world per probe.** Sixty-four probes is 384
+ * submissions in one frame and a hitch a viewer sees; `EnvProbeArray` already bakes a probe at a
+ * time for that reason and gates the whole grid until every layer is filled. What is here is the
+ * schedule, and the part of it that is easy to get wrong is not the bound — it is that **every
+ * probe is reached**. A subset chosen by distance, or by what moved, leaves some probe stale for
+ * ever, and a stale probe in a room whose light changed is a room lit by the previous scene.
+ *
+ * A plain round robin, so it is also reproducible: the same frame index asks for the same probes,
+ * which is what the replay fingerprint needs and what makes a bug in it repeatable.
+ */
+export function probeUpdateSchedule(
+  layers: number,
+  perFrame: number,
+  frameIndex: number,
+  out: Int32Array,
+): number {
+  const count = Math.min(Math.max(0, Math.trunc(perFrame)), layers, out.length);
+  if (count < 1 || layers < 1) return 0;
+  const start = (((Math.trunc(frameIndex) * count) % layers) + layers) % layers;
+  for (let i = 0; i < count; i++) out[i] = (start + i) % layers;
+  return count;
+}

package/src/render/gi/reflection.ts

@@ -0,0 +1,163 @@
+/** A reflection is an indirect ray with a narrow cone, so it goes down the same chain. */
+
+import { GI_SOURCE_SCREEN, traceIndirect } from './chain.ts';
+
+import type { ReadonlyVec3 } from 'gl-matrix';
+import type { GiResources, IndirectResult } from './chain.ts';
+
+/**
+ * **The plan asked for a fallback bolted onto `screenSpaceReflection.ts`, and this is beside it
+ * instead.** That module is in `render/` and the chain is in `render/gi/`; importing upward would
+ * put the whole global-illumination tree behind every scene that draws a mirror, which is the
+ * opposite of the "off by default" this wave is built around. The dependency runs the other way
+ * and `screenSpaceReflection.ts` is untouched — a scene that never asks for the fallback imports
+ * none of this and renders exactly the frame it rendered before.
+ *
+ * What is left once the chain exists is small, and that is the point: **a reflection is an
+ * indirect ray whose direction is the mirror of the view and whose cone is the roughness.** Writing
+ * a second fallback for it would be a second thing to disagree with the first.
+ */
+
+/** A reflective surface, as a shading path holds one. */
+export interface ReflectiveSample {
+  readonly point: ReadonlyVec3;
+  readonly normal: ReadonlyVec3;
+  /** Which way the eye is looking, toward the surface. Need not be unit length. */
+  readonly view: ReadonlyVec3;
+  /** 0 is a mirror, 1 is fully diffuse. See `reflectionCone`. */
+  readonly roughness: number;
+}
+
+export interface ReflectionOptions {
+  /**
+   * Whether a ray the frame cannot answer continues into the world.
+   *
+   * **Off is the shipped behaviour and off is the default a caller should assume.** With it off
+   * this is `traceScreenSpaceRay` and nothing else: a miss is a miss, the surface keeps whatever
+   * the existing fade leaves it, and every scene renders the frame it rendered before this file
+   * existed. That is this wave's first global constraint, and it is asserted in the test rather
+   * than trusted.
+   */
+  readonly fallback: boolean;
+}
+
+/**
+ * Mirror a direction about a normal.
+ *
+ * `d - 2 (d . n) n`, with `n` normalised first because an interpolated normal is rarely unit — and
+ * a normal of length 1.01 mirrors to a direction that is not unit either, which a march then takes
+ * as a step length.
+ *
+ * **A direction already leaving the surface is mirrored back into it**, and that is not
+ * special-cased into something else. A caller that hands over a view vector pointing away from the
+ * surface has a bug one level up, and answering plausibly would hide it.
+ */
+export function reflectDirection(
+  direction: ReadonlyVec3,
+  normal: ReadonlyVec3,
+  out: Float32Array,
+): Float32Array {
+  const dx = direction[0] ?? 0;
+  const dy = direction[1] ?? 0;
+  const dz = direction[2] ?? 0;
+  let nx = normal[0] ?? 0;
+  let ny = normal[1] ?? 0;
+  let nz = normal[2] ?? 0;
+  const length = Math.hypot(nx, ny, nz);
+  if (length > 0) {
+    nx /= length;
+    ny /= length;
+    nz /= length;
+  }
+  const along = 2 * (dx * nx + dy * ny + dz * nz);
+  out[0] = dx - along * nx;
+  out[1] = dy - along * ny;
+  out[2] = dz - along * nz;
+  return out;
+}
+
+/**
+ * The cone half-angle a roughness reflects through.
+ *
+ * **`atan(roughness^2)`, which is the GGX lobe's own width rather than a curve chosen to look
+ * right.** The distribution's half-angle at half its peak is close to `atan(alpha)` and `alpha` is
+ * `roughness^2` in the parameterisation this engine uses everywhere else — `roughnessForLevel` in
+ * `prefilterEnvMap.ts` maps a mip chain by the same square, so a surface that samples level three
+ * of the prefiltered cube and a surface that cone-traces the world field agree about how blurred
+ * they are. Two curves here would be two blurs that diverge with distance.
+ *
+ * Zero is exactly zero, so a mirror traces a pencil ray and no epsilon creeps into the one case a
+ * viewer inspects most closely. One is `atan(1)`, a quarter turn's half — wide, and still short of
+ * the hemisphere a fully diffuse surface gathers over, which is `traceIndirect`'s job and not this.
+ */
+export function reflectionCone(roughness: number): number {
+  const clamped = roughness <= 0 ? 0 : roughness >= 1 ? 1 : roughness;
+  return Math.atan(clamped * clamped);
+}
+
+/** Scratch, because this runs per reflective pixel. */
+const MIRRORED = new Float32Array(3);
+
+/**
+ * Trace a reflection down the chain, or down its first level alone.
+ *
+ * With `fallback` off, only the screen answers and a miss stays a miss — which is what
+ * `screenSpaceReflection.ts` has always done and what keeps every published scene where it is.
+ * With it on, a ray leaving the frame continues into the world's distance field and, behind that,
+ * the probes: a mirror at the edge of the picture reflects the world rather than fading to a matte
+ * surface as the camera turns.
+ */
+export function traceReflection(
+  surface: ReflectiveSample,
+  resources: GiResources,
+  options: ReflectionOptions,
+  out: IndirectResult,
+): IndirectResult {
+  reflectDirection(surface.view, surface.normal, MIRRORED);
+  const ray = {
+    point: surface.point,
+    normal: surface.normal,
+    direction: MIRRORED,
+    coneAngle: reflectionCone(surface.roughness),
+  };
+
+  if (options.fallback) return traceIndirect(ray, resources, out);
+
+  /*
+   * The screen alone. Reached by handing the chain a resource set whose other two levels cannot
+   * contribute — rather than by a second copy of the march — so the frame's own answer is
+   * byte-identical either way and cannot drift from the fallback path's.
+   */
+  traceIndirect(ray, { ...resources, ...SCREEN_ONLY }, out);
+  if (out.blend[0] === 0) {
+    out.hit = false;
+    out.radiance.fill(0);
+    out.blend.fill(0);
+    out.source = GI_SOURCE_SCREEN;
+  } else {
+    /* What the frame could not answer is left unanswered rather than handed downward. */
+    out.radiance[0] = (out.radiance[0] as number) / (out.blend[0] as number);
+    out.radiance[1] = (out.radiance[1] as number) / (out.blend[0] as number);
+    out.radiance[2] = (out.radiance[2] as number) / (out.blend[0] as number);
+    out.blend[0] = 1;
+    out.blend[1] = 0;
+    out.blend[2] = 0;
+    out.source = GI_SOURCE_SCREEN;
+  }
+  return out;
+}
+
+/**
+ * The two levels below the screen, silenced.
+ *
+ * A field whose march can never hit and a probe set that carries nothing, so `traceIndirect` runs
+ * its ordinary path and the screen's share is all there is to normalise. Frozen at module scope
+ * because this is a per-pixel call and the rule about allocating in one is absolute.
+ */
+const SCREEN_ONLY = {
+  fieldRadiance: (_x: number, _y: number, _z: number, out: Float32Array): void => {
+    out.fill(0);
+  },
+  probeValues: new Float32Array(0),
+  probeChannels: 0,
+} as const;