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.

5.1 KB
Raw Blame
// 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;
}