Skip to content

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.

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.md
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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, sideca
return { 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.ts
index 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.ts
index 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: rea
const 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.ts
index 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.ts
index 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.cpp
index 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 frame
counts : vec4u, // x: instances, y: card pixels, z: probe tiles x, w: probe tiles y
sunDir : vec4f, // xyz: toward the sun; w: 1 when there is one
sunRad : vec4f, // rgb: radiance; w: how far off a surface a ray starts
trace : vec4f, // x: how far a ray looks, y: card tolerance, z: blend, w: hit fraction of a cell
sky : vec4f, // rgb: what a ray that meets nothing brings
misc : 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) lid
let 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.py
index 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.0
return 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 d
labs = 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):
+ continue
got = 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.json
new file mode 100644
index 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 file
diff --git a/tools/render-lab/gi_project.py b/tools/render-lab/gi_project.py
index 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.json
index 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 file
diff --git a/tools/render-lab/gi_specs.py b/tools/render-lab/gi_specs.py
index 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)),