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 ShadowPlan.hpp
* @brief What each caster asked the shadow atlas for, and what it got.
*
* @details A caster the atlas could not fit kept no tiles and cast nothing, and
* the frame counted the tiles it DID hand out. So "why does this object
* have no shadow" had no answer anywhere in the engine — not a missing
* panel, a missing fact.
*
* Header-only and free of the renderer, like LodSelection.hpp: the
* giving-way rule is the part worth holding to a criterion, and it
* needs no device to be wrong.
*/
#pragma once
#include "../../core/Types.hpp"
#include "./ShadowAtlas.hpp"
#include <vector>
namespace esengine {
/**
* @brief One caster's claim on the atlas: what it wanted, what it kept, and why
* the difference.
*
* @details `granted < requested` with no refusal is impossible — something gave
* way and the reason is the whole point of recording this.
*/
struct ShadowGrant {
/// The light that asked. Carried so a reader can name it rather than an index.
Entity light{};
/// Tiles asked for: a sun's cascade set, a cube's six faces, or one.
u32 requested = 0;
/// Tiles kept. 0 means this light casts no shadow at all this frame.
u32 granted = 0;
/// Why it did not get what it asked for, from the FIRST attempt that failed —
/// which is the answer to "why not what I asked", not "why not one less".
AtlasRefusal refusal = AtlasRefusal::None;
bool denied() const { return granted == 0; }
bool reduced() const { return granted > 0 && granted < requested; }
};
/** @brief The frame's whole shadow allocation, as numbers something outside it can check. */
struct ShadowPlanReport {
u32 atlasSize = 0;
u32 cellSize = 0;
u32 requestedTiles = 0;
u32 grantedTiles = 0;
std::vector<ShadowGrant> grants;
void clear() {
requestedTiles = 0;
grantedTiles = 0;
grants.clear();
}
u32 deniedCasters() const {
u32 n = 0;
for (const ShadowGrant& g : grants) n += g.denied() ? 1u : 0u;
return n;
}
/** @brief What @p entity asked for and kept, or null when it asked nothing. */
const ShadowGrant* grantFor(Entity entity) const {
for (const ShadowGrant& g : grants) {
if (g.light.raw == entity.raw) return &g;
}
return nullptr;
}
/** @brief Whether this report already contains the same denied claim. */
bool hasSameDenial(const ShadowGrant& claim) const {
const ShadowGrant* previous = grantFor(claim.light);
return claim.denied() && previous && previous->denied()
&& previous->requested == claim.requested && previous->refusal == claim.refusal;
}
u32 reducedCasters() const {
u32 n = 0;
for (const ShadowGrant& g : grants) n += g.reduced() ? 1u : 0u;
return n;
}
};
enum class ShadowClaim : u8 {
AllOrNothing,
AllowFewer,
};
/**
* @brief Claim a complete shadow map, or explicitly allow fewer cascades.
*
* @details A sun settles for fewer rather than costing a positional light the map
* it cannot shorten. Giving way and RECORDING what it gave way from are
* one function, so a caller cannot take the first without the second.
* A point light needs all six faces: a partial cube leaves directions
* unshadowed and consumes tiles that another complete map could use.
*/
inline ShadowGrant claimTiles(ShadowAtlas& atlas, Entity light, u32 want, u32 cells,
i32& outFirst, ShadowClaim policy = ShadowClaim::AllOrNothing) {
ShadowGrant grant{light, want, 0, AtlasRefusal::None};
outFirst = -1;
for (u32 take = want; take > 0; --take) {
AtlasRefusal why = AtlasRefusal::None;
const i32 at = atlas.allocate(take, cells, why);
if (at >= 0) {
outFirst = at;
grant.granted = take;
return grant;
}
// The first refusal is the one that answers the question a reader has.
if (take == want) grant.refusal = why;
if (policy == ShadowClaim::AllOrNothing) break;
}
return grant;
}
} // namespace esengine