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 LightStore.hpp
* @brief Engine-side 2D light registry — the per-frame LightConstants UBO and its CPU mirror.
* @details The render collect path clears this each frame, then accumulates the scene's enabled
* Light components into it (point/directional into the lights array, ambient summed
* into the ambient term). flush() uploads the mirror once and binds it at
* LIGHT_CONSTANTS_BINDING, so every Lit shader reads the same lighting UBO. Owned by
* RenderContext so both the render path and any future SDK push reach one store / one UBO.
*
* @author ESEngine Team
* @date 2026
*
* @copyright Copyright (c) 2026 ESEngine Team
* Licensed under the Apache License, Version 2.0.
*/
#pragma once
#include "../rhi/GfxEnums.hpp"
#include "./LightConstants.hpp"
#include <algorithm>
#include <bit>
#include <cmath>
#include <glm/glm.hpp>
namespace esengine {
class GfxDevice;
/**
* @brief Holds the per-frame 2D lights and their GPU UBO. Mirrors MaterialStore's UBO lifecycle
* (lazy create, dirty upload, device-owned free).
*/
class LightStore {
public:
/// The render path uses this device to create/upload/delete the lighting UBO.
void setDevice(GfxDevice* device) { device_ = device; }
/// Begins a frame's collection: zeroes ambient + all light slots (inactive slots contribute
/// nothing because their intensity is 0) and marks the UBO for re-upload.
void clear() {
data_ = LightConstants{};
count_ = 0;
tiledCount_ = 0;
loopMarked_ = false;
loopTileBits_ = 0;
hasEnvironment_ = false;
dirty_ = true;
}
/// Adds an ambient term (rgb already scaled by intensity). Ambient lights sum rather than
/// occupy a slot. The alpha tracks the active non-ambient light count for shader early-out.
void addAmbient(const glm::vec3& color) {
data_.ambient.x += color.x;
data_.ambient.y += color.y;
data_.ambient.z += color.z;
dirty_ = true;
}
/// How far a hemisphere Ambient light moves the ambient term between a surface facing up and one
/// facing down (ground minus sky, already scaled by intensity). Sums the way the term itself does.
void addAmbientGround(const glm::vec3& delta) {
data_.ambientGround.x += delta.x;
data_.ambientGround.y += delta.y;
data_.ambientGround.z += delta.z;
dirty_ = true;
}
/// Appends a point/directional light. Silently drops past MAX_LIGHTS (the fixed shader loop
/// bound); callers keep the most significant lights first if they exceed the cap.
void addLight(const GpuLight& light) {
if (count_ >= MAX_LIGHTS) return;
data_.lights[count_++] = light;
data_.ambient.w = static_cast<f32>(count_);
dirty_ = true;
}
/// Appends a positional light past the loop's sixteen and marks the tiles its sphere reaches through @p viewProjection.
/// Returns false past MAX_TILED_LIGHTS.
bool addTiledLight(const GpuLight& light, const glm::mat4& viewProjection) {
if (tiledCount_ >= MAX_TILED_LIGHTS) return false;
data_.tiledLights[tiledCount_] = light;
markTiledLight(tiledCount_, viewProjection);
++tiledCount_;
data_.tileInfo = glm::vec4(static_cast<f32>(tiledCount_), static_cast<f32>(TILE_COLUMNS), static_cast<f32>(TILE_ROWS), data_.tileInfo.w);
dirty_ = true;
return true;
}
/// Reprojects the collected lights for another view without changing their identity, illumination or shadow assignments.
/// Call again with the source view after drawing a reflection; its post-processing also reads this block.
void setTiledView(const glm::mat4& viewProjection) {
if (tiledCount_ == 0 && !loopMarked_) return;
std::fill_n(data_.tileMask, TILE_COLUMNS * TILE_ROWS, glm::uvec4(0u));
for (u32 i = 0; i < tiledCount_; ++i) markTiledLight(i, viewProjection);
if (loopMarked_) markLoopLights(viewProjection);
dirty_ = true;
}
/**
* @brief Says, per screen tile, which of the LOOP's sixteen lights can reach a flat lit surface there: the masks' spare fourth word.
* @details A lit sprite or tile works out every light in the loop for every pixel, and that arithmetic is what 2D lighting costs
* (docs/GPU_PERFORMANCE_OPTIONS.md, section 9). With this a pixel skips the lights that cannot reach its tile, and a
* tilemap's strips, which stay on the GPU, need nothing written into them when a light moves. `tileInfo.w` says the word
* is there. Call once the loop's lights are all added.
*
* A flat surface measures a light in the plane's XY alone, whatever its depth, so a tile is only a sound answer where
* the view keeps depth out of the picture's x and y: an orthographic camera looking down the plane's normal. Through
* any other the word is all ones and nothing is skipped. A directional light reaches every tile.
*/
void markLoopLights(const glm::mat4& viewProjection) {
auto* masks = reinterpret_cast<u32(*)[4]>(data_.tileMask);
for (u32 t = 0; t < TILE_COLUMNS * TILE_ROWS; ++t) masks[t][3] = 0u;
const bool flatView = viewProjection[2][0] == 0.0f && viewProjection[2][1] == 0.0f
&& viewProjection[0][3] == 0.0f && viewProjection[1][3] == 0.0f && viewProjection[2][3] == 0.0f;
for (u32 i = 0; i < count_; ++i) {
const GpuLight& light = data_.lights[i];
const bool directional = light.posDir.z >= 0.5f && light.posDir.z < 1.5f;
if (!flatView || directional) {
for (u32 t = 0; t < TILE_COLUMNS * TILE_ROWS; ++t) masks[t][3] |= 1u << i;
continue;
}
if (light.color.a == 0.0f) continue;
// A hair wide, as lightReachMask2D is: the fragment's tile comes from an interpolated position.
const f32 reach = std::max(light.posDir.w, 0.0001f) * 1.001f + 0.001f;
markLightTiles(viewProjection, glm::vec3(light.posDir.x, light.posDir.y, 0.0f), reach, 96u + i, masks);
}
data_.tileInfo.y = static_cast<f32>(TILE_COLUMNS);
data_.tileInfo.z = static_cast<f32>(TILE_ROWS);
data_.tileInfo.w = 1.0f;
loopTileBits_ = 0;
for (u32 t = 0; t < TILE_COLUMNS * TILE_ROWS; ++t) loopTileBits_ += static_cast<u32>(std::popcount(masks[t][3]));
loopMarked_ = true;
dirty_ = true;
}
u32 tiledCount() const { return tiledCount_; }
/// How many (screen tile, loop light) pairs the last markLoopLights left set: 192 tiles times the lights when nothing could be
/// told apart, far fewer under local lights. No pixel shows a light that is skipped, so this is what a gate reads.
u32 loopTileBits() const { return loopTileBits_; }
/// Hands over the shadow tiles a frame rendered: per tile a world -> clip matrix
/// and the atlas rect it was drawn into (bias in w), plus the params whose x is
/// the master switch. Zeroed when nothing cast, so no matrix outlives its map.
void setShadowTiles(const glm::mat4* matrices, const glm::vec4* tiles, u32 count,
const glm::vec4& params) {
for (u32 i = 0; i < MAX_SHADOW_TILES; ++i) {
data_.shadowMatrix[i] = i < count ? matrices[i] : glm::mat4(1.0f);
data_.shadowTile[i] = i < count ? tiles[i] : glm::vec4(0.0f);
}
data_.shadowParams = params;
dirty_ = true;
}
/// Names the atlas tiles light @p slot casts into. What lets a fragment read the
/// right map once more than one light has rendered one; a slot nobody names keeps
/// the zeroed count, which is a light with no map.
/** @brief Says the directional light in @p slot reads the sky's cloud shadow from atlas tile @p tile (GpuLight::spot.x). */
void setLightCloudTile(u32 slot, u32 tile) {
if (slot >= count_) return;
data_.lights[slot].spot.x = static_cast<f32>(tile + 1);
dirty_ = true;
}
void setLightShadowTiles(u32 slot, u32 first, u32 tiles) {
if (slot >= count_) return;
// The two the atlas decides, and nothing else: z is the light's own source size,
// written when it was collected and not this pass's to overwrite.
// The layer range this light carries above the count is not the atlas's to overwrite either.
const f32 range = std::floor(data_.lights[slot].shadowMap.y / LIGHT_TILE_BITS);
data_.lights[slot].shadowMap.x = static_cast<f32>(first);
data_.lights[slot].shadowMap.y = static_cast<f32>(tiles) + LIGHT_TILE_BITS * range;
dirty_ = true;
}
/// The frame's environment. The FIRST ambient light carrying one wins — several
/// do not sum the way flat terms do. `yaw` turns it about +Y in RADIANS and rides
/// in the tint's alpha, which std140 pads into existence whether it is used or not.
/// @return false when one was already set this frame.
bool setEnvironment(const glm::vec3* irradiance, const glm::vec4& params,
const glm::vec3& tint, f32 yaw) {
if (hasEnvironment_) return false;
for (usize i = 0; i < 9; ++i) data_.envIrradiance[i] = glm::vec4(irradiance[i], 0.0f);
data_.envParams = params;
data_.envTint = glm::vec4(tint, yaw);
hasEnvironment_ = true;
dirty_ = true;
return true;
}
bool hasEnvironment() const { return hasEnvironment_; }
/**
* @brief Points the frame at a BAKED atlas: its format, and a box per column.
*
* @details Overwrites `envParams` because the atlas the frame binds is this
* one — the columns past 0 are the scene's rooms, and column 0 is the
* sky as the bake saw it. The irradiance and the tint stay the ambient
* light's: the diffuse half is not what a reflection atlas holds.
*/
void setReflections(const glm::vec4& params, const glm::vec4* boxes, u32 count) {
data_.envParams = params;
data_.reflParams.x = static_cast<f32>(count) + 1.0f;
for (u32 i = 0; i < count * 2 && i < 2 * MAX_REFLECTION_PROBES; ++i) {
data_.reflBox[i] = boxes[i];
}
dirty_ = true;
}
/// How baked reflection columns are shown this frame: their brightness and the colour they keep.
void setReflectionTone(f32 scale, f32 saturation) {
data_.reflParams.y = scale;
data_.reflParams.z = saturation;
dirty_ = true;
}
/// What baked indirect light is multiplied by this frame: the day's or the weather's say on a bake of one moment.
/**
* @brief Keeps one part of the light: @p direct the lights alone, otherwise everything that is not a light.
* @details For a view that splits lighting (ShadingMode::DirectLighting / IndirectLighting). Direct zeroes the
* ambient, the environment's both halves (its tint scales the reflection too), the baked columns' and
* the bake's tint, which together are every term indirectIrradiance and envRadiance read. Indirect drops
* every light, tiled ones included.
*/
void isolate(bool direct) {
if (direct) {
data_.ambient = glm::vec4(0.0f, 0.0f, 0.0f, data_.ambient.w);
data_.ambientGround = glm::vec4(0.0f);
for (auto& c : data_.envIrradiance) c = glm::vec4(0.0f);
data_.envTint = glm::vec4(0.0f);
data_.reflParams.y = 0.0f;
data_.bakedTint = glm::vec4(0.0f);
} else {
count_ = 0;
tiledCount_ = 0;
data_.ambient.w = 0.0f;
}
dirty_ = true;
}
void setBakedTint(const glm::vec3& tint) {
data_.bakedTint = glm::vec4(tint, 1.0f);
dirty_ = true;
}
/// Gives light @p slot a channel of the frame's 2D shadow mask, and says the mask
/// exists. A slot nobody names keeps the -1 it was collected with, which is a light
/// that lights without shadowing.
void setLightShadow2DChannel(u32 slot, u32 channel) {
if (slot >= count_ || channel >= MAX_SHADOW_2D_LIGHTS) return;
data_.lights[slot].shadowMap.w = static_cast<f32>(channel);
dirty_ = true;
}
/// The same for the @p index'th light of the tiled list, the ones past the loop's sixteen.
void setTiledLightShadow2DChannel(u32 index, u32 channel) {
if (index >= tiledCount_ || channel >= MAX_SHADOW_2D_LIGHTS) return;
data_.tiledLights[index].shadowMap.w = static_cast<f32>(channel);
dirty_ = true;
}
/// Gives light @p slot a channel of the frame's shape mask. A slot nobody names
/// keeps -1, which is a light with no shape of its own — it lights a full circle.
void setLightShape2DChannel(u32 slot, u32 channel) {
if (slot >= count_ || channel >= MAX_SHAPE_2D_LIGHTS) return;
data_.lights[slot].falloff.w = static_cast<f32>(channel);
dirty_ = true;
}
/// Where the camera about to draw sits inside the masks (xy = low corner, zw = size,
/// as fractions of one). A zero size says the frame has none; set per camera,
/// because two cameras read two different parts of one screen-space target.
void setMask2DRect(const glm::vec4& rect) {
data_.mask2DRect = rect;
dirty_ = true;
}
/// Uploads the mirror (when dirty) and binds it at LIGHT_CONSTANTS_BINDING. Called once per
/// frame in flush(); the binding persists, only the contents change. No-op without a device.
void uploadAndBind();
/// Frees the GPU UBO. Call while the device is still valid (RenderContext::shutdown).
void free();
u32 count() const { return count_; }
const LightConstants& data() const { return data_; }
private:
void markTiledLight(u32 index, const glm::mat4& viewProjection) {
const auto& light = data_.tiledLights[index];
const glm::vec3 position(light.posDir.x, light.posDir.y, light.shadow.z);
markLightTiles(viewProjection, position, std::max(light.posDir.w, 0.0f), index,
reinterpret_cast<u32(*)[4]>(data_.tileMask));
}
LightConstants data_{};
u32 count_ = 0;
u32 tiledCount_ = 0;
bool loopMarked_ = false;
u32 loopTileBits_ = 0;
bool hasEnvironment_ = false;
BufferHandle ubo_ = BufferHandle::Invalid;
bool dirty_ = true;
GfxDevice* device_ = nullptr;
};
} // namespace esengine