A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
* @file What a `.hdr` panorama becomes: nine irradiance coefficients and a
* prefiltered octahedral atlas.
*
* These are the claims a pixel gate cannot make. A rendered sphere says the
* lighting changed; only arithmetic says it changed to the RIGHT value — and the
* one identity the whole design rests on (a constant environment reconstructs as
* that constant, which is what keeps existing scenes pixel-identical) is checked
* here rather than inferred from a screenshot.
*/
import { describe, it, expect } from 'vitest';
import {
decodeRadianceHdr, projectIrradianceSH, evalIrradianceSH, samplePanorama,
octEncode, octDecode, encodeRgbm, decodeRgbm, atlasLayout, prefilterOctahedral,
importEnvironment, mipCountFor, ENV_MAX_RANGE, encodeSkyPanorama, separateSun,
type Panorama,
} from '../src/assets/environmentImport';
/** A Radiance file in the flat (uncompressed) encoding, one RGBE per pixel. */
function flatHdr(width: number, height: number,
pixel: (x: number, y: number) => [number, number, number]): Uint8Array {
const header = Buffer.from(`#?RADIANCE\nFORMAT=32-bit_rle_rgbe\n\n-Y ${height} +X ${width}\n`);
const body = Buffer.alloc(width * height * 4);
for (let y = 0; y < height; y++) {
for (let x = 0; x < width; x++) {
const [r, g, b] = pixel(x, y);
const peak = Math.max(r, g, b);
let e = 0;
let scale = 0;
if (peak > 1e-9) {
e = Math.ceil(Math.log2(peak)) + 128;
scale = 256 / Math.pow(2, e - 128);
}
const at = (y * width + x) * 4;
body[at] = Math.min(255, Math.floor(r * scale));
body[at + 1] = Math.min(255, Math.floor(g * scale));
body[at + 2] = Math.min(255, Math.floor(b * scale));
body[at + 3] = e;
}
}
return new Uint8Array(Buffer.concat([header, body]));
}
/** The same panorama without the file round trip, for the convolution tests. */
function panorama(width: number, height: number,
pixel: (x: number, y: number) => [number, number, number]): Panorama {
const rgb = new Float32Array(width * height * 3);
for (let y = 0; y < height; y++) {
for (let x = 0; x < width; x++) {
const [r, g, b] = pixel(x, y);
const at = (y * width + x) * 3;
rgb[at] = r; rgb[at + 1] = g; rgb[at + 2] = b;
}
}
return { width, height, rgb };
}
describe('Radiance decode', () => {
it('reads a flat scanline back as the values it was given', () => {
const env = decodeRadianceHdr(flatHdr(4, 2, (x, y) => [x + 1, y + 1, 0.5]));
expect(env.width).toBe(4);
expect(env.height).toBe(2);
// RGBE is a shared 8-bit mantissa, so the round trip is close, not exact.
expect(env.rgb[0]).toBeCloseTo(1, 1);
expect(env.rgb[1]).toBeCloseTo(1, 1);
expect(env.rgb[(1 * 4 + 3) * 3]).toBeCloseTo(4, 1);
});
it('reads the adaptive-RLE encoding as the same picture', () => {
// 8 wide is the narrowest width the RLE header is legal at.
const width = 8;
const values = Array.from({ length: width }, (_, x) => 32 + x * 4);
const header = Buffer.from(`#?RADIANCE\nFORMAT=32-bit_rle_rgbe\n\n-Y 1 +X ${width}\n`);
const rle: number[] = [2, 2, 0, width];
for (let channel = 0; channel < 4; channel++) {
rle.push(width);
for (let x = 0; x < width; x++) rle.push(channel === 3 ? 128 : values[x]!);
}
const env = decodeRadianceHdr(new Uint8Array(Buffer.concat([header, Buffer.from(rle)])));
expect(env.width).toBe(width);
// e = 128 means a scale of 2^-8, so each stored byte reads back as byte/256.
expect(env.rgb[0]).toBeCloseTo(32 / 256, 5);
expect(env.rgb[(width - 1) * 3]).toBeCloseTo((32 + 7 * 4) / 256, 5);
});
it('refuses a file that is not Radiance', () => {
expect(() => decodeRadianceHdr(new Uint8Array([1, 2, 3, 4]))).toThrow(/Radiance/);
});
});
describe('irradiance coefficients', () => {
// THE identity the design rests on: a constant environment must come back as
// that same constant in every direction. If this drifts, every existing lit
// scene changes brightness the day an environment is attached.
it('reconstructs a constant environment as that constant', () => {
const sh = projectIrradianceSH(panorama(64, 32, () => [0.25, 0.5, 0.75]));
for (const [x, y, z] of [[0, 1, 0], [0, -1, 0], [1, 0, 0], [0, 0, 1],
[0.577, 0.577, 0.577]] as const) {
const [r, g, b] = evalIrradianceSH(sh, x, y, z);
expect(r).toBeCloseTo(0.25, 2);
expect(g).toBeCloseTo(0.5, 2);
expect(b).toBeCloseTo(0.75, 2);
}
});
it('puts a lit upper hemisphere above a dark lower one', () => {
const sh = projectIrradianceSH(panorama(64, 32, (_x, y) => (y < 16 ? [1, 1, 1] : [0, 0, 0])));
const up = evalIrradianceSH(sh, 0, 1, 0)[0];
const down = evalIrradianceSH(sh, 0, -1, 0)[0];
const side = evalIrradianceSH(sh, 1, 0, 0)[0];
// Analytic: a white upper hemisphere gives E(up)/π = 1, E(side)/π = 0.5,
// E(down)/π = 0. Order-2 SH rings, so the ends land near rather than on them.
expect(up).toBeGreaterThan(0.9);
expect(side).toBeCloseTo(0.5, 1);
expect(down).toBeLessThan(0.1);
expect(up).toBeGreaterThan(side);
expect(side).toBeGreaterThan(down);
});
it('answers with the colour that lies in that direction, not the average', () => {
// Red on the +Z half of the sphere (the image's centre column), green behind.
const sh = projectIrradianceSH(panorama(64, 32,
(x) => (x > 16 && x < 48 ? [1, 0, 0] : [0, 1, 0])));
const front = evalIrradianceSH(sh, 0, 0, 1);
const back = evalIrradianceSH(sh, 0, 0, -1);
expect(front[0]).toBeGreaterThan(front[1]);
expect(back[1]).toBeGreaterThan(back[0]);
});
});
describe('octahedral mapping', () => {
it('round-trips every direction it is given', () => {
const third = 1 / Math.sqrt(3);
for (const d of [[0, 1, 0], [0, -1, 0], [1, 0, 0], [-1, 0, 0], [0, 0, 1], [0, 0, -1],
[third, third, third], [-third, -third, third]]) {
const [u, v] = octEncode(d[0], d[1], d[2]);
expect(u).toBeGreaterThanOrEqual(0);
expect(u).toBeLessThanOrEqual(1);
const back = octDecode(u, v);
for (let i = 0; i < 3; i++) expect(back[i]).toBeCloseTo(d[i]!, 5);
}
});
it('stays continuous just outside the square, which is what the border is for', () => {
// The texel one step past the edge must be the direction its neighbour across
// the fold sees — otherwise a bilinear tap at the seam blends in nothing.
const inside = octDecode(0.02, 0.5);
const outside = octDecode(-0.02, 0.5);
const dot = inside[0] * outside[0] + inside[1] * outside[1] + inside[2] * outside[2];
expect(dot).toBeGreaterThan(0.99);
});
});
describe('RGBM', () => {
it('round-trips values across the range within a percent of full scale', () => {
for (const v of [0, 0.01, 0.1, 0.5, 1, 3, 7.9]) {
const out = new Uint8Array(4);
encodeRgbm(v, v * 0.5, 0, ENV_MAX_RANGE, out, 0);
const [r, g, b] = decodeRgbm(out[0]!, out[1]!, out[2]!, out[3]!, ENV_MAX_RANGE);
expect(Math.abs(r - v)).toBeLessThan(0.08);
expect(Math.abs(g - v * 0.5)).toBeLessThan(0.08);
expect(b).toBeCloseTo(0, 3);
}
});
it('clamps rather than wrapping above the range', () => {
const out = new Uint8Array(4);
encodeRgbm(100, 100, 100, ENV_MAX_RANGE, out, 0);
const [r] = decodeRgbm(out[0]!, out[1]!, out[2]!, out[3]!, ENV_MAX_RANGE);
expect(r).toBeCloseTo(ENV_MAX_RANGE, 1);
});
});
describe('prefiltered atlas', () => {
it('stops before a face gets too small to be an environment', () => {
// A 4-texel octahedral face is not a blurrier sky, it is a different one.
expect(mipCountFor(128)).toBe(5);
expect(mipCountFor(32)).toBe(3);
expect(mipCountFor(8)).toBe(1);
expect(mipCountFor(128, 2)).toBe(2);
});
it('stacks the mips with a border between them', () => {
const { width, height, offsets } = atlasLayout(128, 6);
expect(width).toBe(130);
expect(height).toBe(130 + 66 + 34 + 18 + 10 + 6);
expect(offsets[0]).toBe(0);
expect(offsets[1]).toBe(130);
// The closed form the shader uses instead of a loop.
for (let mip = 0; mip < 6; mip++) {
expect(offsets[mip]).toBe(2 * 128 * (1 - Math.pow(2, -mip)) + 2 * mip);
}
});
it('reproduces the source in mip 0 and averages it away by the last', () => {
// Sky above, ground below: a mirror sees the half it faces; a fully rough
// surface sees the whole sphere at once.
const env = panorama(64, 32, (_x, y) => (y < 16 ? [0, 0, 4] : [1, 0, 0]));
const { width, rgba } = prefilterOctahedral(env, 16, 4, ENV_MAX_RANGE);
const { offsets } = atlasLayout(16, 4);
const read = (mip: number, dx: number, dy: number, dz: number): [number, number, number] => {
const size = 16 >> mip;
const [u, v] = octEncode(dx, dy, dz);
const px = Math.min(size - 1, Math.floor(u * size)) + 1;
const py = offsets[mip]! + Math.min(size - 1, Math.floor(v * size)) + 1;
const at = (py * width + px) * 4;
return decodeRgbm(rgba[at]!, rgba[at + 1]!, rgba[at + 2]!, rgba[at + 3]!, ENV_MAX_RANGE);
};
const mirrorUp = read(0, 0, 1, 0);
expect(mirrorUp[2]).toBeGreaterThan(3);
expect(mirrorUp[0]).toBeLessThan(0.2);
const mirrorDown = read(0, 0, -1, 0);
expect(mirrorDown[0]).toBeGreaterThan(0.8);
expect(mirrorDown[2]).toBeLessThan(0.2);
// The roughest mip has seen both halves from either side, so the two agree.
const roughUp = read(3, 0, 1, 0);
const roughDown = read(3, 0, -1, 0);
expect(roughUp[2]).toBeGreaterThan(0.5);
expect(roughDown[2]).toBeGreaterThan(0.5);
expect(Math.abs(roughUp[2] - roughDown[2])).toBeLessThan(1.5);
});
it('fills the border with the neighbour across the fold', () => {
const env = panorama(64, 32, (_x, y) => (y < 16 ? [0, 0, 4] : [1, 0, 0]));
const { width, rgba } = prefilterOctahedral(env, 8, 1, ENV_MAX_RANGE);
const texel = (x: number, y: number): [number, number, number] => {
const at = (y * width + x) * 4;
return decodeRgbm(rgba[at]!, rgba[at + 1]!, rgba[at + 2]!, rgba[at + 3]!, ENV_MAX_RANGE);
};
// Column 0 is the border; column 1 is the face's first real texel. Both look
// outward along -X near the horizon, so neither is the untouched black an
// unfilled border would be.
for (let y = 1; y <= 8; y++) {
const border = texel(0, y);
expect(border[0] + border[1] + border[2]).toBeGreaterThan(0.1);
}
});
});
describe('importEnvironment', () => {
it('produces a document and an atlas that describe each other', () => {
const hdr = flatHdr(32, 16, (_x, y) => (y < 8 ? [2, 2, 2] : [0, 0, 0]));
const result = importEnvironment(hdr, 'studio', { faceSize: 32, mipCount: 3 });
expect(result.atlasName).toBe('studio_env.png');
expect(result.document.irradiance).toHaveLength(27);
expect(result.document.faceSize).toBe(32);
expect(result.document.mipCount).toBe(3);
expect(result.document.maxRange).toBe(ENV_MAX_RANGE);
// A PNG, and one whose size the layout predicts.
expect(Array.from(result.atlasBytes.subarray(1, 4))).toEqual([0x50, 0x4e, 0x47]);
const up = evalIrradianceSH(result.document.irradiance, 0, 1, 0)[0];
const down = evalIrradianceSH(result.document.irradiance, 0, -1, 0)[0];
expect(up).toBeGreaterThan(down + 1);
});
});
describe('the sky texture', () => {
it('is the panorama itself, row 0 up, beside the atlas', () => {
const hdr = flatHdr(32, 16, (_x, y) => (y < 8 ? [2, 2, 2] : [0, 0, 0]));
const result = importEnvironment(hdr, 'studio', { faceSize: 32, mipCount: 3 });
expect(result.sky?.name).toBe('studio_sky.png');
const sky = encodeSkyPanorama(decodeRadianceHdr(hdr));
expect([sky.width, sky.height]).toEqual([32, 16]);
const at = (x: number, y: number) => decodeRgbm(...(Array.from(sky.rgba.subarray((y * 32 + x) * 4, (y * 32 + x) * 4 + 4)) as [number, number, number, number]), ENV_MAX_RANGE)[0];
expect(at(5, 2)).toBeCloseTo(2, 1);
expect(at(5, 13)).toBeCloseTo(0, 2);
});
it('comes down by a whole factor, averaging, where the panorama is wider than asked', () => {
const env = panorama(8, 4, (x) => [x % 2 === 0 ? 4 : 0, 0, 0]);
const sky = encodeSkyPanorama(env, 4);
expect([sky.width, sky.height]).toEqual([4, 2]);
expect(decodeRgbm(sky.rgba[0]!, sky.rgba[1]!, sky.rgba[2]!, sky.rgba[3]!, ENV_MAX_RANGE)[0]).toBeCloseTo(2, 1);
});
it('is not written when the import asks for none', () => {
const hdr = flatHdr(32, 16, () => [1, 1, 1]);
expect(importEnvironment(hdr, 'studio', { faceSize: 32, mipCount: 3, skyWidth: 0 }).sky).toBeNull();
});
});
describe('panorama sampling', () => {
it('reads the image centre as +Z and row 0 as +Y', () => {
const env = panorama(8, 4, (x, y) => [x, y, 0]);
const out = new Float32Array(3);
samplePanorama(env, 0, 1, 0, out);
expect(out[1]).toBeLessThan(0.5);
samplePanorama(env, 0, -1, 0, out);
expect(out[1]).toBeGreaterThan(2.5);
samplePanorama(env, 0, 0, 1, out);
expect(out[0]).toBeCloseTo(3.5, 1);
});
});
describe('the sun an import separates from its sky', () => {
const W = 128, H = 64;
// One texel of sun above a dim sky, sized to give irradiance/pi of 1 facing it.
const sunAt = [43, 12] as const;
const sa = Math.sin((sunAt[1] + 0.5) * Math.PI / H) * (Math.PI / H) * (2 * Math.PI / W);
const sky = (x: number, y: number): [number, number, number] =>
x === sunAt[0] && y === sunAt[1] ? [Math.PI / sa, 0.5 * Math.PI / sa, 0.25 * Math.PI / sa]
: y < H / 2 ? [0.15, 0.15, 0.15] : [0.02, 0.02, 0.02];
it('finds it where it is, as bright as it is, and leaves the sky without it', () => {
const doc = importEnvironment(flatHdr(W, H, sky), 'sunny', { faceSize: 8, skyWidth: 0 }).document;
const sun = doc.sun!;
const phi = ((sunAt[0] + 0.5) / W - 0.5) * 2 * Math.PI, theta = (sunAt[1] + 0.5) / H * Math.PI;
const toward = [-Math.sin(theta) * Math.sin(phi), Math.cos(theta), Math.sin(theta) * Math.cos(phi)];
toward.forEach((c, i) => expect(sun.direction[i]).toBeCloseTo(c, 4));
// RGBE keeps eight bits of mantissa, so the texel comes back within a percent.
[1, 0.5, 0.25].forEach((c, i) => expect(sun.color[i]! / c).toBeCloseTo(1, 1));
// Up-facing, the sky alone is its radiance: what is left once the sun is out.
expect(sun.skyIrradiance[0]).toBeLessThan(doc.irradiance[0]! * 0.5);
const noSun = importEnvironment(flatHdr(W, H, (_x, y) => (y < H / 2 ? [0.15, 0.15, 0.15] : [0.02, 0.02, 0.02])),
'overcast', { faceSize: 8, skyWidth: 0 }).document;
for (let i = 0; i < 27; i++) expect(sun.skyIrradiance[i]).toBeCloseTo(noSun.irradiance[i]!, 2);
});
it('is not found in a sky with no compact source', () => {
const overcast = importEnvironment(flatHdr(W, H, (_x, y) => (y < H / 2 ? [1, 1, 1] : [0.1, 0.1, 0.1])),
'overcast', { faceSize: 8, skyWidth: 0 });
expect(overcast.document.sun).toBeUndefined();
// A bright WINDOW is a patch of sky: too wide for one direction to stand in for it.
const window = { rgb: new Float32Array(W * H * 3), width: W, height: H };
for (let y = 0; y < H; y++) for (let x = 0; x < W; x++) {
const v = x > 40 && x < 80 && y > 10 && y < 30 ? 50 : 0.1;
window.rgb.set([v, v, v], (y * W + x) * 3);
}
expect(separateSun(window)).toBeNull();
});
});