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 TargetPool.hpp
* @brief The render targets a frame borrows from, keyed by shape — owned by
* the frame, not by any one graph that draws from it.
*
* A RenderGraph is a CHAIN, and a frame holds several of them: one per camera
* and one for the screen-level stack. While the pool lived inside the graph,
* every `begin()` handed every target back, so nothing could be borrowed across
* two chains — which is why the shadow atlas had to be a framebuffer of its own,
* created on the first shadowed frame and held for the rest of the run.
*
* Splitting it out makes the lifetime the borrower's to state: a chain's
* transient goes back at its last read, the atlas goes back at the end of the
* frame, and both come out of the same physical targets on the next one.
*
* Handles carry a generation. A slot outlives the target in it — evicting frees
* the memory and leaves the slot to be refilled — so an index alone would let a
* handle taken before an eviction name whatever landed in that slot afterwards,
* and a frame holding the atlas across a window resize would draw its shadows
* into a post-process target. The generation makes a stale handle name nothing.
*/
#pragma once
#include "../../core/Types.hpp"
#include "../rhi/Framebuffer.hpp"
#include "../rhi/GfxEnums.hpp"
#include <vector>
namespace esengine {
class GfxDevice;
namespace rg {
/**
* @brief A borrowed target: a slot index, and the generation of what is in it.
*
* @details Opaque — pack and unpack are the pool's. Compare it, hold it, hand it
* back; a handle whose target has since been freed resolves to nothing
* rather than to the next thing that took the slot.
*/
using TargetHandle = u32;
constexpr TargetHandle kNoTarget = static_cast<TargetHandle>(-1);
/** What a borrower asks for. Sizes are pixels — a scale is the caller's to resolve. */
struct TargetShape {
u32 width = 0;
u32 height = 0;
GfxPixelFormat format = GfxPixelFormat::RGBA8;
bool linearFilter = true;
bool depthStencil = false;
/// Samples the target is DRAWN into with; what it hands back to be sampled
/// is always single-sample, because the target resolves itself.
u32 samples = 1;
/// A second colour attachment for the surface's material (see FramebufferSpec::gbuffer).
bool gbuffer = false;
/// Written by a compute shader as a storage texture, and sampled after.
bool storage = false;
};
class TargetPool {
public:
explicit TargetPool(GfxDevice& device);
~TargetPool();
TargetPool(const TargetPool&) = delete;
TargetPool& operator=(const TargetPool&) = delete;
/**
* @brief Borrow a target of this shape, reusing one or creating it.
* @return kNoTarget if the device could not make one.
*/
TargetHandle acquire(const TargetShape& shape);
/** Give one back. Borrowing again may hand out the same physical target. */
void release(TargetHandle handle);
/** Whether a handle still names a live target — false once it was freed. */
bool holds(TargetHandle handle) const;
FramebufferHandle framebufferOf(TargetHandle handle) const;
TextureHandle textureOf(TargetHandle handle) const;
/** The depth attachment, for a target that has one — an effect reading the
* scene's depth samples this. Invalid when the shape carried no depth. */
TextureHandle depthTextureOf(TargetHandle handle) const;
/** Its second colour attachment, Invalid for a target made without one. */
TextureHandle gbufferTextureOf(TargetHandle handle) const;
TextureHandle albedoTextureOf(TargetHandle handle) const;
/**
* @brief One tick of the clock every borrowed target is aged against.
*
* @details Called once per graph. A target out on loan does not age; one
* nothing has borrowed for {@link kIdleTicksBeforeEvict} ticks is
* memory held against a chain that was turned off, or a scene that
* stopped casting shadows, and is destroyed.
*/
void age();
/** Drop everything. For shutdown and for device loss, after which the
* handles the pool holds name nothing. */
void clear();
/** Physical targets currently allocated. Diagnostics and tests. */
u32 count() const;
/** What they cost in GPU memory, so a budget reads bytes rather than a
* count of things with no common size. */
u64 bytes() const;
/**
* @brief Ticks a target may go unborrowed before the pool destroys it.
*
* @details High on purpose: acquire() resets it, so this bounds only how
* long a target NOTHING asks for is kept against being asked for
* again. At a small number a target used by one of several chains
* would thrash on the ticks the others take.
*/
static constexpr u32 kIdleTicksBeforeEvict = 120;
/** @brief Bytes of unborrowed targets the pool keeps, whatever their age: past it the longest idle are destroyed. */
static constexpr u64 kIdleByteBudget = 256ull * 1024 * 1024;
/** @brief Ticks unborrowed before a target counts against that budget. More than one, since age runs once per graph and a frame can
* have several: a target one graph borrows is otherwise idle on the ticks the others take. */
static constexpr u32 kBudgetGraceTicks = 4;
private:
struct Entry {
Unique<Framebuffer> fbo;
TargetShape shape;
bool inUse = false;
/// Ticks since anything borrowed it; age() adds, acquire() zeroes.
u32 idle = 0;
/// Bumped whenever the target in this slot is freed, which is what makes
/// every handle to it stale.
u32 generation = 0;
};
/// Slots live in the low bits so the count is what bounds them, not the
/// generation: 64K slots is far past any frame, and a generation that wraps
/// would need the same slot freed 64K times while one handle survived.
static constexpr u32 kSlotBits = 16;
static constexpr u32 kSlotMask = (1u << kSlotBits) - 1;
/// The entry a handle names, or nullptr if it names one that has been freed.
const Entry* resolve(TargetHandle handle) const;
GfxDevice& device_;
std::vector<Entry> entries_;
};
} // namespace rg
} // namespace esengine