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
// Native CTest harness for the full-screen RenderGraph.
//
// Reuse, culling and target sizing are all invisible in a correct image, so
// what this asserts on is the SEQUENCE of device calls a graph produces.
#include "MockGfxDevice.hpp"
#include "esengine/renderer/graph/RenderGraph.hpp"
#include <cstdio>
#include <string>
#include <vector>
using namespace esengine;
static int g_failures = 0;
#define CHECK(cond, msg) \
do { \
if (!(cond)) { std::printf("FAIL: %s\n", msg); ++g_failures; } \
else { std::printf("ok: %s\n", msg); } \
} while (0)
namespace {
rg::PassDesc fullscreen(const char* name, std::vector<rg::ResourceId> reads,
rg::ResourceId write, std::vector<std::string>* ran = nullptr) {
rg::PassDesc pass;
pass.name = name;
pass.reads = std::move(reads);
pass.write = write;
if (ran) {
const std::string label = name;
pass.execute = [ran, label](const rg::PassContext&) { ran->push_back(label); };
}
return pass;
}
} // namespace
int main() {
// A persistent capture is an input to the scene, not its replacement.
{
MockGfxDevice d;
rg::RenderGraph graph(d);
std::vector<std::string> ran;
graph.begin(256, 128);
const auto screen = graph.importTarget(FramebufferHandle{9}, 256, 128);
const auto capture = graph.importTarget(FramebufferHandle{10}, 128, 64, false);
graph.addPass(fullscreen("capture", {}, capture, &ran));
auto scene = fullscreen("scene", {}, screen, &ran);
scene.dependencies.push_back(capture);
graph.addPass(std::move(scene));
graph.execute();
CHECK((ran == std::vector<std::string>{"capture", "scene"}),
"a non-output import preserves the final scene and its capture dependency");
}
// --- a linear chain runs on two physical targets ---
{
MockGfxDevice d;
rg::RenderGraph graph(d);
std::vector<std::string> ran;
graph.begin(256, 128);
const auto scene = graph.importTexture(TextureHandle{7}, 256, 128);
const auto out = graph.importTarget(FramebufferHandle{9}, 256, 128);
const auto a = graph.createTarget({});
const auto b = graph.createTarget({});
graph.addPass(fullscreen("extract", {scene}, a, &ran));
graph.addPass(fullscreen("blur", {a}, b, &ran));
graph.addPass(fullscreen("composite", {b, scene}, out, &ran));
graph.execute();
CHECK(ran.size() == 3, "every pass the image depends on runs");
CHECK(graph.pooledTargetCount() == 2, "a linear chain needs two physical targets");
CHECK(d.createFramebufferCalls == 2, "and allocates exactly those two");
CHECK(d.passLog.size() == 3, "one render pass opened per graph pass");
CHECK(d.passLog.back().target == FramebufferHandle{9},
"the last pass draws into the imported target");
}
// --- a third link reuses the first target rather than allocating ---
{
MockGfxDevice d;
rg::RenderGraph graph(d);
graph.begin(256, 128);
const auto scene = graph.importTexture(TextureHandle{7}, 256, 128);
const auto out = graph.importTarget(FramebufferHandle{9}, 256, 128);
const auto a = graph.createTarget({});
const auto b = graph.createTarget({});
const auto c = graph.createTarget({});
graph.addPass(fullscreen("p0", {scene}, a));
graph.addPass(fullscreen("p1", {a}, b));
graph.addPass(fullscreen("p2", {b}, c));
graph.addPass(fullscreen("p3", {c}, out));
graph.execute();
CHECK(graph.pooledTargetCount() == 2, "a longer chain still needs only two");
}
// --- a pass nothing reads is not run ---
{
MockGfxDevice d;
rg::RenderGraph graph(d);
std::vector<std::string> ran;
graph.begin(64, 64);
const auto scene = graph.importTexture(TextureHandle{7}, 64, 64);
const auto out = graph.importTarget(FramebufferHandle{9}, 64, 64);
const auto orphan = graph.createTarget({});
graph.addPass(fullscreen("dead", {scene}, orphan, &ran));
graph.addPass(fullscreen("blit", {scene}, out, &ran));
graph.execute();
CHECK(ran.size() == 1 && ran[0] == "blit", "the pass no path reaches is culled");
CHECK(d.createFramebufferCalls == 0, "and its target is never allocated");
}
// --- a pass declares its own size ---
{
MockGfxDevice d;
rg::RenderGraph graph(d);
u32 blurW = 0, blurH = 0;
graph.begin(200, 100);
const auto scene = graph.importTexture(TextureHandle{7}, 200, 100);
const auto out = graph.importTarget(FramebufferHandle{9}, 200, 100);
rg::TargetDesc half;
half.scale = 0.5f;
const auto small = graph.createTarget(half);
rg::PassDesc blur = fullscreen("blur", {scene}, small);
blur.execute = [&](const rg::PassContext& ctx) { blurW = ctx.width; blurH = ctx.height; };
graph.addPass(std::move(blur));
graph.addPass(fullscreen("composite", {small, scene}, out));
graph.execute();
CHECK(blurW == 100 && blurH == 50, "a half-scale pass runs at half the reference size");
CHECK(d.viewportLog.size() >= 1 && d.viewportLog[0].w == 100 && d.viewportLog[0].h == 50,
"the viewport follows the target, not the screen");
}
// --- reads bind in declaration order ---
{
MockGfxDevice d;
rg::RenderGraph graph(d);
TextureHandle first = TextureHandle::Invalid, second = TextureHandle::Invalid;
graph.begin(64, 64);
const auto scene = graph.importTexture(TextureHandle{7}, 64, 64);
const auto out = graph.importTarget(FramebufferHandle{9}, 64, 64);
const auto blurred = graph.createTarget({});
graph.addPass(fullscreen("blur", {scene}, blurred));
rg::PassDesc composite = fullscreen("composite", {blurred, scene}, out);
composite.execute = [&](const rg::PassContext& ctx) {
first = ctx.input(0);
second = ctx.input(1);
};
graph.addPass(std::move(composite));
graph.execute();
CHECK(second == TextureHandle{7}, "a pass reads the scene because it declared it second");
CHECK(first != TextureHandle::Invalid && first != second,
"and the blur result as its first input");
CHECK(d.bindLog.size() == 3, "each read is bound once, at its declared unit");
CHECK(d.bindLog[1].first == 0 && d.bindLog[2].first == 1,
"units follow declaration order");
}
// --- the pool outlives the frame ---
{
MockGfxDevice d;
rg::RenderGraph graph(d);
for (int frame = 0; frame < 3; ++frame) {
graph.begin(64, 64);
const auto scene = graph.importTexture(TextureHandle{7}, 64, 64);
const auto out = graph.importTarget(FramebufferHandle{9}, 64, 64);
const auto mid = graph.createTarget({});
graph.addPass(fullscreen("blur", {scene}, mid));
graph.addPass(fullscreen("blit", {mid}, out));
graph.execute();
}
CHECK(d.createFramebufferCalls == 1, "three frames of the same graph allocate once");
graph.releasePool();
CHECK(graph.pooledTargetCount() == 0, "releasePool drops what device loss invalidated");
}
// --- nothing runs without a declared output ---
{
MockGfxDevice d;
rg::RenderGraph graph(d);
std::vector<std::string> ran;
graph.begin(64, 64);
const auto scene = graph.importTexture(TextureHandle{7}, 64, 64);
const auto mid = graph.createTarget({});
graph.addPass(fullscreen("blur", {scene}, mid, &ran));
graph.execute();
// Not a no-op worth being lenient about: with no imported target, the
// default framebuffer is the screen, and a stray pass would draw on it.
CHECK(ran.empty(), "a graph with no output runs nothing");
}
// --- the scene target: owned and pooled here, filled somewhere else ---
{
MockGfxDevice d;
rg::RenderGraph graph(d);
graph.begin(256, 128);
const auto sceneId = graph.createExternalTarget({});
// Drawable BEFORE execute, which is the whole point: a frame reaches the
// host as several calls and the geometry lands between them.
CHECK(sceneId != rg::kNoResource, "an external target is handed out at declaration");
CHECK(graph.framebufferOf(sceneId) != FramebufferHandle::Default,
"and names a real framebuffer to draw into");
CHECK(d.createFramebufferCalls == 1, "allocated once, at that moment");
const auto out = graph.importTarget(FramebufferHandle{9}, 256, 128);
const auto a = graph.createTarget({});
const auto b = graph.createTarget({});
graph.addPass(fullscreen("effect", {sceneId}, a));
graph.addPass(fullscreen("grade", {a}, b));
graph.addPass(fullscreen("blit", {b}, out));
graph.execute();
// Recycled at its last read like any other transient: nothing after
// "effect" reads the scene, so "grade" is handed that same physical
// target back — two allocations for a three-link chain, not three.
CHECK(d.createFramebufferCalls == 2, "the scene target goes back to the pool and is reused");
CHECK(graph.pooledTargetCount() == 2, "the pool owns it, not the pipeline");
}
// --- a target can name its pixels instead of a fraction of the frame ---
{
MockGfxDevice d;
rg::RenderGraph graph(d);
u32 atlasW = 0, atlasH = 0;
graph.begin(800, 600);
const auto out = graph.importTarget(FramebufferHandle{9}, 800, 600);
rg::TargetDesc atlas;
atlas.width = 2048;
atlas.height = 2048;
atlas.depthStencil = true;
const auto maps = graph.createTarget(atlas);
rg::PassDesc shadow = fullscreen("shadow", {}, maps);
shadow.execute = [&](const rg::PassContext& ctx) { atlasW = ctx.width; atlasH = ctx.height; };
graph.addPass(std::move(shadow));
graph.addPass(fullscreen("scene", {maps}, out));
graph.execute();
CHECK(atlasW == 2048 && atlasH == 2048,
"an absolute size is the target's own, not a fraction of the frame");
// The point of asking in pixels: the same atlas at a different window
// size is the same resource, so the pool hands back the one it has.
graph.begin(1920, 1080);
const auto out2 = graph.importTarget(FramebufferHandle{9}, 1920, 1080);
const auto maps2 = graph.createTarget(atlas);
graph.addPass(fullscreen("shadow", {}, maps2));
graph.addPass(fullscreen("scene", {maps2}, out2));
graph.execute();
CHECK(d.createFramebufferCalls == 1,
"and it survives a resize the fraction-sized targets do not");
}
// --- a resource named but not bound still orders the two passes ---
//
// The scene reaches the atlas through its materials, not a sampler the graph
// wired: as a read it would claim a unit; as nothing, its producer is culled.
{
MockGfxDevice d;
rg::RenderGraph graph(d);
std::vector<std::string> ran;
graph.begin(256, 128);
const auto out = graph.importTarget(FramebufferHandle{9}, 256, 128);
rg::TargetDesc atlas;
atlas.width = 2048;
atlas.height = 2048;
atlas.depthStencil = true;
const auto maps = graph.createTarget(atlas);
graph.addPass(fullscreen("shadow-atlas", {}, maps, &ran));
rg::PassDesc scene = fullscreen("scene", {}, out, &ran);
scene.dependencies.push_back(maps);
graph.addPass(std::move(scene));
graph.execute();
CHECK(ran.size() == 2 && ran[0] == "shadow-atlas" && ran[1] == "scene",
"a pass reached only through a dependency survives culling, and runs first");
CHECK(d.bindLog.empty(), "and costs no texture unit, because nothing declared a read");
CHECK(graph.pooledTargetCount() == 1, "the atlas is a pooled target like any other");
// Lifetime has to count it too: an atlas whose last reader is not counted
// would either be recycled while the scene still samples it, or held to
// the end of the frame and paid for twice on the next camera.
graph.begin(256, 128);
const auto out2 = graph.importTarget(FramebufferHandle{9}, 256, 128);
const auto maps2 = graph.createTarget(atlas);
graph.addPass(fullscreen("shadow-atlas", {}, maps2));
rg::PassDesc scene2 = fullscreen("scene", {}, out2);
scene2.dependencies.push_back(maps2);
graph.addPass(std::move(scene2));
const auto after = graph.createTarget(atlas);
graph.addPass(fullscreen("second-camera-atlas", {}, after));
rg::PassDesc scene3 = fullscreen("scene-2", {}, out2);
scene3.dependencies.push_back(after);
graph.addPass(std::move(scene3));
graph.execute();
CHECK(d.createFramebufferCalls == 1,
"the atlas goes back after the pass that names it, so the next one reuses it");
}
// --- the pool gives back what nothing asks for any more ---
{
MockGfxDevice d;
rg::RenderGraph graph(d);
// A frame with a blur chain: the scene, plus the half-size target it runs on.
graph.begin(256, 256);
const auto scene = graph.importTexture(TextureHandle{7}, 256, 256);
const auto out = graph.importTarget(FramebufferHandle{9}, 256, 256);
rg::TargetDesc half;
half.scale = 0.5f;
const auto small = graph.createTarget(half);
graph.addPass(fullscreen("blur", {scene}, small));
graph.addPass(fullscreen("composite", {small, scene}, out));
graph.execute();
CHECK(graph.pooledTargetCount() == 1, "the chain's target is pooled");
CHECK(graph.pooledTargetBytes() == 128ull * 128ull * 4ull,
"and a budget can read what it costs in bytes");
// The effect is turned off. Nothing asks for a 128x128 target again.
for (int frame = 0; frame < 121; ++frame) {
graph.begin(256, 256);
const auto sc = graph.importTexture(TextureHandle{7}, 256, 256);
const auto o = graph.importTarget(FramebufferHandle{9}, 256, 256);
graph.addPass(fullscreen("blit", {sc}, o));
graph.execute();
}
CHECK(graph.pooledTargetCount() == 0,
"a target nothing has asked for in 120 graphs goes back");
CHECK(graph.pooledTargetBytes() == 0, "and stops being counted against the budget");
}
// --- ...but not one that is still being used ---
{
MockGfxDevice d;
rg::RenderGraph graph(d);
for (int frame = 0; frame < 200; ++frame) {
graph.begin(256, 256);
const auto scene = graph.importTexture(TextureHandle{7}, 256, 256);
const auto out = graph.importTarget(FramebufferHandle{9}, 256, 256);
const auto mid = graph.createTarget({});
graph.addPass(fullscreen("blur", {scene}, mid));
graph.addPass(fullscreen("blit", {mid}, out));
graph.execute();
}
// The count alone would not catch a wrong eviction: evicted and
// reallocated leaves a pool of one too. What it cost to get there is
// the half that bites.
CHECK(graph.pooledTargetCount() == 1, "a target asked for every graph is kept");
CHECK(d.createFramebufferCalls == 1, "and never reallocated");
}
// --- a frame's chains share one pool, and something can hold across them ---
{
MockGfxDevice d;
rg::TargetPool pool(d);
rg::RenderGraph graph(d, pool);
// What the shadow atlas is: borrowed before any chain runs and still
// its own after two have. Deliberately the SHAPE A CHAIN WANTS — a
// 2048² one no chain asks for could not be taken either way.
rg::TargetShape held_shape;
held_shape.width = 256;
held_shape.height = 256;
const rg::TargetHandle held = pool.acquire(held_shape);
const FramebufferHandle heldFbo = pool.framebufferOf(held);
CHECK(held != rg::kNoTarget && heldFbo != FramebufferHandle::Default,
"a frame can borrow a target before any chain begins");
FramebufferHandle chainFbo = FramebufferHandle::Default;
for (int camera = 0; camera < 2; ++camera) {
graph.begin(256, 256);
const auto scene = graph.createExternalTarget({});
chainFbo = graph.framebufferOf(scene);
const auto out = graph.importTarget(FramebufferHandle{9}, 256, 256);
graph.addPass(fullscreen("blit", {scene}, out));
graph.execute();
}
CHECK(chainFbo != heldFbo,
"a chain is never handed the target the frame is still holding");
CHECK(pool.framebufferOf(held) == heldFbo,
"which is still the frame's after two chains ran over the same pool");
CHECK(pool.count() == 2, "the held one and the chains' own, not one per chain");
// Given back at the end of the frame, it is a candidate again — which is
// the whole difference from a framebuffer the frame keeps forever.
pool.release(held);
for (int tick = 0; tick < rg::TargetPool::kIdleTicksBeforeEvict; ++tick) pool.age();
CHECK(pool.count() == 0, "and once given back it ages out like anything else");
}
// --- a resize leaves a target of every size behind, and the pool does not keep them all ---
{
MockGfxDevice d;
rg::TargetPool pool(d);
rg::TargetShape shape;
shape.format = GfxPixelFormat::RGBA16F;
// A window dragged through two hundred sizes, one borrowed and given back each tick.
for (u32 size = 0; size < 200; ++size) {
shape.width = 1000 + size * 3;
shape.height = 800 + size * 2;
pool.release(pool.acquire(shape));
pool.age();
}
CHECK(pool.bytes() <= rg::TargetPool::kIdleByteBudget + 64ull * 1024 * 1024,
"idle targets are kept within a byte budget, not for two seconds each");
CHECK(pool.count() < 200, "and the sizes the window has left are gone");
}
// --- what a frame uses every frame is kept, however much of it there is ---
{
MockGfxDevice d;
rg::TargetPool pool(d);
// Past the idle budget between them, as a 4096 shadow atlas and a 4x scene target at 2670x1200 are. All of it has just been given
// back when the pool ages, and that is not the same as nobody wanting it.
rg::TargetShape atlas;
atlas.width = atlas.height = 4096;
atlas.depthStencil = true;
rg::TargetShape scene;
scene.width = 2670;
scene.height = 1200;
scene.format = GfxPixelFormat::RGBA16F;
scene.depthStencil = true;
scene.samples = 4;
const rg::TargetHandle firstAtlas = pool.acquire(atlas);
const rg::TargetHandle firstScene = pool.acquire(scene);
CHECK(pool.bytes() > rg::TargetPool::kIdleByteBudget, "the two together are past the budget");
pool.release(firstAtlas);
pool.release(firstScene);
for (u32 frame = 0; frame < 300; ++frame) {
pool.age();
const rg::TargetHandle a = pool.acquire(atlas);
const rg::TargetHandle s = pool.acquire(scene);
pool.release(a);
pool.release(s);
}
CHECK(pool.holds(firstAtlas) && pool.holds(firstScene), "a frame's own targets are not destroyed and rebuilt every frame");
CHECK(pool.count() == 2, "and no second set has grown");
// And once nothing asks for them, they do go.
for (u32 tick = 0; tick < rg::TargetPool::kBudgetGraceTicks + 1; ++tick) pool.age();
CHECK(pool.bytes() <= rg::TargetPool::kIdleByteBudget, "left alone, they answer to the budget again");
}
// --- a handle outliving its target names nothing, not the next thing ---
{
MockGfxDevice d;
rg::TargetPool pool(d);
rg::TargetShape shape;
shape.width = 128;
shape.height = 128;
const rg::TargetHandle held = pool.acquire(shape);
CHECK(pool.holds(held), "a fresh handle names its target");
// What a window resize does: reclaim everything, then hand the slot to
// the next borrower. Without a generation the stale handle would name
// the newcomer, and the frame would draw its shadows into a post target.
pool.clear();
CHECK(!pool.holds(held), "a handle whose target was dropped names nothing");
CHECK(pool.framebufferOf(held) == FramebufferHandle::Default,
"and answers with no framebuffer rather than someone else's");
const rg::TargetHandle next = pool.acquire(shape);
CHECK(next != held, "the refilled slot is a different handle");
CHECK(!pool.holds(held) && pool.holds(next),
"so the newcomer is reachable and the ghost still is not");
}
// --- a compute pass opens no render pass, writes a storage target, and feeds the pass after it ---
{
MockGfxDevice d;
rg::RenderGraph graph(d);
std::vector<std::string> ran;
graph.begin(256, 128);
const auto screen = graph.importTarget(FramebufferHandle{9}, 256, 128);
const auto scene = graph.importTexture(TextureHandle{5}, 256, 128);
rg::TargetDesc storage;
storage.storage = true;
const auto computed = graph.createTarget(storage);
TextureHandle seenInput = TextureHandle::Invalid;
TextureHandle seenOutput = TextureHandle::Invalid;
rg::PassDesc compute;
compute.name = "compute";
compute.reads = {scene};
compute.write = computed;
compute.compute = true;
compute.execute = [&](const rg::PassContext& ctx) {
ran.push_back("compute");
seenInput = ctx.input(0);
seenOutput = ctx.output;
};
graph.addPass(std::move(compute));
graph.addPass(fullscreen("draw", {computed}, screen, &ran));
graph.execute();
CHECK((ran == std::vector<std::string>{"compute", "draw"}), "a compute pass runs in order with the draws around it");
CHECK(d.beginRenderPassCalls == 1, "and opens no render pass of its own");
CHECK(seenInput == TextureHandle{5}, "it is told the texture it reads");
CHECK(seenOutput != TextureHandle::Invalid, "and the storage texture it writes");
}
// --- a compute pass nothing reads is culled like any other ---
{
MockGfxDevice d;
rg::RenderGraph graph(d);
std::vector<std::string> ran;
graph.begin(64, 64);
const auto screen = graph.importTarget(FramebufferHandle{9}, 64, 64);
rg::TargetDesc storage;
storage.storage = true;
const auto unused = graph.createTarget(storage);
rg::PassDesc compute;
compute.name = "compute";
compute.write = unused;
compute.compute = true;
compute.execute = [&](const rg::PassContext&) { ran.push_back("compute"); };
graph.addPass(std::move(compute));
graph.addPass(fullscreen("draw", {}, screen, &ran));
graph.execute();
CHECK((ran == std::vector<std::string>{"draw"}), "a compute pass whose output nothing reaches is dropped");
}
std::printf(g_failures == 0 ? "\nALL PASS\n" : "\n%d FAILURE(S)\n", g_failures);
return g_failures == 0 ? 0 : 1;
}