Skip to content

Code-first video & image, rendered natively on WebGPU.

feat(3d): screen-space reflections and diffuse GI, specular anti-aliasing

okanasl90bacac8f2a5
diff --git a/nodes/node-compositor/SKILL.md b/nodes/node-compositor/SKILL.md
index 5ece9dc1..88623fe7 100644
--- a/nodes/node-compositor/SKILL.md
+++ b/nodes/node-compositor/SKILL.md
@@ -216,6 +216,7 @@ Each track represents animatable property modifications:
- **Volumetric Fog & Light Shafts (`volumetricFog` in `environment`):** `kind: "light"` with `lightType: "environment"` and `volumetricFog: true | { density, anisotropy, heightFalloff, baseHeight, color, lightIntensity, ambientIntensity, maxDistance, steps, noise: { scale, strength, speed, octaves } }` runs half-resolution raymarching with Interleaved Gradient Noise jitter, Henyey-Greenstein phase scattering, 3D FBM wind-animated density noise, and multi-light shadow-map sampling (carving god rays behind shadow casters), followed by depth-aware bilateral upsampling. `volumetricFogDensity`, `volumetricFogAnisotropy`, and `volumetricFogNoiseStrength` can be animated or driven by `Signal`s.
- **Substrate multi-lobe materials:** physical-shading surfaces (any scene with an `environment` light) on `model3d` nodes, 3D cards and 3D text accept extra lobes on top of `roughness`/`metallic`: `clearcoat` 0..1 + `clearcoatRoughness` (default 0.08; IOR 1.5 GGX varnish that attenuates the base), `anisotropy` -1..1 + `anisotropyRotation` degrees (tangent-space anisotropic GGX: brushed metal, satin), `subsurface` 0..1 + `subsurfaceColor` (default `#ff6b4a`; wrap diffuse, terminator bleed and back-lit transmission), `sheen` 0..1 + `sheenColor` + `sheenRoughness` (default 0.5; Charlie cloth/velvet lobe), `iridescence` 0..1 or `{ intensity, thickness, ior }` + `iridescenceThickness` nm (100..1200, default 400) + `iridescenceIor` (default 1.3; RGB thin-film interference), and `triplanar: true | { scale, sharpness }` + `triplanarScale` (repeats per 256 world px) + `triplanarSharpness` (1..16, default 4) for world-space UV-less texture projection. All numeric lobe props are animatable.
- **HDRI environments:** an environment light's `hdri` takes an equirectangular panorama: a Radiance `.hdr` (RGBE) or OpenEXR `.exr` file path (resolved from the working directory) or the file's bytes (told apart by magic bytes); it then replaces the procedural preset as the image-based light for reflections and ambient, honoring `intensity`, `rotation` and `exposure`. On first use per device a compute pass prefilters it into a GGX radiance cubemap (faces up to 256², one mip per roughness step, split-sum importance sampling) for reflections, and the CPU projects it onto L2 spherical harmonics for diffuse irradiance; both are cached (up to 8 panoramas per device, least recently used destroyed). `.exr` reads single-part scanline or tiled files (level 0 of mip/ripmaps) with NONE, RLE, ZIPS, ZIP, PIZ or PXR24 compression and HALF/FLOAT/UINT `R`,`G`,`B` (or `Y`) channels; lossy B44/B44A/DWAA/DWAB/HTJ2K, deep and multi-part files fail with an error naming the cause.
+- **Screen-space reflections & GI (`ssr`, `gi` in `environment`):** `ssr: true | { intensity (0..1, default 0.85), maxRoughness (0..1, 0.6), thickness (world px, 120), steps (16..64, 32) }` makes glossy physical surfaces reflect whatever the camera sees (walls, curved metal, emissives off the floor plane); `gi: true | { intensity (0..4, 1), radius (world px, 400), samples (4..16, 6) }` adds ambient occlusion and one diffuse bounce of visible light (color bleeding from neon and lit walls). Either one renders the 3D scene twice: a radiance pass, then Hi-Z reflection tracing and a horizon-scan GI gather (bilateral-denoised) on it, then the shading pass, which swaps each surface's environment reflection for the traced one (glossy ones read a blurred radiance pyramid matching their lobe, so output is noise-free and identical every frame) and occludes its ambient light before tone mapping and fog. Screen-space limits apply: anything off screen or hidden behind other geometry reflects the environment instead; the planar `floor` reflection is unaffected. Needs physical shading; non-physical (legacy, toon) surfaces ignore it.
- **Art-directed 3D lighting:** `material: "toon"` on meshes, flat 3D cards and native 3D text uses the shared direct lights, colors, point/spot attenuation, cast shadows, environment fog and tone mapping. Optional `toon: { shadowColor, lightColor, threshold, softness, diffuse }` controls the shadow/lit albedo multipliers, terminator cosine/width and Lambert modelling (defaults: model shade color or `#80808c`, white, 0.075, 0.25, 0). Lit/physical materials retain their own shading.
- **Geometry outlines:** an environment light's optional `outlines: true | { color, width, referenceHeight, creaseAngle, depthThreshold, opacity }` runs a depth/normal ink pass before camera depth blur and bloom (defaults: `#16131c`, 1.5 px at height 1080, 45°, 0.01, 1). It reuses the linear-depth attachment's spare channels for octahedral surface normals and outline participation. Inverse-depth curvature avoids false contours on perspective planes; normal discontinuities find creases without inking texture/shadow/triangulation seams. `outline: false` on a layer/model opts out while retaining depth occlusion; `creaseAngle: 180` disables creases. Ink fades into the environment fog. 3D `anchorX/Y` pivots remain fixed under scale/rotation and leave identity placement unchanged.
With MSAA enabled, retain original scene color and geometry samples and shade ink per sample before resolving color. A single-sample ink pass after the scene resolve loses subpixel coverage between outlined surfaces. Lens blur uses a separate nearest-sample geometry resolve. The scene's geometry is still drawn once.
diff --git a/nodes/node-compositor/src/renderers/webgpu-renderer.ts b/nodes/node-compositor/src/renderers/webgpu-renderer.ts
index 9285590e..9281700b 100644
--- a/nodes/node-compositor/src/renderers/webgpu-renderer.ts
+++ b/nodes/node-compositor/src/renderers/webgpu-renderer.ts
@@ -1466,6 +1466,8 @@ export const CompositorWebGPURenderer: WebGPUNodeRenderer = async (args) => {
fog: lop.fog,
floor: lop.floor,
outlines: lop.outlines,
+ ssr: lop.ssr,
+ gi: lop.gi,
...(volumetricFog && { volumetricFog }),
...(intensity !== undefined && { intensity }),
};
@@ -1626,8 +1628,14 @@ export const CompositorWebGPURenderer: WebGPUNodeRenderer = async (args) => {
const outlineSetting = sceneEnvironment?.outlines;
const outlines = outlineSetting === true ? {} : outlineSetting || null;
const volumetricFogEnabled = Boolean(sceneEnvironment?.volumetricFog);
+ const screenIndirectEnabled = Boolean(
+ sceneEnvironment?.ssr || sceneEnvironment?.gi,
+ );
const geometryEnabled =
- dofEnabled || Boolean(outlines) || volumetricFogEnabled;
+ dofEnabled ||
+ Boolean(outlines) ||
+ volumetricFogEnabled ||
+ screenIndirectEnabled;
let linearDepthTex: GPUTexture | undefined;
let linearDepthView: GPUTextureView | undefined;
if (geometryEnabled) {
@@ -1870,73 +1878,87 @@ export const CompositorWebGPURenderer: WebGPUNodeRenderer = async (args) => {
);
}
- const {
- pass: pass3d,
- cameraBindGroup,
- cameraBuffer,
- lightsBindGroup,
- } = r3d.beginPass(
- encoder,
- scene3dView,
- nativeWidth,
- nativeHeight,
- camera,
- "clear",
- { r: 0, g: 0, b: 0, a: 0 },
- linearDepthView,
- sceneLights,
- {
- environment: sceneEnvironment,
- shadow: shadow.length ? shadow : null,
- },
- Boolean(sceneBloom),
- );
-
- if (floorSpec && blurredReflectionTex) {
- r3d.drawFloor(
- pass3d,
- cameraBindGroup,
- lightsBindGroup,
- blurredReflectionTex,
- floorSpec,
- geometryEnabled,
- Boolean(sceneBloom),
+ const sceneShadow = shadow.length ? shadow : null;
+ /** One forward pass over the scene: floor, then the sorted draws. */
+ const drawScene = (
+ screenIndirect: "radiance" | "apply" | undefined,
+ writeHdr: boolean,
+ ) => {
+ const begun = r3d.beginPass(
+ encoder,
+ scene3dView,
+ nativeWidth,
+ nativeHeight,
+ camera,
+ "clear",
+ { r: 0, g: 0, b: 0, a: 0 },
+ linearDepthView,
+ sceneLights,
+ {
+ environment: sceneEnvironment,
+ shadow: sceneShadow,
+ screenIndirect,
+ },
+ writeHdr,
);
- }
- for (const item of ordered) {
- if (item.kind === "quad") {
- r3d.drawTextureQuad(
- pass3d,
- cameraBindGroup,
- lightsBindGroup,
- item.texture,
- item.opts,
- geometryEnabled,
- );
- } else if (item.kind === "slug") {
- r3d.drawSlugText(
- pass3d,
- cameraBindGroup,
- lightsBindGroup,
- item.batches,
- item.opts,
- item.stackBase,
- geometryEnabled,
- );
- } else if (item.kind === "mesh") {
- r3d.drawMesh3D(
- pass3d,
+ const { pass, cameraBindGroup, lightsBindGroup } = begun;
+ if (floorSpec && blurredReflectionTex) {
+ r3d.drawFloor(
+ pass,
cameraBindGroup,
lightsBindGroup,
- item.meshBuffers ?? item.mesh,
- item.texture,
- isGlass(item) ? { ...item.opts, backdrop: curTex } : item.opts,
+ blurredReflectionTex,
+ floorSpec,
geometryEnabled,
+ writeHdr,
);
}
- }
+ for (const item of ordered) {
+ if (item.kind === "quad") {
+ r3d.drawTextureQuad(
+ pass,
+ cameraBindGroup,
+ lightsBindGroup,
+ item.texture,
+ item.opts,
+ geometryEnabled,
+ );
+ } else if (item.kind === "slug") {
+ r3d.drawSlugText(
+ pass,
+ cameraBindGroup,
+ lightsBindGroup,
+ item.batches,
+ item.opts,
+ item.stackBase,
+ geometryEnabled,
+ );
+ } else if (item.kind === "mesh") {
+ r3d.drawMesh3D(
+ pass,
+ cameraBindGroup,
+ lightsBindGroup,
+ item.meshBuffers ?? item.mesh,
+ item.texture,
+ isGlass(item) ? { ...item.opts, backdrop: curTex } : item.opts,
+ geometryEnabled,
+ );
+ }
+ }
+ pass.end();
+ return begun;
+ };
- pass3d.end();
+ // Screen-space reflections and GI read the scene's own light: draw
+ // its radiance once, trace it, then shade with what was found.
+ if (screenIndirectEnabled && sceneEnvironment) {
+ const { cameraBuffer: radianceCamera } = drawScene("radiance", true);
+ r3d.traceScreenIndirect(encoder, radianceCamera, sceneEnvironment);
+ }
+ const { cameraBindGroup, cameraBuffer, lightsBindGroup } = drawScene(
+ screenIndirectEnabled ? "apply" : undefined,
+ Boolean(sceneBloom),
+ );
let final3dTex = scene3dTex;
if (outlines && linearDepthTex) {
diff --git a/packages/compositions/src/program/schema.ts b/packages/compositions/src/program/schema.ts
index 068d8490..3d43b70c 100644
--- a/packages/compositions/src/program/schema.ts
+++ b/packages/compositions/src/program/schema.ts
@@ -1561,6 +1561,32 @@ export type EnvironmentVolumetricFog = z.infer<
typeof EnvironmentVolumetricFogSchema
>;
+export const EnvironmentSsrSchema = z
+ .object({
+ /** How fully a found reflection replaces the environment's, 0..1. Default 0.85. */
+ intensity: z.number().min(0).max(1).optional(),
+ /** Roughest surface that traces reflections (0..1). Default 0.6. */
+ maxRoughness: z.number().min(0).max(1).optional(),
+ /** How far behind a surface, in world px, a ray still counts as hitting it. Default 120. */
+ thickness: z.number().min(1).optional(),
+ /** Hi-Z march iterations per ray (16..64). Default 32. */
+ steps: z.number().int().min(16).max(64).optional(),
+ })
+ .strict();
+export type EnvironmentSsr = z.infer<typeof EnvironmentSsrSchema>;
+
+export const EnvironmentGiSchema = z
+ .object({
+ /** Strength of the bounced light, 0..4. Default 1. */
+ intensity: z.number().min(0).max(4).optional(),
+ /** Gather radius in world px. Default 400. */
+ radius: z.number().min(1).optional(),
+ /** Horizon-scan directions per pixel (4..16). Default 6. */
+ samples: z.number().int().min(4).max(16).optional(),
+ })
+ .strict();
+export type EnvironmentGi = z.infer<typeof EnvironmentGiSchema>;
+
export interface LightNode {
id: string;
kind: "light";
@@ -1613,6 +1639,10 @@ export interface LightNode {
volumetricFogAnisotropy?: number;
/** Animatable / signal-driven override for volumetricFog.noise.strength. */
volumetricFogNoiseStrength?: number;
+ /** Screen-space reflections of nearby geometry and emissives on glossy surfaces. */
+ ssr?: boolean | EnvironmentSsr;
+ /** Screen-space diffuse GI: occlusion and color bleeding from visible surfaces. */
+ gi?: boolean | EnvironmentGi;
/** Optional depth/normal outlines, before depth of field and bloom. */
outlines?: boolean | GeometryOutlineOptions;
/** Glow around emissive surfaces and hot highlights: `true` or settings. */
@@ -1666,6 +1696,8 @@ export const LightNodeSchema: z.ZodType<LightNode> = z
volumetricFogDensity: z.number().min(0).optional(),
volumetricFogAnisotropy: z.number().min(-0.95).max(0.95).optional(),
volumetricFogNoiseStrength: z.number().min(0).max(1).optional(),
+ ssr: z.union([z.boolean(), EnvironmentSsrSchema]).optional(),
+ gi: z.union([z.boolean(), EnvironmentGiSchema]).optional(),
outlines: z.union([z.boolean(), GeometryOutlineOptionsSchema]).optional(),
bloom: z.union([z.boolean(), BloomConfigSchema]).optional(),
startFrame: z.number().int().min(0).default(0),
diff --git a/packages/framefields/src/index.ts b/packages/framefields/src/index.ts
index 5628a8db..a18449a6 100644
--- a/packages/framefields/src/index.ts
+++ b/packages/framefields/src/index.ts
@@ -539,8 +539,12 @@ export {
EnvironmentFloorSchema,
type EnvironmentFog,
EnvironmentFogSchema,
+ type EnvironmentGi,
+ EnvironmentGiSchema,
type EnvironmentPreset,
EnvironmentPresetSchema,
+ type EnvironmentSsr,
+ EnvironmentSsrSchema,
type EnvironmentVolumetricFog,
type EnvironmentVolumetricFogNoise,
EnvironmentVolumetricFogNoiseSchema,
@@ -3673,6 +3677,8 @@ export interface EnvironmentOptions
| "fog"
| "floor"
| "outlines"
+ | "ssr"
+ | "gi"
| "bloom"
| "startFrame"
| "durationFrames"
diff --git a/packages/framefields/src/lighting.ts b/packages/framefields/src/lighting.ts
index bff425dd..693add1f 100644
--- a/packages/framefields/src/lighting.ts
+++ b/packages/framefields/src/lighting.ts
@@ -30,6 +30,10 @@ export interface LightingRigOptions {
fog?: EnvironmentOptions["fog"];
/** Volumetric fog & shadowed light shafts (god rays): `true` or settings. */
volumetricFog?: EnvironmentOptions["volumetricFog"];
+ /** Screen-space reflections of nearby geometry on glossy surfaces: `true` or settings. */
+ ssr?: EnvironmentOptions["ssr"];
+ /** Screen-space diffuse GI (contact occlusion and color bleeding): `true` or settings. */
+ gi?: EnvironmentOptions["gi"];
/** Glow around emissive surfaces and highlights: `true` or settings. */
bloom?: EnvironmentOptions["bloom"];
/** Prefix for the rig's node ids. */
@@ -124,6 +128,8 @@ function rig(
toneMapping: options.toneMapping,
fog: options.fog,
volumetricFog: options.volumetricFog,
+ ssr: options.ssr,
+ gi: options.gi,
bloom: options.bloom,
}),
Light.directional({
diff --git a/packages/framefields/src/screen-indirect-render.test.ts b/packages/framefields/src/screen-indirect-render.test.ts
new file mode 100644
index 00000000..107a9338
--- /dev/null
+++ b/packages/framefields/src/screen-indirect-render.test.ts
@@ -0,0 +1,234 @@
+import { describe, expect, it } from "vitest";
+import {
+ Composition,
+ CompositorProgramSchema,
+ type EnvironmentOptions,
+ Layer,
+ Layer3D,
+} from "./index.js";
+import { decodePngPixels } from "./test-utils/pixels.js";
+
+const W = 320;
+const H = 180;
+
+type Rgb = [number, number, number];
+
+interface Floor {
+ color: string;
+ metallic: number;
+ roughness: number;
+}
+
+const CHROME: Floor = { color: "#d0d0d0", metallic: 1, roughness: 0.05 };
+const MATTE: Floor = { color: "#d8d8d8", metallic: 0, roughness: 0.9 };
+
+/**
+ * A slab floor (top face at y = 300) with a hot magenta sphere resting on
+ * it and, optionally, a box on its right, seen from above and in front.
+ */
+function scene(
+ floor: Floor,
+ env: EnvironmentOptions,
+ options: { box?: boolean; sun?: boolean } = {},
+): Composition {
+ const comp = new Composition({
+ width: W,
+ height: H,
+ fps: 30,
+ durationFrames: 1,
+ backgroundColor: "#000000",
+ });
+ comp.add([
+ Layer.camera({
+ x: 160,
+ y: 120,
+ z: -700,
+ targetX: 160,
+ targetY: 260,
+ targetZ: 0,
+ }),
+ Layer.environment("night", { intensity: 0.5, ...env }),
+ ...(options.sun
+ ? [
+ Layer.directionalLight({
+ x: -400,
+ y: -900,
+ z: -500,
+ targetX: 160,
+ targetY: 300,
+ targetZ: 0,
+ intensity: 1.2,
+ }),
+ ]
+ : []),
+ Layer3D.roundedBox({
+ x: 160,
+ y: 320,
+ z: 0,
+ width: 1400,
+ height: 40,
+ depth: 1400,
+ ...floor,
+ }),
+ Layer3D.sphere({
+ x: 110,
+ y: 230,
+ z: 0,
+ radius: 70,
+ segments: 64,
+ color: "#101010",
+ emissive: "#ff2a8a",
+ emissiveIntensity: 3,
+ }),
+ ...(options.box
+ ? [
+ Layer3D.roundedBox({
+ x: 290,
+ y: 220,
+ z: 0,
+ width: 90,
+ height: 160,
+ depth: 90,
+ color: "#e0e0e0",
+ metallic: 0,
+ roughness: 0.9,
+ }),
+ ]
+ : []),
+ ]);
+ return comp;
+}
+
+async function render(comp: Composition): Promise<Uint8ClampedArray> {
+ return (await decodePngPixels(await comp.renderFrame({ frame: 0 }))).pixels;
+}
+
+/** Mean RGB over the box [x0, x1) × [y0, y1). */
+function mean(
+ px: Uint8ClampedArray,
+ x0: number,
+ y0: number,
+ x1: number,
+ y1: number,
+): Rgb {
+ const sum: Rgb = [0, 0, 0];
+ let n = 0;
+ for (let y = y0; y < y1; y++) {
+ for (let x = x0; x < x1; x++) {
+ const i = (y * W + x) * 4;
+ for (let c = 0; c < 3; c++) sum[c] += px[i + c] ?? 0;
+ n++;
+ }
+ }
+ return sum.map((v) => v / n) as Rgb;
+}
+
+interface Box {
+ x0: number;
+ y0: number;
+ x1: number;
+ y1: number;
+}
+
+/** Bounding box of the pixels whose color passes `test`. */
+function bounds(px: Uint8ClampedArray, test: (rgb: Rgb) => boolean): Box {
+ const box = { x0: W, y0: H, x1: -1, y1: -1 };
+ for (let y = 0; y < H; y++) {
+ for (let x = 0; x < W; x++) {
+ const i = (y * W + x) * 4;
+ if (!test([px[i] ?? 0, px[i + 1] ?? 0, px[i + 2] ?? 0])) continue;
+ box.x0 = Math.min(box.x0, x);
+ box.y0 = Math.min(box.y0, y);
+ box.x1 = Math.max(box.x1, x + 1);
+ box.y1 = Math.max(box.y1, y + 1);
+ }
+ }
+ expect(box.x1).toBeGreaterThan(box.x0);
+ return box;
+}
+
+/** The glowing sphere: bright magenta. */
+const isSphere = ([r, g, b]: Rgb) => r > 200 && r > g + 60 && b > g;
+
+const luma = ([r, g, b]: Rgb) => 0.2126 * r + 0.7152 * g + 0.0722 * b;
+
+describe("screen-space reflections and GI", () => {
+ it("reflects an emissive object off the floor in a chrome floor", async () => {
+ const off = await render(scene(CHROME, {}));
+ const on = await render(scene(CHROME, { ssr: true }));
+ // Below the sphere, where its mirror image lies, the floor shows the
+ // dark night environment without SSR and the magenta sphere with it.
+ const s = bounds(off, isSphere);
+ const cx = Math.round((s.x0 + s.x1) / 2);
+ const mirrored = (px: Uint8ClampedArray) =>
+ mean(px, cx - 8, s.y1 + 6, cx + 8, s.y1 + 26);
+ const [r0, g0, b0] = mirrored(off);
+ const [r1, g1, b1] = mirrored(on);
+ expect(r0).toBeLessThan(40);
+ expect(r1).toBeGreaterThan(r0 + 150);
+ expect(r1).toBeGreaterThan(g1 + 100);
+ expect(b1 - b0).toBeGreaterThan(g1 - g0 + 30);
+ // Nothing above the far floor: it keeps reflecting the environment.
+ const far = (px: Uint8ClampedArray) => mean(px, 240, 150, 300, 175);
+ const [fr0, fg0, fb0] = far(off);
+ const [fr1, fg1, fb1] = far(on);
+ expect(
+ Math.abs(fr1 - fr0) + Math.abs(fg1 - fg0) + Math.abs(fb1 - fb0),
+ ).toBeLessThan(3);
+ });
+
+ it("leaves rough surfaces above maxRoughness to the environment", async () => {
+ const rough: Floor = { ...CHROME, roughness: 0.8 };
+ const off = await render(scene(rough, {}));
+ const on = await render(scene(rough, { ssr: { maxRoughness: 0.5 } }));
+ let diff = 0;
+ for (let i = 0; i < off.length; i++)
+ diff += Math.abs((off[i] ?? 0) - (on[i] ?? 0));
+ expect(diff / (W * H)).toBeLessThan(0.05);
+ });
+
+ it("bleeds an emissive object's color onto a matte floor", async () => {
+ const off = await render(scene(MATTE, {}));
+ const on = await render(scene(MATTE, { gi: true }));
+ // On the floor just below the sphere's base red and blue rise
+ // against green: magenta light.
+ const s = bounds(off, isSphere);
+ const cx = Math.round((s.x0 + s.x1) / 2);
+ const [r0, g0, b0] = mean(off, cx - 10, s.y1 + 2, cx + 10, s.y1 + 10);
+ const [r1, g1, b1] = mean(on, cx - 10, s.y1 + 2, cx + 10, s.y1 + 10);
+ expect(r1 - r0).toBeGreaterThan(25);
+ expect(b1 - b0).toBeGreaterThan(5);
+ expect(Math.abs(g1 - g0)).toBeLessThan(6);
+ // Far from the sphere the floor is lit as before.
+ const far = (px: Uint8ClampedArray) => luma(mean(px, 20, 150, 60, 175));
+ expect(Math.abs(far(on) - far(off))).toBeLessThan(3);
+ });
+
+ it("darkens environment light where a box meets the floor", async () => {
+ const comp = (gi: boolean) =>
+ scene(
+ MATTE,
+ { intensity: 2.5, ...(gi && { gi: { intensity: 0 } }) },
+ { box: true },
+ );
+ const off = await render(comp(false));
+ const on = await render(comp(true));
+ // The grey box: blue-leaning and darker than the lit floor.
+ const b = bounds(off, ([r, , bl]) => bl > r + 25 && r < 120);
+ const contact = (px: Uint8ClampedArray) =>
+ luma(mean(px, b.x0 + 4, b.y1, b.x1 - 4, b.y1 + 3));
+ const open = (px: Uint8ClampedArray) => luma(mean(px, 40, 150, 80, 170));
+ expect(contact(on)).toBeLessThan(contact(off) - 8);
+ expect(Math.abs(open(on) - open(off))).toBeLessThan(2);
+ });
+
+ it("keeps comp.toSpec() schema-valid with ssr and gi settings", () => {
+ const comp = scene(CHROME, {
+ ssr: { intensity: 0.7, maxRoughness: 0.4, thickness: 80, steps: 48 },
+ gi: { intensity: 1.5, radius: 300, samples: 8 },
+ });
+ expect(CompositorProgramSchema.safeParse(comp.toSpec()).success).toBe(true);
+ const bad = scene(CHROME, { ssr: { steps: 8 } });
+ expect(CompositorProgramSchema.safeParse(bad.toSpec()).success).toBe(false);
+ });
+});
diff --git a/packages/webgpu-renderers/src/math3d/environment3d.ts b/packages/webgpu-renderers/src/math3d/environment3d.ts
index 59dc6c79..8b9570ad 100644
--- a/packages/webgpu-renderers/src/math3d/environment3d.ts
+++ b/packages/webgpu-renderers/src/math3d/environment3d.ts
@@ -82,6 +82,28 @@ export interface Environment3DVolumetricFog {
noise?: boolean | Environment3DVolumetricFogNoise;
}
+/** Screen-space reflections: glossy surfaces reflect what the camera sees. */
+export interface Environment3DSsrOptions {
+ /** How fully a found reflection replaces the environment's, 0..1. Default 0.85. */
+ intensity?: number;
+ /** Roughest surface that traces reflections (0..1); rougher ones keep the environment. Default 0.6. */
+ maxRoughness?: number;
+ /** How far behind a surface, in world px, a ray still counts as hitting it. Default 120. */
+ thickness?: number;
+ /** Hi-Z march iterations per ray (16..64). Default 32. */
+ steps?: number;
+}
+
+/** Screen-space diffuse GI: ambient occlusion plus one bounce of visible light. */
+export interface Environment3DGiOptions {
+ /** Strength of the bounced light, 0..4. Default 1. */
+ intensity?: number;
+ /** Gather radius in world px. Default 400. */
+ radius?: number;
+ /** Horizon-scan directions per pixel (4..16). Default 6. */
+ samples?: number;
+}
+
export interface Environment3DOptions {
preset?: EnvironmentPreset;
/** Equirectangular panorama for real HDRI IBL: a `.hdr` (Radiance RGBE) or `.exr` (OpenEXR) path, or the file's bytes. */
@@ -105,6 +127,10 @@ export interface Environment3DOptions {
outlines?: boolean | GeometryOutlineOptions;
/** Froxel-style volumetric participating media & shadowed light shafts (god rays). */
volumetricFog?: boolean | Environment3DVolumetricFog;
+ /** Screen-space reflections of nearby geometry and emissives on glossy surfaces. */
+ ssr?: boolean | Environment3DSsrOptions;
+ /** Screen-space diffuse GI: occlusion and color bleeding from visible surfaces. */
+ gi?: boolean | Environment3DGiOptions;
}
interface PresetDef {
@@ -221,6 +247,49 @@ export interface ResolvedEnvironment {
opacity: number;
};
volumetricFog?: ResolvedVolumetricFog;
+ ssr?: ResolvedSsr;
+ gi?: ResolvedGi;
+}
+
+export interface ResolvedSsr {
+ intensity: number;
+ maxRoughness: number;
+ thickness: number;
+ steps: number;
+}
+
+export interface ResolvedGi {
+ intensity: number;
+ radius: number;
+ samples: number;
+}
+
+const clamp = (v: number, lo: number, hi: number) =>
+ Math.max(lo, Math.min(hi, v));
+
+export function resolveSsr(
+ ssr: boolean | Environment3DSsrOptions | undefined,
+): ResolvedSsr | undefined {
+ if (!ssr) return undefined;
+ const cfg: Environment3DSsrOptions = ssr === true ? {} : ssr;
+ return {
+ intensity: clamp(cfg.intensity ?? 0.85, 0, 1),
+ maxRoughness: clamp(cfg.maxRoughness ?? 0.6, 0, 1),
+ thickness: Math.max(1, cfg.thickness ?? 120),
+ steps: Math.round(clamp(cfg.steps ?? 32, 16, 64)),
+ };
+}
+
+export function resolveGi(
+ gi: boolean | Environment3DGiOptions | undefined,
+): ResolvedGi | undefined {
+ if (!gi) return undefined;
+ const cfg: Environment3DGiOptions = gi === true ? {} : gi;
+ return {
+ intensity: clamp(cfg.intensity ?? 1, 0, 4),
+ radius: Math.max(1, cfg.radius ?? 400),
+ samples: Math.round(clamp(cfg.samples ?? 6, 4, 16)),
+ };
}
export function resolveVolumetricFog(
@@ -301,6 +370,8 @@ export function resolveEnvironment(
}
: undefined,
volumetricFog: resolveVolumetricFog(opts.volumetricFog, horizonLinear),
+ ssr: resolveSsr(opts.ssr),
+ gi: resolveGi(opts.gi),
};
}
diff --git a/packages/webgpu-renderers/src/math3d/light3d.ts b/packages/webgpu-renderers/src/math3d/light3d.ts
index 3bef862a..e2a5a89f 100644
--- a/packages/webgpu-renderers/src/math3d/light3d.ts
+++ b/packages/webgpu-renderers/src/math3d/light3d.ts
@@ -75,9 +75,16 @@ export const MAX_LIGHTS = 8;
/**
* 16 (ambient) + 16 (params) + 8 * 64 (lights), then the physical-shading
* block appended after them: 8 vec4 (128) + shadow matrix (64) +
- * floorParams (16) + HDRI irradiance SH (9 vec4, 144).
+ * floorParams (16) + HDRI irradiance SH (9 vec4, 144) + screen indirect (16).
*/
-export const LIGHT_UNIFORM_SIZE_BYTES = 544 + 128 + 64 + 16 + 144;
+export const LIGHT_UNIFORM_SIZE_BYTES = 544 + 128 + 64 + 16 + 144 + 16;
+
+/**
+ * Which half of a screen-space indirect (SSR / GI) frame a pass draws:
+ * `radiance` writes the unfogged scene radiance the traces read; `apply`
+ * shades with the traced reflections and bounce light.
+ */
+export type ScreenIndirectPass = "radiance" | "apply";
/** A prefiltered HDRI as the lights uniform describes it. */
export interface HdriUniforms {
@@ -300,6 +307,7 @@ export const Light3D = {
shadow?: ShadowUniformInfo | null,
isReflectionPass = false,
hdri?: HdriUniforms,
+ screenIndirect?: ScreenIndirectPass,
): Float32Array {
const buffer = new Float32Array(LIGHT_UNIFORM_SIZE_BYTES / 4);
Light3D.packPhysicalBlock(
@@ -309,6 +317,7 @@ export const Light3D = {
shadow,
isReflectionPass,
hdri,
+ screenIndirect,
);
if ((!lights || lights.length === 0) && !environment) {
@@ -459,6 +468,7 @@ export const Light3D = {
shadow?: ShadowUniformInfo | null,
isReflectionPass = false,
hdri?: HdriUniforms,
+ screenIndirect?: ScreenIndirectPass,
): void {
const base = 8 + MAX_LIGHTS * 16; // first float after the lights array
let ambR = 0;
@@ -480,9 +490,22 @@ export const Light3D = {
buffer[base + 3] = 1; // exposure multiplier
let envIntensity = 1.0;
+ // x = 0 off, 1 radiance pass, 2 apply; y / z = SSR / GI strength (-1 off); w = SSR max roughness.
+ buffer.set([0, -1, -1, 0], base + 88);
if (environment) {
const env = resolveEnvironment(environment);
envIntensity = env.intensity;
+ if (screenIndirect && !isReflectionPass && (env.ssr || env.gi)) {
+ buffer.set(
+ [
+ screenIndirect === "radiance" ? 1 : 2,
+ env.ssr?.intensity ?? -1,
+ env.gi?.intensity ?? -1,
+ env.ssr?.maxRoughness ?? 0,
+ ],
+ base + 88,
+ );
+ }
// 1 procedural; 2 + max mip with a prefiltered HDRI cubemap bound.
const envMode = hdri ? 2 + hdri.maxMip : 1;
if (hdri) buffer.set(hdri.sh.subarray(0, 36), base + 52);
diff --git a/packages/webgpu-renderers/src/math3d/screen-indirect.test.ts b/packages/webgpu-renderers/src/math3d/screen-indirect.test.ts
new file mode 100644
index 00000000..44d0af10
--- /dev/null
+++ b/packages/webgpu-renderers/src/math3d/screen-indirect.test.ts
@@ -0,0 +1,54 @@
+import { describe, expect, it } from "vitest";
+import { resolveGi, resolveSsr } from "./environment3d.js";
+import { LIGHT_UNIFORM_SIZE_BYTES, Light3D, MAX_LIGHTS } from "./light3d.js";
+
+/** First float of `LightsUniforms.indirect`. */
+const INDIRECT = 8 + MAX_LIGHTS * 16 + 88;
+
+describe("screen-space indirect settings", () => {
+ it("resolves defaults and clamps ssr / gi settings", () => {
+ expect(resolveSsr(undefined)).toBeUndefined();
+ expect(resolveSsr(false)).toBeUndefined();
+ expect(resolveSsr(true)).toEqual({
+ intensity: 0.85,
+ maxRoughness: 0.6,
+ thickness: 120,
+ steps: 32,
+ });
+ expect(
+ resolveSsr({ intensity: 3, maxRoughness: -1, thickness: 0, steps: 200 }),
+ ).toEqual({ intensity: 1, maxRoughness: 0, thickness: 1, steps: 64 });
+ expect(resolveGi(true)).toEqual({ intensity: 1, radius: 400, samples: 6 });
+ expect(resolveGi({ intensity: 9, radius: -5, samples: 2.6 })).toEqual({
+ intensity: 4,
+ radius: 1,
+ samples: 4,
+ });
+ });
+
+ it("packs the pass mode and strengths after the SH block", () => {
+ expect(INDIRECT * 4 + 16).toBe(LIGHT_UNIFORM_SIZE_BYTES);
+ const env = { ssr: { intensity: 0.5, maxRoughness: 0.3 }, gi: true };
+ const at = (b: Float32Array) =>
+ Array.from(b.subarray(INDIRECT, INDIRECT + 4));
+ const pack = (pass?: "radiance" | "apply", reflection = false) =>
+ at(
+ Light3D.packLightsUniforms([], env, null, reflection, undefined, pass),
+ );
+ expect(pack()).toEqual([0, -1, -1, 0]);
+ expect(pack("radiance")[0]).toBe(1);
+ expect(pack("apply").map((v) => +v.toFixed(3))).toEqual([2, 0.5, 1, 0.3]);
+ // The planar floor reflection never reads traced light.
+ expect(pack("apply", true)).toEqual([0, -1, -1, 0]);
+ // Without gi, its strength reads as off.
+ const ssrOnly = Light3D.packLightsUniforms(
+ [],
+ { ssr: true },
+ null,
+ false,
+ undefined,
+ "apply",
+ );
+ expect(at(ssrOnly)[2]).toBe(-1);
+ });
+});
diff --git a/packages/webgpu-renderers/src/renderer3d/index.ts b/packages/webgpu-renderers/src/renderer3d/index.ts
index 6d5c25bc..9c3aee44 100644
--- a/packages/webgpu-renderers/src/renderer3d/index.ts
+++ b/packages/webgpu-renderers/src/renderer3d/index.ts
@@ -13,6 +13,7 @@ export * from "./shadow-depth.js";
export * from "./shadow-frustum.js";
export * from "./shadow-pipeline.js";
export * from "./ssao-pipeline.js";
+export * from "./ssr-gi-pipeline.js";
export * from "./surface-params.js";
export * from "./swarm3d-pipeline.js";
export * from "./text-extruder.js";
diff --git a/packages/webgpu-renderers/src/renderer3d/quad3d-pipeline.ts b/packages/webgpu-renderers/src/renderer3d/quad3d-pipeline.ts
index 5037c42f..fac4c754 100644
--- a/packages/webgpu-renderers/src/renderer3d/quad3d-pipeline.ts
+++ b/packages/webgpu-renderers/src/renderer3d/quad3d-pipeline.ts
@@ -56,6 +56,28 @@ export function createLightsLayout(
visibility: GPUShaderStage.FRAGMENT,
sampler: { type: "filtering" },
},
+ // Screen-space indirect light (SsrGiPipeline): reflection hits,
+ // the radiance pyramid they read and the diffuse bounce.
+ {
+ binding: 6,
+ visibility: GPUShaderStage.FRAGMENT,
+ texture: { sampleType: "unfilterable-float" },
+ },
+ {
+ binding: 7,
+ visibility: GPUShaderStage.FRAGMENT,
+ texture: { sampleType: "float" },
+ },
+ {
+ binding: 8,
+ visibility: GPUShaderStage.FRAGMENT,
+ texture: { sampleType: "float" },
+ },
+ {
+ binding: 9,
+ visibility: GPUShaderStage.FRAGMENT,
+ sampler: { type: "filtering" },
+ },
],
});
}
diff --git a/packages/webgpu-renderers/src/renderer3d/renderer3d.ts b/packages/webgpu-renderers/src/renderer3d/renderer3d.ts
index 7b3fb0ca..d091f905 100644
--- a/packages/webgpu-renderers/src/renderer3d/renderer3d.ts
+++ b/packages/webgpu-renderers/src/renderer3d/renderer3d.ts
@@ -42,6 +42,7 @@ import {
type Light3DOptions,
type Mat4,
Matrix4Math,
+ type ScreenIndirectPass,
type Vec3,
Vector3Math,
} from "../math3d/index.js";
@@ -72,6 +73,16 @@ import {
transformAabb,
} from "./shadow-frustum.js";
import { Slug3DPipeline } from "./slug3d-pipeline.js";
+import {
+ HIZ_FORMAT,
+ HIZ_LEVELS,
+ mipLevels,
+ RADIANCE_LEVELS,
+ SCREEN_GI_FORMAT,
+ SCREEN_RADIANCE_FORMAT,
+ SSR_HIT_FORMAT,
+ SsrGiPipeline,
+} from "./ssr-gi-pipeline.js";
import type { SurfaceParams } from "./surface-params.js";
import { Swarm3DPipeline } from "./swarm3d-pipeline.js";
import { VolumetricFogPipeline } from "./volumetric-fog-pipeline.js";
@@ -235,6 +246,18 @@ export interface Scene3DWorld {
environment?: Environment3DOptions | null;
/** From `renderShadowMap`, when a light casts shadows. */
shadow?: ShadowUniformInfo | ShadowUniformInfo[] | null;
+ /**
+ * Screen-space reflections / GI (`environment.ssr`, `environment.gi`) take
+ * two passes: `radiance`, then `traceScreenIndirect`, then `apply`.
+ */
+ screenIndirect?: ScreenIndirectPass;
+}
+
+/** Textures one `traceScreenIndirect` writes and the `apply` pass reads. */
+interface ScreenIndirectTextures {
+ hits: GPUTexture;
+ radiance: GPUTexture;
+ gi: GPUTexture;
}
/** Something that can fall into a shadow map. */
@@ -315,6 +338,10 @@ export class Renderer3D {
private outlinePipeline: GeometryOutlinePipeline | null = null;
private geometryResolvePipeline: GeometryResolvePipeline | null = null;
private volumetricFogPipeline: VolumetricFogPipeline | null = null;
+ private ssrGiPipeline: SsrGiPipeline | null = null;
+ private screenIndirect: ScreenIndirectTextures | null = null;
+ private placeholderScreenIndirect: ScreenIndirectTextures | null = null;
+ private screenSampler: GPUSampler | null = null;
private lastCameraBuffer: GPUBuffer | null = null;
/**
@@ -446,9 +473,14 @@ export class Renderer3D {
label: string,
width: number,
height: number,
- desc: { format: GPUTextureFormat; usage: number; sampleCount?: number },
+ desc: {
+ format: GPUTextureFormat;
+ usage: number;
+ sampleCount?: number;
+ mipLevelCount?: number;
+ },
): GPUTexture {
- const key = `${label}:${width}x${height}:${desc.sampleCount ?? 1}:${desc.usage}`;
+ const key = `${label}:${width}x${height}:${desc.sampleCount ?? 1}:${desc.mipLevelCount ?? 1}:${desc.usage}`;
this.attachmentsUsed.add(key);
let texture = this.attachments.get(key);
if (!texture) {
@@ -472,6 +504,7 @@ export class Renderer3D {
this.outlinePipeline?.reset();
this.bloomPipeline?.resetPools();
this.volumetricFogPipeline?.resetPools();
+ this.ssrGiPipeline?.resetPools();
this.cameraPool.reset();
// The cached camera buffer goes back to the pool and may be handed
// out again (e.g. to a shadow pass's light camera): never reuse it
@@ -729,6 +762,7 @@ export class Renderer3D {
Array.isArray(world?.shadow) ? world.shadow[0] : world?.shadow,
false,
hdri,
+ world?.screenIndirect,
);
return this.lightsPool.getBuffer(this.device, lightsData);
}
@@ -740,6 +774,7 @@ export class Renderer3D {
lights: Light3DOptions[],
shadows: ShadowUniformInfo[],
environment?: Environment3DOptions | null,
+ screenIndirect?: ScreenIndirectPass,
): GPUBindGroup {
const data = Light3D.packDirectLights(lights, shadows);
if (data.byteLength > this.device.limits.maxStorageBufferBindingSize)
@@ -793,10 +828,109 @@ export class Renderer3D {
{ binding: 3, resource: { buffer: directBuffer } },
{ binding: 4, resource: envTex.createView({ dimension: "cube" }) },
{ binding: 5, resource: this.envSampler },
+ ...this.screenIndirectEntries(screenIndirect),
],
});
}
+ /** Group 3 bindings 6..9: the traced screen indirect light, or 1×1 stand-ins. */
+ private screenIndirectEntries(
+ pass?: ScreenIndirectPass,
+ ): GPUBindGroupEntry[] {
+ this.screenSampler ??= this.device.createSampler({
+ label: "ScreenIndirectSampler",
+ magFilter: "linear",
+ minFilter: "linear",
+ mipmapFilter: "linear",
+ addressModeU: "clamp-to-edge",
+ addressModeV: "clamp-to-edge",
+ });
+ const stand = (format: GPUTextureFormat) =>
+ this.device.createTexture({
+ label: "ScreenIndirectPlaceholder",
+ size: { width: 1, height: 1 },
+ format,
+ usage: GPUTextureUsage.TEXTURE_BINDING,
+ });
+ this.placeholderScreenIndirect ??= {
+ hits: stand(SSR_HIT_FORMAT),
+ radiance: stand(SCREEN_RADIANCE_FORMAT),
+ gi: stand(SCREEN_GI_FORMAT),
+ };
+ const textures =
+ pass === "apply" && this.screenIndirect
+ ? this.screenIndirect
+ : this.placeholderScreenIndirect;
+ return [
+ { binding: 6, resource: textures.hits.createView() },
+ { binding: 7, resource: textures.radiance.createView() },
+ { binding: 8, resource: textures.gi.createView() },
+ { binding: 9, resource: this.screenSampler },
+ ];
+ }
+
+ /**
+ * Traces screen-space reflections and diffuse GI from the radiance pass
+ * just ended (`beginPass` with `screenIndirect: "radiance"`, a geometry
+ * target and `writeHdr`), for the `apply` pass that follows.
+ */
+ traceScreenIndirect(
+ encoder: GPUCommandEncoder,
+ cameraBuffer: GPUBuffer,
+ environment: Environment3DOptions,
+ ): void {
+ const resolved = resolveEnvironment(environment);
+ const geometry = this.linearDepthTexture;
+ const radiance = this.hdrTexture;
+ if (!geometry || !radiance)
+ throw new Error(
+ "traceScreenIndirect needs a radiance pass with a geometry target and writeHdr",
+ );
+ // The radiance pass kept its geometry samples: resolve by nearest sample.
+ this.resolveGeometry(encoder, geometry);
+ const { width, height } = geometry;
+ const storage =
+ GPUTextureUsage.STORAGE_BINDING | GPUTextureUsage.TEXTURE_BINDING;
+ const target = (
+ label: string,
+ format: GPUTextureFormat,
+ mipLevelCount = 1,
+ ) =>
+ this.attachment(label, width, height, {
+ format,
+ usage: storage,
+ mipLevelCount,
+ });
+ const textures: ScreenIndirectTextures = {
+ hits: target("Renderer3DSsrHits", SSR_HIT_FORMAT),
+ radiance: target(
+ "Renderer3DScreenRadiance",
+ SCREEN_RADIANCE_FORMAT,
+ mipLevels(width, height, RADIANCE_LEVELS),
+ ),
+ gi: target("Renderer3DScreenGi", SCREEN_GI_FORMAT),
+ };
+ this.ssrGiPipeline ??= new SsrGiPipeline(this.device);
+ this.ssrGiPipeline.run({
+ encoder,
+ cameraBuffer,
+ geometry,
+ radiance,
+ hits: textures.hits,
+ radiancePyramid: textures.radiance,
+ bounce: textures.gi,
+ bounceScratch: target("Renderer3DScreenGiScratch", SCREEN_GI_FORMAT),
+ hiz: target(
+ "Renderer3DHiZ",
+ HIZ_FORMAT,
+ mipLevels(width, height, HIZ_LEVELS),
+ ),
+ ssr: resolved.ssr,
+ gi: resolved.gi,
+ });
+ this.screenIndirect = textures;
+ }
+
/** Local bounds of a mesh, computed once. */
private meshAabb(mesh: Mesh3DData): Aabb {
let box = this.meshBounds.get(mesh);
@@ -1117,6 +1251,7 @@ export class Renderer3D {
: [world.shadow]
: [],
world?.environment,
+ world?.screenIndirect,
);
const msaa = this.sampleCount > 1;
@@ -1185,8 +1320,12 @@ export class Renderer3D {
{ r: Math.min(camera.far, 65504), g: 0.5, b: 0.5, a: 0 },
"clear",
);
- // Outline metadata needs a nearest-sample resolve, not a color average.
- if (msaa && world?.environment?.outlines) {
+ // Outline metadata and screen-space traces need a nearest-sample
+ // resolve (see GeometryResolvePipeline), not an average.
+ if (
+ msaa &&
+ (world?.environment?.outlines || world?.screenIndirect === "radiance")
+ ) {
geometryAttachment.resolveTarget = undefined;
geometryAttachment.storeOp = "store";
}
@@ -2344,6 +2483,9 @@ export class Renderer3D {
this.bloomPipeline?.destroy();
this.outlinePipeline?.destroy();
this.volumetricFogPipeline?.destroy();
+ this.ssrGiPipeline?.destroy();
+ for (const t of Object.values(this.placeholderScreenIndirect ?? {}))
+ t.destroy();
this.depthTexture?.destroy();
for (const texture of this.shadowTextures.values()) texture.destroy();
this.shadowTextures.clear();
diff --git a/packages/webgpu-renderers/src/renderer3d/ssr-gi-pipeline.ts b/packages/webgpu-renderers/src/renderer3d/ssr-gi-pipeline.ts
new file mode 100644
index 00000000..fa42015b
--- /dev/null
+++ b/packages/webgpu-renderers/src/renderer3d/ssr-gi-pipeline.ts
@@ -0,0 +1,669 @@
+/**
+ * Lumen-lite screen-space indirect light, traced from one radiance pass:
+ *
+ * 1. Hi-Z: a min-depth pyramid over the resolved geometry buffer.
+ * 2. SSR: every pixel marches its mirror reflection through the pyramid,
+ * skipping empty space a whole cell at a time, and stores the pixel it
+ * hit with a confidence (screen edge, back faces, thickness). Glossy
+ * surfaces do not jitter rays: the shading pass reads the radiance
+ * pyramid at the level matching their reflection cone, so reflections
+ * are noise-free and identical from frame to frame.
+ * 3. GI: a horizon scan around each pixel gathers ambient visibility and
+ * the light leaving the surfaces that rise above the horizon (one
+ * diffuse bounce), then a depth- and normal-aware blur denoises it.
+ *
+ * The shading pass (see `screenIndirectAt` in lighting3d.ts) folds both into
+ * each material's environment terms before tone mapping and fog.
+ */
+
+import type { ResolvedGi, ResolvedSsr } from "../math3d/index.js";
+import { BufferPool } from "../renderer2d/buffer-pool.js";
+import { cameraUniformsWgsl } from "../shaders/lighting3d.js";
+
+/** Reflection hits: pixel positions need full float precision at 4K. */
+export const SSR_HIT_FORMAT: GPUTextureFormat = "rgba32float";
+export const SCREEN_RADIANCE_FORMAT: GPUTextureFormat = "rgba16float";
+export const SCREEN_GI_FORMAT: GPUTextureFormat = "rgba16float";
+/** Hi-Z: r = nearest, g = farthest depth in each cell. */
+export const HIZ_FORMAT: GPUTextureFormat = "rg32float";
+/** Hi-Z levels: down to 64 px cells. */
+export const HIZ_LEVELS = 7;
+/** Radiance pyramid levels: enough for a rough lobe's footprint. */
+export const RADIANCE_LEVELS = 7;
+const PARAMS_BYTES = 48;
+
+/** Mip levels of a full chain for `width`×`height`, capped at `max`. */
+export function mipLevels(width: number, height: number, max: number): number {
+ return Math.min(max, Math.floor(Math.log2(Math.max(width, height))) + 1);
+}
+
+const geometryWgsl = /* wgsl */ `
+${cameraUniformsWgsl}
+struct Params {
+ size : vec2<f32>,
+ maxLevel : f32,
+ steps : f32,
+ thickness : f32,
+ ssrOn : f32,
+ giRadius : f32,
+ giSamples : f32,
+ blurDir : vec2<f32>,
+ _pad : vec2<f32>,
+};
+@group(0) @binding(0) var<uniform> cam : CameraUniforms;
+@group(0) @binding(1) var<uniform> params : Params;
+@group(0) @binding(2) var geometry : texture_2d<f32>;
+
+const PI = 3.14159265359;
+
+fn isBackground(depth: f32) -> bool {
+ return depth >= min(cam.cameraDir.w, 65504.0) * 0.999;
+}
+
+// Inverse of geometryPixel's octahedral encoding.
+fn decodeNormal(e: vec2<f32>) -> vec3<f32> {
+ let f = e * 2.0 - 1.0;
+ var n = vec3<f32>(f.x, f.y, 1.0 - abs(f.x) - abs(f.y));
+ let t = max(-n.z, 0.0);
+ n.x += select(t, -t, n.x >= 0.0);
+ n.y += select(t, -t, n.y >= 0.0);
+ return normalize(n);
+}
+
+struct PixelRay {
+ origin : vec3<f32>,
+ dir : vec3<f32>,
+};
+
+// The camera ray through a pixel position; perspective or orthographic.
+fn pixelRay(px: vec2<f32>) -> PixelRay {
+ let ndc = vec2<f32>(px.x / params.size.x * 2.0 - 1.0, 1.0 - px.y / params.size.y * 2.0);
+ let a = cam.invViewProjMatrix * vec4<f32>(ndc, 0.0, 1.0);
+ let b = cam.invViewProjMatrix * vec4<f32>(ndc, 1.0, 1.0);
+ var r: PixelRay;
+ r.origin = a.xyz / a.w;
+ r.dir = normalize(b.xyz / b.w - r.origin);
+ return r;
+}
+
+fn linearDepth(p: vec3<f32>) -> f32 {
+ return dot(p - cam.cameraPos.xyz, cam.cameraDir.xyz);
+}
+
+// The world point at linear depth \`depth\` along a pixel's camera ray.
+fn worldOnRay(r: PixelRay, depth: f32) -> vec3<f32> {
+ return r.origin + r.dir * ((depth - linearDepth(r.origin)) / dot(r.dir, cam.cameraDir.xyz));
+}
+
+// Pixel position (xy) and clip w of a world point.
+fn project(p: vec3<f32>) -> vec3<f32> {
+ let c = cam.viewProjMatrix * vec4<f32>(p, 1.0);
+ let ndc = c.xy / c.w;
+ return vec3<f32>((ndc.x * 0.5 + 0.5) * params.size.x, (0.5 - ndc.y * 0.5) * params.size.y, c.w);
+}
+
+// A surface normal turned toward the camera ray that sees it.
+fn facing(n: vec3<f32>, viewDir: vec3<f32>) -> vec3<f32> {
+ return select(n, -n, dot(n, viewDir) > 0.0);
+}
+`;
+
+const hizWgsl = /* wgsl */ `
+@group(0) @binding(0) var src : texture_2d<f32>;
+@group(0) @binding(1) var dst : texture_storage_2d<rg32float, write>;
+
+@compute @workgroup_size(8, 8)
+fn init(@builtin(global_invocation_id) id : vec3<u32>) {
+ let size = textureDimensions(dst);
+ if (id.x >= size.x || id.y >= size.y) { return; }
+ let d = textureLoad(src, id.xy, 0).r;
+ textureStore(dst, id.xy, vec4<f32>(d, d, 0.0, 0.0));
+}
+
+// Min and max over the 2x2 (2x3 / 3x3 at an odd edge) source texels a cell covers.
+@compute @workgroup_size(8, 8)
+fn down(@builtin(global_invocation_id) id : vec3<u32>) {
+ let size = textureDimensions(dst);
+ if (id.x >= size.x || id.y >= size.y) { return; }
+ let srcSize = vec2<i32>(textureDimensions(src));
+ let base = vec2<i32>(id.xy) * 2;
+ let extra = vec2<i32>(
+ select(1, 2, id.x == size.x - 1u && (srcSize.x & 1) == 1),
+ select(1, 2, id.y == size.y - 1u && (srcSize.y & 1) == 1),
+ );
+ var lo = 3.0e38;
+ var hi = 0.0;
+ for (var y = 0; y <= extra.y; y++) {
+ for (var x = 0; x <= extra.x; x++) {
+ let d = textureLoad(src, min(base + vec2<i32>(x, y), srcSize - 1), 0).rg;
+ lo = min(lo, d.x);
+ hi = max(hi, d.y);
+ }
+ }
+ textureStore(dst, id.xy, vec4<f32>(lo, hi, 0.0, 0.0));
+}
+`;
+
+const radianceWgsl = /* wgsl */ `
+@group(0) @binding(0) var src : texture_2d<f32>;
+@group(0) @binding(1) var dst : texture_storage_2d<rgba16float, write>;
+
+@compute @workgroup_size(8, 8)
+fn init(@builtin(global_invocation_id) id : vec3<u32>) {
+ let size = textureDimensions(dst);
+ if (id.x >= size.x || id.y >= size.y) { return; }
+ textureStore(dst, id.xy, textureLoad(src, id.xy, 0));
+}
+
+// Premultiplied box filter: coverage averages with the light, so reading
+// rgb / a later recovers the radiance of what is there.
+@compute @workgroup_size(8, 8)
+fn down(@builtin(global_invocation_id) id : vec3<u32>) {
+ let size = textureDimensions(dst);
+ if (id.x >= size.x || id.y >= size.y) { return; }
+ let srcMax = vec2<i32>(textureDimensions(src)) - 1;
+ let base = vec2<i32>(id.xy) * 2;
+ var sum = vec4<f32>(0.0);
+ for (var y = 0; y < 2; y++) {
+ for (var x = 0; x < 2; x++) {
+ sum += textureLoad(src, min(base + vec2<i32>(x, y), srcMax), 0);
+ }
+ }
+ textureStore(dst, id.xy, sum * 0.25);
+}
+`;
+
+const traceWgsl = /* wgsl */ `
+${geometryWgsl}
+@group(0) @binding(3) var hiz : texture_2d<f32>;
+@group(0) @binding(4) var hits : texture_storage_2d<rgba32float, write>;
+
+struct ScreenRay {
+ s0 : vec2<f32>,
+ d : vec2<f32>,
+ // Linear depth over screen distance is perspective-correct as
+ // (depth / w, 1 / w), both linear in screen space.
+ zk0 : f32,
+ zk1 : f32,
+ k0 : f32,
+ k1 : f32,
+ tMax : f32,
+};
+
+fn depthAt(r: ScreenRay, t: f32) -> f32 {
+ return mix(r.zk0, r.zk1, t) / mix(r.k0, r.k1, t);
+}
+
+// Screen parameter where the segment leaves the viewport.
+fn viewportExit(s0: vec2<f32>, d: vec2<f32>) -> f32 {
+ var t = 1.0;
+ if (d.x > 1e-6) { t = min(t, (params.size.x - s0.x) / d.x); }
+ if (d.x < -1e-6) { t = min(t, -s0.x / d.x); }
+ if (d.y > 1e-6) { t = min(t, (params.size.y - s0.y) / d.y); }
+ if (d.y < -1e-6) { t = min(t, -s0.y / d.y); }
+ return t;
+}
+
+// The reflected ray from P along R as a screen segment, clipped to the
+// near plane and the viewport. tMax <= 0: nothing on screen to hit.
+fn screenRay(P: vec3<f32>, R: vec3<f32>, depth: f32) -> ScreenRay {
+ var r: ScreenRay;
+ let near = cam.cameraPos.w;
+ let rdz = dot(R, cam.cameraDir.xyz);
+ var len = cam.cameraDir.w;
+ if (rdz < 0.0) {
+ len = min(len, (depth - near * 1.5) / -rdz);
+ }
+ r.tMax = 0.0;
+ if (len <= 0.0) { return r; }
+ let a = project(P);
+ let end = P + R * len;
+ let b = project(end);
+ r.s0 = a.xy;
+ r.d = b.xy - a.xy;
+ r.k0 = 1.0 / a.z;
+ r.k1 = 1.0 / b.z;
+ r.zk0 = depth * r.k0;
+ r.zk1 = linearDepth(end) * r.k1;
+ if (length(r.d) < 1.0) { return r; }
+ r.tMax = viewportExit(r.s0, r.d);
+ return r;
+}
+
+// Hi-Z march: climb while the ray passes a whole cell in front of its
+// nearest surface, or behind its farthest by more than any pixel in it
+// could still count as a hit; descend when it might touch one; classify the
+// pixel at the finest level. \`steps\` budgets the cells the ray advances through;
+// descending into a cell is free (at most maxLevel times per advance).
+// Returns the hit pixel (xy) and its confidence in w (0: a miss).
+fn hizTrace(r: ScreenRay, P: vec3<f32>, R: vec3<f32>) -> vec4<f32> {
+ let invLen = 1.0 / length(r.d);
+ let eps = 0.02 * invLen;
+ let towardPositive = r.d > vec2<f32>(0.0);
+ let maxLevel = i32(params.maxLevel);
+ let advances = i32(params.steps);
+ var t = 1.5 * invLen;
+ var level = 0;
+ var advanced = 0;
+ // Whether the ray has been in front of the scene since it left its
+ // surface. One that starts out behind its neighbors is inside its own
+ // body (a grazing ray off a convex surface): those are not hits.
+ var seenFront = false;
+ for (var i = 0; i < advances * (maxLevel + 1) && advanced < advances; i++) {
+ if (t >= r.tMax) { break; }
+ let pos = r.s0 + r.d * t;
+ let cellSize = f32(1 << u32(level));
+ let cell = floor(pos / cellSize);
+ let boundary = (cell + select(vec2<f32>(0.0), vec2<f32>(1.0), towardPositive)) * cellSize;
+ let tx = select(1e9, (boundary.x - r.s0.x) / r.d.x, abs(r.d.x) > 1e-6);
+ let ty = select(1e9, (boundary.y - r.s0.y) / r.d.y, abs(r.d.y) > 1e-6);
+ let tExit = min(min(tx, ty), r.tMax);
+ let zEnter = depthAt(r, t);
+ let zExit = depthAt(r, tExit);
+ let levelMax = vec2<i32>(textureDimensions(hiz, level)) - 1;
+ let depths = textureLoad(hiz, clamp(vec2<i32>(cell), vec2<i32>(0), levelMax), level).rg;
+ let zMin = depths.x;
+ let rayNear = min(zEnter, zExit);
+ let span = abs(zExit - zEnter);
+ let inFront = max(zEnter, zExit) < zMin;
+ if (inFront || rayNear - depths.y - span > params.thickness) {
+ t = tExit + eps;
+ level = min(level + 1, maxLevel);
+ advanced++;
+ seenFront = seenFront || inFront;
+ continue;
+ }
+ if (level > 0) {
+ level -= 1;
+ continue;
+ }
+ let behind = rayNear - zMin;
+ if (behind <= 0.0) {
+ // The ray crosses the pixel's depth inside the pixel.
+ return vec4<f32>(cell + 0.5, 0.0, 1.0);
+ }
+ // Behind the pixel's surface: it either met that surface on the way
+ // (its tangent plane meets the ray over this pixel) or is passing
+ // behind it. Pixel depths alone cannot tell, the surface's plane can.
+ let pixel = cell + 0.5;
+ let hitRay = pixelRay(pixel);
+ let hn = facing(decodeNormal(textureLoad(geometry, vec2<i32>(cell), 0).gb), hitRay.dir);
+ let Q = worldOnRay(hitRay, zMin);
+ let denom = dot(R, hn);
+ // Near a silhouette the plane runs along the view ray, where it
+ // meets the reflected ray says little: leave those to the thickness.
+ if (denom < -1e-4 && abs(dot(hn, hitRay.dir)) > 0.25) {
+ let X = project(P + R * (dot(Q - P, hn) / denom)).xy;
+ if (distance(X, pixel) <= 1.5 && distance(X, r.s0) >= 1.5) {
+ return vec4<f32>(pixel, 0.0, 1.0);
+ }
+ }
+ // Otherwise a hit within the surface's assumed thickness, trusted less
+ // the deeper the ray is. A ray covers |zExit - zEnter| of depth per
+ // pixel, so it may have crossed anywhere in that span since its last
+ // step: only depth beyond it counts against the thickness.
+ let past = max(behind - span, 0.0);
+ if (seenFront && past <= params.thickness) {
+ return vec4<f32>(pixel, 0.0, 1.0 - past / params.thickness);
+ }
+ t = tExit + eps;
+ advanced++;
+ }
+ return vec4<f32>(0.0);
+}
+
+@compute @workgroup_size(8, 8)
+fn trace(@builtin(global_invocation_id) id : vec3<u32>) {
+ if (f32(id.x) >= params.size.x || f32(id.y) >= params.size.y) { return; }
+ let ip = vec2<i32>(id.xy);
+ let g = textureLoad(geometry, ip, 0);
+ if (isBackground(g.r)) {
+ textureStore(hits, ip, vec4<f32>(0.0));
+ return;
+ }
+ // z always carries the traced surface's depth: the shading pass checks
+ // it to tell that surface from a transparent one drawn over it.
+ var out = vec4<f32>(0.0, 0.0, g.r, 0.0);
+ if (params.ssrOn > 0.5) {
+ let px = vec2<f32>(id.xy) + 0.5;
+ let ray = pixelRay(px);
+ let P = worldOnRay(ray, g.r);
+ let N = facing(decodeNormal(g.gb), ray.dir);
+ let R = reflect(ray.dir, N);
+ let sr = screenRay(P, R, g.r);
+ if (sr.tMax > 0.0) {
+ let hit = hizTrace(sr, P, R);
+ if (hit.w > 0.0) {
+ let hg = textureLoad(geometry, vec2<i32>(hit.xy), 0);
+ let hitRay = pixelRay(hit.xy);
+ // The camera sees the side of the hit facing it; a ray that
+ // reaches the other side would show light it cannot see.
+ let hn = facing(decodeNormal(hg.gb), hitRay.dir);
+ let frontFace = 1.0 - smoothstep(-0.2, 0.0, dot(hn, R));
+ let edge = min(hit.xy, params.size - hit.xy) / (0.08 * min(params.size.x, params.size.y));
+ let edgeFade = clamp(min(edge.x, edge.y), 0.0, 1.0);
+ // Rays back toward the camera leave the screen's knowledge fast.
+ let toward = 1.0 - smoothstep(0.5, 0.9, dot(R, -cam.cameraDir.xyz));
+ out = vec4<f32>(hit.xy, g.r, hit.w * frontFace * edgeFade * toward);
+ }
+ }
+ }
+ textureStore(hits, ip, out);
+}
+`;
+
+const giWgsl = /* wgsl */ `
+${geometryWgsl}
+@group(0) @binding(3) var radiance : texture_2d<f32>;
+@group(0) @binding(4) var radianceSampler : sampler;
+@group(0) @binding(5) var gi : texture_storage_2d<rgba16float, write>;
+
+const STEPS = 8;
+
+// Jimenez's interleaved gradient noise: a fixed per-pixel rotation, so the
+// same frame always renders the same and the blur removes the pattern.
+fn ign(p: vec2<f32>) -> f32 {
+ return fract(52.9829189 * fract(dot(p, vec2<f32>(0.06711056, 0.00583715))));
+}
+
+@compute @workgroup_size(8, 8)
+fn gather(@builtin(global_invocation_id) id : vec3<u32>) {
+ if (f32(id.x) >= params.size.x || f32(id.y) >= params.size.y) { return; }
+ let ip = vec2<i32>(id.xy);
+ let g = textureLoad(geometry, ip, 0);
+ if (isBackground(g.r)) {
+ textureStore(gi, ip, vec4<f32>(0.0, 0.0, 0.0, 1.0));
+ return;
+ }
+ let px = vec2<f32>(id.xy) + 0.5;
+ let ray = pixelRay(px);
+ let P = worldOnRay(ray, g.r);
+ let N = facing(decodeNormal(g.gb), ray.dir);
+ let right = normalize(vec3<f32>(cam.viewMatrix[0][0], cam.viewMatrix[1][0], cam.viewMatrix[2][0]));
+ let radiusPx = clamp(distance(project(P + right * params.giRadius).xy, px), 2.0, 0.5 * min(params.size.x, params.size.y));
+ let rotation = ign(px);
+ let jitter = ign(px + vec2<f32>(5.588, 3.17));
+ let dirs = i32(params.giSamples);
+ let maxMip = f32(textureNumLevels(radiance) - 1u);
+ var occlusion = 0.0;
+ var bounce = vec3<f32>(0.0);
+ for (var di = 0; di < dirs; di++) {
+ let phi = (f32(di) + rotation) / f32(dirs) * PI;
+ let dir = vec2<f32>(cos(phi), sin(phi));
+ for (var side = -1.0; side <= 1.0; side += 2.0) {
+ // Sine of the horizon's elevation above the tangent plane. The
+ // cosine-weighted share of the hemisphere between elevations
+ // a and b is sin^2 b - sin^2 a, so each surface that rises above
+ // the horizon blocks, and sends its light through, that band.
+ var horizon = 0.0;
+ for (var k = 0; k < STEPS; k++) {
+ let f = (f32(k) + jitter) / f32(STEPS);
+ let rPx = max(1.5, f * f * radiusPx);
+ let sp = px + dir * side * rPx;
+ if (any(sp < vec2<f32>(0.0)) || any(sp >= params.size)) { break; }
+ let sip = vec2<i32>(sp);
+ let sg = textureLoad(geometry, sip, 0);
+ if (isBackground(sg.r)) { continue; }
+ let sray = pixelRay(vec2<f32>(sip) + 0.5);
+ let S = worldOnRay(sray, sg.r);
+ let w = S - P;
+ let dist = length(w);
+ if (dist < 1e-3) { continue; }
+ let h = w / dist;
+ let falloff = 1.0 - smoothstep(0.5 * params.giRadius, params.giRadius, dist);
+ // A small bias keeps flat surfaces from shadowing themselves
+ // through depth quantization.
+ let e = (dot(h, N) - 0.05) * falloff;
+ if (e > horizon) {
+ let sn = facing(decodeNormal(sg.gb), sray.dir);
+ let towardP = max(dot(sn, -h), 0.0);
+ let mip = clamp(log2(max(rPx / f32(STEPS), 1.0)), 0.0, maxMip);
+ let c = textureSampleLevel(radiance, radianceSampler, sp / params.size, mip);
+ let L = select(vec3<f32>(0.0), c.rgb / c.a, c.a > 1e-3);
+ bounce += L * towardP * (e * e - horizon * horizon);
+ horizon = e;
+ }
+ }
+ occlusion += horizon * horizon;
+ }
+ }
+ let count = f32(dirs * 2);
+ textureStore(gi, ip, vec4<f32>(bounce / count, 1.0 - occlusion / count));
+}
+`;
+
+const blurWgsl = /* wgsl */ `
+${geometryWgsl}
+@group(0) @binding(3) var src : texture_2d<f32>;
+@group(0) @binding(4) var dst : texture_storage_2d<rgba16float, write>;
+
+const RADIUS = 5;
+
+// Separable bilateral blur: weights fall off with distance, with depth
+// difference relative to depth, and with normal difference.
+@compute @workgroup_size(8, 8)
+fn blur(@builtin(global_invocation_id) id : vec3<u32>) {
+ if (f32(id.x) >= params.size.x || f32(id.y) >= params.size.y) { return; }
+ let ip = vec2<i32>(id.xy);
+ let g = textureLoad(geometry, ip, 0);
+ if (isBackground(g.r)) {
+ textureStore(dst, ip, textureLoad(src, ip, 0));
+ return;
+ }
+ let n = decodeNormal(g.gb);
+ let maxIp = vec2<i32>(params.size) - 1;
+ let step = vec2<i32>(params.blurDir);
+ var sum = vec4<f32>(0.0);
+ var wsum = 0.0;
+ for (var i = -RADIUS; i <= RADIUS; i++) {
+ let q = clamp(ip + step * i, vec2<i32>(0), maxIp);
+ let qg = textureLoad(geometry, q, 0);
+ if (isBackground(qg.r)) { continue; }
+ let fi = f32(i);
+ let spatial = exp(-fi * fi / (2.0 * 3.0 * 3.0));
+ let dz = abs(qg.r - g.r) / max(g.r, 1.0);
+ let depthW = exp(-dz * 60.0);
+ let normalW = pow(max(abs(dot(decodeNormal(qg.gb), n)), 0.0), 16.0);
+ let w = spatial * depthW * normalW;
+ sum += textureLoad(src, q, 0) * w;
+ wsum += w;
+ }
+ textureStore(dst, ip, sum / max(wsum, 1e-5));
+}
+`;
+
+/** What `SsrGiPipeline.run` reads and where it writes. */
+export interface SsrGiInputs {
+ encoder: GPUCommandEncoder;
+ /** Camera uniform buffer of the radiance pass (`CameraUniforms`). */
+ cameraBuffer: GPUBuffer;
+ /** Resolved single-sample geometry buffer: r = linear depth, gb = octahedral normal. */
+ geometry: GPUTexture;
+ /** Premultiplied linear scene radiance of the radiance pass. */
+ radiance: GPUTexture;
+ /** Full-resolution reflection hits (`SSR_HIT_FORMAT`, storage). */
+ hits: GPUTexture;
+ /** Radiance pyramid (`SCREEN_RADIANCE_FORMAT`, storage, full mip chain). */
+ radiancePyramid: GPUTexture;
+ /** Diffuse bounce + visibility (`SCREEN_GI_FORMAT`, storage). */
+ bounce: GPUTexture;
+ /** Intermediate of the separable blur, same format and size as `bounce`. */
+ bounceScratch: GPUTexture;
+ /** Min/max depth pyramid (`HIZ_FORMAT`, storage, full mip chain). */
+ hiz: GPUTexture;
+ ssr?: ResolvedSsr;
+ gi?: ResolvedGi;
+}
+
+export class SsrGiPipeline {
+ private params = new BufferPool(
+ PARAMS_BYTES,
+ GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+ );
+ private sampler: GPUSampler;
+ private hizInit: GPUComputePipeline;
+ private hizDown: GPUComputePipeline;
+ private radInit: GPUComputePipeline;
+ private radDown: GPUComputePipeline;
+ private trace: GPUComputePipeline;
+ private gather: GPUComputePipeline;
+ private blur: GPUComputePipeline;
+
+ constructor(private device: GPUDevice) {
+ const compute = (label: string, code: string, entryPoint: string) =>
+ device.createComputePipeline({
+ label: `SsrGi.${label}`,
+ layout: "auto",
+ compute: {
+ module: device.createShaderModule({ label: `ssr-gi-${label}`, code }),
+ entryPoint,
+ },
+ });
+ this.hizInit = compute("hizInit", hizWgsl, "init");
+ this.hizDown = compute("hizDown", hizWgsl, "down");
+ this.radInit = compute("radianceInit", radianceWgsl, "init");
+ this.radDown = compute("radianceDown", radianceWgsl, "down");
+ this.trace = compute("trace", traceWgsl, "trace");
+ this.gather = compute("gather", giWgsl, "gather");
+ this.blur = compute("blur", blurWgsl, "blur");
+ this.sampler = device.createSampler({
+ label: "SsrGiRadianceSampler",
+ magFilter: "linear",
+ minFilter: "linear",
+ mipmapFilter: "linear",
+ addressModeU: "clamp-to-edge",
+ addressModeV: "clamp-to-edge",
+ });
+ }
+
+ run(inputs: SsrGiInputs): void {
+ const { encoder, geometry, hits } = inputs;
+ const width = hits.width;
+ const height = hits.height;
+ const groups = (w: number, h: number): [number, number] => [
+ Math.ceil(w / 8),
+ Math.ceil(h / 8),
+ ];
+ const pass = encoder.beginComputePass({ label: "SsrGi" });
+
+ this.buildPyramid(pass, this.hizInit, this.hizDown, geometry, inputs.hiz);
+ this.buildPyramid(
+ pass,
+ this.radInit,
+ this.radDown,
+ inputs.radiance,
+ inputs.radiancePyramid,
+ );
+
+ const params = (blurDir: [number, number]) => {
+ const data = new Float32Array(PARAMS_BYTES / 4);
+ data.set([
+ width,
+ height,
+ inputs.hiz.mipLevelCount - 1,
+ inputs.ssr?.steps ?? 0,
+ inputs.ssr?.thickness ?? 0,
+ inputs.ssr ? 1 : 0,
+ inputs.gi?.radius ?? 0,
+ inputs.gi?.samples ?? 0,
+ blurDir[0],
+ blurDir[1],
+ ]);
+ return this.params.getBuffer(this.device, data);
+ };
+ const shared = (
+ pipeline: GPUComputePipeline,
+ paramsBuffer: GPUBuffer,
+ extra: GPUBindGroupEntry[],
+ ) =>
+ this.device.createBindGroup({
+ layout: pipeline.getBindGroupLayout(0),
+ entries: [
+ { binding: 0, resource: { buffer: inputs.cameraBuffer } },
+ { binding: 1, resource: { buffer: paramsBuffer } },
+ { binding: 2, resource: geometry.createView() },
+ ...extra,
+ ],
+ });
+ const base = params([0, 0]);
+
+ pass.setPipeline(this.trace);
+ pass.setBindGroup(
+ 0,
+ shared(this.trace, base, [
+ { binding: 3, resource: inputs.hiz.createView() },
+ { binding: 4, resource: hits.createView() },
+ ]),
+ );
+ pass.dispatchWorkgroups(...groups(width, height));
+
+ if (inputs.gi) {
+ pass.setPipeline(this.gather);
+ pass.setBindGroup(
+ 0,
+ shared(this.gather, base, [
+ { binding: 3, resource: inputs.radiancePyramid.createView() },
+ { binding: 4, resource: this.sampler },
+ { binding: 5, resource: inputs.bounce.createView() },
+ ]),
+ );
+ pass.dispatchWorkgroups(...groups(width, height));
+ for (const [dir, from, to] of [
+ [[1, 0], inputs.bounce, inputs.bounceScratch],
+ [[0, 1], inputs.bounceScratch, inputs.bounce],
+ ] as const) {
+ pass.setPipeline(this.blur);
+ pass.setBindGroup(
+ 0,
+ shared(this.blur, params([dir[0], dir[1]]), [
+ { binding: 3, resource: from.createView() },
+ { binding: 4, resource: to.createView() },
+ ]),
+ );
+ pass.dispatchWorkgroups(...groups(width, height));
+ }
+ }
+ pass.end();
+ }
+
+ /** Level 0 copies `source`; each level after reduces the one before. */
+ private buildPyramid(
+ pass: GPUComputePassEncoder,
+ init: GPUComputePipeline,
+ down: GPUComputePipeline,
+ source: GPUTexture,
+ pyramid: GPUTexture,
+ ): void {
+ const level = (mip: number) =>
+ pyramid.createView({ baseMipLevel: mip, mipLevelCount: 1 });
+ for (let mip = 0; mip < pyramid.mipLevelCount; mip++) {
+ const pipeline = mip === 0 ? init : down;
+ pass.setPipeline(pipeline);
+ pass.setBindGroup(
+ 0,
+ this.device.createBindGroup({
+ layout: pipeline.getBindGroupLayout(0),
+ entries: [
+ {
+ binding: 0,
+ resource: mip === 0 ? source.createView() : level(mip - 1),
+ },
+ { binding: 1, resource: level(mip) },
+ ],
+ }),
+ );
+ pass.dispatchWorkgroups(
+ Math.ceil(Math.max(1, pyramid.width >> mip) / 8),
+ Math.ceil(Math.max(1, pyramid.height >> mip) / 8),
+ );
+ }
+ }
+
+ resetPools(): void {
+ this.params.reset();
+ }
+
+ destroy(): void {
+ this.params.destroy();
+ }
+}
diff --git a/packages/webgpu-renderers/src/shaders/lighting3d.ts b/packages/webgpu-renderers/src/shaders/lighting3d.ts
index 61d30187..6a57642e 100644
--- a/packages/webgpu-renderers/src/shaders/lighting3d.ts
+++ b/packages/webgpu-renderers/src/shaders/lighting3d.ts
@@ -11,7 +11,8 @@
* procedural studio environment (image-based light), emissive, exposure,
* AgX / ACES tone mapping and display-space fog.
*/
-export const lighting3dWgsl = `
+/** The 3D camera uniform block, as `Renderer3D` packs it. */
+export const cameraUniformsWgsl = `
struct CameraUniforms {
viewMatrix : mat4x4<f32>,
projMatrix : mat4x4<f32>,
@@ -22,6 +23,10 @@ struct CameraUniforms {
dofParams : vec4<f32>, // x = focusDistance, y = fStop, z = maxBlurRadius, w = dofEnabled
screenParams : vec4<f32>, // x = surfaceWidth, y = surfaceHeight, z = time, w = unused
};
+`;
+
+export const lighting3dWgsl = `
+${cameraUniformsWgsl}
struct GPULight {
posType : vec4<f32>, // xyz = position, w = type (0=ambient, 1=directional, 2=point, 3=spot)
@@ -58,6 +63,7 @@ struct LightsUniforms {
shadowMatrix : mat4x4<f32>,
floorParams : vec4<f32>, // x = floorY, y = fadeDistance, z = isReflectionPass, w = environment intensity
envSh : array<vec4<f32>, 9>, // HDRI irradiance / PI as L2 SH (rgb), environment space
+ indirect : vec4<f32>, // x = screen indirect (0 off, 1 radiance pass, 2 apply), y = SSR strength, z = GI strength (-1 off), w = SSR max roughness
};
const PI = 3.14159265359;
@@ -232,6 +238,124 @@ fn envIrradiance(nIn: vec3<f32>) -> vec3<f32> {
return max(e, vec3<f32>(0.0)) * max(0.0, lights.floorParams.w);
}
+// ── Screen-space indirect light ─────────────────────────────────────────
+// A radiance pass renders the scene once; SsrGiPipeline traces reflections
+// and gathers one diffuse bounce from it; the shading pass reads both here,
+// so tone mapping, fog and every material lobe treat them like any other light.
+
+struct ScreenIndirect {
+ valid : bool,
+ /** This fragment's pixel position, and the texel it falls in. */
+ pixel : vec2<f32>,
+ texel : vec2<i32>,
+ /** Linear depth: tells the traced surface's pixels from others. */
+ depth : f32,
+ /** rgb = bounce irradiance / PI, a = ambient visibility. */
+ gi : vec4<f32>,
+};
+
+// Traced results belong to a fragment when the trace started on its surface.
+fn sameSurface(tracedDepth: f32, depth: f32) -> bool {
+ return abs(tracedDepth - depth) <= max(2.0, depth * 0.02);
+}
+
+fn screenIndirectAt(worldPos: vec3<f32>) -> ScreenIndirect {
+ var si: ScreenIndirect;
+ si.valid = false;
+ si.gi = vec4<f32>(0.0, 0.0, 0.0, 1.0);
+ if (lights.indirect.x < 1.5) {
+ return si;
+ }
+ let clip = cam.viewProjMatrix * vec4<f32>(worldPos, 1.0);
+ if (clip.w <= 0.0) {
+ return si;
+ }
+ let size = vec2<f32>(textureDimensions(screenHit));
+ let px = (vec2<f32>(clip.x, -clip.y) / clip.w * 0.5 + 0.5) * size;
+ let ip = vec2<i32>(clamp(px, vec2<f32>(0.0), size - 1.0));
+ // Only the surface the trace started from owns the pixel's result: a
+ // transparent layer in front of it keeps its own environment light.
+ let depth = dot(worldPos - cam.cameraPos.xyz, cam.cameraDir.xyz);
+ if (!sameSurface(textureLoad(screenHit, ip, 0).z, depth)) {
+ return si;
+ }
+ si.valid = true;
+ si.pixel = px;
+ si.texel = ip;
+ si.depth = depth;
+ if (lights.indirect.z >= 0.0) {
+ si.gi = textureLoad(screenGi, ip, 0);
+ }
+ return si;
+}
+
+/// The environment's radiance \`env\` along the reflection, replaced by what
+/// the screen shows there where traced rays found it. Each pixel reuses the
+/// rays of its 3x3 neighbors on the same surface, weighted by their
+/// confidence: one ray per pixel leaves holes and seams where hits are
+/// ambiguous (rays grazing hidden surfaces); pooled, they resolve smoothly.
+fn screenReflection(si: ScreenIndirect, rough: f32, env: vec3<f32>) -> vec3<f32> {
+ if (!si.valid || lights.indirect.y < 0.0) {
+ return env;
+ }
+ let maxRough = max(lights.indirect.w, 1e-3);
+ let fade = 1.0 - smoothstep(maxRough * 0.6, maxRough, rough);
+ if (fade <= 0.0) {
+ return env;
+ }
+ let size = vec2<f32>(textureDimensions(screenRadiance, 0));
+ let maxTexel = vec2<i32>(size) - 1;
+ let maxMip = f32(textureNumLevels(screenRadiance) - 1u);
+ var radiance = vec3<f32>(0.0);
+ var found = 0.0;
+ var rays = 0.0;
+ for (var dy = -1; dy <= 1; dy++) {
+ for (var dx = -1; dx <= 1; dx++) {
+ let hit = textureLoad(screenHit, clamp(si.texel + vec2<i32>(dx, dy), vec2<i32>(0), maxTexel), 0);
+ if (!sameSurface(hit.z, si.depth)) {
+ continue;
+ }
+ rays += 1.0;
+ if (hit.w <= 0.0) {
+ continue;
+ }
+ // A glossy lobe reaches the hit as a cone (half-angle ~ alpha):
+ // read the radiance pyramid at the level matching its footprint.
+ let footprint = 2.4 * rough * rough * distance(hit.xy, si.pixel);
+ let mip = clamp(log2(max(footprint, 1.0)), 0.0, maxMip);
+ let c = textureSampleLevel(screenRadiance, screenSampler, hit.xy / size, mip);
+ if (c.a <= 1e-3) {
+ continue;
+ }
+ let w = hit.w * min(c.a, 1.0);
+ radiance += c.rgb / c.a * w;
+ found += w;
+ }
+ }
+ if (found <= 0.0) {
+ return env;
+ }
+ let confidence = found / rays * fade * lights.indirect.y;
+ return mix(env, radiance / found, confidence);
+}
+
+/// Ambient irradiance / PI, occluded by nearby geometry, plus its bounce light.
+fn screenAmbient(si: ScreenIndirect, irradiance: vec3<f32>) -> vec3<f32> {
+ if (!si.valid || lights.indirect.z < 0.0) {
+ return irradiance;
+ }
+ return irradiance * si.gi.a + si.gi.rgb * lights.indirect.z;
+}
+
+/// Lagarde's specular occlusion from ambient visibility.
+fn screenSpecularOcclusion(si: ScreenIndirect, nDotV: f32, rough: f32) -> f32 {
+ if (!si.valid || lights.indirect.z < 0.0) {
+ return 1.0;
+ }
+ let ao = si.gi.a;
+ return clamp(pow(nDotV + ao, exp2(-16.0 * rough - 1.0)) - 1.0 + ao, 0.0, 1.0);
+}
+
// Karis' analytic approximation of the split-sum environment BRDF.
fn envBrdfApprox(f0: vec3<f32>, rough: f32, nDotV: f32) -> vec3<f32> {
let c0 = vec4<f32>(-1.0, -0.0275, -0.572, 0.022);
@@ -567,6 +691,25 @@ fn evalIridescence(cosTheta1: f32, thicknessNm: f32, filmIor: f32, baseF0: vec3<
return clamp(interf, vec3<f32>(0.0), vec3<f32>(1.0));
}
+/// The squared GGX alpha a pixel's spread of normals adds to every lobe,
+/// measured by \`measureSpecularFilter\` at the start of the fragment.
+var<private> specularFilterAlpha2 : f32 = 0.0;
+
+/// Screen-space normal variance under a Gaussian pixel filter (sigma^2 =
+/// 0.25), capped so silhouettes do not turn matte. Derivatives need uniform
+/// control flow, so fragment shaders call this before they branch.
+fn measureSpecularFilter(worldNormal: vec3<f32>) {
+ let du = dpdx(worldNormal);
+ let dv = dpdy(worldNormal);
+ specularFilterAlpha2 = min(2.0 * 0.25 * (dot(du, du) + dot(dv, dv)), 0.18);
+}
+
+/// Perceptual roughness whose alpha^2 is widened by \`extraAlpha2\`.
+fn filteredRoughness(rough: f32, extraAlpha2: f32) -> f32 {
+ let a2 = rough * rough * rough * rough;
+ return sqrt(sqrt(clamp(a2 + extraAlpha2, 0.0, 1.0)));
+}
+
// Multi-lobe Substrate PBR: GGX (isotropic or anisotropic) + Thin-Film Iridescence +
// Subsurface wrap/transmission + Charlie Cloth Sheen + Clearcoat secondary lobe + IBL.
fn shadePhysicalSubstrate(
@@ -586,14 +729,19 @@ fn shadePhysicalSubstrate(
}
let R = reflect(-V, N);
let nDotV = max(dot(N, V), 1e-4);
- let r = clamp(rough, 0.03, 1.0);
+ // Geometric specular anti-aliasing (Kaplanyan et al. 2016, Tokuyoshi &
+ // Kaplanyan 2019): a pixel sees every normal its footprint covers, so the
+ // lobe can be no narrower than their spread. Without it a near-mirror's
+ // highlight from a small light is a sub-pixel spike that a pixel center
+ // hits or misses as the camera moves: it flickers, and bloom flashes it.
+ let r = filteredRoughness(clamp(rough, 0.03, 1.0), specularFilterAlpha2);
let a = r * r;
let a2 = a * a;
let f0 = mix(vec3<f32>(0.04), albedo, metal);
let diffuseColor = albedo * (1.0 - metal);
let cc = clamp(substrate.clearcoat.x, 0.0, 1.0);
- let ccRough = clamp(substrate.clearcoat.y, 0.03, 1.0);
+ let ccRough = filteredRoughness(clamp(substrate.clearcoat.y, 0.03, 1.0), specularFilterAlpha2);
let ccA = ccRough * ccRough;
let ccA2 = ccA * ccA;
let aniso = clamp(substrate.clearcoat.z, -0.95, 0.95);
@@ -740,13 +888,15 @@ fn shadePhysicalSubstrate(
f0_ibl = mix(f0, fIridView, iridWeight);
}
- let irradiance = envIrradiance(N) + lights.ambientLinear.rgb;
+ let si = screenIndirectAt(worldPos);
+ let specOcclusion = screenSpecularOcclusion(si, nDotV, r);
+ let irradiance = screenAmbient(si, envIrradiance(N) + lights.ambientLinear.rgb);
var diffAmbient = diffuseColor * irradiance;
if (sssWeight > 0.001) {
let backIrradiance = envIrradiance(-N) * 0.35 + irradiance * 0.25;
diffAmbient += sssColor * (diffuseColor * 0.5 + vec3<f32>(0.5)) * backIrradiance * sssWeight * 0.45;
}
- let specEnv = envRadiance(R_ibl, r) * envBrdfApprox(f0_ibl, r, nDotV);
+ let specEnv = screenReflection(si, r, envRadiance(R_ibl, r) * specOcclusion) * envBrdfApprox(f0_ibl, r, nDotV);
var iblTotal = diffAmbient + specEnv;
if (sheenWeight > 0.001) {
@@ -759,7 +909,7 @@ fn shadePhysicalSubstrate(
if (cc > 0.001) {
let Fc_ibl = 0.04 + 0.96 * pow(1.0 - nDotV, 5.0);
- let ccEnv = envRadiance(R, ccRough) * Fc_ibl * cc;
+ let ccEnv = screenReflection(si, ccRough, envRadiance(R, ccRough) * specOcclusion) * Fc_ibl * cc;
iblTotal = iblTotal * (1.0 - cc * Fc_ibl) + ccEnv;
}
@@ -887,7 +1037,9 @@ fn shadeSurfaceSubstrate(
}
}
out.display = linearToSrgb(display);
- out.hdr = hdr;
+ // The radiance pass feeds screen-space traces: scene light, before
+ // exposure and before the camera's fog.
+ out.hdr = select(hdr, radiance, lights.indirect.x > 0.5 && lights.indirect.x < 1.5);
return out;
}
@@ -906,4 +1058,8 @@ export const lightsBindingsWgsl = `
@group(3) @binding(3) var<storage, read> directLights : array<DirectLight>;
@group(3) @binding(4) var envMap : texture_cube<f32>;
@group(3) @binding(5) var envSampler : sampler;
+@group(3) @binding(6) var screenHit : texture_2d<f32>;
+@group(3) @binding(7) var screenRadiance : texture_2d<f32>;
+@group(3) @binding(8) var screenGi : texture_2d<f32>;
+@group(3) @binding(9) var screenSampler : sampler;
`;
diff --git a/packages/webgpu-renderers/src/shaders/mesh3d.ts b/packages/webgpu-renderers/src/shaders/mesh3d.ts
index 8e887dbd..0d1875c0 100644
--- a/packages/webgpu-renderers/src/shaders/mesh3d.ts
+++ b/packages/webgpu-renderers/src/shaders/mesh3d.ts
@@ -267,6 +267,7 @@ fn sampleTriplanar4(tex: texture_2d<f32>, p: vec3<f32>, dp1: vec3<f32>, dp2: vec
fn shadeMesh(in: VertexOutput, isFront: bool) -> MeshFragment {
// Every sample and derivative up front, in uniform control flow.
+ measureSpecularFilter(in.worldNormal);
var texColor = textureSample(mainTex, texSampler, in.uv);
var normalSample = textureSample(normalTex, texSampler, in.normalUv).xyz;
var mrSample = textureSample(metalRoughTex, texSampler, in.mrUv);
diff --git a/packages/webgpu-renderers/src/shaders/quad3d.ts b/packages/webgpu-renderers/src/shaders/quad3d.ts
index 85311cfc..d354164a 100644
--- a/packages/webgpu-renderers/src/shaders/quad3d.ts
+++ b/packages/webgpu-renderers/src/shaders/quad3d.ts
@@ -173,6 +173,7 @@ struct QuadFragment {
};
fn shadeQuad(in: VertexOutput, isFront: bool) -> QuadFragment {
+ measureSpecularFilter(in.worldNormal);
// One-sided quads cull against their declared normal, not the hardware
// winding: the Y-down view basis mirrors winding, so front_facing reads
// camera-facing quads as back faces.
diff --git a/plugins/framefields/skills/framefields-compose/SKILL.md b/plugins/framefields/skills/framefields-compose/SKILL.md
index 32ec104b..5fe3759b 100644
--- a/plugins/framefields/skills/framefields-compose/SKILL.md
+++ b/plugins/framefields/skills/framefields-compose/SKILL.md
@@ -459,6 +459,8 @@ comp.add([
volumetricFog: { density: 0.025, anisotropy: 0.6, noise: { strength: 0.4, speed: [18, -6, 10] } }, // participating medium + god rays
bloom: true, // or { intensity: 0.3, threshold: 1.6, radius: 6 }
floor: { y: 200, color: "#111115", reflectivity: 0.8, roughness: 0.25, fadeDistance: 800 }, // glossy floor reflection
+ ssr: true, // screen-space reflections on glossy surfaces
+ gi: { intensity: 1.2 }, // contact occlusion + one bounce of visible light
}),
Layer.directionalLight({ x: 400, y: -1200, z: -600, targetX: 960, targetY: 540, castShadow: true }),
Layer.rectLight({ x: 960, y: -300, z: -400, targetX: 960, targetY: 540, width: 320, height: 140, intensity: 2, castShadow: true }),
@@ -476,6 +478,7 @@ Layer3D.cylinder({ ..., height: 400, color: "#111", emissive: "#4da3ff", emissiv
- **Volumetric Fog & Light Shafts (`volumetricFog`):** `Layer.environment("night", { volumetricFog: true | { density, anisotropy, heightFalloff, baseHeight, color, lightIntensity, ambientIntensity, maxDistance, steps, noise: { scale, strength, speed, octaves } } })` raymarches participating media at half resolution with depth-aware bilateral upsampling. Any shadow-casting `directional`, `spot`, `rect`, or `point` light automatically carves volumetric light shafts (god rays) through the fog behind occluders. `density`, `anisotropy`, and `noise.strength` accept numbers or live `Signal` objects directly.
- **Substrate lobes (physical shading, needs an environment):** every `Layer3D.*` mesh, `Layer.model` and 3D card accepts `clearcoat` / `clearcoatRoughness` (car paint, lacquer), `anisotropy` (-1..1) / `anisotropyRotation` (deg; brushed metal), `subsurface` / `subsurfaceColor` (wax, jade, skin), `sheen` / `sheenColor` / `sheenRoughness` (velvet, cloth), `iridescence` (0..1 or `{ intensity, thickness, ior }`; soap, oil, beetle shell) with `iridescenceThickness` (nm) / `iridescenceIor`, and `triplanar: true | { scale, sharpness }` for world-space textures on UV-less meshes. Numeric lobes take numbers or live `Signal`s (`clearcoat: bass`). Example: `Layer3D.sphere({ radius: 90, color: "#8a0f1c", metallic: 0.6, roughness: 0.35, clearcoat: 1, clearcoatRoughness: 0.05 })`.
- **HDRI environments:** pass a `.hdr` or `.exr` path instead of a preset: `Layer.environment("assets/hdri/studio.exr", { intensity: 1.2, rotation: 90 })` (or `{ hdri: path }`). The panorama lights and reflects every physical surface; preset names keep working; relative paths resolve from the working directory. EXR files must use lossless compression (NONE, RLE, ZIPS, ZIP, PIZ or PXR24); re-save B44/DWA files as ZIP.
+- **Screen-space reflections & GI (`ssr`, `gi`):** `Layer.environment("night", { ssr: true, gi: true })`. `ssr` (`{ intensity, maxRoughness, thickness, steps }`) reflects nearby geometry and emissives in glossy surfaces: chrome, wet floors, lacquer, walls. `gi` (`{ intensity, radius, samples }`) adds contact occlusion and color bleeding from visible surfaces, e.g. a neon sign tinting the floor. Each costs a second 3D pass; only what is on screen can be reflected or bounce, so keep key reflected objects in frame. Use `floor` for a planar mirror that also shows off-screen objects.
- **Art-directed materials:** `material: "toon"` works on meshes, flat 3D cards and native 3D text. Its `toon` options are `shadowColor` (shadow-side albedo multiplier; model shade color or `#80808c`), `lightColor` (lit-side multiplier; white), `threshold` (terminator cosine; 0.075), `softness` (transition width; 0.25) and `diffuse` (0 flat through 1 Lambert; 0). Toon surfaces use all scene lights, their colors, point/spot attenuation and real cast shadows; environment exposure, tone mapping, fog and emissive bloom still apply. Lower `threshold` to wrap light around a surface, or raise `shadowColor` for a bright shadow floor on illustrated cards. Physical and unlit materials are independent of these options.
- **Geometry outlines (ink):** `Layer.environment("neutral", { outlines: true })`, or `outlines: { color: "#191721", width: 2, referenceHeight: 1080, creaseAngle: 45, depthThreshold: 0.01, opacity: 1 }`. `width` is px at `referenceHeight`, scaled with the output height; start near 1 px at export height. Ink comes from depth and normals, so textures, shadows and coplanar seams get none; `creaseAngle: 180` keeps only silhouettes. `outline: false` on a layer/model excludes it but keeps it occluding ink behind it (for already-inked artwork). Ink follows fog and runs before depth blur and bloom; heavy lens blur spreads it into wide bands. Separate from the image-space `Toon` effect. `Layer3D.cube({ faces: { front: Layer.box(...) } })` faces inherit the cube's `toon`, `outline`, emissive and shadow settings unless set per face. Example: `examples/34_spatial_styling` in the engine repo.
- **3D pivots:** `anchorX/Y` choose the point held fixed during scale/rotation; changing an anchor at identity transform leaves the layer in place. Use `anchorY: 1` to keep a character's feet planted while scaling.
diff --git a/specs/ue58-engine-roadmap.md b/specs/ue58-engine-roadmap.md
index 893bef28..5821a8cf 100644
--- a/specs/ue58-engine-roadmap.md
+++ b/specs/ue58-engine-roadmap.md
@@ -182,6 +182,8 @@ export interface Environment3DGiOptions {
- While horizon-scanning depth slices around each pixel, sample the direct-lit HDR color buffer at visible horizon hits, accumulating indirect diffuse irradiance $\mathbf{E}_{\text{indirect}}$ and bent normal $\mathbf{n}_{\text{bent}}$.
- Edge-preserving spatial denoise (normal + depth bilateral filter) composites indirect diffuse + specular before bloom and tone mapping.
+**Status (implemented):** `renderer3d/ssr-gi-pipeline.ts`. Deviations from the plan above, each for determinism or correctness: (1) SSR and GI run between two forward passes (a `radiance` pass writing pre-exposure, unfogged radiance plus the nearest-sample geometry buffer, then an `apply` pass), so the traced light enters each material's own environment terms (`screenIndirectAt` in `lighting3d.ts`) before tone mapping and fog: no material G-buffer and every Substrate lobe stays correct. (2) No GGX VNDF ray jitter: glossy surfaces cone-sample a premultiplied radiance pyramid at their lobe's footprint, which is noise-free and frame-to-frame stable without TAA. (3) Both trace at full resolution. (4) The Hi-Z holds min and max depth, so rays skip cells they pass wholly in front of or wholly behind (beyond `thickness`); `steps` budgets cell advances and level changes are free. Hits are classified by the hit pixel's tangent plane (a crossing) before falling back to `thickness`, which only applies once the ray has been in front of the scene (no self-hits off convex rims). (5) The shading pass pools each pixel's 3×3 neighbors' rays on the same surface, weighted by confidence, which resolves the holes and seams single rays leave. GI is a cosine-weighted horizon scan (visible band `sin²b − sin²a` per surface) with fixed interleaved-gradient rotation and a separable depth/normal bilateral blur; `SsaoPipeline` is left unused. The `ssr`-without-environment lint is moot since both options live on the environment.
+
---
## Phase 4: Procedural Terrain, SDF Booleans & PCG Surface Scatter