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 probes.ts
* @brief What light arrives at a point in the air, as nine coefficients.
*
* @details The bounce's gather, aimed from a point rather than from a surface:
* the whole sphere instead of a hemisphere, and no normal to weight by.
* It is the same light field the atlas holds, sampled where a thing that
* moves can be — which is the one place a lightmap cannot answer.
*/
import type { Bvh } from './bvh';
import { rayRadiance, type HitLookup } from './solve';
import type { SkyRadiance } from './reflection';
import { shBasis, convolveCosine, convolveCosineScalar } from './sh';
/** Where one grid of probes sits, and how many. */
export interface ProbeGrid {
/** The world box the probes fill, corner to corner. */
min: readonly [number, number, number];
max: readonly [number, number, number];
/** Probes along each axis. */
resolution: readonly [number, number, number];
}
/**
* Directions over the whole sphere, as a fixed low-discrepancy set (Fibonacci).
* Fixed and not random, for the reason the hemisphere's set is: a bake that
* answers differently twice cannot be told from one that answers wrongly once.
*/
function sphere(samples: number): Float32Array {
const out = new Float32Array(samples * 3);
const golden = Math.PI * (3 - Math.sqrt(5));
for (let i = 0; i < samples; i++) {
const y = 1 - (2 * i + 1) / samples;
const r = Math.sqrt(Math.max(0, 1 - y * y));
const phi = i * golden;
out[i * 3] = Math.cos(phi) * r;
out[i * 3 + 1] = y;
out[i * 3 + 2] = Math.sin(phi) * r;
}
return out;
}
/**
* Where probe `i` of `n` sits along one axis.
*
* On the CORNERS — the rule ProbeStore's trilinear read assumes, so a volume's
* own bounds are covered by its own probes. One probe sits at the middle, which
* is the value that read takes for the whole axis.
*/
export function probeAt(min: number, max: number, i: number, n: number): number {
if (n <= 1) return (min + max) * 0.5;
return min + (max - min) * (i / (n - 1));
}
/**
* Nine RGB coefficients per probe, in grid order with x varying fastest.
*
* `atlas` is the solved light field indexed by texel — what a surface gives off,
* before its own albedo. A ray that hits geometry with no place in the atlas
* returns black rather than the sky: something is there, and it is unlit.
*
* With `skyVisibility` (nine floats per probe, zeroed), the sky is NOT gathered: a
* ray that escapes adds to how much of the sky the probe sees instead, convolved
* the same way, so the frame can light the probe with whatever sky it has then
* (sky occlusion). What the sky gave the surfaces the probe sees, their bounce, is
* still in the atlas and so still in the irradiance.
*/
export function solveProbes(grid: ProbeGrid, bvh: Bvh, lookup: HitLookup,
atlas: Float32Array, atlasSize: number, samples: number,
sky: SkyRadiance, skyVisibility?: Float32Array): Float32Array {
const [nx, ny, nz] = grid.resolution;
const count = Math.max(0, nx) * Math.max(0, ny) * Math.max(0, nz);
const out = new Float32Array(count * 27);
if (count === 0) return out;
const dirs = sphere(samples);
const basis = new Float32Array(9);
const seen = new Float32Array(3);
// The Monte-Carlo weight of one direction over the sphere, folded in once.
const weight = (4 * Math.PI) / samples;
for (let z = 0; z < nz; z++) {
const pz = probeAt(grid.min[2], grid.max[2], z, nz);
for (let y = 0; y < ny; y++) {
const py = probeAt(grid.min[1], grid.max[1], y, ny);
for (let x = 0; x < nx; x++) {
const px = probeAt(grid.min[0], grid.max[0], x, nx);
const at = (x + y * nx + z * nx * ny) * 27;
const vAt = (x + y * nx + z * nx * ny) * 9;
for (let s = 0; s < samples; s++) {
const dx = dirs[s * 3]!, dy = dirs[s * 3 + 1]!, dz = dirs[s * 3 + 2]!;
shBasis(dx, dy, dz, basis);
if (!rayRadiance(bvh, lookup, atlas, atlasSize, px, py, pz, dx, dy, dz,
seen, 0, at * samples + s)) {
if (skyVisibility) {
for (let i = 0; i < 9; i++) skyVisibility[vAt + i]! += basis[i]! * weight;
continue;
}
sky(dx, dy, dz, seen, 0);
}
const r = seen[0]!, g = seen[1]!, b = seen[2]!;
for (let i = 0; i < 9; i++) {
const w = basis[i]! * weight;
out[at + i * 3]! += r * w;
out[at + i * 3 + 1]! += g * w;
out[at + i * 3 + 2]! += b * w;
}
}
convolveCosine(out, at);
if (skyVisibility) convolveCosineScalar(skyVisibility, vAt);
}
}
}
return out;
}