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): surface cache - mesh cards baked at import, lit by the sun with distance-field shadows, and looked up by a ray's hit

yhhe10f19087300
diff --git a/docs/GI_LUMEN_DESIGN.md b/docs/GI_LUMEN_DESIGN.md
index 5ec0616cf..228960d96 100644
--- a/docs/GI_LUMEN_DESIGN.md
+++ b/docs/GI_LUMEN_DESIGN.md
@@ -111,8 +111,8 @@
| 期 | 内容 | 验收 |
|---|---|---|
-| P0 | 网格 SDF 烘焙(pipeline)+ `.esmeshsdf` 资源类型与加载器 + 全局距离场。**已落地(2026-11-11)**:烘焙器 `pipeline/src/assets/meshSdf.ts`;导入设置 `distanceField`(默认关);`MeshSdfAssetLoader`;CPU 合成的 clipmap `sdk/src/gi/globalSdf.ts`(环形寻址、按脏区重建、`sphereTrace`/`occluded`);WGSL 追踪 `GLOBAL_SDF_WGSL`,由 `tools/gi/check-sdf-wgsl.mjs` 在无头 WebGPU 上与球的闭式解比对。**未做**:clipmap 接到渲染帧的网格实例、上传 GPU 存储缓冲、编辑器里的导入开关+ 全局距离场 clipmap + `sphereTrace`/`occlusion` 公共 WGSL | 新 oracle 场景:球、盒、薄墙的距离值和闭式解比对(`tools/oracle`);薄墙 10 cm 在 0.1 m 格下 `occlusion` 为真 |
-| P1 | 表面缓存:card 烘焙、图集分配、直接光 + 自发光刷新 | 卡面亮度与 `shade()` 参考一致;自发光面板出现在命中点取光里 |
+| P0 | 网格 SDF 烘焙 + `.esmeshsdf` 资源类型与加载器 + 全局距离场 clipmap + 公共 WGSL 追踪 | 球、盒、薄墙的距离和追踪与闭式解比对;WGSL 追踪由 `tools/gi/check-sdf-wgsl.mjs` 在无头 WebGPU 上校验。**已落地(2026-11-11)**:`pipeline/src/assets/meshSdf.ts`、`MeshSdfAssetLoader`、`sdk/src/gi/globalSdf.ts`;导入设置 `dynamicGI`(默认关)。**未做**:clipmap 接到渲染帧的网格实例、上传 GPU 存储缓冲、编辑器导入开关 |
+| P1 | 表面缓存:card 烘焙、直接光 + 自发光、命中点取光 | 卡面亮度与 Lambert 闭式值一致,SDF 遮挡产生阴影,自发光出现在命中点取光里。**CPU 参考已落地(2026-11-11)**:`pipeline/src/assets/meshCards.ts`(`.esmeshcards`,6 个轴向 card)、`MeshCardsAssetLoader`、`sdk/src/gi/surfaceCache.ts`(`light`、`lookup`)、`pipeline/tests/surface-cache.test.ts`。**未做**:基色贴图不读(只用材质基色与顶点色)、图集分配、GPU 刷新通道 |
| P2 | 屏幕探针 + SDF 追踪 + 时间/空间滤波,单次反弹 | `gi_leak` 为 0;`gi_room` 阴影区 0.6–1.1 |
| P3 | 表面缓存吃上一帧间接光(多次反弹)+ 世界辐射缓存 | `gi_room` 0.8–1.1;`gi_away` ≥ 0.8;`gi_emissive` ≥ 0.8 |
| P4 | 成本:自适应探针、光线预算、QualityConfig 档位、手机与桌面实测 | 帧时间达标;gate 内加成本断言(同阴影通道做法) |
diff --git a/pipeline/src/assets/importModelFile.ts b/pipeline/src/assets/importModelFile.ts
index 4357e3ce0..b0b0a7713 100644
--- a/pipeline/src/assets/importModelFile.ts
+++ b/pipeline/src/assets/importModelFile.ts
@@ -21,6 +21,8 @@ import {
} from './modelImport';
import { modelStem, readModelSource } from './readModelSource';
import { bakeMeshSdf, encodeMeshSdf } from './meshSdf';
+import { bakeMeshCards } from './meshCards';
+import { encodeMeshCards } from '../../../sdk/src/gi/cardFormat';
import { parseManifest } from '../project/format';
export interface ModelImportSettings {
@@ -31,8 +33,8 @@ export interface ModelImportSettings {
lodMinTriangles: number;
characters: boolean;
springBones: boolean;
- /** Bake a signed distance field beside each mesh (`<name>.esmeshsdf`), which the dynamic GI traces against. */
- distanceField: boolean;
+ /** Bake what the dynamic GI reads of each mesh: its distance field (`<name>.esmeshsdf`) and its surface cards (`<name>.esmeshcards`). */
+ dynamicGI: boolean;
}
export interface ImportedModel {
@@ -66,7 +68,7 @@ export interface ImportModelOptions {
}
const DEFAULTS: ModelImportSettings = {
- scale: 1, lightmapUV: false, specularMap: 'color', lodLevels: 0, lodMinTriangles: 256, characters: false, springBones: false, distanceField: false,
+ scale: 1, lightmapUV: false, specularMap: 'color', lodLevels: 0, lodMinTriangles: 256, characters: false, springBones: false, dynamicGI: false,
};
/** What a model's `.meta` asks of the import; the schema's defaults where it is silent or unreadable. One read, because two would be two chances to disagree. */
@@ -74,7 +76,7 @@ export function modelSettings(absSource: string): ModelImportSettings {
try {
const meta = JSON.parse(readFileSync(`${absSource}.meta`, 'utf8')) as
{ importer?: { scale?: unknown; lightmapUV?: unknown; specularMap?: unknown;
- lodLevels?: unknown; lodMinTriangles?: unknown; characterMaterials?: unknown; springBones?: unknown; distanceField?: unknown } };
+ lodLevels?: unknown; lodMinTriangles?: unknown; characterMaterials?: unknown; springBones?: unknown; dynamicGI?: unknown } };
const imp = meta.importer;
const scale = imp?.scale;
const levels = imp?.lodLevels;
@@ -87,7 +89,7 @@ export function modelSettings(absSource: string): ModelImportSettings {
lodMinTriangles: typeof minTriangles === 'number' && minTriangles >= 0 ? minTriangles : 256,
characters: imp?.characterMaterials === 'auto',
springBones: imp?.springBones === 'auto',
- distanceField: imp?.distanceField === true,
+ dynamicGI: imp?.dynamicGI === true,
};
} catch {
return { ...DEFAULTS };
@@ -127,7 +129,7 @@ export async function importModelFile(opts: ImportModelOptions): Promise<Importe
const sourceDir = opts.originDir ?? path.dirname(absSource);
const stem = modelStem(absSource);
const projectRef = (abs: string): string => path.relative(path.resolve(root), abs).split(path.sep).join('/');
- const { scale, lightmapUV, specularMap, lodLevels, lodMinTriangles, characters, springBones, distanceField } = { ...modelSettings(absSource), ...opts.settings };
+ const { scale, lightmapUV, specularMap, lodLevels, lodMinTriangles, characters, springBones, dynamicGI } = { ...modelSettings(absSource), ...opts.settings };
const { meshes, textures, nodes, animations, externalFiles, warnings } = await readModelSource(
new Uint8Array(readFileSync(absSource)), stem,
@@ -259,9 +261,15 @@ export async function importModelFile(opts: ImportModelOptions): Promise<Importe
await write(`${lodName(mesh, i + 1)}.esmesh`, lodBytes);
}
// A skinned or morphing mesh moves its surface: a field baked from the bind pose would be a wrong wall.
- if (distanceField && !mesh.data.inverseBindMatrices && !mesh.data.morph) {
+ if (dynamicGI && !mesh.data.inverseBindMatrices && !mesh.data.morph) {
const field = bakeMeshSdf(mesh.data, { cellSize: (0.1 * projectUnitsPerMeter(root)) / Math.max(scale, 1e-6) });
if (field) await write(`${mesh.name}.esmeshsdf`, encodeMeshSdf(field));
+ const m = mesh.material;
+ const cards = bakeMeshCards(mesh.data, {
+ cell: (0.25 * projectUnitsPerMeter(root)) / Math.max(scale, 1e-6),
+ baseColor: m ? [m.baseColor[0], m.baseColor[1], m.baseColor[2]] : undefined, emissive: m?.emissive,
+ });
+ if (cards) await write(`${mesh.name}.esmeshcards`, encodeMeshCards(cards));
}
}
}
diff --git a/pipeline/src/assets/meshCards.ts b/pipeline/src/assets/meshCards.ts
new file mode 100644
index 000000000..dd885fe31
--- /dev/null
+++ b/pipeline/src/assets/meshCards.ts
@@ -0,0 +1,91 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file meshCards.ts
+ * @brief Bakes the six axis cards of a mesh at import: what the surface cache lights (docs/GI_LUMEN_DESIGN.md, 3.3).
+ *
+ * @details Each card is an orthographic render from outside along one axis, done on the CPU: every triangle that faces the viewer is
+ * scan-converted at the card's pixel centres and the nearest wins. Colour is the material's base colour times the vertex
+ * colour where the mesh has one; a base-colour TEXTURE is not read (the bake works from the mesh and its constants), so a
+ * textured surface is cached at its tint, not its picture. That is stated here because it is the largest thing the bake
+ * leaves out.
+ */
+import { MeshChannel, MeshChannelType, type MeshData } from 'esengine';
+import { CARD_AXES, NO_DEPTH, type MeshCard, type MeshCards } from '../../../sdk/src/gi/cardFormat';
+import { meshPositions } from './meshSdf';
+
+export interface MeshCardOptions {
+ /** World size of a card pixel; raised so no card is wider than `maxResolution`. */
+ cell: number;
+ maxResolution?: number;
+ baseColor?: readonly [number, number, number];
+ emissive?: readonly [number, number, number];
+}
+
+function vertexColors(data: MeshData): Float32Array | null {
+ const c = data.channels.find((ch) => ch.semantic === MeshChannel.Color && ch.components >= 3
+ && (ch.type === MeshChannelType.Float32 || ch.type === MeshChannelType.UNorm8));
+ if (!c) return null;
+ const view = new DataView(data.vertices.buffer, data.vertices.byteOffset, data.vertices.byteLength);
+ const out = new Float32Array(data.vertexCount * 3);
+ for (let v = 0; v < data.vertexCount; v++) for (let k = 0; k < 3; k++) {
+ out[v * 3 + k] = c.type === MeshChannelType.Float32
+ ? view.getFloat32(v * data.vertexStride + c.offset + k * 4, true)
+ : view.getUint8(v * data.vertexStride + c.offset + k) / 255;
+ }
+ return out;
+}
+
+export function bakeMeshCards(data: MeshData, options: MeshCardOptions): MeshCards | null {
+ const positions = meshPositions(data);
+ if (!positions || data.indices.length < 3) return null;
+ const colors = vertexColors(data), base = options.baseColor ?? [1, 1, 1], emit = options.emissive ?? [0, 0, 0];
+ const maxRes = options.maxResolution ?? 32;
+ const extent = [0, 1, 2].map((k) => data.aabbMax[k]! - data.aabbMin[k]!);
+ const cell = Math.max(options.cell, Math.max(...extent, 1e-9) / maxRes);
+ const emissiveScale = Math.max(...emit, 1e-6);
+ const cards: MeshCard[] = [];
+ for (const { axis, sign, u, v } of CARD_AXES) {
+ const width = Math.max(1, Math.min(maxRes, Math.ceil(extent[u]! / cell))), height = Math.max(1, Math.min(maxRes, Math.ceil(extent[v]! / cell)));
+ const n = width * height;
+ const card: MeshCard = { width, height, depth: new Uint16Array(n).fill(NO_DEPTH), normal: new Int8Array(n * 3), albedo: new Uint8Array(n * 3), emissive: new Uint8Array(n * 3) };
+ const best = new Float32Array(n).fill(Infinity);
+ const du = extent[u]! / width, dv = extent[v]! / height, ext = extent[axis]! || 1;
+ for (let t = 0; t < data.indices.length; t += 3) {
+ const i = [data.indices[t]!, data.indices[t + 1]!, data.indices[t + 2]!];
+ const P = i.map((k) => [positions[k * 3]!, positions[k * 3 + 1]!, positions[k * 3 + 2]!]);
+ const e1 = [0, 1, 2].map((k) => P[1]![k]! - P[0]![k]!), e2 = [0, 1, 2].map((k) => P[2]![k]! - P[0]![k]!);
+ const nx = e1[1]! * e2[2]! - e1[2]! * e2[1]!, ny = e1[2]! * e2[0]! - e1[0]! * e2[2]!, nz = e1[0]! * e2[1]! - e1[1]! * e2[0]!;
+ const nl = Math.hypot(nx, ny, nz);
+ if (nl < 1e-20) continue;
+ const nrm = [nx / nl, ny / nl, nz / nl];
+ if (nrm[axis]! * sign <= 1e-6) continue; // not facing this card's viewer
+ // Barycentric in the (u, v) plane.
+ const ax = P[0]![u]!, ay = P[0]![v]!, bx = P[1]![u]!, by = P[1]![v]!, cx = P[2]![u]!, cy = P[2]![v]!;
+ const det = (bx - ax) * (cy - ay) - (cx - ax) * (by - ay);
+ if (Math.abs(det) < 1e-20) continue;
+ const x0 = Math.max(Math.floor((Math.min(ax, bx, cx) - data.aabbMin[u]!) / du), 0), x1 = Math.min(Math.floor((Math.max(ax, bx, cx) - data.aabbMin[u]!) / du), width - 1);
+ const y0 = Math.max(Math.floor((Math.min(ay, by, cy) - data.aabbMin[v]!) / dv), 0), y1 = Math.min(Math.floor((Math.max(ay, by, cy) - data.aabbMin[v]!) / dv), height - 1);
+ for (let y = y0; y <= y1; y++) for (let x = x0; x <= x1; x++) {
+ const pu = data.aabbMin[u]! + (x + 0.5) * du, pv = data.aabbMin[v]! + (y + 0.5) * dv;
+ const l1 = ((pu - ax) * (cy - ay) - (cx - ax) * (pv - ay)) / det, l2 = ((bx - ax) * (pv - ay) - (pu - ax) * (by - ay)) / det, l0 = 1 - l1 - l2;
+ const eps = -1e-6;
+ if (l0 < eps || l1 < eps || l2 < eps) continue;
+ const a = l0 * P[0]![axis]! + l1 * P[1]![axis]! + l2 * P[2]![axis]!;
+ const depth = sign > 0 ? data.aabbMax[axis]! - a : a - data.aabbMin[axis]!;
+ const px = x + y * width;
+ if (depth >= best[px]!) continue;
+ best[px] = depth;
+ card.depth[px] = Math.min(Math.round((depth / ext) * 65534), 65534);
+ for (let k = 0; k < 3; k++) {
+ card.normal[px * 3 + k] = Math.round(nrm[k]! * 127);
+ const tint = colors ? l0 * colors[i[0]! * 3 + k]! + l1 * colors[i[1]! * 3 + k]! + l2 * colors[i[2]! * 3 + k]! : 1;
+ card.albedo[px * 3 + k] = Math.round(Math.min(Math.max(base[k]! * tint, 0), 1) * 255);
+ card.emissive[px * 3 + k] = Math.round(Math.min(Math.max(emit[k]! / emissiveScale, 0), 1) * 255);
+ }
+ }
+ }
+ cards.push(card);
+ }
+ return { aabbMin: [...data.aabbMin], aabbMax: [...data.aabbMax], cell, emissiveScale, cards };
+}
diff --git a/pipeline/tests/model-distance-field.test.ts b/pipeline/tests/model-distance-field.test.ts
index 74def4bb6..30d312d9a 100644
--- a/pipeline/tests/model-distance-field.test.ts
+++ b/pipeline/tests/model-distance-field.test.ts
@@ -1,7 +1,7 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
- * @file A model imported with `distanceField` on gets a `.esmeshsdf` beside each mesh; without it, none.
+ * @file A model imported with `dynamicGI` on gets a `.esmeshsdf` and `.esmeshcards` beside each mesh; without it, none.
*/
import { mkdtempSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
@@ -9,6 +9,7 @@ import path from 'node:path';
import { afterAll, describe, expect, it } from 'vitest';
import { importModelFile } from '../src/assets/importModelFile';
import { decodeMeshSdf, sampleMeshSdf } from '../src/assets/meshSdf';
+import { decodeMeshCards } from '../../sdk/src/gi/cardFormat';
/** A cube of half extent 50 (units), glTF with outward winding. */
function cubeGltf(): string {
@@ -40,13 +41,13 @@ describe('importing a model with a distance field', () => {
const roots: string[] = [];
afterAll(() => { for (const r of roots) rmSync(r, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 }); });
- async function run(distanceField: boolean) {
+ async function run(dynamicGI: boolean) {
const root = mkdtempSync(path.join(tmpdir(), 'model-sdf-'));
roots.push(root);
const dir = path.join(root, 'assets', 'models');
mkdirSync(dir, { recursive: true });
writeFileSync(path.join(dir, 'cube.gltf'), cubeGltf());
- const result = await importModelFile({ root, destDir: 'assets/models', absSource: path.join(dir, 'cube.gltf'), settings: { distanceField } });
+ const result = await importModelFile({ root, destDir: 'assets/models', absSource: path.join(dir, 'cube.gltf'), settings: { dynamicGI } });
return { result, dir, files: readdirSync(dir) };
}
@@ -58,10 +59,13 @@ describe('importing a model with a distance field', () => {
const sdf = decodeMeshSdf(new Uint8Array(readFileSync(path.join(dir, name!))));
expect(sampleMeshSdf(sdf, [0, 0, 0])).toBeLessThan(-40);
expect(sampleMeshSdf(sdf, [80, 0, 0])).toBeGreaterThan(20);
+ const cardsName = files.find((f) => f.endsWith('.esmeshcards'));
+ expect(cardsName).toBeDefined();
+ expect(decodeMeshCards(new Uint8Array(readFileSync(path.join(dir, cardsName!)))).cards.length).toBe(6);
});
it('writes none unless it is asked to', async () => {
const { files } = await run(false);
- expect(files.some((f) => f.endsWith('.esmeshsdf'))).toBe(false);
+ expect(files.some((f) => f.endsWith('.esmeshsdf') || f.endsWith('.esmeshcards'))).toBe(false);
});
});
diff --git a/pipeline/tests/surface-cache.test.ts b/pipeline/tests/surface-cache.test.ts
new file mode 100644
index 000000000..0de654b16
--- /dev/null
+++ b/pipeline/tests/surface-cache.test.ts
@@ -0,0 +1,151 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file surface-cache.test.ts
+ * @brief Mesh cards baked from a box, lit by a sun with the scene distance field for shadows, against the Lambert values the maths gives.
+ */
+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 { decodeMeshCards, encodeMeshCards } from '../../sdk/src/gi/cardFormat';
+import { GlobalSdf } from '../../sdk/src/gi/globalSdf';
+import { SurfaceCache } from '../../sdk/src/gi/surfaceCache';
+
+function meshOf(positions: number[], indices: number[]): MeshData {
+ const vertexCount = positions.length / 3, vertices = new Uint8Array(vertexCount * 12), view = new DataView(vertices.buffer);
+ positions.forEach((v, i) => view.setFloat32(i * 4, v, true));
+ const min = [Infinity, Infinity, Infinity] as [number, number, number], max = [-Infinity, -Infinity, -Infinity] as [number, number, number];
+ for (let v = 0; v < vertexCount; v++) for (let k = 0; k < 3; k++) { min[k] = Math.min(min[k], positions[v * 3 + k]!); max[k] = Math.max(max[k], positions[v * 3 + k]!); }
+ return { channels: [{ semantic: MeshChannel.Position, components: 3, type: MeshChannelType.Float32, offset: 0 }], vertexStride: 12, vertexCount,
+ vertices, indices: new Uint32Array(indices), aabbMin: min, aabbMax: max };
+}
+
+function box(h: [number, number, number]): MeshData {
+ const p: number[] = [];
+ for (let i = 0; i < 8; i++) p.push((i & 1 ? 1 : -1) * h[0], (i & 2 ? 1 : -1) * h[1], (i & 4 ? 1 : -1) * h[2]);
+ const idx: number[] = [];
+ for (const [a, b, c, d] of [[0, 2, 3, 1], [4, 5, 7, 6], [0, 1, 5, 4], [2, 6, 7, 3], [0, 4, 6, 2], [1, 3, 7, 5]] as [number, number, number, number][]) {
+ const pa = p.slice(a * 3, a * 3 + 3), pb = p.slice(b * 3, b * 3 + 3), pc = p.slice(c * 3, c * 3 + 3);
+ const u = pb.map((v, k) => v - pa[k]!), w = pc.map((v, k) => v - pa[k]!);
+ const n = [u[1]! * w[2]! - u[2]! * w[1]!, u[2]! * w[0]! - u[0]! * w[2]!, u[0]! * w[1]! - u[1]! * w[0]!];
+ idx.push(...(n[0]! * pa[0]! + n[1]! * pa[1]! + n[2]! * pa[2]! > 0 ? [a, b, c, a, c, d] : [a, c, b, a, d, c]));
+ }
+ return meshOf(p, idx);
+}
+
+const matrix = (t: [number, number, number], s = 1): number[] => [s, 0, 0, 0, 0, s, 0, 0, 0, 0, s, 0, t[0], t[1], t[2], 1];
+const ALBEDO = [0.8, 0.4, 0.2] as const;
+// Faces: 0 +x, 1 -x, 2 +y, 3 -y, 4 +z, 5 -z.
+const TOP = 2, SIDE = 0, BOTTOM = 3;
+
+describe('mesh cards', () => {
+ const cards = bakeMeshCards(box([1, 1, 1]), { cell: 0.25, baseColor: ALBEDO })!;
+
+ it('are six views of a box, each filled edge to edge with the face that looks out', () => {
+ expect(cards.cards.length).toBe(6);
+ for (const card of cards.cards) {
+ expect(card.width).toBe(8);
+ expect(card.height).toBe(8);
+ expect(card.depth.every((d) => d === 0)).toBe(true);
+ }
+ const top = cards.cards[TOP]!;
+ expect(Array.from(top.normal.slice(0, 3))).toEqual([0, 127, 0]);
+ expect(Array.from(top.albedo.slice(0, 3))).toEqual(ALBEDO.map((c) => Math.round(c * 255)));
+ });
+
+ it('read back as written', () => {
+ const back = decodeMeshCards(encodeMeshCards(cards));
+ expect(back.cell).toBeCloseTo(cards.cell, 6);
+ expect(back.cards[SIDE]!.albedo).toEqual(cards.cards[SIDE]!.albedo);
+ expect(back.cards[TOP]!.depth).toEqual(cards.cards[TOP]!.depth);
+ expect(() => decodeMeshCards(new Uint8Array(100))).toThrow();
+ });
+
+ it('record the depth of a surface set back from the box face', () => {
+ // A flat plate at y = 0.5 inside a box of height 1: seen from +y it is 0.5 down from the top of the box, seen from -y it faces away.
+ const plate = meshOf([-1, 0.5, -1, 1, 0.5, -1, 1, 0.5, 1, -1, 0.5, 1, 0, 1, 0, 0, -1, 0], [0, 2, 1, 0, 3, 2]);
+ const c = bakeMeshCards(plate, { cell: 0.5 })!;
+ const top = c.cards[TOP]!;
+ expect(top.depth[0]).toBeGreaterThan(0);
+ expect(Math.abs((top.depth[0]! / 65534) * 2 - 0.5)).toBeLessThan(0.01);
+ expect(c.cards[BOTTOM]!.depth[0]).toBe(65535);
+ });
+});
+
+describe('the surface cache', () => {
+ const cards = bakeMeshCards(box([1, 1, 1]), { cell: 0.25, baseColor: ALBEDO, emissive: [0.5, 0, 0] })!;
+ const lit = (toLight: [number, number, number], extra?: (cache: SurfaceCache, sdf: GlobalSdf) => void, ownSdf = false) => {
+ const sdf = new GlobalSdf([{ dim: 64, cell: 0.25 }, { dim: 64, cell: 1 }]);
+ sdf.setCenter([0, 0, 0]);
+ const cache = new SurfaceCache();
+ cache.add({ id: 1, cards, worldFromLocal: matrix([0, 0, 0]) });
+ if (ownSdf) sdf.update({ id: 1, sdf: bakeMeshSdf(box([1, 1, 1]), { cellSize: 0.1 })!, worldFromLocal: matrix([0, 0, 0]) });
+ extra?.(cache, sdf);
+ cache.light({ sun: { toLight, radiance: [1, 1, 1] }, sdf, bias: 0.4 });
+ return { cache, sdf };
+ };
+
+ it('lights a face by albedo times the sun times the cosine, and adds what the surface emits', () => {
+ const dir = [0.6, 0.8, 0] as [number, number, number];
+ const { cache } = lit(dir);
+ const top = cache.radianceAt(1, TOP, 3, 3)!, side = cache.radianceAt(1, SIDE, 3, 3)!, bottom = cache.radianceAt(1, BOTTOM, 3, 3)!;
+ for (let k = 0; k < 3; k++) {
+ expect(top[k]!).toBeCloseTo(ALBEDO[k]! * 0.8 + (k === 0 ? 0.5 : 0), 2);
+ expect(side[k]!).toBeCloseTo(ALBEDO[k]! * 0.6 + (k === 0 ? 0.5 : 0), 2);
+ expect(bottom[k]!).toBeCloseTo(k === 0 ? 0.5 : 0, 2); // facing away: emission only
+ }
+ });
+
+ it('shadows a face the distance field says is behind something, and only that face', () => {
+ const plate = box([3, 0.2, 3]);
+ const { cache } = lit([0, 1, 0], (_cache, sdf) => {
+ sdf.update({ id: 2, sdf: bakeMeshSdf(plate, { cellSize: 0.1 })!, worldFromLocal: matrix([0, 3, 0]) });
+ });
+ // The plate is a body in the field and not in the cache: its shadow falls on the box under it.
+ expect(cache.radianceAt(1, TOP, 3, 3)![1]!).toBeCloseTo(0, 2);
+ const open = lit([0, 1, 0]).cache.radianceAt(1, TOP, 3, 3)!;
+ expect(open[1]!).toBeCloseTo(ALBEDO[1]!, 2);
+ });
+
+ it('is not shadowed by its own mesh', () => {
+ const { cache } = lit([0, 1, 0], undefined, true);
+ expect(cache.radianceAt(1, TOP, 3, 3)![1]!).toBeCloseTo(ALBEDO[1]!, 2);
+ });
+
+ it('answers a ray with the face it looks at: the top from above, the side from the side, nothing from open air', () => {
+ const { cache } = lit([0, 1, 0]);
+ const fromAbove = cache.lookup([0.3, 1, 0.2], [0, -1, 0], 0.3)!;
+ expect(fromAbove[1]!).toBeCloseTo(ALBEDO[1]!, 2);
+ const fromSide = cache.lookup([1, 0.2, 0.1], [-1, 0, 0], 0.3)!;
+ expect(fromSide[1]!).toBeCloseTo(0, 2); // the side is not toward the sun
+ expect(cache.lookup([0.3, 2.5, 0.2], [0, -1, 0], 0.3)).toBeNull();
+ expect(cache.lookup([9, 9, 9], [0, -1, 0], 0.3)).toBeNull();
+ });
+
+ it('blends the faces a slanted ray sees by how squarely it looks at each', () => {
+ const { cache } = lit([0, 1, 0]);
+ const r = cache.lookup([1, 1, 0.1], [-Math.SQRT1_2, -Math.SQRT1_2, 0], 0.3)!;
+ // Half top (lit: albedo), half side (dark): about half the albedo.
+ expect(r[1]!).toBeCloseTo(ALBEDO[1]! / 2, 1);
+ });
+
+ it('feeds an indirect term through the albedo', () => {
+ const sdf = new GlobalSdf([{ dim: 32, cell: 0.5 }]);
+ const cache = new SurfaceCache();
+ cache.add({ id: 1, cards, worldFromLocal: matrix([0, 0, 0]) });
+ cache.light({ sdf, indirect: () => [0.5, 0.5, 0.5] });
+ const r = cache.radianceAt(1, BOTTOM, 2, 2)!;
+ expect(r[1]!).toBeCloseTo(ALBEDO[1]! * 0.5, 2);
+ });
+
+ it('follows an instance that is moved and scaled', () => {
+ const cache = new SurfaceCache();
+ cache.add({ id: 1, cards, worldFromLocal: matrix([10, 0, 0], 2) });
+ cache.light({ sun: { toLight: [0, 1, 0], radiance: [1, 1, 1] } });
+ // Scaled by 2 about its centre, the top is at y = 2.
+ const r = cache.lookup([10.5, 2, 0.5], [0, -1, 0], 0.3)!;
+ expect(r[1]!).toBeCloseTo(ALBEDO[1]!, 2);
+ expect(cache.lookup([0.5, 1, 0.5], [0, -1, 0], 0.3)).toBeNull();
+ });
+});
diff --git a/sdk/src/asset/Assets.ts b/sdk/src/asset/Assets.ts
index 22295f6e3..325c2c2d4 100644
--- a/sdk/src/asset/Assets.ts
+++ b/sdk/src/asset/Assets.ts
@@ -42,6 +42,7 @@ import { isBuiltinMeshRef } from './builtinMeshes';
import { EnvironmentAssetLoader } from './loaders/EnvironmentAssetLoader';
import { ProbeVolumeAssetLoader } from './loaders/ProbeVolumeAssetLoader';
import { MeshSdfAssetLoader } from './loaders/MeshSdfAssetLoader';
+import { MeshCardsAssetLoader } from './loaders/MeshCardsAssetLoader';
import { FontAssetLoader } from './loaders/FontAssetLoader';
import { AudioAssetLoader } from './loaders/AudioAssetLoader';
import { AnimClipAssetLoader } from './loaders/AnimClipAssetLoader';
@@ -2693,6 +2694,7 @@ export class Assets {
this.register(new EnvironmentAssetLoader(core));
this.register(new ProbeVolumeAssetLoader(core));
this.register(new MeshSdfAssetLoader());
+ this.register(new MeshCardsAssetLoader());
// The audio loader needs the AudioAPI outside load() too (unload /
// invalidate have no LoadContext), so it shares Assets' lazy accessor.
this.register(new AudioAssetLoader(() => this.getAudio_()));
diff --git a/sdk/src/asset/loaders/MeshCardsAssetLoader.ts b/sdk/src/asset/loaders/MeshCardsAssetLoader.ts
new file mode 100644
index 000000000..e8ae5a469
--- /dev/null
+++ b/sdk/src/asset/loaders/MeshCardsAssetLoader.ts
@@ -0,0 +1,25 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+import type { AssetLoader, LoadContext } from '../AssetLoader';
+import { decodeMeshCards, type MeshCards } from '../../gi/cardFormat';
+
+/**
+ * Loads `.esmeshcards` — the six axis views of a mesh the dynamic GI's surface cache lights. Plain memory, like the distance field.
+ */
+export class MeshCardsAssetLoader implements AssetLoader<MeshCards> {
+ readonly type = 'meshCards';
+ readonly extensions = ['.esmeshcards'];
+
+ async load(path: string, ctx: LoadContext): Promise<MeshCards> {
+ const bytes = new Uint8Array(await ctx.loadBinary(ctx.catalog.getBuildPath(path)));
+ try {
+ return decodeMeshCards(bytes);
+ } catch (err) {
+ throw new Error(`${path}: ${err instanceof Error ? err.message : String(err)}`);
+ }
+ }
+
+ unload(): void {
+ // Decoded arrays are ordinary memory the caller may still hold.
+ }
+}
diff --git a/sdk/src/gi/cardFormat.ts b/sdk/src/gi/cardFormat.ts
new file mode 100644
index 000000000..39f1485b2
--- /dev/null
+++ b/sdk/src/gi/cardFormat.ts
@@ -0,0 +1,105 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file cardFormat.ts
+ * @brief `.esmeshcards`: the six axis views of a mesh the surface cache lights (docs/GI_LUMEN_DESIGN.md, 3.3).
+ *
+ * @details A card is an orthographic view of the mesh from outside along one of +-x, +-y, +-z: for each pixel the nearest surface that
+ * faces the viewer, as its depth from the mesh's bounding box, its normal, its colour and what it emits. The pixel grid
+ * spans the box face, so a card says nothing about where the mesh stands in the world: the instance's transform does.
+ *
+ * Face order is +x, -x, +y, -y, +z, -z (`CARD_AXES`). The two axes a card's pixels run along are the other two, in order
+ * (for +-x: y then z; for +-y: x then z; for +-z: x then y); pixel (i, j) is centred at box min + (i + 0.5, j + 0.5) * cell there.
+ */
+
+export interface MeshCard {
+ width: number;
+ height: number;
+ /** Depth from the box face the card looks in from, in 1/65535ths of the box's extent along the card's axis; 65535 = nothing here. */
+ depth: Uint16Array;
+ /** Unit normal, signed bytes (x, y, z) per pixel; /127. */
+ normal: Int8Array;
+ /** Linear albedo, bytes (r, g, b) per pixel. */
+ albedo: Uint8Array;
+ /** Emission, bytes (r, g, b) per pixel, times `MeshCards.emissiveScale` / 255. */
+ emissive: Uint8Array;
+}
+
+export interface MeshCards {
+ aabbMin: [number, number, number];
+ aabbMax: [number, number, number];
+ /** World size of one pixel the card was baked at. */
+ cell: number;
+ emissiveScale: number;
+ /** +x, -x, +y, -y, +z, -z. */
+ cards: MeshCard[];
+}
+
+export const NO_DEPTH = 65535;
+/** Per face: the axis it looks along, the sign of the side it looks from, and the two axes its pixels run over. */
+export const CARD_AXES: ReadonlyArray<{ axis: number; sign: 1 | -1; u: number; v: number }> = [
+ { axis: 0, sign: 1, u: 1, v: 2 }, { axis: 0, sign: -1, u: 1, v: 2 },
+ { axis: 1, sign: 1, u: 0, v: 2 }, { axis: 1, sign: -1, u: 0, v: 2 },
+ { axis: 2, sign: 1, u: 0, v: 1 }, { axis: 2, sign: -1, u: 0, v: 1 },
+];
+
+export const MESH_CARDS_MAGIC = 0x44435345; // 'ESCD'
+const HEADER = 4 * (2 + 3 + 3 + 2);
+
+export function encodeMeshCards(m: MeshCards): Uint8Array {
+ let size = HEADER;
+ for (const c of m.cards) size += 4 + c.width * c.height * (2 + 3 + 3 + 3);
+ const bytes = new Uint8Array(size), view = new DataView(bytes.buffer);
+ let o = 0;
+ const u32 = (v: number) => { view.setUint32(o, v, true); o += 4; };
+ const f32 = (v: number) => { view.setFloat32(o, v, true); o += 4; };
+ u32(MESH_CARDS_MAGIC); u32(1);
+ m.aabbMin.forEach(f32); m.aabbMax.forEach(f32);
+ f32(m.cell); f32(m.emissiveScale);
+ for (const c of m.cards) {
+ view.setUint16(o, c.width, true); view.setUint16(o + 2, c.height, true); o += 4;
+ for (let i = 0; i < c.depth.length; i++) view.setUint16(o + i * 2, c.depth[i]!, true);
+ o += c.depth.length * 2;
+ for (const plane of [c.normal, c.albedo, c.emissive]) {
+ bytes.set(new Uint8Array(plane.buffer, plane.byteOffset, plane.byteLength), o);
+ o += plane.byteLength;
+ }
+ }
+ return bytes;
+}
+
+export function decodeMeshCards(bytes: Uint8Array): MeshCards {
+ const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+ if (bytes.byteLength < HEADER || view.getUint32(0, true) !== MESH_CARDS_MAGIC) throw new Error('not a mesh card file');
+ if (view.getUint32(4, true) !== 1) throw new Error(`unsupported mesh card file version ${view.getUint32(4, true)}`);
+ const f = (at: number) => view.getFloat32(at, true);
+ const aabbMin: [number, number, number] = [f(8), f(12), f(16)], aabbMax: [number, number, number] = [f(20), f(24), f(28)];
+ const cell = f(32), emissiveScale = f(36);
+ let o = HEADER;
+ const cards: MeshCard[] = [];
+ for (let k = 0; k < 6; k++) {
+ if (o + 4 > bytes.byteLength) throw new Error('mesh card file is truncated');
+ const width = view.getUint16(o, true), height = view.getUint16(o + 2, true);
+ o += 4;
+ const n = width * height;
+ if (o + n * 11 > bytes.byteLength) throw new Error('mesh card file is truncated');
+ const depth = new Uint16Array(n);
+ for (let i = 0; i < n; i++) depth[i] = view.getUint16(o + i * 2, true);
+ o += n * 2;
+ const normal = new Int8Array(bytes.slice(o, o + n * 3).buffer); o += n * 3;
+ const albedo = bytes.slice(o, o + n * 3); o += n * 3;
+ const emissive = bytes.slice(o, o + n * 3); o += n * 3;
+ cards.push({ width, height, depth, normal, albedo, emissive });
+ }
+ return { aabbMin, aabbMax, cell, emissiveScale, cards };
+}
+
+/** The card pixel of face `face` that a local-space point falls in, or null outside the box; with the depth of that point from the card's plane. */
+export function cardPixel(m: MeshCards, face: number, p: readonly [number, number, number]): { x: number; y: number; depth: number } | null {
+ const { axis, sign, u, v } = CARD_AXES[face]!, card = m.cards[face]!;
+ const extent = m.aabbMax[axis]! - m.aabbMin[axis]!;
+ const fu = (p[u]! - m.aabbMin[u]!) / (m.aabbMax[u]! - m.aabbMin[u]! || 1), fv = (p[v]! - m.aabbMin[v]!) / (m.aabbMax[v]! - m.aabbMin[v]! || 1);
+ if (fu < 0 || fu >= 1 || fv < 0 || fv >= 1) return null;
+ const depth = sign > 0 ? m.aabbMax[axis]! - p[axis]! : p[axis]! - m.aabbMin[axis]!;
+ return { x: Math.min(Math.floor(fu * card.width), card.width - 1), y: Math.min(Math.floor(fv * card.height), card.height - 1), depth: depth / (extent || 1) };
+}
diff --git a/sdk/src/gi/surfaceCache.ts b/sdk/src/gi/surfaceCache.ts
new file mode 100644
index 000000000..cfb1a5e24
--- /dev/null
+++ b/sdk/src/gi/surfaceCache.ts
@@ -0,0 +1,182 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file surfaceCache.ts
+ * @brief The scene's surfaces with the light on them, kept per card pixel: what a ray that hits a surface brings back (docs/GI_LUMEN_DESIGN.md, 3.3).
+ *
+ * @details An instance is a mesh's cards (`.esmeshcards`) placed in the world. Lighting a card pixel is: the sun's direct light, gated by the
+ * scene's distance field (so a wall shadows what is behind it with no shadow map in the cache), plus an indirect term handed in
+ * by the caller (the previous frame's gather: that is how the cache converges on many bounces), times the albedo, plus the emission.
+ * Radiance is in the engine's units for a diffuse surface: albedo times the irradiance over pi, so a surface facing a sun of
+ * intensity I reads albedo * I.
+ *
+ * A ray's hit is looked up by `lookup`: the point where the distance field stopped it and the direction it came in, answered by
+ * the cards that face the ray, blended by how squarely they face it.
+ *
+ * This is the reference the GPU refresh follows; it runs on the CPU in tests and in tools.
+ */
+import { CARD_AXES, NO_DEPTH, cardPixel, type MeshCards } from './cardFormat';
+import type { GlobalSdf } from './globalSdf';
+
+export interface CardInstance {
+ id: number;
+ cards: MeshCards;
+ /** Column-major 4x4, local to world: rotation, translation, one uniform scale. */
+ worldFromLocal: ArrayLike<number>;
+}
+
+export interface SunLight {
+ /** Unit vector toward the sun. */
+ toLight: readonly [number, number, number];
+ /** Colour times intensity: the radiance a surface facing the sun gives per unit albedo. */
+ radiance: readonly [number, number, number];
+}
+
+export interface LightOptions {
+ sun?: SunLight;
+ /** Shadows from the scene distance field; the sun is unshadowed without it. */
+ sdf?: GlobalSdf;
+ /** How far a shadow ray looks. */
+ shadowRange?: number;
+ /** Extra light per surface point, to be multiplied by the albedo: the indirect term. Receives the world position and unit normal. */
+ indirect?: (position: [number, number, number], normal: [number, number, number]) => readonly [number, number, number];
+ /** How far off the surface a shadow ray starts, in world units; must clear the growth of the distance field. */
+ bias?: number;
+}
+
+interface Placed {
+ instance: CardInstance;
+ scale: number;
+ inverse: Float64Array;
+ /** Per card pixel, linear RGB: what the surface gives out. */
+ radiance: Float32Array[];
+ min: [number, number, number];
+ max: [number, number, number];
+}
+
+export class SurfaceCache {
+ private placed_ = new Map<number, Placed>();
+
+ add(instance: CardInstance): void {
+ const m = instance.worldFromLocal, scale = Math.hypot(m[0]!, m[1]!, m[2]!);
+ const r = [0, 1, 2].map((c) => [0, 1, 2].map((row) => m[c * 4 + row]! / scale));
+ const inverse = new Float64Array(16);
+ for (let row = 0; row < 3; row++) {
+ for (let col = 0; col < 3; col++) inverse[col * 4 + row] = r[row]![col]! / scale;
+ inverse[12 + row] = -(r[row]![0]! * m[12]! + r[row]![1]! * m[13]! + r[row]![2]! * m[14]!) / scale;
+ }
+ inverse[15] = 1;
+ const { cards } = instance;
+ const min: [number, number, number] = [Infinity, Infinity, Infinity], max: [number, number, number] = [-Infinity, -Infinity, -Infinity];
+ for (let c = 0; c < 8; c++) {
+ const l = [c & 1 ? cards.aabbMax[0] : cards.aabbMin[0], c & 2 ? cards.aabbMax[1] : cards.aabbMin[1], c & 4 ? cards.aabbMax[2] : cards.aabbMin[2]];
+ for (let k = 0; k < 3; k++) {
+ const w = m[k]! * l[0]! + m[4 + k]! * l[1]! + m[8 + k]! * l[2]! + m[12 + k]!;
+ min[k] = Math.min(min[k], w); max[k] = Math.max(max[k], w);
+ }
+ }
+ this.placed_.set(instance.id, { instance, scale, inverse, radiance: cards.cards.map((c) => new Float32Array(c.width * c.height * 3)), min, max });
+ }
+
+ remove(id: number): void { this.placed_.delete(id); }
+
+ /** The radiance of one card pixel as last lit (tests and tools). */
+ radianceAt(id: number, face: number, x: number, y: number): [number, number, number] | null {
+ const placed = this.placed_.get(id);
+ if (!placed) return null;
+ const card = placed.instance.cards.cards[face]!, i = x + y * card.width;
+ if (card.depth[i] === NO_DEPTH) return null;
+ const r = placed.radiance[face]!;
+ return [r[i * 3]!, r[i * 3 + 1]!, r[i * 3 + 2]!];
+ }
+
+ /** The world position and unit normal of a card pixel, or null where it holds no surface. */
+ private pixelSurface_(placed: Placed, face: number, x: number, y: number): { position: [number, number, number]; normal: [number, number, number] } | null {
+ const { cards } = placed.instance, card = cards.cards[face]!, i = x + y * card.width;
+ if (card.depth[i] === NO_DEPTH) return null;
+ const { axis, sign, u, v } = CARD_AXES[face]!;
+ const local: [number, number, number] = [0, 0, 0];
+ local[u] = cards.aabbMin[u]! + ((x + 0.5) / card.width) * (cards.aabbMax[u]! - cards.aabbMin[u]!);
+ local[v] = cards.aabbMin[v]! + ((y + 0.5) / card.height) * (cards.aabbMax[v]! - cards.aabbMin[v]!);
+ const depth = (card.depth[i]! / 65534) * (cards.aabbMax[axis]! - cards.aabbMin[axis]!);
+ local[axis] = sign > 0 ? cards.aabbMax[axis]! - depth : cards.aabbMin[axis]! + depth;
+ const m = placed.instance.worldFromLocal;
+ const position = [0, 1, 2].map((k) => m[k]! * local[0] + m[4 + k]! * local[1] + m[8 + k]! * local[2] + m[12 + k]!) as [number, number, number];
+ const n = [card.normal[i * 3]! / 127, card.normal[i * 3 + 1]! / 127, card.normal[i * 3 + 2]! / 127];
+ const nl = Math.hypot(...n) || 1;
+ const normal = [0, 1, 2].map((k) => (m[k]! * n[0]! + m[4 + k]! * n[1]! + m[8 + k]! * n[2]!) / (placed.scale * nl)) as [number, number, number];
+ return { position, normal };
+ }
+
+ /** Refreshes every card pixel's radiance. */
+ light(options: LightOptions): void {
+ const range = options.shadowRange ?? 500, bias = options.bias ?? 0.3;
+ for (const placed of this.placed_.values()) {
+ const { cards } = placed.instance;
+ cards.cards.forEach((card, face) => {
+ for (let y = 0; y < card.height; y++) for (let x = 0; x < card.width; x++) {
+ const i = x + y * card.width, out = placed.radiance[face]!;
+ const s = this.pixelSurface_(placed, face, x, y);
+ if (!s) { out[i * 3] = out[i * 3 + 1] = out[i * 3 + 2] = 0; continue; }
+ const light = [0, 0, 0];
+ const sun = options.sun;
+ if (sun) {
+ const ndl = s.normal[0] * sun.toLight[0] + s.normal[1] * sun.toLight[1] + s.normal[2] * sun.toLight[2];
+ if (ndl > 0) {
+ 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];
+ const blocked = options.sdf ? options.sdf.sphereTrace(origin, sun.toLight as [number, number, number], range) !== null : false;
+ if (!blocked) for (let k = 0; k < 3; k++) light[k] += sun.radiance[k]! * ndl;
+ }
+ }
+ if (options.indirect) {
+ const g = options.indirect(s.position, s.normal);
+ for (let k = 0; k < 3; k++) light[k] += g[k]!;
+ }
+ for (let k = 0; k < 3; k++) {
+ out[i * 3 + k] = (card.albedo[i * 3 + k]! / 255) * light[k]! + (card.emissive[i * 3 + k]! / 255) * cards.emissiveScale;
+ }
+ }
+ });
+ }
+ }
+
+ /**
+ * What a ray brings back from the surface it hit at `point`, travelling along unit `dir`: the radiance of the cards that face it,
+ * blended by how squarely each does, from the pixel whose surface is within `tolerance` of the point. Null when no card sees it.
+ */
+ lookup(point: readonly [number, number, number], dir: readonly [number, number, number], tolerance: number): [number, number, number] | null {
+ for (const placed of this.placed_.values()) {
+ let near = true;
+ for (let k = 0; k < 3; k++) if (point[k]! < placed.min[k]! - tolerance || point[k]! > placed.max[k]! + tolerance) { near = false; break; }
+ if (!near) continue;
+ const i = placed.inverse;
+ const local = [0, 1, 2].map((k) => i[k]! * point[0]! + i[4 + k]! * point[1]! + i[8 + k]! * point[2]! + i[12 + k]!) as [number, number, number];
+ const d = [0, 1, 2].map((k) => i[k]! * dir[0]! + i[4 + k]! * dir[1]! + i[8 + k]! * dir[2]!);
+ const dl = Math.hypot(...d) || 1;
+ const { cards } = placed.instance;
+ const sum = [0, 0, 0];
+ let total = 0;
+ for (let axis = 0; axis < 3; axis++) {
+ const weight = Math.abs(d[axis]! / dl);
+ if (weight < 0.05) continue;
+ // The face the ray looks at: the one on the side it came from.
+ const face = axis * 2 + (d[axis]! > 0 ? 1 : 0);
+ const clamped: [number, number, number] = [local[0], local[1], local[2]];
+ for (let k = 0; k < 3; k++) clamped[k] = Math.min(Math.max(clamped[k]!, cards.aabbMin[k]!), cards.aabbMax[k]! - 1e-9);
+ const px = cardPixel(cards, face, clamped);
+ if (!px) continue;
+ const card = cards.cards[face]!, idx = px.x + px.y * card.width;
+ if (card.depth[idx] === NO_DEPTH) continue;
+ const ext = cards.aabbMax[axis]! - cards.aabbMin[axis]!;
+ const cardDepth = (card.depth[idx]! / 65534) * ext;
+ const pointDepth = px.depth * ext;
+ if (Math.abs(cardDepth - pointDepth) * placed.scale > tolerance) continue;
+ const r = placed.radiance[face]!;
+ for (let k = 0; k < 3; k++) sum[k] += weight * r[idx * 3 + k]!;
+ total += weight;
+ }
+ if (total > 0) return [sum[0]! / total, sum[1]! / total, sum[2]! / total];
+ }
+ return null;
+ }
+}
diff --git a/tools/assetMetaTable.js b/tools/assetMetaTable.js
index c02d09d50..966b506df 100644
--- a/tools/assetMetaTable.js
+++ b/tools/assetMetaTable.js
@@ -88,6 +88,7 @@ export const EXT_TO_TYPE = Object.freeze({
'.esprobes': 'probeVolume',
'.esmesh': 'mesh',
'.esmeshsdf': 'meshSdf',
+ '.esmeshcards': 'meshCards',
// A model as the steps that build it. Never shipped: saving one bakes the sibling
// `.esmesh`, and that is what a scene references. Typed for the same reason
// `.esmatgraph` is, and apart from `model` because nothing imports it.