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
#pragma once
#include "../../core/Types.hpp"
#include "./GfxDevice.hpp"
#include <vector>
#include <array>
namespace esengine {
// LayoutId / LAYOUT_COUNT now live in GfxEnums.hpp (a leaf header) so PipelineState can
// reference LayoutId without pulling in the GfxDevice include cycle.
/**
* Per-frame vertex/index staging with one independent VBO+EBO+vertex-layout per stream.
*
* Design note: heterogeneous vertex formats (BatchVertex 20B, ShapeVertex 48B,
* ...) cannot safely share a single VBO because each plugin computes
* `baseVertex = byteOffset / sizeof(OwnVertex)`. Once a prior plugin writes a
* non-multiple of the next plugin's vertex size, the next plugin's baseVertex
* truncates and the GPU reads garbage vertices. Giving each layout its own
* stream makes every offset "vertex 0" for that layout by construction — no
* alignment discipline needed at call sites, no cross-plugin coupling.
*/
class TransientBufferPool {
public:
explicit TransientBufferPool(GfxDevice& device);
/// The device the pool's buffers live on, for a plugin that keeps geometry of its own on it.
GfxDevice& device() { return device_; }
/** Initialize layouts; stream storage is allocated on its first non-empty write. */
void init(u32 initialVertexBytes = 2 * 1024 * 1024,
u32 initialIndexCount = 256 * 1024);
void shutdown();
void beginFrame();
u32 allocVertices(LayoutId layout, u32 byteSize);
u32 allocIndices(LayoutId layout, u32 count);
void writeVertices(LayoutId layout, u32 byteOffset, const void* data, u32 byteSize);
void writeIndices(LayoutId layout, u32 indexOffset, const u32* data, u32 count);
u32 appendVertices(LayoutId layout, const void* data, u32 byteSize);
u32 appendIndices(LayoutId layout, const u32* data, u32 count);
/** Copy a valid written range to the stream tail; false leaves the stream unchanged. */
bool copyIndexRange(LayoutId layout, u32 offset, u32 count, u32& copiedAt);
/** Upload every non-empty stream's staging to its VBO/EBO. */
void upload();
/** Bind this stream's vertex + index buffers for the next draw. */
void bindLayout(LayoutId layout);
/**
* Bind an instanced stream with its per-instance buffer rebased to @p instanceByteOffset.
* GLES3 has no baseInstance, so each emitter's instanced draw rebases the instance
* slot here before drawElementsInstanced. The static quad slot is untouched.
*/
void bindInstanceLayout(LayoutId layout, u32 instanceByteOffset);
/** The same layout with the per-instance slot taken from @p instances whole — records a compute kernel wrote. */
void bindInstanceBuffer(LayoutId layout, BufferHandle instances);
/** Creates a stream's static buffers (a particle's quad and indices) without writing to it: a draw whose records
* live elsewhere still needs them, and nothing else would ask. */
void reserveStream(LayoutId layout) { ensureStorage(layout); }
/** The device vertex layout a pipeline drawing this stream must reference. */
VertexLayoutHandle layoutHandle(LayoutId layout) const;
/** Byte stride of this stream's writable vertex slot (the per-instance slot for
* ParticleInstance) — the single source for baseVertex math, so submission code
* never hardcodes a sizeof that could drift from the device layout. */
u32 vertexStride(LayoutId layout) const;
/** Direct write-through pointer into a layout's staging, for hot paths
* that want to format vertices in place after `allocVertices`. */
u8* vertexData(LayoutId layout);
u32 vertexBytesUsed(LayoutId layout) const;
u32 indicesUsed(LayoutId layout) const;
const u32* indexData(LayoutId layout) const;
BufferHandle vertexBuffer(LayoutId layout) const;
BufferHandle indexBuffer(LayoutId layout) const;
/** @brief The frame's per-object records. Invalid until a frame writes some. */
TextureHandle instanceTexture() const { return stream(LayoutId::MeshInstance).texture; }
private:
struct Stream {
BufferHandle vbo = BufferHandle::Invalid; // for ParticleInstance: the per-instance (streamed) buffer
BufferHandle ebo = BufferHandle::Invalid;
VertexLayoutHandle layout = VertexLayoutHandle::Invalid;
BufferHandle quad_vbo = BufferHandle::Invalid; // ParticleInstance only: static unit-quad geometry (slot 0)
/// MeshInstance only: the frame's records live in a texture, because a
/// vertex attribute can only be read at the instance the hardware is on
/// and a record has to be reachable by index.
TextureHandle texture = TextureHandle::Invalid;
u32 texture_rows = 0; ///< Rows the texture currently holds.
std::vector<u8> vertex_staging;
std::vector<u32> index_staging; // 32-bit indices: a single Batch stream can exceed 65535 vertices
u32 vertex_stride = 0;
u32 vertex_write_pos = 0;
u32 index_write_pos = 0;
u32 vbo_capacity = 0;
u32 ebo_capacity = 0;
};
void setupStream(LayoutId layout);
void ensureStorage(LayoutId layout);
void uploadInstanceRows(Stream& s, u32& grows, u32& writes);
static constexpr u32 instanceRowBytes() { return MESH_INSTANCE_TEXTURE_WIDTH * 16; }
void growVertexStaging(Stream& s, u32 requiredBytes);
void growIndexStaging(Stream& s, u32 requiredCount);
Stream& stream(LayoutId layout);
const Stream& stream(LayoutId layout) const;
GfxDevice& device_;
std::array<Stream, LAYOUT_COUNT> streams_{};
u32 initial_vertex_bytes_ = 0;
u32 initial_index_count_ = 0;
bool initialized_ = false;
};
} // namespace esengine