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.

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