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.

6.2 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    PerDrawBlocks.hpp
 * @brief   A uniform range per draw, so two draws never write into one block.
 *
 * @details A queue write lands where the pass is SUBMITTED, not where it was
 *          called, so a block shared between two draws is read by both with what
 *          the last wrote. Ranges are handed out per FRAME and not per pass: one
 *          submission stands behind a frame's several passes.
 *
 *          The ranges are carved from a few large pages rather than a buffer each,
 *          and a pass stages all of its draws' blocks before it uploads them once
 *          per page: creating a buffer costs the GPU process far more than writing
 *          one, and a first frame of eight thousand draws once spent half a minute
 *          creating them.
 */
#pragma once

#include "../../core/Types.hpp"
#include "./GfxDevice.hpp"

#include <algorithm>
#include <cstring>
#include <vector>

namespace esengine {

class PerDrawBlocks {
public:
    /** @brief Where one draw's block was staged; a default one binds the zero block. */
    struct Range {
        u32 page = NONE;
        u32 offset = 0;
    };

    /** @brief Claims the pool for blocks of @p blockSize bytes, plus the zero one. */
    void init(GfxDevice& device, u32 blockSize) {
        shutdown();
        device_ = &device;
        blockSize_ = blockSize;
        pageBytes_ = std::max(PAGE_BYTES, alignUp(blockSize));
        pages_.clear();
        page_ = 0;
        cursor_ = 0;
        used_ = 0;
        const std::vector<u8> zeros(blockSize, 0);
        zero_ = device.createBuffer({GfxBufferUsage::Uniform, blockSize, /*dynamic=*/false},
                                    GfxContent::retained(), zeros.data());
    }

    /** @brief Releases every page and the zero block while the device is alive. */
    void shutdown() {
        if (!device_) return;
        for (const Page& page : pages_) {
            if (page.buffer != BufferHandle::Invalid) device_->deleteBuffer(page.buffer);
        }
        if (zero_ != BufferHandle::Invalid) device_->deleteBuffer(zero_);
        pages_.clear();
        zero_ = BufferHandle::Invalid;
        device_ = nullptr;
        blockSize_ = pageBytes_ = cursor_ = used_ = 0;
        page_ = 0;
    }

    /** @brief Hands every range back. Called once per FRAME — see the file note. */
    void beginFrame() {
        page_ = 0;
        cursor_ = 0;
        used_ = 0;
    }

    /**
     * @brief Copies @p size bytes of @p bytes into a range of this frame's, to reach
     *        the GPU at the next upload(); a block it cannot hold stages nothing.
     *
     * @details The next range starts after the bytes staged: a draw reads only
     *          what it was given, so the rest of its binding may be the next
     *          draw's. Grows rather than wraps, which would share a range.
     */
    Range stage(const void* bytes, u32 size) {
        if (!device_ || !bytes || size == 0 || size > blockSize_) return {};
        if (page_ < pages_.size() && cursor_ + blockSize_ > pageBytes_) {
            ++page_;
            cursor_ = 0;
        }
        if (page_ == pages_.size()) {
            Page page;
            page.buffer = device_->createBuffer(
                {GfxBufferUsage::Uniform, pageBytes_, /*dynamic=*/true}, GfxContent::transient(),
                nullptr);
            page.bytes.assign(pageBytes_, 0);
            pages_.push_back(std::move(page));
        }
        Page& page = pages_[page_];
        std::memcpy(page.bytes.data() + cursor_, bytes, size);
        page.dirtyFrom = std::min(page.dirtyFrom, cursor_);
        page.dirtyTo = std::max(page.dirtyTo, cursor_ + size);
        const Range range{static_cast<u32>(page_), cursor_};
        cursor_ += alignUp(size);
        ++used_;
        return range;
    }

    /** @brief Sends what was staged since the last upload, one write per page. */
    void upload() {
        for (Page& page : pages_) {
            if (page.dirtyFrom >= page.dirtyTo) continue;
            device_->updateBuffer(page.buffer, page.dirtyFrom, page.bytes.data() + page.dirtyFrom,
                                  page.dirtyTo - page.dirtyFrom);
            page.dirtyFrom = NONE;
            page.dirtyTo = 0;
        }
    }

    /** @brief Binds @p range to @p slot — the zero block for a range staging refused. */
    void bind(u32 slot, Range range) const {
        if (!device_) return;
        if (range.page >= pages_.size()) {
            bindZero(slot);
            return;
        }
        device_->setUniformBuffer(slot, pages_[range.page].buffer, range.offset, blockSize_);
    }

    /** @brief Binds what a draw with nothing to say reads: zeroed once and never
     *         written, so "none" is an object rather than an erasure. */
    void bindZero(u32 slot) const {
        if (device_) device_->setUniformBuffer(slot, zero_);
    }

    /** @brief Ranges this frame has handed out — a per-frame cost, for the profile. */
    u32 used() const { return used_; }

private:
    static constexpr u32 NONE = 0xFFFFFFFFu;
    static constexpr u32 PAGE_BYTES = 128 * 1024;
    static u32 alignUp(u32 n) {
        return (n + GFX_UNIFORM_OFFSET_ALIGNMENT - 1) / GFX_UNIFORM_OFFSET_ALIGNMENT *
               GFX_UNIFORM_OFFSET_ALIGNMENT;
    }

    struct Page {
        BufferHandle buffer = BufferHandle::Invalid;
        std::vector<u8> bytes;
        u32 dirtyFrom = NONE;
        u32 dirtyTo = 0;
    };

    GfxDevice* device_ = nullptr;
    u32 blockSize_ = 0;
    u32 pageBytes_ = 0;
    std::vector<Page> pages_;
    usize page_ = 0;
    u32 cursor_ = 0;
    u32 used_ = 0;
    BufferHandle zero_ = BufferHandle::Invalid;
};

/**
 * @brief The uniform blocks a draw rewrites immediately before it.
 *
 * @details One parameter and not four: every caller passes the same set from the
 *          same owner, so a block added to the vocabulary reaches the draw loop
 *          without every call site having to learn its name.
 */
struct PerDrawBlockSet {
    PerDrawBlocks* skin = nullptr;
    PerDrawBlocks* morph = nullptr;
    PerDrawBlocks* probe = nullptr;
    PerDrawBlocks* instance = nullptr;
    PerDrawBlocks* planar = nullptr;
};

}  // namespace esengine