A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
feat(gi): a distance field of three levels that follows the camera, and point and spot lights - lit in the cards with the frame's own falloff, shadowed through the field, held to the CPU reference on the lamp lab
yhh818ebb80787c
diff --git a/docs/GI_LUMEN_DESIGN.md b/docs/GI_LUMEN_DESIGN.mdindex 9ec3efc32..0c9e8ec08 100644--- a/docs/GI_LUMEN_DESIGN.md+++ b/docs/GI_LUMEN_DESIGN.md@@ -126,6 +126,15 @@没测的:手机(Adreno/Mali),更大的场景(实例多、距离场更大),以及更高分辨率下应用通道的 0.9 ms 往上的增长。+## 5.2 多级距离场与点光(2026-11-11)++- **多级 clipmap**:后效参数 `u_cellSize`(世界单位,默认 0)。0 为原来的单窗口(整个场景放进一个 128³ 的场);大于 0 则是三级场,格子依次为 1×、4×、16× `u_cellSize`,各 128³,跟随相机(相机每走 8 个细格重新居中,只重建新进入的薄片,再整体上传)。着色器里光线走当前点所在的最细一级,走出这一级的窗口就交给下一级;命中点按所在级的格子放宽卡面容差。距离场合成里,离某个实例超过 reach 的格子直接跳过该实例,实验房间合成约 0.4 s。+ 对 Cycles(`dgil`:2.5 cm 细格,房间的后半部分只在粗级里):`gi_room` 0.55–1.25、`gi_away` 0.51–0.87、`gi_leak` 室内 0,与单窗口一致。+- **点光和聚光**:场景里最近相机的至多 8 盏,按引擎自己的衰减(`distanceFalloff`:线性斜坡、反平方、内径,聚光的 smoothstep 锥)给卡面直接光,阴影也是穿过距离场的射线,到灯为止。CPU 参考在 `surfaceCache.ts`(`PointLight`),对闭式值有 5 个测试;GPU 在 `lightsDirect`。+ 验证:`gi_point` 实验室(密闭房间,一盏 0.3 强度的灯)。Cycles 的点光是反平方的瓦特,单位对不上,所以参照是 CPU 求解器(与 Cycles 对过太阳的那个)。GPU 对 CPU 参照 0.89–1.06;`dgim`(网格版)和 `dgil`(多级)同样通过。+- **没测**:聚光在 GPU 上(只有 CPU 单元测试)、点光阴影在大场景、多级场相机移动时的重建与上传成本、手机。+- 帧时间:720p 约 3.6–3.8 ms(多级与一盏灯),比单窗口无灯多约 0.3 ms。+## 6. 分期每期独立可验收、可回退,期间旧 `voxelGI` 一直可用。diff --git a/pipeline/tests/gi-lab.test.ts b/pipeline/tests/gi-lab.test.tsindex 3616fa21f..0c7e8bf84 100644--- a/pipeline/tests/gi-lab.test.ts+++ b/pipeline/tests/gi-lab.test.ts@@ -8,14 +8,14 @@* tools/render-lab/gi_reference.json: Cycles' linear light, 12 bounces, over a patch of each surface. What is asserted is the same* share of Cycles' light the lab check (gi_oracle.py) uses for the engine's other methods.*/-import { readFileSync } from 'node:fs';+import { readFileSync, writeFileSync } from 'node:fs';import path from 'node:path';import { describe, it, expect } from 'vitest';import { MeshChannel, MeshChannelType, type MeshData } from 'esengine';import { bakeMeshCards } from '../src/assets/meshCards';import { bakeMeshSdf } from '../src/assets/meshSdf';import { GlobalSdf } from '../../sdk/src/gi/globalSdf';-import { SurfaceCache } from '../../sdk/src/gi/surfaceCache';+import { SurfaceCache, type PointLight } from '../../sdk/src/gi/surfaceCache';import { solveBounces, type ProbeScene } from '../../sdk/src/gi/screenProbes';const reference = JSON.parse(readFileSync(path.resolve(import.meta.dirname, '../../tools/render-lab/gi_reference.json'), 'utf8')).regions as Record<string, Record<string, number[]>>;@@ -72,7 +72,7 @@ const sunTravel = (elev: number, azim: number): [number, number, number] => {return [Math.cos(e) * Math.sin(a), -Math.sin(e), Math.cos(e) * Math.cos(a)];};-function solve(boxes: Box[], sun: { elev: number; azim: number } | null, bounces = 4, raysSeed = 0) {+function solve(boxes: Box[], sun: { elev: number; azim: number } | null, bounces = 4, raysSeed = 0, lights: PointLight[] = []) {const sdf = new GlobalSdf([{ dim: 128, cell: 5 }]);sdf.setCenter([0, 150, 0]);const cache = new SurfaceCache();@@ -84,7 +84,7 @@ function solve(boxes: Box[], sun: { elev: number; azim: number } | null, bounces});const scene: ProbeScene = { sdf, cache, range: 900, bias: 9, tolerance: 14 };const travel = sun ? sunTravel(sun.elev, sun.azim) : null;- solveBounces(scene, { sun: travel ? { toLight: [-travel[0], -travel[1], -travel[2]], radiance: [1, 1, 1] } : undefined, sdf, bias: 9, shadowRange: 900 }, bounces);+ solveBounces(scene, { sun: travel ? { toLight: [-travel[0], -travel[1], -travel[2]], radiance: [1, 1, 1] } : undefined, lights, sdf, bias: 9, shadowRange: 900 }, bounces);void raysSeed;return { cache, sdf };}@@ -130,4 +130,22 @@ describe('the dynamic GI over the render lab rooms', () => {// is 0.1 to 1.7 on screen and 0.3 to 0.5 off it; the band is the accuracy this has today, so a change that makes it worse fails.for (const s of [...shares, ...awayShares]) { expect(s).toBeGreaterThan(0.4); expect(s).toBeLessThan(2.0); }}, 300000);++ it('lights the room of gi_point by a lamp: the CPU reference the GPU method is held to', () => {+ // The lamp of tools/render-lab/gi_specs.py: at (0, 200, 50), intensity 0.3 (an 8-bit picture cannot hold more), linear falloff to 600.+ const lamp: PointLight = { position: [0, 200, 50], radiance: [0.3, 0.3, 0.3], reach: 600, innerRadius: 0, falloff: 1 };+ const { cache } = solve(room(), null, 5, 0, [lamp]);+ const rows: Array<[string, [number, number, number], [number, number, number]]> = [+ ['ceiling', [0, 299, 50], [0, -1, 0]], ['red wall', [199, 150, 50], [-1, 0, 0]], ['green wall', [-199, 150, 50], [1, 0, 0]],+ ['back wall', [0, 150, 249], [0, 0, -1]], ['floor', [0, 1, 50], [0, 1, 0]], ['block, lit side', [-90, 50, 29], [0, 0, -1]],+ ];+ const out: Record<string, number[]> = {};+ for (const [name, p, n] of rows) {+ const e = share(cache, p, n, [1, 1, 1]).e;+ out[name] = e;+ console.log(`gi_point ${name.padEnd(16)} ${e.map((v) => v.toFixed(3)).join(' ')}`);+ expect(Math.max(...e)).toBeGreaterThan(0.02);+ }+ if (process.env.WRITE_REF) writeFileSync(path.resolve(import.meta.dirname, '../../tools/render-lab/gi_point_reference.json'), JSON.stringify({ source: 'the CPU solver of pipeline/tests/gi-lab.test.ts (distance field + surface cache + probes, 5 bounces), linear radiance at each region', regions: out }, null, 1));+ }, 300000);});diff --git a/pipeline/tests/gpu-scene.test.ts b/pipeline/tests/gpu-scene.test.tsindex 2829fd915..fa527f57e 100644--- a/pipeline/tests/gpu-scene.test.ts+++ b/pipeline/tests/gpu-scene.test.ts@@ -10,6 +10,7 @@ import { bakeMeshCards } from '../src/assets/meshCards';import { bakeMeshSdf } from '../src/assets/meshSdf';import { buildInstances, type GIEntry } from '../../sdk/src/gi/dynamicGISystem';import { packGPUScene, GI_HEADER_FLOATS, GI_INSTANCE_FLOATS } from '../../sdk/src/gi/gpuScene';+import { GlobalSdf } from '../../sdk/src/gi/globalSdf';function box(h: [number, number, number]): MeshData {const p: number[] = [];@@ -129,3 +130,59 @@ describe('the packed scene', () => {expect(packGPUScene([], null)).toBeNull();});});++describe('a field that follows the camera', () => {+ const boxes = [entry(CUBE, transform([0, 0, 0], [8, 1, 8])), entry(CUBE, transform([600, 50, 0], [2, 2, 2])), entry(CUBE, transform([-2500, 0, 0], [20, 4, 20]))];+ const { instances } = buildInstances(boxes, CUBE, () => null);++ it('packs three levels, each four times the last, with their windows and where their fields start', () => {+ const sdf = new GlobalSdf([{ dim: 128, cell: 5 }, { dim: 128, cell: 20 }, { dim: 128, cell: 80 }]);+ sdf.setCenter([0, 0, 0]);+ instances.forEach((inst, id) => sdf.update({ id, sdf: inst.sdf, worldFromLocal: inst.worldFromLocal }));+ const scene = packGPUScene(instances, null, { sdf })!;+ const h = scene.header, cells = 128 ** 3, stride = cells + cells / 4;+ expect(h[22]).toBe(3);+ expect(scene.sdf.length).toBe(3 * stride);+ // Level 1 and 2: dim, cell, origin, reach, field offset, owner offset.+ expect([h[24], h[25], h[30], h[31]]).toEqual([128, 20, stride, stride + cells]);+ expect([h[32], h[33], h[38], h[39]]).toEqual([128, 80, 2 * stride, 2 * stride + cells]);+ // The finest window is centred on the camera: 64 cells of 5 either side.+ expect(h[2]).toBe(-64);+ });++ it('hands a ray over to a coarser level where the finer window ends, and finds the far box there', () => {+ const sdf = new GlobalSdf([{ dim: 128, cell: 5 }, { dim: 128, cell: 20 }, { dim: 128, cell: 80 }]);+ sdf.setCenter([0, 0, 0]);+ instances.forEach((inst, id) => sdf.update({ id, sdf: inst.sdf, worldFromLocal: inst.worldFromLocal }));+ const levelOf = (p: [number, number, number]) => sdf.levels.indexOf(sdf.levelAt(p)!);+ // The windows are 640, 2560 and 10240 across: 100 is in the first, 1000 in the second, 2000 only in the third.+ expect([levelOf([100, 0, 0]), levelOf([-1000, 0, 0]), levelOf([-2000, 0, 0])]).toEqual([0, 1, 2]);+ // From beside the near box toward the far one (its face is at x = -1500, 1050 away): the ray crosses all three levels and stops at it.+ const t = sdf.sphereTrace([-450, 0, 0], [-1, 0, 0], 4000)!;+ expect(t).toBeGreaterThan(950);+ expect(t).toBeLessThan(1100);+ // Straight past it, at a height the box does not reach, nothing is in the way.+ expect(sdf.sphereTrace([-450, 900, 0], [-1, 0, 0], 4000)).toBeNull();+ });+});++describe('lights in the packed scene', () => {+ const { instances } = buildInstances([entry(CUBE, transform([0, 0, 0], [4, 1, 4]))], CUBE, () => null);++ it('packs a lamp and a spot as the sixteen floats the kernels read', () => {+ const scene = packGPUScene(instances, null, { lights: [+ { position: [1, 2, 3], radiance: [0.3, 0.4, 0.5], reach: 600, innerRadius: 50, falloff: 2 },+ { position: [4, 5, 6], radiance: [1, 1, 1], reach: 300, metre: 100, spot: { axis: [0, -2, 0], innerCos: 0.9, outerCos: 0.7 } },+ ] })!;+ const h = scene.header, f = (i: number, n: number) => Array.from(h.slice(40 + i * 16, 40 + i * 16 + n)).map((v) => +v.toFixed(4));+ expect(h[23]).toBe(2);+ expect(f(0, 16)).toEqual([1, 2, 3, 600, 0.3, 0.4, 0.5, 0, 0, -1, 0, 2, 50, 1, 0, 0]);+ // The spot: kind 2, its aim normalised, an inverse-square falloff written as minus the units to a metre, then the cone cosines.+ expect(f(1, 16)).toEqual([4, 5, 6, 300, 1, 1, 1, 2, 0, -1, 0, -100, 0, 0.9, 0.7, 0]);+ });++ it('takes no more lights than the kernels have room for', () => {+ const many = Array.from({ length: 12 }, (_, i) => ({ position: [i, 0, 0] as [number, number, number], radiance: [1, 1, 1] as [number, number, number], reach: 100 }));+ expect(packGPUScene(instances, null, { lights: many })!.header[23]).toBe(8);+ });+});diff --git a/pipeline/tests/surface-cache.test.ts b/pipeline/tests/surface-cache.test.tsindex 0de654b16..f94223989 100644--- a/pipeline/tests/surface-cache.test.ts+++ b/pipeline/tests/surface-cache.test.ts@@ -149,3 +149,61 @@ describe('the surface cache', () => {expect(cache.lookup([0.5, 1, 0.5], [0, -1, 0], 0.3)).toBeNull();});});++describe('point and spot lights in the surface cache', () => {+ const plate = bakeMeshCards(box([200, 5, 200]), { cell: 50, baseColor: [0.5, 0.5, 0.5] })!;+ const cache = (placeAt: [number, number, number] = [0, 0, 0]) => {+ const c = new SurfaceCache();+ c.add({ id: 1, cards: plate, worldFromLocal: matrix(placeAt) });+ return c;+ };+ // The plate's top card is 8 x 8 pixels of 50: the pixel centre at (25, 25) is where a lamp straight above it is 100 away at a right angle.+ const topCentre = (c: SurfaceCache) => c.lookup([25, 5, 25], [0, -1, 0], 1)![0]!;++ it('lights a surface under a lamp by the lamp, the falloff and the cosine', () => {+ const c = cache();+ const lamp = { position: [25, 105, 25] as [number, number, number], radiance: [2, 2, 2] as [number, number, number], reach: 400, innerRadius: 0, falloff: 1 };+ c.light({ lights: [lamp] });+ // 100 above, straight down: the ramp is (400 - 100) / 400 = 0.75, the cosine 1, albedo 0.5.+ expect(topCentre(c)).toBeCloseTo(0.5 * 2 * 0.75, 2);+ });++ it('follows the frame inverse-square falloff, let go over the reach', () => {+ const c = cache();+ const lamp = { position: [25, 105, 25] as [number, number, number], radiance: [1, 1, 1] as [number, number, number], reach: 400, metre: 100 };+ c.light({ lights: [lamp] });+ const q = 100 / 400, w = (1 - q ** 4) ** 2;+ expect(topCentre(c)).toBeCloseTo(0.5 * w / 1, 2);+ });++ it('lights nothing past its reach, or from behind the surface', () => {+ const c = cache();+ c.light({ lights: [{ position: [25, 605, 25], radiance: [1, 1, 1], reach: 400 }] });+ expect(topCentre(c)).toBe(0);+ const d = cache();+ d.light({ lights: [{ position: [25, -95, 25], radiance: [1, 1, 1], reach: 400 }] });+ expect(topCentre(d)).toBe(0);+ });++ it('cuts a spot to its cone', () => {+ const spot = (aim: [number, number, number]) => ({ position: [25, 105, 25] as [number, number, number], radiance: [1, 1, 1] as [number, number, number], reach: 400, falloff: 1,+ spot: { axis: aim, innerCos: Math.cos(0.3), outerCos: Math.cos(0.5) } });+ const on = cache(), off = cache();+ on.light({ lights: [spot([0, -1, 0])] });+ off.light({ lights: [spot([1, 0, 0])] });+ expect(topCentre(on)).toBeGreaterThan(0.3);+ expect(topCentre(off)).toBe(0);+ });++ it('is shadowed by a body between the surface and the lamp', () => {+ const c = cache();+ const sdf = new GlobalSdf([{ dim: 64, cell: 8 }]);+ sdf.setCenter([0, 100, 0]);+ sdf.update({ id: 2, sdf: bakeMeshSdf(box([40, 5, 40]), { cellSize: 8 })!, worldFromLocal: matrix([25, 60, 25]) });+ c.light({ lights: [{ position: [25, 140, 25], radiance: [1, 1, 1], reach: 400 }], sdf, bias: 12 });+ expect(topCentre(c)).toBe(0);+ const lit = cache();+ lit.light({ lights: [{ position: [25, 140, 25], radiance: [1, 1, 1], reach: 400 }] });+ expect(topCentre(lit)).toBeGreaterThan(0);+ });+});diff --git a/sdk/src/gi/dynamicGISystem.ts b/sdk/src/gi/dynamicGISystem.tsindex c224c99fb..3e6720147 100644--- a/sdk/src/gi/dynamicGISystem.ts+++ b/sdk/src/gi/dynamicGISystem.ts@@ -15,13 +15,16 @@import type { App } from '../app/app';import { defineSystem } from '../ecs/system';import { Query } from '../ecs/query';-import { MeshRenderer, Transform, Light, PostProcessVolume, type MeshRendererData, type TransformData, type LightData, type PostProcessVolumeData } from '../ecs/component';+import { MeshRenderer, Transform, Light, Camera, PostProcessVolume, type MeshRendererData, type TransformData, type LightData, type CameraData, type PostProcessVolumeData } from '../ecs/component';import { LightType } from '../wasm/wasm.generated';import { Assets } from '../asset/AssetPlugin';import type { Entity } from '../types';import { withScratch } from '../wasm/wasmScratch';import { Material } from '../render/material';import { analyticBox, packGPUScene, type GIInstance, type GILight } from './gpuScene';+import { GlobalSdf } from './globalSdf';+import type { PointLight } from './surfaceCache';+import { worldUnitsPerMeter } from '../ecs/worldUnits';import type { MeshSdf } from './meshSdfFormat';import type { MeshCards } from './cardFormat';@@ -79,11 +82,28 @@ export function buildInstances(entries: readonly GIEntry[], cube: number, sidecareturn { instances, key };}-function wantsDynamicGI(volumes: Iterable<[Entity, PostProcessVolumeData]>): boolean {+/** The settings of the first enabled `dynamicGI` effect of the volumes, or null when there is none. */+function dynamicGIEffect(volumes: Iterable<[Entity, PostProcessVolumeData]>): { cellSize: number } | null {for (const [, v] of volumes) {- for (const e of v.effects as Array<{ type: string; enabled?: boolean }>) if (e.type === 'dynamicGI' && e.enabled !== false) return true;+ for (const e of v.effects as Array<{ type: string; enabled?: boolean; uniforms?: Record<string, number> }>) {+ if (e.type === 'dynamicGI' && e.enabled !== false) return { cellSize: Number(e.uniforms?.u_cellSize ?? 0) || 0 };+ }+ }+ return null;+}++/** A point or spot light of the scene, as the GI lights with it. */+export function pointLightOf(l: LightData, t: TransformData): PointLight | null {+ if (!l.enabled || l.intensity <= 0 || (l.type !== LightType.Point && l.type !== LightType.Spot) || l.radius <= 0) return null;+ const q = t.worldRotation, p = t.worldPosition;+ const radiance: [number, number, number] = [l.color.r * l.intensity, l.color.g * l.intensity, l.color.b * l.intensity];+ const light: PointLight = { position: [p.x, p.y, p.z], radiance, reach: l.radius, innerRadius: l.innerRadius, falloff: l.falloff, ...(l.inverseSquare ? { metre: worldUnitsPerMeter() } : {}) };+ if (l.type === LightType.Spot) {+ // The aim is the rotation's -Z, as the sun's is.+ const ax = -(2 * (q.x * q.z + q.w * q.y)), ay = -(2 * (q.y * q.z - q.w * q.x)), az = -(1 - 2 * (q.x * q.x + q.y * q.y));+ light.spot = { axis: [ax, ay, az], innerCos: Math.cos((l.innerAngle * Math.PI) / 360), outerCos: Math.cos((l.outerAngle * Math.PI) / 360) };}- return false;+ return light;}/** The emissive colour of a material, black where it has none. */@@ -104,6 +124,8 @@ type Loader = {export function dynamicGISystem(app: App) {let cube = 0, loading = false, lastKey = '';+ // The field that follows the camera, kept between frames so that a camera that moves rebuilds only the slabs that came into view.+ let follow: { sdf: GlobalSdf; instancesKey: string; cell: number } | null = null;// The baked files beside a mesh, by its path: null while loading and for a mesh that has none.const sidecars = new Map<string, GISidecars | null>();const request = (path: string): void => {@@ -119,10 +141,11 @@ export function dynamicGISystem(app: App) {() => { /* a mesh with no baked files is simply not in the scene */ });};return defineSystem(- [Query(MeshRenderer, Transform), Query(Light, Transform), Query(PostProcessVolume)],+ [Query(MeshRenderer, Transform), Query(Light, Transform), Query(PostProcessVolume), Query(Camera, Transform)],(meshes: Iterable<[Entity, MeshRendererData, TransformData]>, lights: Iterable<[Entity, LightData, TransformData]>,- volumes: Iterable<[Entity, PostProcessVolumeData]>) => {- if (!wantsDynamicGI(volumes)) { lastKey = ''; return; }+ volumes: Iterable<[Entity, PostProcessVolumeData]>, cameras: Iterable<[Entity, CameraData, TransformData]>) => {+ const effect = dynamicGIEffect(volumes);+ if (!effect) { lastKey = ''; follow = null; return; }const m = app.wasmModule;if (!m?.postprocess_setGIScene) return;if (cube === 0) {@@ -142,6 +165,13 @@ export function dynamicGISystem(app: App) {light = { toLight: [-ax / n, -ay / n, -az / n], radiance: [l.color.r * l.intensity, l.color.g * l.intensity, l.color.b * l.intensity] };break;}+ const point: PointLight[] = [];+ for (const [, l, t] of lights) { const p = pointLightOf(l, t); if (p) point.push(p); }+ let eye: [number, number, number] | null = null;+ for (const [, c, t] of cameras) if (c.isActive) { eye = [t.worldPosition.x, t.worldPosition.y, t.worldPosition.z]; break; }+ // The lights that matter are the ones nearest the eye: only a handful fit.+ if (eye && point.length > 8) point.sort((a, b) => Math.hypot(a.position[0] - eye![0], a.position[1] - eye![1], a.position[2] - eye![2]) - Math.hypot(b.position[0] - eye![0], b.position[1] - eye![1], b.position[2] - eye![2]));+ const lightKey = point.slice(0, 8).map((l) => `${l.position.map((v) => v.toFixed(2)).join(',')};${l.radiance.join(',')};${l.reach};${l.innerRadius};${l.falloff};${l.metre ?? 0};${l.spot ? l.spot.axis.map((v) => v.toFixed(3)).join(',') + l.spot.innerCos + l.spot.outerCos : ''}`).join('|');const assets = app.hasResource(Assets) ? app.getResource(Assets) as unknown as Loader : null;const entries: GIEntry[] = [];for (const [, r, t] of meshes) {@@ -154,10 +184,30 @@ export function dynamicGISystem(app: App) {entries.push({ mesh: r.mesh, transform: t, colour: [r.color.r, r.color.g, r.color.b], emissive: emissiveOf(r.material), path });}const { instances, key: sceneKey } = buildInstances(entries, cube, (p) => sidecars.get(p) ?? null);- const key = (light ? `${light.toLight.join(',')}|${light.radiance.join(',')}` : 'dark') + sceneKey;+ // A cell size asks for the field that follows the eye: three levels, each four times the last, around the camera. Without one the+ // field is a single window that holds the whole scene.+ const following = effect.cellSize > 0 && eye !== null;+ const snap = following ? effect.cellSize * 8 : 1;+ const eyeKey = following ? eye!.map((v) => Math.floor(v / snap)).join(',') : '';+ const key = (light ? `${light.toLight.join(',')}|${light.radiance.join(',')}` : 'dark') + sceneKey + '#' + lightKey + '#' + effect.cellSize + eyeKey;if (key === lastKey || instances.length === 0) return;lastKey = key;- const scene = packGPUScene(instances, light);+ let sdf: GlobalSdf | undefined;+ if (following) {+ const cell = effect.cellSize;+ if (!follow || follow.cell !== cell || follow.instancesKey !== sceneKey) {+ const fresh = new GlobalSdf([{ dim: 128, cell }, { dim: 128, cell: cell * 4 }, { dim: 128, cell: cell * 16 }]);+ fresh.setCenter(eye!);+ instances.forEach((inst, id) => fresh.update({ id, sdf: inst.sdf, worldFromLocal: inst.worldFromLocal }));+ follow = { sdf: fresh, instancesKey: sceneKey, cell };+ } else {+ follow.sdf.setCenter(eye!);+ }+ sdf = follow.sdf;+ } else {+ follow = null;+ }+ const scene = packGPUScene(instances, light, { sdf, lights: point.slice(0, 8) });if (!scene) return;withScratch(m, (alloc) => {const put = (data: ArrayBufferView): number => {diff --git a/sdk/src/gi/globalSdf.ts b/sdk/src/gi/globalSdf.tsindex 2b3d0853a..5aa98b32e 100644--- a/sdk/src/gi/globalSdf.ts+++ b/sdk/src/gi/globalSdf.ts@@ -211,6 +211,9 @@ export class GlobalSdf {const p: [number, number, number] = [(x + 0.5) * level.cell, (y + 0.5) * level.cell, (z + 0.5) * level.cell];let d = reach, owner = 0;for (const placed of near) {+ // An instance further from the cell than the reach (outside its own box grown by it) cannot be what the cell remembers.+ if (p[0] < placed.min[0]! - reach || p[0] > placed.max[0]! + reach || p[1] < placed.min[1]! - reach || p[1] > placed.max[1]! + reach+ || p[2] < placed.min[2]! - reach || p[2] > placed.max[2]! + reach) continue;const v = this.distanceTo_(placed, p);if (v < d) { d = v; owner = placed.instance.id < 126 ? placed.instance.id + 1 : 127; }}diff --git a/sdk/src/gi/gpuScene.ts b/sdk/src/gi/gpuScene.tsindex c68693c78..908e43777 100644--- a/sdk/src/gi/gpuScene.ts+++ b/sdk/src/gi/gpuScene.ts@@ -17,6 +17,7 @@* The CPU twins (globalSdf.ts, surfaceCache.ts, screenProbes.ts) are checked against Cycles; the kernels are the same arithmetic.*/import { GlobalSdf, type SdfInstance } from './globalSdf';+import type { PointLight } from './surfaceCache';import { CARD_AXES, NO_DEPTH, type MeshCards } from './cardFormat';import type { MeshSdf } from './meshSdfFormat';@@ -40,7 +41,11 @@ export interface GPUScene {pixels: Uint32Array;}-export const GI_HEADER_FLOATS = 24;+/** Header floats: 0-21 the first level and the scene (see the layout above), 22 levels, 23 lights, 24-39 the second and third level, 40- the lights. */+export const GI_MAX_LEVELS = 3;+export const GI_MAX_LIGHTS = 8;+export const GI_LIGHT_FLOATS = 16;+export const GI_HEADER_FLOATS = 40 + GI_MAX_LIGHTS * GI_LIGHT_FLOATS;export const GI_INSTANCE_FLOATS = 80;/** A box of the given size centred on the origin, as a distance field and as cards, without any mesh: what a primitive is to the GI. */@@ -74,11 +79,21 @@ export function analyticBox(size: readonly [number, number, number], colour: reaconst scaleOf = (m: ArrayLike<number>): number => Math.hypot(m[0]!, m[1]!, m[2]!);-/** Composes the instances into one distance field window and lays everything out for the engine. */-export function packGPUScene(instances: readonly GIInstance[], light: GILight | null, options: { dim?: number; sky?: readonly [number, number, number]; bias?: number } = {}): GPUScene | null {- if (instances.length === 0) return null;- const dim = options.dim ?? 128;- // The window covers the instances' boxes: the cell is the smallest power-free size that fits them, with the border a trace needs.+export interface PackOptions {+ dim?: number;+ sky?: readonly [number, number, number];+ bias?: number;+ /** Point and spot lights, up to GI_MAX_LIGHTS. */+ lights?: readonly PointLight[];+ /**+ * A field to pack as it stands (levels that follow the camera, composed by the caller); without one the instances are composed into a+ * single window that holds them all.+ */+ sdf?: GlobalSdf;+}++/** The bounds of the instances' cards in the world. */+export function instanceBounds(instances: readonly GIInstance[]): { min: number[]; max: number[] } {const min = [Infinity, Infinity, Infinity], max = [-Infinity, -Infinity, -Infinity];for (const inst of instances) {const m = inst.worldFromLocal, { aabbMin, aabbMax } = inst.cards;@@ -90,12 +105,26 @@ export function packGPUScene(instances: readonly GIInstance[], light: GILight |}}}+ return { min, max };+}++/** Composes the instances into a distance field (one window that holds them all, or the caller's) and lays everything out for the engine. */+export function packGPUScene(instances: readonly GIInstance[], light: GILight | null, options: PackOptions = {}): GPUScene | null {+ if (instances.length === 0) return null;+ const dim = options.dim ?? 128;+ const { min, max } = instanceBounds(instances);const extent = Math.max(max[0]! - min[0]!, max[1]! - min[1]!, max[2]! - min[2]!);- const cell = (extent * 1.15) / (dim - 4);- const sdf = new GlobalSdf([{ dim, cell }]);- sdf.setCenter([(min[0]! + max[0]!) / 2, (min[1]! + max[1]!) / 2, (min[2]! + max[2]!) / 2]);- instances.forEach((inst, id) => { const s: SdfInstance = { id, sdf: inst.sdf, worldFromLocal: inst.worldFromLocal }; sdf.update(s); });- const level = sdf.levels[0]!;+ let sdf = options.sdf;+ if (!sdf) {+ // The window covers the instances' boxes: the cell is the one that fits them, with the border a trace needs.+ const cell = (extent * 1.15) / (dim - 4);+ sdf = new GlobalSdf([{ dim, cell }]);+ sdf.setCenter([(min[0]! + max[0]!) / 2, (min[1]! + max[1]!) / 2, (min[2]! + max[2]!) / 2]);+ instances.forEach((inst, id) => { const s: SdfInstance = { id, sdf: inst.sdf, worldFromLocal: inst.worldFromLocal }; sdf!.update(s); });+ }+ const levels = sdf.levels.slice(0, GI_MAX_LEVELS);+ const level = levels[0]!;+ const cell = level.cell;const pixelTotal = instances.reduce((a, inst) => a + inst.cards.cards.reduce((b, c) => b + c.width * c.height, 0), 0);const header = new Float32Array(GI_HEADER_FLOATS);@@ -137,15 +166,39 @@ export function packGPUScene(instances: readonly GIInstance[], light: GILight |});});- const bias = options.bias ?? Math.max(cell * 1.6, 0.5);+ // A ray starts off its surface by more than the instances' own fields are grown (a body is half a cell of ITS mesh fatter than it is), or it+ // starts inside the body it left; and a card is forgiven by about as much. This is the meshes' cell, not the clipmap's.+ const growth = Math.max(...instances.map((inst) => inst.sdf.inflate), 0);+ const bias = options.bias ?? Math.max(cell * 1.6, growth * 1.8, 0.5);+ const tolerance = Math.max(cell * 3, growth * 3.5);const set = (i: number, ...v: number[]) => { v.forEach((x, k) => { header[i + k] = x; }); };- set(0, dim, cell, level.origin[0]!, level.origin[1]!, level.origin[2]!, cell * GlobalSdf.REACH_CELLS, instances.length, pixelTotal);- set(8, ...(light?.toLight ?? [0, 1, 0]), light ? 1 : 0, ...(light?.radiance ?? [0, 0, 0]), bias, extent * 2.5, cell * 3);+ set(0, level.dim, cell, level.origin[0]!, level.origin[1]!, level.origin[2]!, cell * GlobalSdf.REACH_CELLS, instances.length, pixelTotal);+ set(8, ...(light?.toLight ?? [0, 1, 0]), light ? 1 : 0, ...(light?.radiance ?? [0, 0, 0]), bias, extent * 2.5, tolerance);set(18, ...(options.sky ?? [0, 0, 0]), 0.25);- // The field, then which instance each cell is nearest to, four cells to a word of seven-bit ids (a word with a top bit set could read as a- // NaN, and a device is free to change those).- const cells = level.data.length, packed = new Float32Array(cells + cells / 4), words = new Uint32Array(packed.buffer, cells * 4, cells / 4);- packed.set(level.data);- for (let i = 0; i < cells; i++) words[i >> 2]! |= level.owner[i]! << ((i & 3) * 8);+ set(22, levels.length);+ // The field of every level, each followed by its owner words (four cells to a word of seven-bit ids; a word with a top bit set could+ // read as a NaN, and a device is free to change those). Level 0 sits first, so the header's offsets for it are 0 and dim^3.+ let floats = 0;+ for (const l of levels) floats += l.data.length + l.data.length / 4;+ const packed = new Float32Array(floats);+ let at = 0;+ levels.forEach((l, k) => {+ const cells = l.data.length;+ packed.set(l.data, at);+ const words = new Uint32Array(packed.buffer, (at + cells) * 4, cells / 4);+ for (let i = 0; i < cells; i++) words[i >> 2]! |= l.owner[i]! << ((i & 3) * 8);+ if (k > 0) set(24 + (k - 1) * 8, l.dim, l.cell, l.origin[0]!, l.origin[1]!, l.origin[2]!, l.cell * GlobalSdf.REACH_CELLS, at, at + cells);+ at += cells + cells / 4;+ });+ const lights = (options.lights ?? []).slice(0, GI_MAX_LIGHTS);+ set(23, lights.length);+ lights.forEach((l, i) => {+ const o = 40 + i * GI_LIGHT_FLOATS, aim = l.spot?.axis ?? [0, -1, 0];+ const len = Math.hypot(aim[0], aim[1], aim[2]) || 1;+ // fo.y of the frame's distanceFalloff: the ramp's power, or minus the world units to the metre for an inverse-square light.+ const fy = l.metre && l.metre > 0 ? -l.metre : (l.falloff ?? 1);+ set(o, l.position[0], l.position[1], l.position[2], l.reach, l.radiance[0], l.radiance[1], l.radiance[2], l.spot ? 2 : 0,+ aim[0] / len, aim[1] / len, aim[2] / len, fy, l.innerRadius ?? 0, l.spot?.innerCos ?? 1, l.spot?.outerCos ?? 0, 0);+ });return { header, sdf: packed, instances: instanceData, pixels };}diff --git a/sdk/src/gi/surfaceCache.ts b/sdk/src/gi/surfaceCache.tsindex 6eadd6ac6..8f2c79667 100644--- a/sdk/src/gi/surfaceCache.ts+++ b/sdk/src/gi/surfaceCache.ts@@ -32,8 +32,43 @@ export interface SunLight {radiance: readonly [number, number, number];}+/**+ * A point or spot light, as the frame lights with it (distanceFalloff and spotCone in ShaderParser.cpp): held at full out to `innerRadius`,+ * then ramped to `reach` raised to `falloff`; or, with `metre` set, 1/d^2 in metres (`metre` world units to one) let go over the reach by+ * (1 - (d/reach)^4)^2. A spot is also cut to its cone by a smoothstep from the cosine of the outer half angle to the inner one.+ */+export interface PointLight {+ position: readonly [number, number, number];+ /** Colour times intensity. */+ radiance: readonly [number, number, number];+ reach: number;+ innerRadius?: number;+ /** The power the ramp is raised to (1 = linear); ignored when `metre` is set. */+ falloff?: number;+ /** World units to a metre: set for an inverse-square light. */+ metre?: number;+ spot?: { axis: readonly [number, number, number]; innerCos: number; outerCos: number };+}++/** How much of a light reaches `distance` away: the frame's distanceFalloff. */+export function lightReach(light: PointLight, distance: number): number {+ if (distance >= light.reach) return 0;+ if (light.metre && light.metre > 0) {+ const m = distance / light.metre, q = distance / Math.max(light.reach, 1e-4);+ const w = Math.min(Math.max(1 - q * q * q * q, 0), 1);+ return (w * w) / Math.max(m * m, 0.01);+ }+ const inner = Math.max(light.innerRadius ?? 0, 0);+ const ramp = Math.min(Math.max((light.reach - distance) / Math.max(light.reach - inner, 1e-4), 0), 1);+ return Math.pow(ramp, Math.max(light.falloff ?? 1, 1e-3));+}++const smoothstep = (a: number, b: number, x: number): number => { const t = Math.min(Math.max((x - a) / (b - a || 1e-9), 0), 1); return t * t * (3 - 2 * t); };+export interface LightOptions {sun?: SunLight;+ /** Point and spot lights, shadowed by the distance field like the sun. */+ lights?: readonly PointLight[];/** Shadows from the scene distance field; the sun is unshadowed without it. */sdf?: GlobalSdf;/** How far a shadow ray looks. */@@ -128,6 +163,24 @@ export class SurfaceCache {if (!blocked) for (let k = 0; k < 3; k++) light[k] += sun.radiance[k]! * ndl;}}+ for (const l of options.lights ?? []) {+ const to = [l.position[0] - s.position[0], l.position[1] - s.position[1], l.position[2] - s.position[2]];+ const dist = Math.hypot(to[0]!, to[1]!, to[2]!);+ if (dist < 1e-6 || dist >= l.reach) continue;+ const dir = [to[0]! / dist, to[1]! / dist, to[2]! / dist];+ const ndl = s.normal[0] * dir[0]! + s.normal[1] * dir[1]! + s.normal[2] * dir[2]!;+ if (ndl <= 0) continue;+ let atten = lightReach(l, dist);+ if (l.spot) {+ const a = l.spot.axis, len = Math.hypot(a[0], a[1], a[2]) || 1;+ atten *= smoothstep(l.spot.outerCos, l.spot.innerCos, -(dir[0]! * a[0] + dir[1]! * a[1] + dir[2]! * a[2]) / len);+ }+ if (atten <= 0) continue;+ const origin: [number, number, number] = [s.position[0] + s.normal[0] * bias, s.position[1] + s.normal[1] * bias, s.position[2] + s.normal[2] * bias];+ // The ray stops at the light: a body between is what blocks it.+ const blocked = options.sdf ? options.sdf.sphereTrace(origin, dir as [number, number, number], dist - bias) !== null : false;+ if (!blocked) for (let k = 0; k < 3; k++) light[k] += l.radiance[k]! * atten * ndl;+ }if (options.indirect) {const g = options.indirect(s.position, s.normal);for (let k = 0; k < 3; k++) light[k] += g[k]!;diff --git a/sdk/src/postprocess/effects.ts b/sdk/src/postprocess/effects.tsindex 16fab9a93..99bd8fea4 100644--- a/sdk/src/postprocess/effects.ts+++ b/sdk/src/postprocess/effects.ts@@ -581,6 +581,9 @@ registerEffect({{ name: 'u_cardSlices', label: 'Card Update Frames', min: 1, max: 16, step: 1, defaultValue: 4 },// One in this many of a probe's 64 rays is traced each frame, alternating; the history fills the rest in.{ name: 'u_probeStride', label: 'Probe Ray Stride', min: 1, max: 8, step: 1, defaultValue: 2 },+ // 0 fits one field to the whole scene. A size (world units) makes three levels, each four times the last, that follow the camera: the+ // finest holds what is near the eye at this resolution and the others carry the far scene, so a world larger than one window works.+ { name: 'u_cellSize', label: 'Field Cell Size', min: 0, max: 1000, step: 0.1, defaultValue: 0, worldUnits: 1 },],});diff --git a/src/esengine/renderer/frame/DynamicGI.cpp b/src/esengine/renderer/frame/DynamicGI.cppindex 72083a885..70a7520fd 100644--- a/src/esengine/renderer/frame/DynamicGI.cpp+++ b/src/esengine/renderer/frame/DynamicGI.cpp@@ -26,8 +26,11 @@ constexpr u32 kProbeTexels = 3; // the vector that integrates a probe against a/// The header the SDK writes (sdk/src/gi/gpuScene.ts), by index.enum Header : u32 {kDim = 0, kCell, kOriginX, kOriginY, kOriginZ, kReach, kInstances, kPixels,- kSunX, kSunY, kSunZ, kSunOn, kSunR, kSunG, kSunB, kBias, kRange, kTolerance, kSkyR, kSkyG, kSkyB, kHit, kHeaderSize+ kSunX, kSunY, kSunZ, kSunOn, kSunR, kSunG, kSunB, kBias, kRange, kTolerance, kSkyR, kSkyG, kSkyB, kHit, kLevels, kLights,+ /// Levels 1 and 2, eight floats each: dim, cell, origin x y z, reach, offset, owner offset. Then the lights, sixteen floats each.+ kLevelBlock = 24, kLightBlock = 40, kHeaderSize = 40};+constexpr u32 kMaxLevels = 3, kMaxLights = 8, kLightFloats = 16;struct ParamsBlock {f32 sdf[4];@@ -38,8 +41,12 @@ struct ParamsBlock {f32 trace[4];f32 sky[4];f32 misc[4];+ i32 levelA[kMaxLevels][4]; // origin xyz, cells per axis+ f32 levelB[kMaxLevels][4]; // cell size, reach+ u32 levelC[kMaxLevels][4]; // where the field starts in the buffer, and its owner words+ f32 lights[kMaxLights * 4][4];};-static_assert(sizeof(ParamsBlock) == 128, "the GI block is eight vec4s");+static_assert(sizeof(ParamsBlock) == 128 + 3 * 48 + 512, "the GI block: eight vec4s, three levels, eight lights of four");#ifdef ES_ENABLE_WEBGPU// The CPU twin of what is here is in sdk/src/gi (globalSdf.ts sphereTrace, surfaceCache.ts lookup, screenProbes.ts tracePoint);@@ -51,14 +58,18 @@ static_assert(sizeof(ParamsBlock) == 128, "the GI block is eight vec4s");const char* kCommon = R"WGSL(struct Frame { projection : mat4x4f, camera : vec4f, inverseViewProjection : mat4x4f, renderOrigin : vec4f };struct GI {- sdf : vec4f, // x: cells per axis, y: cell size, z: reach, w: intensity- origin : vec4i, // xyz: the window's first cell; w: the frame+ sdf : vec4f, // x: levels of the field, y: lights, w: intensity+ origin : vec4i, // w: the framecounts : vec4u, // x: instances, y: card pixels, z: probe tiles x, w: probe tiles ysunDir : vec4f, // xyz: toward the sun; w: 1 when there is onesunRad : vec4f, // rgb: radiance; w: how far off a surface a ray startstrace : vec4f, // x: how far a ray looks, y: card tolerance, z: blend, w: hit fraction of a cellsky : vec4f, // rgb: what a ray that meets nothing bringsmisc : vec4f, // x: how many frames the cards are spread over; y: 1 of every this many rays of a probe is traced a frame; z: pixels between probes+ levelA : array<vec4i, 3>, // per level: the first cell of its window, cells per axis+ levelB : array<vec4f, 3>, // per level: cell size, reach+ levelC : array<vec4u, 3>, // per level: where its field starts in sdfData, and its owner words+ lights : array<vec4f, 32>, // eight lights of four: position and reach | colour and kind | aim and falloff | inner radius and cone cosines};@group(0) @binding(0) var<uniform> frame : Frame;@group(0) @binding(1) var<uniform> gi : GI;@@ -69,42 +80,49 @@ struct GI {const PI : f32 = 3.14159265;-fn cellValue(c : vec3i) -> f32 {- let d = i32(gi.sdf.x);+fn cellValue(l : u32, c : vec3i) -> f32 {+ let d = gi.levelA[l].w;let w = c & vec3i(d - 1);- return sdfData[u32(w.x + w.y * d + w.z * d * d)];+ return sdfData[gi.levelC[l].x + u32(w.x + w.y * d + w.z * d * d)];}-fn sdfSample(p : vec3f) -> f32 {- let g = p / gi.sdf.y - vec3f(0.5);+fn sdfSample(l : u32, p : vec3f) -> f32 {+ let g = p / gi.levelB[l].x - vec3f(0.5);let i0 = vec3i(floor(g));let f = g - vec3f(i0);- let c000 = cellValue(i0);- let c100 = cellValue(i0 + vec3i(1, 0, 0));- let c010 = cellValue(i0 + vec3i(0, 1, 0));- let c110 = cellValue(i0 + vec3i(1, 1, 0));- let c001 = cellValue(i0 + vec3i(0, 0, 1));- let c101 = cellValue(i0 + vec3i(1, 0, 1));- let c011 = cellValue(i0 + vec3i(0, 1, 1));- let c111 = cellValue(i0 + vec3i(1, 1, 1));+ let c000 = cellValue(l, i0);+ let c100 = cellValue(l, i0 + vec3i(1, 0, 0));+ let c010 = cellValue(l, i0 + vec3i(0, 1, 0));+ let c110 = cellValue(l, i0 + vec3i(1, 1, 0));+ let c001 = cellValue(l, i0 + vec3i(0, 0, 1));+ let c101 = cellValue(l, i0 + vec3i(1, 0, 1));+ let c011 = cellValue(l, i0 + vec3i(0, 1, 1));+ let c111 = cellValue(l, i0 + vec3i(1, 1, 1));return mix(mix(mix(c000, c100, f.x), mix(c010, c110, f.x), f.y), mix(mix(c001, c101, f.x), mix(c011, c111, f.x), f.y), f.z);}-fn inField(p : vec3f) -> bool {- let c = p / gi.sdf.y - vec3f(gi.origin.xyz);- return all(c >= vec3f(1.0)) && all(c <= vec3f(gi.sdf.x - 1.0));+// The finest level whose window holds p at least a cell from its edge, or -1.+fn levelAt(p : vec3f) -> i32 {+ for (var l = 0u; l < u32(gi.sdf.x); l = l + 1u) {+ let c = p / gi.levelB[l].x - vec3f(gi.levelA[l].xyz);+ if (all(c >= vec3f(1.0)) && all(c <= vec3f(f32(gi.levelA[l].w) - 1.0))) { return i32(l); }+ }+ return -1;}-// Distance along dir to the first surface within maxT, or -1. A ray that starts inside a body hits at 0.+// Distance along dir to the first surface within maxT, or -1. A ray that starts inside a body hits at 0. It walks the finest level+// that holds it and hands over to a coarser one where the finer ends.fn sdfTrace(origin : vec3f, dir : vec3f, maxT : f32) -> f32 {var t = 0.0;- let cell = gi.sdf.y;for (var i = 0; i < 160; i = i + 1) {if (t >= maxT) { return -1.0; }let p = origin + dir * t;- if (!inField(p)) { return -1.0; }+ let li = levelAt(p);+ if (li < 0) { return -1.0; }+ let l = u32(li);+ let cell = gi.levelB[l].x;// Far from anything (the cell the point is in says so by more than three cells) one read is enough: the field there, less the- // farthest a point can be from its cell's centre, is a distance nothing is nearer than. Close to a surface the 8 reads of a trilinear.- let near = cellValue(vec3i(floor(p / cell)));+ // farthest a point can be from its cell centre, is a distance nothing is nearer than. Close to a surface the 8 reads of a trilinear.+ let near = cellValue(l, vec3i(floor(p / cell)));if (near > cell * 3.0) { t = t + near - cell * 0.87; continue; }- let d = sdfSample(p);+ let d = sdfSample(l, p);if (d < cell * gi.trace.w) { return t; }t = t + max(d, cell * 0.25);}@@ -137,8 +155,7 @@ fn unpackColour(w : u32) -> vec3f {// What the cards of one instance say a ray brings back from the surface it hit at point, travelling along dir: the cards that face it,// blended by how squarely each does, from the pixel whose surface is within the tolerance of the point. w is how far that pixel is, or// -1 when no card of the instance holds the point.-fn lookupIn(i : u32, point : vec3f, dir : vec3f) -> vec4f {- let tol = gi.trace.y;+fn lookupIn(i : u32, point : vec3f, dir : vec3f, tol : f32) -> vec4f {let b = instBase(i);let wmin = insts[b + 7u];let wmax = insts[b + 8u];@@ -186,32 +203,66 @@ fn lookupIn(i : u32, point : vec3f, dir : vec3f) -> vec4f {return vec4f(sum / total, error);}-// Which instance a cell is nearest to (id + 1; 0 for none, 127 for an id the table cannot hold). The words after the field hold four each.-fn ownerAt(c : vec3i) -> u32 {- let d = i32(gi.sdf.x);+// Which instance a cell of a level is nearest to (id + 1; 0 for none, 127 for an id the table cannot hold). The words after the field hold four each.+fn ownerAt(l : u32, c : vec3i) -> u32 {+ let d = gi.levelA[l].w;let w = c & vec3i(d - 1);let idx = u32(w.x + w.y * d + w.z * d * d);- let cells = u32(d * d * d);- return (bitcast<u32>(sdfData[cells + (idx >> 2u)]) >> ((idx & 3u) * 8u)) & 127u;+ return (bitcast<u32>(sdfData[gi.levelC[l].y + (idx >> 2u)]) >> ((idx & 3u) * 8u)) & 127u;}// What a ray brings back from the surface it hit at point. The field names the instance the point is by, so the cards of that one are-// asked; only where it says none (or its cards do not hold the point) are all of them, and of those the nearest wins.+// asked; only where it says none (or its cards do not hold the point) are all of them, and of those the nearest wins. A hit found in a+// coarse level is a cell of that level off the surface, and the cards are asked to forgive as much.fn lookup(point : vec3f, dir : vec3f) -> vec3f {- let owner = ownerAt(vec3i(floor(point / gi.sdf.y)));+ let l = u32(max(levelAt(point), 0));+ let cell = gi.levelB[l].x;+ let tol = max(gi.trace.y, cell * 1.5);+ let owner = ownerAt(l, vec3i(floor(point / cell)));if (owner > 0u && owner < 127u && owner <= gi.counts.x) {- let r = lookupIn(owner - 1u, point, dir);+ let r = lookupIn(owner - 1u, point, dir, tol);if (r.w >= 0.0) { return r.xyz; }}var best = vec3f(0.0);var bestError = 1e30;for (var i = 0u; i < gi.counts.x; i = i + 1u) {- let r = lookupIn(i, point, dir);+ let r = lookupIn(i, point, dir, tol);if (r.w >= 0.0 && r.w < bestError) { bestError = r.w; best = r.xyz; }}return best;}+// The frame falloff of a light over a distance (distanceFalloff in ShaderParser.cpp): held at full to the inner radius, ramped to the reach+// raised to the power fy; or, for fy < 0, 1 / d^2 in metres (-fy world units to one) let go over the reach.+fn lightFalloff(dist : f32, reach : f32, inner : f32, fy : f32) -> f32 {+ let ramp = clamp((reach - dist) / max(reach - inner, 1e-4), 0.0, 1.0);+ let shaped = pow(ramp, max(fy, 1e-3));+ let metres = dist / max(-fy, 1e-4);+ let q = dist / max(reach, 1e-4);+ let w = clamp(1.0 - q * q * q * q, 0.0, 1.0);+ return select(shaped, w * w / max(metres * metres, 0.01), fy < 0.0);+}++// What the point and spot lights give a surface at pos facing n, shadowed by the field: each is a ray from just off the surface to the light.+fn lightsDirect(pos : vec3f, n : vec3f, origin : vec3f) -> vec3f {+ var sum = vec3f(0.0);+ for (var i = 0u; i < u32(gi.sdf.y); i = i + 1u) {+ let a = gi.lights[i * 4u]; let b = gi.lights[i * 4u + 1u]; let c = gi.lights[i * 4u + 2u]; let d = gi.lights[i * 4u + 3u];+ let to = a.xyz - pos;+ let dist = length(to);+ if (dist < 1e-4 || dist >= a.w) { continue; }+ let dir = to / dist;+ let ndl = dot(n, dir);+ if (ndl <= 0.0) { continue; }+ var atten = lightFalloff(dist, a.w, d.x, c.w);+ if (b.w > 1.5) { atten = atten * smoothstep(d.z, d.y, dot(c.xyz, -dir)); }+ if (atten <= 0.0) { continue; }+ let t = sdfTrace(origin, dir, max(dist - gi.sunRad.w, 0.0));+ if (t < 0.0) { sum = sum + b.xyz * atten * ndl; }+ }+ return sum;+}+fn hash3(a : u32, b : u32, c : u32) -> f32 {var h = (a * 73856093u) ^ (b * 19349663u) ^ (c * 83492791u);h = (h ^ (h >> 16u)) * 0x45d9f3bu;@@ -300,6 +351,7 @@ fn main(@builtin(workgroup_id) wg : vec3u, @builtin(local_invocation_index) lidlet ndl = dot(n, gi.sunDir.xyz);if (ndl > 0.0 && sdfTrace(origin, gi.sunDir.xyz, gi.trace.x) < 0.0) { direct = gi.sunRad.xyz * ndl; }}+ direct = direct + lightsDirect(pos, n, origin);let now = albedo * (direct + cardSum[0] * (2.0 / 64.0)) + emissive;// A card is relit once in `slices` frames, so each relight carries that much more of the change.let blend = select(min(gi.trace.z * f32(slices), 1.0), 1.0, !settled);@@ -602,9 +654,26 @@ rg::ResourceId DynamicGI::declare(rg::RenderGraph& graph, rg::ResourceId input,const DynamicGIScene& s = dynamicGIScene();const std::vector<f32>& h = s.header;ParamsBlock b{};- b.sdf[0] = h[kDim]; b.sdf[1] = h[kCell]; b.sdf[2] = h[kReach]; b.sdf[3] = p.intensity;- b.origin[0] = static_cast<i32>(h[kOriginX]); b.origin[1] = static_cast<i32>(h[kOriginY]); b.origin[2] = static_cast<i32>(h[kOriginZ]);+ const u32 levels = std::clamp(static_cast<u32>(h[kLevels]), 1u, kMaxLevels);+ const u32 lights = std::min(static_cast<u32>(h[kLights]), kMaxLights);+ b.sdf[0] = static_cast<f32>(levels); b.sdf[1] = static_cast<f32>(lights); b.sdf[3] = p.intensity;b.origin[3] = static_cast<i32>(frame_);+ // Level 0 is the header's own fields; its field starts the buffer and its owner words follow it.+ const u32 dim0 = static_cast<u32>(h[kDim]);+ b.levelA[0][0] = static_cast<i32>(h[kOriginX]); b.levelA[0][1] = static_cast<i32>(h[kOriginY]); b.levelA[0][2] = static_cast<i32>(h[kOriginZ]);+ b.levelA[0][3] = static_cast<i32>(dim0);+ b.levelB[0][0] = h[kCell]; b.levelB[0][1] = h[kReach];+ b.levelC[0][0] = 0; b.levelC[0][1] = dim0 * dim0 * dim0;+ for (u32 k = 1; k < levels; ++k) {+ const u32 at = kLevelBlock + (k - 1) * 8;+ b.levelA[k][0] = static_cast<i32>(h[at + 2]); b.levelA[k][1] = static_cast<i32>(h[at + 3]); b.levelA[k][2] = static_cast<i32>(h[at + 4]);+ b.levelA[k][3] = static_cast<i32>(h[at]);+ b.levelB[k][0] = h[at + 1]; b.levelB[k][1] = h[at + 5];+ b.levelC[k][0] = static_cast<u32>(h[at + 6]); b.levelC[k][1] = static_cast<u32>(h[at + 7]);+ }+ for (u32 i = 0; i < lights; ++i) {+ for (u32 v = 0; v < 4; ++v) for (u32 c = 0; c < 4; ++c) b.lights[i * 4 + v][c] = h[kLightBlock + i * kLightFloats + v * 4 + c];+ }b.counts[0] = static_cast<u32>(h[kInstances]); b.counts[1] = static_cast<u32>(h[kPixels]);b.counts[2] = probeTilesX_; b.counts[3] = probeTilesY_;b.sunDir[0] = h[kSunX]; b.sunDir[1] = h[kSunY]; b.sunDir[2] = h[kSunZ]; b.sunDir[3] = h[kSunOn];diff --git a/tools/render-lab/gi_oracle.py b/tools/render-lab/gi_oracle.pyindex 0698dd012..e2c542217 100644--- a/tools/render-lab/gi_oracle.py+++ b/tools/render-lab/gi_oracle.py@@ -31,6 +31,8 @@ METHODS = {'baked': {'BAKE': '1', 'BOUNCES': '8'},'vgi': {'EFFECTS': json.dumps([{'type': 'voxelGI', 'enabled': True, 'uniforms': {}}])},'dgi': {'BACKEND': 'webgpu', 'HEADLESS_GPU': '1', 'EFFECTS': json.dumps([{'type': 'dynamicGI', 'enabled': True, 'uniforms': {}}])},+ # The same with a field that follows the camera: three levels from a 2.5 cm cell, so the far half of the room is in the coarse ones.+ 'dgil': {'BACKEND': 'webgpu', 'HEADLESS_GPU': '1', 'EFFECTS': json.dumps([{'type': 'dynamicGI', 'enabled': True, 'uniforms': {'u_cellSize': 2.5}}])},# The same, with every box a mesh and the `.esmeshsdf` / `.esmeshcards` an import with `dynamicGI` on writes beside it (make_mesh_boxes.mjs).'dgim': {'BACKEND': 'webgpu', 'HEADLESS_GPU': '1', 'MESH_BOXES': '1', 'EFFECTS': json.dumps([{'type': 'dynamicGI', 'enabled': True, 'uniforms': {}}])},}@@ -51,6 +53,12 @@ BANDS = {('gi_room', 'dgim'): (0.45, 1.45),('gi_away', 'dgim'): (0.45, 1.30),('gi_leak', 'dgim'): ('zero', 0.0005),+ ('gi_point', 'dgi'): (0.8, 1.25),+ ('gi_point', 'dgim'): (0.7, 1.4),+ ('gi_room', 'dgil'): (0.45, 1.45),+ ('gi_away', 'dgil'): (0.45, 1.30),+ ('gi_leak', 'dgil'): ('zero', 0.0005),+ ('gi_point', 'dgil'): (0.7, 1.4),('gi_emissive', 'dgim'): (0.75, 1.50),}# Wrong today, on purpose written down: the lightmap baker has no notion of an emissive surface (tools/lightmap-wasm/kernel.cpp carries albedo@@ -64,6 +72,10 @@ KNOWN_GAP = {}+# A lab with no Cycles picture (a lamp) is for the methods that light from the scene's own lights.+ONLY = {'gi_point': ['dgi', 'dgim', 'dgil']}++def lin(img):c = img / 255.0return np.where(c <= 0.04045, c / 12.92, ((c + 0.055) / 1.055) ** 2.4)@@ -100,6 +112,8 @@ def main():args = sys.argv[1:]flag = lambda n, d: args[args.index(n) + 1] if n in args else dlabs = flag('--labs', ','.join(S.GI)).split(',')+ if '--reference' in args:+ labs = [l for l in labs if os.path.exists(os.path.join(OUT, 'ref_%s.png' % l))]if '--reference' in args:data = {}for lab in labs:@@ -113,6 +127,8 @@ def main():failures = []for lab in labs:for method in methods:+ if method not in ONLY.get(lab, methods):+ continuegot = read(run_engine(lab, method), lab)ref = reference[lab]band = BANDS.get((lab, method))diff --git a/tools/render-lab/gi_point_reference.json b/tools/render-lab/gi_point_reference.jsonnew file mode 100644index 000000000..98a0053d1--- /dev/null+++ b/tools/render-lab/gi_point_reference.json@@ -0,0 +1,35 @@+{+ "source": "the CPU solver of pipeline/tests/gi-lab.test.ts (distance field + surface cache + probes, 5 bounces), linear radiance at each region",+ "regions": {+ "ceiling": [+ 0.46703070402145386,+ 0.43674567341804504,+ 0.38927045464515686+ ],+ "red wall": [+ 0.35834455490112305,+ 0.08538033068180084,+ 0.057939574122428894+ ],+ "green wall": [+ 0.09033013135194778,+ 0.3040061891078949,+ 0.08436840772628784+ ],+ "back wall": [+ 0.39758965373039246,+ 0.36648428440093994,+ 0.3240619897842407+ ],+ "floor": [+ 0.4505634605884552,+ 0.3864316940307617,+ 0.3555760681629181+ ],+ "block, lit side": [+ 0.2224079966545105,+ 0.2366098314523697,+ 0.17272616922855377+ ]+ }+}\ No newline at end of filediff --git a/tools/render-lab/gi_project.py b/tools/render-lab/gi_project.pyindex ee40a23c8..9594b1723 100644--- a/tools/render-lab/gi_project.py+++ b/tools/render-lab/gi_project.py@@ -54,6 +54,13 @@ for i, (name, centre, size, colour) in enumerate(spec['boxes']):'scale': {'x': 1, 'y': 1, 'z': 1} if MESH_BOXES else {'x': size[0] / 100.0, 'y': size[1] / 100.0, 'z': size[2] / 100.0}}},{'type': 'MeshRenderer', 'data': mr}]})+if spec.get('point'):+ pt = spec['point']+ entities.append({'id': 7, 'name': 'Lamp', 'parent': None, 'children': [], 'visible': True, 'components': [+ {'type': 'Transform', 'data': {'position': {'x': pt['pos'][0], 'y': pt['pos'][1], 'z': pt['pos'][2]}}},+ {'type': 'Light', 'data': {'type': 0, 'color': {'r': 1, 'g': 1, 'b': 1, 'a': 1}, 'intensity': pt['intensity'], 'radius': pt['radius'],+ 'innerRadius': 0.0, 'falloff': 1.0, 'inverseSquare': False, 'enabled': True, 'meshShadows': True, 'shadowStrength': 1.0}}]})+if spec['sun']:sw, sx, sy, sz = L.sun_quaternion(spec['sun']['dir'])entities.append({'id': 5, 'name': 'Sun', 'parent': None, 'children': [], 'visible': True, 'components': [diff --git a/tools/render-lab/gi_reference.json b/tools/render-lab/gi_reference.jsonindex e4763dd83..49b733861 100644--- a/tools/render-lab/gi_reference.json+++ b/tools/render-lab/gi_reference.json@@ -118,6 +118,41 @@0.17265174206204573,0.1341937111131402]+ },+ "gi_point": {+ "ceiling": [+ 0.46703070402145386,+ 0.43674567341804504,+ 0.38927045464515686+ ],+ "red wall": [+ 0.35834455490112305,+ 0.08538033068180084,+ 0.057939574122428894+ ],+ "green wall": [+ 0.09033013135194778,+ 0.3040061891078949,+ 0.08436840772628784+ ],+ "back wall": [+ 0.39758965373039246,+ 0.36648428440093994,+ 0.3240619897842407+ ],+ "floor": [+ 0.4505634605884552,+ 0.3864316940307617,+ 0.3555760681629181+ ],+ "block, lit side": [+ 0.2224079966545105,+ 0.2366098314523697,+ 0.17272616922855377+ ]}+ },+ "sources": {+ "gi_point": "the CPU solver of pipeline/tests/gi-lab.test.ts (distance field + surface cache + probes, 5 bounces), linear radiance at each region"}}\ No newline at end of filediff --git a/tools/render-lab/gi_specs.py b/tools/render-lab/gi_specs.pyindex dbc0f1fcb..713b40633 100644--- a/tools/render-lab/gi_specs.py+++ b/tools/render-lab/gi_specs.py@@ -68,6 +68,9 @@ GI = {# The room closed, the sun on its roof and walls outside: every pixel inside is 0 in Cycles, so whatever the engine shows is leak.'gi_leak': dict(cam=CAM_IN, boxes=room(), sun=dict(dir=sun_dir(40.0, 60.0), intensity=1.0)),# The room closed and dark but for an emissive panel on the back wall: the light of an emissive surface, which a lamp list does not have.+ # The room closed and lit by one lamp inside it (linear falloff to its radius): the engine lights what the lamp reaches, and the GI adds what those+ # surfaces bounce. No Cycles reference (its point lights are inverse-square watts); the reference is the CPU solver the GI is held to, tools/render-lab/gi_point_reference.json.+ 'gi_point': dict(cam=CAM_IN, boxes=room(), sun=None, point=dict(pos=(0.0, 200.0, 50.0), intensity=0.3, radius=600.0)),'gi_emissive': dict(cam=CAM_IN, boxes=room(emissive=dict(centre=(0.0, 150.0, 248.0), size=(120.0, 70.0, 4.0))), sun=None, emission=4.0),}@@ -87,6 +90,10 @@ REGIONS = {('ceiling', (0.0, 299.0, 150.0)), ('red wall', (199.0, 120.0, 120.0)), ('green wall', (-199.0, 120.0, 120.0)),('back wall', (60.0, 200.0, 249.0)), ('floor', (100.0, 1.0, 150.0)),],+ 'gi_point': [+ ('ceiling', (0.0, 299.0, 50.0)), ('red wall', (199.0, 150.0, 50.0)), ('green wall', (-199.0, 150.0, 50.0)),+ ('back wall', (0.0, 150.0, 249.0)), ('floor', (0.0, 1.0, 50.0)), ('block, lit side', (-90.0, 50.0, 29.0)),+ ],'gi_emissive': [('panel (emitter)', (0.0, 150.0, 246.0)), ('ceiling', (0.0, 299.0, 150.0)), ('red wall', (199.0, 120.0, 150.0)),('green wall', (-199.0, 120.0, 150.0)), ('floor', (60.0, 1.0, 150.0)), ('block, top', (-90.0, 100.5, 80.0)),