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 ProbeStore.hpp
* @brief Which baked grid a point stands in, and what it says there.
*
* @details The frame's LightProbeVolume components, as bounds plus the grid each
* one reads. Filled during collection and read during collection — a
* volume is borrowed, not copied, so nothing here outlives the frame
* that gathered it.
*
* Two ways a draw reads one. Per object: the nine coefficients where the
* draw stands, read here on the CPU — one value for the whole mesh. Per
* pixel: the grid itself, packed into the frame's probe atlas, and the
* draw's run says where in it — so one merged mesh spanning a shed and
* the yard outside is dark under the roof and lit in the open.
*/
#pragma once
#include "../../core/Half.hpp"
#include "../../core/Revision.hpp"
#include "../../core/Types.hpp"
#include "../../resource/ProbeVolume.hpp"
#include "./ProbeConstants.hpp"
#include <algorithm>
#include <cmath>
#include <glm/glm.hpp>
#include <vector>
namespace esengine {
/** @brief The frame's probe volumes, and the trilinear read through them. */
class ProbeStore {
public:
/** @brief One volume: a world box, and the grid solved inside it. */
struct Volume {
glm::vec3 min{0.0f};
glm::vec3 max{0.0f};
const ProbeVolume* grid = nullptr;
/// Where its grid sits in the atlas: the texel its coefficient 0, probe (0,0,0) is at. -1 = not placed.
i32 atlasX = -1;
i32 atlasY = -1;
};
void clear() { volumes_.clear(); }
/** @brief Takes a volume, or ignores one no point can be inside. A grid whose
* coefficients do not match its resolution is not half-usable. */
void add(const glm::vec3& min, const glm::vec3& max, const ProbeVolume* grid) {
if (!grid || !grid->isValid()) return;
if (max.x <= min.x || max.y <= min.y || max.z <= min.z) return;
volumes_.push_back({min, max, grid});
}
bool empty() const { return volumes_.empty(); }
u32 count() const { return static_cast<u32>(volumes_.size()); }
/**
* @brief What the frame's probe volumes say, as a number that changes whenever it does (see core/Revision.hpp): asked after the
* collect, it moves only when this frame's set differs from the one it last answered for.
*/
u64 revision() const {
u64 h = 0xcbf29ce484222325ull;
const auto mix = [&h](const void* data, usize bytes) {
const auto* p = static_cast<const u8*>(data);
for (usize i = 0; i < bytes; ++i) { h ^= p[i]; h *= 0x100000001b3ull; }
};
for (const Volume& v : volumes_) {
mix(&v.min, sizeof(v.min));
mix(&v.max, sizeof(v.max));
mix(&v.grid, sizeof(v.grid));
mix(&v.grid->revision, sizeof(v.grid->revision));
}
if (revision_ == 0 || h != revision_hash_) {
revision_hash_ = h;
revision_ = nextRevision();
}
return revision_;
}
/**
* @brief The irradiance at @p p, read trilinearly. False = no volume holds it.
* @details Probes sit on the box's CORNERS, so a volume's own bounds are
* covered by its own probes and a read never extrapolates. Where two
* volumes overlap the SMALLER wins: a room inside a hall was baked to
* say something the hall's spacing could not.
*/
bool sample(const glm::vec3& p, ProbeConstants& out, bool perPixel = false) const {
const Volume* best = nullptr;
f32 bestSize = 0.0f;
for (const Volume& v : volumes_) {
if (p.x < v.min.x || p.x > v.max.x || p.y < v.min.y || p.y > v.max.y
|| p.z < v.min.z || p.z > v.max.z) continue;
const glm::vec3 e = v.max - v.min;
const f32 size = e.x * e.y * e.z;
if (!best || size < bestSize) { best = &v; bestSize = size; }
}
if (!best) return false;
const ProbeVolume& g = *best->grid;
if (perPixel && best->atlasX >= 0 && atlas_texture_ != 0) {
writeGridRun(*best, out);
return true;
}
i32 low[3] = {0, 0, 0};
i32 high[3] = {0, 0, 0};
f32 frac[3] = {0.0f, 0.0f, 0.0f};
for (u32 a = 0; a < 3; ++a) {
const i32 n = g.resolution[static_cast<int>(a)];
if (n <= 1) continue;
const f32 span = best->max[static_cast<int>(a)] - best->min[static_cast<int>(a)];
f32 u = (p[static_cast<int>(a)] - best->min[static_cast<int>(a)]) / span
* static_cast<f32>(n - 1);
u = std::fmin(std::fmax(u, 0.0f), static_cast<f32>(n - 1));
i32 i0 = static_cast<i32>(std::floor(u));
if (i0 > n - 2) i0 = n - 2;
low[a] = i0;
high[a] = i0 + 1;
frac[a] = u - static_cast<f32>(i0);
}
const i32 strideY = g.resolution.x;
const i32 strideZ = g.resolution.x * g.resolution.y;
const bool sky = g.hasSkyVisibility();
out = ProbeConstants{};
for (u32 corner = 0; corner < 8; ++corner) {
const f32 w = ((corner & 1u) ? frac[0] : 1.0f - frac[0])
* ((corner & 2u) ? frac[1] : 1.0f - frac[1])
* ((corner & 4u) ? frac[2] : 1.0f - frac[2]);
if (w <= 0.0f) continue;
const i32 x = (corner & 1u) ? high[0] : low[0];
const i32 y = (corner & 2u) ? high[1] : low[1];
const i32 z = (corner & 4u) ? high[2] : low[2];
const usize base = static_cast<usize>(x + y * strideY + z * strideZ) * 9;
for (u32 c = 0; c < 9; ++c) {
const glm::vec3& sh = g.irradiance[base + c];
out.irradiance[c].x += sh.x * w;
out.irradiance[c].y += sh.y * w;
out.irradiance[c].z += sh.z * w;
}
// The sky's visibility rides the spare channels: [1..8].w and reflection.y for the first.
if (sky) {
out.reflection.y += g.skyVisibility[base] * w;
for (u32 c = 1; c < 9; ++c) out.irradiance[c].w += g.skyVisibility[base + c] * w;
}
}
out.irradiance[0].w = 1.0f;
if (sky) out.reflection.z = 1.0f;
return true;
}
/**
* @brief The volume a whole object stands in, by its world box rather than its origin.
* @details An imported level's meshes keep their origin where the file put it — often the world's origin, far from
* the walls they draw — so asking at the origin leaves a shed's walls in no volume at all. The box's centre
* is asked first; a box whose centre is in none reads the smallest volume it overlaps, at the point of that
* volume nearest its centre. Per pixel, every pixel then reads the grid where it stands anyway.
*/
bool sampleBox(const glm::vec3& centre, const glm::vec3& half, ProbeConstants& out, bool perPixel = false) const {
if (sample(centre, out, perPixel)) return true;
const Volume* best = nullptr;
f32 bestSize = 0.0f;
for (const Volume& v : volumes_) {
const glm::vec3 vc = (v.min + v.max) * 0.5f;
const glm::vec3 vh = (v.max - v.min) * 0.5f;
const glm::vec3 gap = glm::abs(centre - vc) - (half + vh);
if (gap.x > 0.0f || gap.y > 0.0f || gap.z > 0.0f) continue;
const f32 size = vh.x * vh.y * vh.z;
if (!best || size < bestSize) { best = &v; bestSize = size; }
}
if (!best) return false;
return sample(glm::clamp(centre, best->min, best->max), out, perPixel);
}
/**
* @brief Places every volume's grid in the atlas. True when the atlas's texels changed and want uploading.
*
* @details A grid is a block nine coefficient tiles wide (each resX x resY, one per coefficient) and resZ
* slices tall, the blocks stacked down the atlas. Within a tile the hardware filters x and y and never
* across a tile's edge (a read sits between the first and last probe's texel centres), and the shader
* blends the two slices around its z. A grid that would not fit @p maxSize keeps the per-object read.
* Two volumes reading the same grid share its block.
*/
bool layoutAtlas(u32 maxSize) {
std::vector<u64> key;
key.reserve(volumes_.size());
u32 width = 0;
u32 height = 0;
for (usize i = 0; i < volumes_.size(); ++i) {
Volume& v = volumes_[i];
v.atlasX = -1;
v.atlasY = -1;
for (usize j = 0; j < i; ++j) {
if (volumes_[j].grid == v.grid) { v.atlasX = volumes_[j].atlasX; v.atlasY = volumes_[j].atlasY; break; }
}
if (v.atlasX >= 0) continue;
const glm::ivec3 r = v.grid->resolution;
const u32 w = 9u * static_cast<u32>(r.x);
const u32 h = static_cast<u32>(r.y) * static_cast<u32>(r.z);
if (w > maxSize || height + h > maxSize) continue;
v.atlasX = 0;
v.atlasY = static_cast<i32>(height);
height += h;
width = std::max(width, w);
key.push_back(v.grid->revision);
key.push_back(static_cast<u64>(v.atlasY));
}
const bool changed = key != atlas_key_ || width != atlas_width_ || height != atlas_height_;
atlas_key_ = std::move(key);
atlas_width_ = width;
atlas_height_ = height;
return changed;
}
u32 atlasWidth() const { return atlas_width_; }
u32 atlasHeight() const { return atlas_height_; }
/** @brief The atlas's texels, RGBA half floats: a coefficient's rgb, and the sky's visibility in a (0 for a grid
* baked without it). Laid out as layoutAtlas placed them. */
void fillAtlas(std::vector<u16>& out) const {
out.assign(static_cast<usize>(atlas_width_) * atlas_height_ * 4, 0);
for (usize i = 0; i < volumes_.size(); ++i) {
const Volume& v = volumes_[i];
if (v.atlasX < 0) continue;
bool repeat = false;
for (usize j = 0; j < i; ++j) repeat = repeat || volumes_[j].grid == v.grid;
if (repeat) continue;
const ProbeVolume& g = *v.grid;
const i32 rx = g.resolution.x;
const i32 ry = g.resolution.y;
const i32 rz = g.resolution.z;
const bool sky = g.hasSkyVisibility();
for (i32 z = 0; z < rz; ++z) {
for (i32 y = 0; y < ry; ++y) {
for (i32 x = 0; x < rx; ++x) {
const usize probe = static_cast<usize>(x + y * rx + z * rx * ry) * 9;
const usize row = static_cast<usize>(v.atlasY + z * ry + y);
for (i32 c = 0; c < 9; ++c) {
const usize col = static_cast<usize>(v.atlasX + c * rx + x);
u16* t = &out[(row * atlas_width_ + col) * 4];
const glm::vec3& sh = g.irradiance[probe + static_cast<usize>(c)];
t[0] = packHalf(sh.x);
t[1] = packHalf(sh.y);
t[2] = packHalf(sh.z);
t[3] = packHalf(sky ? g.skyVisibility[probe + static_cast<usize>(c)] : 0.0f);
}
}
}
}
}
}
/** @brief The atlas texture this frame's per-pixel runs point into; 0 = none, and every draw reads per object. */
void setAtlasTexture(u32 id) { atlas_texture_ = id; }
u32 atlasTexture() const { return atlas_texture_; }
private:
/**
* @brief A run that says where the grid is rather than what it holds; the shaders' probeGridIrradiance reads it.
* @details [0].w = 2 marks it. [1] = the box's min and resX, [2] = probes per world unit along each axis (resolution
* less one over the box's size; 0 on a flat axis) and resY, [3] = the block's first texel and the atlas's
* inverse size, [4].x = resZ. The reflection column and the sky flag stay where a per-object run has them.
*/
void writeGridRun(const Volume& v, ProbeConstants& out) const {
const ProbeVolume& g = *v.grid;
const glm::vec3 e = v.max - v.min;
const glm::vec3 r = glm::vec3(g.resolution);
out = ProbeConstants{};
out.irradiance[0].w = 2.0f;
out.irradiance[1] = glm::vec4(v.min, r.x);
out.irradiance[2] = glm::vec4(r.x > 1.0f ? (r.x - 1.0f) / e.x : 0.0f,
r.y > 1.0f ? (r.y - 1.0f) / e.y : 0.0f,
r.z > 1.0f ? (r.z - 1.0f) / e.z : 0.0f, r.y);
out.irradiance[3] = glm::vec4(static_cast<f32>(v.atlasX), static_cast<f32>(v.atlasY),
1.0f / static_cast<f32>(atlas_width_), 1.0f / static_cast<f32>(atlas_height_));
out.irradiance[4] = glm::vec4(r.z, 0.0f, 0.0f, 0.0f);
if (g.hasSkyVisibility()) out.reflection.z = 1.0f;
}
std::vector<Volume> volumes_;
mutable u64 revision_ = 0;
mutable u64 revision_hash_ = 0;
std::vector<u64> atlas_key_;
u32 atlas_width_ = 0;
u32 atlas_height_ = 0;
u32 atlas_texture_ = 0;
};
} // namespace esengine