Skip to content

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.

16.6 KB
Raw Blame
// 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