@driftengine/core 3.63.0 → 4.1.0

package/dist/render/gi/probeTrace.js

@@ -0,0 +1,128 @@
+/**
+ * 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.js';
+/**
+ * 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, frame, out) {
+    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, directions, count, edge, out) {
+    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);
+            const nx = TEXEL_DIR[0];
+            const ny = TEXEL_DIR[1];
+            const nz = TEXEL_DIR[2];
+            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] +
+                    ny * directions[i * 3 + 1] +
+                    nz * directions[i * 3 + 2];
+                if (weight <= 0)
+                    continue;
+                weights += weight;
+                r += samples[i * 3] * weight;
+                g += samples[i * 3 + 1] * weight;
+                b += samples[i * 3 + 2] * 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/dist/render/gi/probeVolume.d.ts

@@ -0,0 +1,136 @@
+/** The last level of the chain: a probe volume that knows where the walls are. */
+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 declare 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 declare 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 declare const PROBE_VISIBILITY_CRUSH = 0.01;
+export declare function createProbeVisibility(edge: number, layers: number): ProbeVisibility;
+/**
+ * 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 declare function bakeProbeVisibility(visibility: ProbeVisibility, layer: number, distanceInDirection: (x: number, y: number, z: number) => number): void;
+/**
+ * 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 declare function probeVisibilityWeight(visibility: ProbeVisibility, layer: number, x: number, y: number, z: number, distanceM: number): number;
+/**
+ * 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 declare function visibleProbes(grid: ProbeGrid, visibility: ProbeVisibility | null, x: number, y: number, z: number, out: ProbeBlend): ProbeBlend;
+/**
+ * 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 declare function sampleProbeVolume(blend: ProbeBlend, values: Float32Array, channels: number, out: Float32Array): Float32Array;
+/**
+ * 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 declare function probeUpdateSchedule(layers: number, perFrame: number, frameIndex: number, out: Int32Array): number;

package/dist/render/gi/probeVolume.js

@@ -0,0 +1,191 @@
+/** The last level of the chain: a probe volume that knows where the walls are. */
+import { nearestProbes } from '../probeGrid.js';
+import { octInsetDir, octInsetUv } from '../shaders/octahedral.js';
+/**
+ * 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, layers) {
+    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 = [0, 0];
+const DIR = [0, 0, 0];
+const PROBE_AT = [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, layer, distanceInDirection) {
+    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, layer, x, y, z) {
+    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], meanSquare: moments[at + 1] };
+}
+function clampTexel(value, edge) {
+    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, layer, x, y, z, distanceM) {
+    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, visibility, x, y, z, out) {
+    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];
+        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] * 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] / 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, values, channels, out) {
+    for (let channel = 0; channel < channels; channel++)
+        out[channel] = 0;
+    for (let slot = 0; slot < blend.layers.length; slot++) {
+        const weight = blend.weights[slot];
+        if (weight === 0)
+            continue;
+        const base = blend.layers[slot] * channels;
+        for (let channel = 0; channel < channels; channel++) {
+            out[channel] = out[channel] + values[base + channel] * 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, perFrame, frameIndex, out) {
+    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/dist/render/gi/reflection.d.ts

@@ -0,0 +1,73 @@
+/** A reflection is an indirect ray with a narrow cone, so it goes down the same chain. */
+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 declare function reflectDirection(direction: ReadonlyVec3, normal: ReadonlyVec3, out: Float32Array): Float32Array;
+/**
+ * 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 declare function reflectionCone(roughness: number): number;
+/**
+ * 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 declare function traceReflection(surface: ReflectiveSample, resources: GiResources, options: ReflectionOptions, out: IndirectResult): IndirectResult;

package/dist/render/gi/reflection.js

@@ -0,0 +1,109 @@
+/** A reflection is an indirect ray with a narrow cone, so it goes down the same chain. */
+import { GI_SOURCE_SCREEN, traceIndirect } from './chain.js';
+/**
+ * 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, normal, out) {
+    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) {
+    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, resources, options, out) {
+    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] / out.blend[0];
+        out.radiance[1] = out.radiance[1] / out.blend[0];
+        out.radiance[2] = out.radiance[2] / out.blend[0];
+        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, _y, _z, out) => {
+        out.fill(0);
+    },
+    probeValues: new Float32Array(0),
+    probeChannels: 0,
+};