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.mdindex 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.tsindex 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.tsindex 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> = zvolumetricFogDensity: 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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 arraylet ambR = 0;@@ -480,9 +490,22 @@ export const Light3D = {buffer[base + 3] = 1; // exposure multiplierlet 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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 = dofEnabledscreenParams : 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 intensityenvSh : 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.tsindex 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: vecfn 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.tsindex 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.mdindex 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 raysbloom: 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.mdindex 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