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
#include "./TransientBufferPool.hpp"
#include "../../core/Log.hpp"
#include "../../core/FrameProfiler.hpp"
#include <cstring>
#include <algorithm>
namespace esengine {
TransientBufferPool::TransientBufferPool(GfxDevice& device)
: device_(device) {
}
void TransientBufferPool::init(u32 initialVertexBytes, u32 initialIndexCount) {
if (initialized_) return;
initial_vertex_bytes_ = initialVertexBytes;
initial_index_count_ = initialIndexCount;
for (auto layout : {LayoutId::Batch, LayoutId::ParticleInstance, LayoutId::Shape,
LayoutId::Sky,
LayoutId::MeshInstance}) {
setupStream(layout);
}
initialized_ = true;
}
void TransientBufferPool::shutdown() {
if (!initialized_) return;
for (auto& s : streams_) {
if (s.layout != VertexLayoutHandle::Invalid) {
device_.deleteVertexLayout(s.layout);
s.layout = VertexLayoutHandle::Invalid;
}
if (s.vbo != BufferHandle::Invalid) { device_.deleteBuffer(s.vbo); s.vbo = BufferHandle::Invalid; }
if (s.ebo != BufferHandle::Invalid) { device_.deleteBuffer(s.ebo); s.ebo = BufferHandle::Invalid; }
if (s.quad_vbo != BufferHandle::Invalid) { device_.deleteBuffer(s.quad_vbo); s.quad_vbo = BufferHandle::Invalid; }
if (s.texture != TextureHandle::Invalid) {
device_.deleteTexture(s.texture);
s.texture = TextureHandle::Invalid;
}
s.texture_rows = 0;
s.vertex_staging.clear();
s.index_staging.clear();
s.vertex_write_pos = 0;
s.index_write_pos = 0;
s.vbo_capacity = 0;
s.ebo_capacity = 0;
}
initialized_ = false;
}
void TransientBufferPool::beginFrame() {
for (auto& s : streams_) {
s.vertex_write_pos = 0;
s.index_write_pos = 0;
}
}
TransientBufferPool::Stream& TransientBufferPool::stream(LayoutId layout) {
return streams_[static_cast<u32>(layout)];
}
const TransientBufferPool::Stream& TransientBufferPool::stream(LayoutId layout) const {
return streams_[static_cast<u32>(layout)];
}
/**
* @brief The frame's records onto the GPU, as whole rows.
*
* @details Whole rows because a partial one asks the upload to describe a
* rectangle the staging is not laid out as. The record divides the row
* evenly, so a row boundary never falls inside one.
*/
void TransientBufferPool::uploadInstanceRows(Stream& s, u32& grows, u32& writes) {
const u32 rowBytes = instanceRowBytes();
const u32 rows = (s.vertex_write_pos + rowBytes - 1) / rowBytes;
if (static_cast<u64>(s.vertex_staging.size()) < static_cast<u64>(rows) * rowBytes) {
s.vertex_staging.resize(static_cast<usize>(rows) * rowBytes);
}
if (rows > s.texture_rows) {
// Doubling, the way the staging grows: a workload creeping upward
// otherwise reallocates a texture every frame.
// The texture is created from the staging, so the staging is as tall as the texture, and neither is taller than a device guarantees.
const u32 limit = MESH_INSTANCE_MAX_RECORDS * MESH_INSTANCE_TEXELS / MESH_INSTANCE_TEXTURE_WIDTH;
const u32 want = std::min(std::max(rows, s.texture_rows * 2), std::max(rows, limit));
if (s.vertex_staging.size() < static_cast<usize>(want) * rowBytes) {
s.vertex_staging.resize(static_cast<usize>(want) * rowBytes);
}
if (s.texture != TextureHandle::Invalid) device_.deleteTexture(s.texture);
TextureDesc desc;
desc.width = MESH_INSTANCE_TEXTURE_WIDTH;
desc.height = want;
desc.format = GfxPixelFormat::RGBA32F;
// Fetched by index, never filtered: a value between two records belongs
// to no object, and full floats are not filterable everywhere anyway.
desc.minFilter = TextureFilter::Nearest;
desc.magFilter = TextureFilter::Nearest;
desc.wrapS = TextureWrap::ClampToEdge;
desc.wrapT = TextureWrap::ClampToEdge;
desc.mipmaps = false;
s.texture = device_.createTexture(desc, GfxContent::transient(), s.vertex_staging.data());
s.texture_rows = s.texture == TextureHandle::Invalid ? 0 : want;
++grows;
return;
}
// No flip: this is a record store addressed by index, not an image, so row 0
// has to stay the row the writer wrote first.
device_.updateTexture(s.texture, 0, 0, MESH_INSTANCE_TEXTURE_WIDTH, rows,
s.vertex_staging.data(), /*flipY=*/false);
++writes;
}
u32 TransientBufferPool::allocVertices(LayoutId layout, u32 byteSize) {
Stream& s = stream(layout);
if (byteSize) ensureStorage(layout);
u32 offset = s.vertex_write_pos;
u32 newPos = s.vertex_write_pos + byteSize;
if (newPos > static_cast<u32>(s.vertex_staging.size())) {
growVertexStaging(s, newPos);
}
s.vertex_write_pos = newPos;
return offset;
}
u32 TransientBufferPool::allocIndices(LayoutId layout, u32 count) {
Stream& s = stream(layout);
if (count) ensureStorage(layout);
u32 offset = s.index_write_pos;
u32 newPos = s.index_write_pos + count;
if (newPos > static_cast<u32>(s.index_staging.size())) {
growIndexStaging(s, newPos);
}
s.index_write_pos = newPos;
return offset;
}
void TransientBufferPool::writeVertices(LayoutId layout, u32 byteOffset, const void* data, u32 byteSize) {
std::memcpy(stream(layout).vertex_staging.data() + byteOffset, data, byteSize);
}
void TransientBufferPool::writeIndices(LayoutId layout, u32 indexOffset, const u32* data, u32 count) {
std::memcpy(stream(layout).index_staging.data() + indexOffset, data, count * sizeof(u32));
}
u32 TransientBufferPool::appendVertices(LayoutId layout, const void* data, u32 byteSize) {
u32 offset = allocVertices(layout, byteSize);
writeVertices(layout, offset, data, byteSize);
return offset;
}
u32 TransientBufferPool::appendIndices(LayoutId layout, const u32* data, u32 count) {
u32 offset = allocIndices(layout, count);
writeIndices(layout, offset, data, count);
return offset;
}
void TransientBufferPool::upload() {
// What the upload was ASKED to move, beside what it cost. A spike that tracks
// bytes is workload; a spike at unchanged bytes is the allocation or driver
// path, and one number cannot tell those apart.
u32 streams = 0, vertexBytes = 0, indexBytes = 0, grows = 0, writes = 0;
// Growth goes through resizeBuffer, which keeps the handle stable, so per-draw
// buffer bindings and the backend's cached vertex state stay valid.
for (auto& s : streams_) {
if (&s == &stream(LayoutId::MeshInstance)) {
if (s.vertex_write_pos == 0) continue;
++streams;
vertexBytes += s.vertex_write_pos;
uploadInstanceRows(s, grows, writes);
continue;
}
if (s.vbo == BufferHandle::Invalid) continue;
if (s.vertex_write_pos == 0 && s.index_write_pos == 0) continue;
++streams;
vertexBytes += s.vertex_write_pos;
indexBytes += s.index_write_pos * static_cast<u32>(sizeof(u32));
// Grow to the STAGING capacity, which already doubles — not to what this
// frame needed, which reallocates every frame for a workload creeping
// upward (2.1MB, 2.2MB, 2.3MB). One growth rule, in growVertexStaging.
if (s.vertex_write_pos > s.vbo_capacity) {
s.vbo_capacity = static_cast<u32>(s.vertex_staging.size());
device_.resizeBuffer(s.vbo, s.vbo_capacity, s.vertex_staging.data());
++grows;
} else if (s.vertex_write_pos > 0) {
device_.updateBuffer(s.vbo, 0, s.vertex_staging.data(), s.vertex_write_pos);
++writes;
}
u32 eboBytes = s.index_write_pos * sizeof(u32);
u32 eboCapBytes = s.ebo_capacity * sizeof(u32);
if (eboBytes > eboCapBytes) {
s.ebo_capacity = static_cast<u32>(s.index_staging.size());
device_.resizeBuffer(s.ebo, static_cast<u32>(s.ebo_capacity * sizeof(u32)),
s.index_staging.data());
++grows;
} else if (eboBytes > 0) {
device_.updateBuffer(s.ebo, 0, s.index_staging.data(), eboBytes);
++writes;
}
}
ES_PROFILE_COUNTER("render.upload.streams", streams);
ES_PROFILE_COUNTER("render.upload.vertexBytes", vertexBytes);
ES_PROFILE_COUNTER("render.upload.indexBytes", indexBytes);
ES_PROFILE_COUNTER("render.upload.grows", grows);
ES_PROFILE_COUNTER("render.upload.writes", writes);
}
void TransientBufferPool::bindLayout(LayoutId layout) {
const Stream& s = stream(layout);
if (layout == LayoutId::ParticleInstance) {
bindInstanceLayout(layout, 0);
return;
}
device_.setVertexBuffer(0, s.vbo, 0);
device_.setIndexBuffer(s.ebo);
}
void TransientBufferPool::bindInstanceLayout(LayoutId layout, u32 instanceByteOffset) {
const Stream& s = stream(layout);
device_.setVertexBuffer(0, s.quad_vbo, 0);
device_.setVertexBuffer(1, s.vbo, instanceByteOffset);
device_.setIndexBuffer(s.ebo);
}
void TransientBufferPool::bindInstanceBuffer(LayoutId layout, BufferHandle instances) {
const Stream& s = stream(layout);
device_.setVertexBuffer(0, s.quad_vbo, 0);
device_.setVertexBuffer(1, instances, 0);
device_.setIndexBuffer(s.ebo);
}
VertexLayoutHandle TransientBufferPool::layoutHandle(LayoutId layout) const {
return stream(layout).layout;
}
u8* TransientBufferPool::vertexData(LayoutId layout) {
return stream(layout).vertex_staging.data();
}
u32 TransientBufferPool::vertexBytesUsed(LayoutId layout) const {
return stream(layout).vertex_write_pos;
}
u32 TransientBufferPool::indicesUsed(LayoutId layout) const {
return stream(layout).index_write_pos;
}
const u32* TransientBufferPool::indexData(LayoutId layout) const {
return stream(layout).index_staging.data();
}
bool TransientBufferPool::copyIndexRange(LayoutId layout, u32 offset, u32 count, u32& copiedAt) {
auto& s = stream(layout);
if (count == 0 || offset > s.index_write_pos || count > s.index_write_pos - offset
|| count > ~u32{0} - s.index_write_pos) return false;
copiedAt = allocIndices(layout, count);
// Allocation can grow the vector; resolve both addresses afterwards.
std::memmove(s.index_staging.data() + copiedAt, s.index_staging.data() + offset,
static_cast<usize>(count) * sizeof(u32));
return true;
}
BufferHandle TransientBufferPool::vertexBuffer(LayoutId layout) const {
return stream(layout).vbo;
}
BufferHandle TransientBufferPool::indexBuffer(LayoutId layout) const {
return stream(layout).ebo;
}
u32 TransientBufferPool::vertexStride(LayoutId layout) const {
return stream(layout).vertex_stride;
}
void TransientBufferPool::ensureStorage(LayoutId layout) {
Stream& s = stream(layout);
if (layout == LayoutId::MeshInstance || s.vbo != BufferHandle::Invalid) return;
if (layout == LayoutId::ParticleInstance) {
// Per-instance (per-particle) stream: dynamic, streamed each frame.
s.vertex_staging.resize(initial_vertex_bytes_);
s.vbo_capacity = initial_vertex_bytes_;
s.vbo = device_.createBuffer({GfxBufferUsage::Vertex, s.vbo_capacity, /*dynamic=*/true},
GfxContent::transient(), nullptr);
// Static unit quad (pos + uv) and its 6 indices, uploaded once. UVs are laid out
// so the instance shader's a_texCoord*uvScale+uvOffset reproduces the prior
// per-corner particle UVs.
struct QuadV { f32 px, py, u, v; };
const QuadV quad[4] = {
{ -0.5f, -0.5f, 0.0f, 1.0f },
{ 0.5f, -0.5f, 1.0f, 1.0f },
{ 0.5f, 0.5f, 1.0f, 0.0f },
{ -0.5f, 0.5f, 0.0f, 0.0f },
};
const u32 quadIdx[6] = { 0, 1, 2, 2, 3, 0 };
s.quad_vbo = device_.createBuffer(
{GfxBufferUsage::Vertex, static_cast<u32>(sizeof(quad)), /*dynamic=*/false},
GfxContent::retained(), quad);
s.ebo = device_.createBuffer(
{GfxBufferUsage::Index, static_cast<u32>(sizeof(quadIdx)), /*dynamic=*/false},
GfxContent::retained(), quadIdx);
return;
}
s.vertex_staging.resize(initial_vertex_bytes_);
s.index_staging.resize(initial_index_count_);
s.vbo_capacity = initial_vertex_bytes_;
s.ebo_capacity = initial_index_count_;
s.vbo = device_.createBuffer({GfxBufferUsage::Vertex, s.vbo_capacity, /*dynamic=*/true},
GfxContent::transient(), nullptr);
s.ebo = device_.createBuffer(
{GfxBufferUsage::Index, static_cast<u32>(s.ebo_capacity * sizeof(u32)), /*dynamic=*/true},
GfxContent::transient(), nullptr);
}
void TransientBufferPool::setupStream(LayoutId layout) {
Stream& s = stream(layout);
if (layout == LayoutId::MeshInstance) {
// Only a stream, and not a vertex one: the frame's per-object records go
// in a texture, so a shader can reach any record by index rather than only
// the one the hardware happens to be on.
s.vertex_stride = MESH_INSTANCE_STRIDE;
s.texture_rows = 0;
return;
}
if (layout == LayoutId::ParticleInstance) {
// Slot 0: the static quad (per vertex). Slot 1: the instance stream (per instance),
// rebased per draw in bindInstanceLayout.
VertexLayoutDesc desc;
desc.attributeCount = 8;
desc.strides[0] = 16;
desc.strides[1] = 44;
desc.instanceStep[1] = true;
desc.attributes[0] = {0, 2, GfxDataType::Float, false, 0, 0};
desc.attributes[1] = {1, 2, GfxDataType::Float, false, 8, 0};
// The instance position carries all three axes: a particle simulated in
// depth and uploaded as a pair is drawn on the plane it left.
desc.attributes[2] = {2, 3, GfxDataType::Float, false, 0, 1};
desc.attributes[3] = {3, 2, GfxDataType::Float, false, 12, 1};
desc.attributes[4] = {4, 1, GfxDataType::Float, false, 20, 1};
desc.attributes[5] = {5, 4, GfxDataType::UnsignedByte, true, 24, 1};
desc.attributes[6] = {6, 2, GfxDataType::Float, false, 28, 1};
desc.attributes[7] = {7, 2, GfxDataType::Float, false, 36, 1};
s.vertex_stride = desc.strides[1];
s.layout = device_.createVertexLayout(desc);
return;
}
VertexLayoutDesc desc;
switch (layout) {
case LayoutId::Batch:
// BatchVertex: pos(12) + color(4) + uv(8) + texIndex(4) + sdfBias(4)
desc.attributeCount = 5;
desc.strides[0] = 32;
desc.attributes[0] = {0, 3, GfxDataType::Float, false, 0, 0};
desc.attributes[1] = {1, 4, GfxDataType::UnsignedByte, true, 12, 0};
desc.attributes[2] = {2, 2, GfxDataType::Float, false, 16, 0};
desc.attributes[3] = {3, 1, GfxDataType::Float, false, 24, 0};
desc.attributes[4] = {4, 1, GfxDataType::Float, false, 28, 0};
break;
case LayoutId::Shape:
desc.attributeCount = 4;
desc.strides[0] = 48;
desc.attributes[0] = {0, 2, GfxDataType::Float, false, 0, 0};
desc.attributes[1] = {1, 2, GfxDataType::Float, false, 8, 0};
desc.attributes[2] = {2, 4, GfxDataType::Float, false, 16, 0};
desc.attributes[3] = {3, 4, GfxDataType::Float, false, 32, 0};
break;
case LayoutId::Sky:
// One vec3 and nothing else: a layout may not declare an attribute its
// shader does not consume, which is why this is not the Batch one.
desc.attributeCount = 1;
desc.strides[0] = 12;
desc.attributes[0] = {0, 3, GfxDataType::Float, false, 0, 0};
break;
default:
break;
}
s.vertex_stride = desc.strides[0];
s.layout = device_.createVertexLayout(desc);
}
void TransientBufferPool::growVertexStaging(Stream& s, u32 requiredBytes) {
u32 newSize = static_cast<u32>(s.vertex_staging.size());
if (newSize == 0) newSize = 1024;
while (newSize < requiredBytes) {
newSize = newSize * 2;
}
s.vertex_staging.resize(newSize);
// Growing to fit a frame is what the pool is for, not a fault.
ES_LOG_DEBUG("TransientBufferPool: vertex staging grown to {}KB", newSize / 1024);
}
void TransientBufferPool::growIndexStaging(Stream& s, u32 requiredCount) {
u32 newSize = static_cast<u32>(s.index_staging.size());
if (newSize == 0) newSize = 1024;
while (newSize < requiredCount) {
newSize = newSize * 2;
}
s.index_staging.resize(newSize);
ES_LOG_DEBUG("TransientBufferPool: index staging grown to {} indices", newSize);
}
} // namespace esengine