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.

17.0 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
#pragma once

#include "../../core/Types.hpp"
#include "./DrawCommand.hpp"
#include "../rhi/GfxDevice.hpp"
#include "../rhi/TransientBufferPool.hpp"
#include "../frame/FrameCapture.hpp"
#include "../store/MorphConstants.hpp"
#include "../store/ProbeConstants.hpp"
#include "../store/InstanceConstants.hpp"
#include "../rhi/PerDrawBlocks.hpp"
#include "../../math/Math.hpp"

#include <algorithm>
#include <functional>
#include <string>
#include <utility>
#include <unordered_map>
#include <span>
#include <vector>

namespace esengine {

class MaterialStore;

class DrawList {
public:
    void clear();
    void push(const DrawCommand& cmd);

    // Sorts, then coalesces contiguous compatible commands — combining up to 8 textures
    // into one multi-texture batch and stamping each command's per-vertex sampler slot
    // (hence the pool, whose staging it rewrites; call before upload()).
    void finalize(TransientBufferPool& pool);

    /// How many of the frame's TOP texture units are screen-space light masks: one for
    /// the shadow mask, two when a light also carries a shape. Set BEFORE finalize (the
    /// merge spends slots) and reserved top-down, so a sampler's unit never moves.
    void reserveMask2DSlots(u32 count) { mask_2d_slots_ = std::min(count, MAX_CMD_TEXTURE_SLOTS); }

    /// The pass this list is about to execute into carries a second colour attachment, so the draws
    /// whose shaders write it say so in their pipelines. Set for the scene pass and cleared after:
    /// the same list is executed into other targets, which have no second output to take.
    void setGBufferPass(bool on) { gbuffer_pass_ = on; }

    /// A mask itself, which every draw then binds on its unit. Zero leaves the unit
    /// filled with white — "nothing shadows anything", and "the shape covers all".
    void setMask2DTexture(u32 unit, u32 textureId) {
        if (unit < MAX_CMD_TEXTURE_SLOTS) mask_2d_textures_[unit] = textureId;
    }

    // Each merged command resolves to an immutable pipeline (program + layout + blend +
    // depth + stencil + cull) bound via GfxDevice::setPipeline; per-draw dynamic state
    // (scissor, stencil ref, textures) is applied directly. Per-frame constants come from
    // the FrameConstants UBO bound by RenderContext; per-material constants from each
    // command's material UBO, bound here via MaterialStore::bindForDraw.
    // white_texture_id fills a Batch draw's unused sampler slots — a STABLE texture
    // so those slots stay pinned across draws and the bind cache dedups them
    // (filling with the draw's own tex re-pointed all 8 units on every tex change).
    /// Which of the list's draws an execute makes. A draw whose material reads the picture behind it (`u_sceneColor`) has to be
    /// made after a copy of that picture is taken, so the frame executes the list twice: the rest, then those.
    enum class Phase : u8 { All, WithoutSceneColor, SceneColorOnly, OpaqueOnly, BlendedOnly };
    /// What a run of the list is for. A depth prepass draws the opaque surfaces that have a depth program, into the depth buffer alone; the colour
    /// pass that follows (`ColorAfterPrepass`) draws those same surfaces where their depth is equal to what is there, so a pixel is shaded once, for
    /// the surface that is in front of it.
    enum class DrawPass : u8 { Color, DepthPrepass, ColorAfterPrepass };
    void execute(GfxDevice& device, TransientBufferPool& buffers,
                 MaterialStore& materials, u32 white_texture_id = 0,
                 FrameCapture* capture = nullptr,
                 const PerDrawBlockSet& blocks = {}, Phase phase = Phase::All, DrawPass pass = DrawPass::Color);

    /// Told, while a list executes, which shader the draws that follow use (and with nullptr that they are over): what lets a profiler time
    /// the scene a shader at a time. Empty costs nothing; a sink is installed only while someone is measuring.
    void setShaderRunSink(std::function<void(const char*)> sink) { shader_run_sink_ = std::move(sink); }

    /// How many merged draws the last execute left out because their program was not ready (GfxDevice::setSkipPendingPrograms).
    u32 skippedForProgram() const { return skipped_for_program_; }

    /// How many of the merged draws take part in a depth prepass; 0 means a prepass has nothing to draw.
    u32 depthPrepassDraws() const;

    /// Whether any merged draw reads the picture behind it.
    bool anyUsesSceneColor(const MaterialStore& materials) const;
    /** @brief Whether a draw is of a material that does not work without a picture of the scene (MaterialStore::needsScenePicture). */
    bool anyNeedsScenePicture(const MaterialStore& materials) const;
    /// Whether the list holds a blended draw that does not refract: what has to be ordered against a refracting surface by where it is, not by when it was drawn.
    bool anyBlendedWithoutSceneColor(const MaterialStore& materials) const;
    /// Whether any merged draw reads the distance to the opaque scene behind it.
    bool anyUsesSceneDepth(const MaterialStore& materials) const;

    /** Append one draw's bone matrices; returns where they start. Frame-scoped,
     *  like the vertex pool: a command references an offset, not a copy. */
    u32 addSkinMatrices(const glm::mat4* matrices, u32 count);
    const glm::mat4* skinMatrices() const { return skin_matrices_.data(); }

    /** Append one draw's shapes; returns 1 + where they sit, so that 0 stays
     *  available for "this draw is in the shape it was authored in". */
    u32 addMorphShapes(const MorphConstants& shapes);

    /** Append one draw's indirect light; returns 1 + where it sits, so that 0
     *  stays available for "no volume holds this draw". */
    u32 addProbe(const ProbeConstants& probe);
    u32 addPlanar(const PlanarConstants& value) { planar_.push_back(value); return static_cast<u32>(planar_.size()); }

    u32 commandCount() const { return static_cast<u32>(commands_.size()); }
    /** Entities by original submission type, independent of a merged run's head. */
    u32 sourceEntityCount(RenderType type) const {
        const auto index = static_cast<u32>(type);
        return index < entity_counts_.size() ? entity_counts_[index] : 0;
    }
    u32 mergedDrawCallCount() const { return merged_draw_calls_; }
    /** How many of the last finalize's draws started for @p reason. */
    u32 breakCount(BatchBreak reason) const { return breaks_[static_cast<u32>(reason)]; }
    /** How many submitted commands the last finalize folded into another. */
    u32 mergedAwayCount() const { return merged_away_; }
    /** The entities merged draw @p index was made from, in draw order. */
    std::span<const Entity> runEntities(u32 index) const;


    const DrawCommand* commands() const { return commands_.data(); }

    /**
     * @brief A hash of what the list draws: each command's program, geometry, state and ranges, and the bone matrices and
     *        shapes it carries. Folded into @p seed.
     *
     * @details Not the bytes of the instance records, which live in the pool (hash those beside it), and not what a material
     *          or a texture holds. Two lists with the same hash over the same pool draw the same pixels; read after finalize().
     */
    u64 contentHash(u64 seed) const;
    const DrawCommand& command(u32 index) const { return commands_[index]; }

    // Bit i set ⇒ layer i (0..31) sorts by world Y within the layer (top-down
    // occlusion) instead of material/depth. Lives here so pushBatchDraw — the one
    // key-building site — consults it for every render path uniformly.
    void setYSortMask(u32 mask) { ysort_mask_ = mask; }
    u32 ySortMask() const { return ysort_mask_; }

    // Bit i set ⇒ layer i (0..31) is painted in TREE order: its draws sort by where their entity stands in the hierarchy (a preorder walk,
    // children in their list order), whatever they are — a sprite, a label, a shape. That is how a scene of nodes is stacked in an authoring
    // tool that has no per-material or per-depth ordering, and it is the only order in which a panel can cover the text of the panel
    // beneath it: ordered by shader, every label would land above every image of the layer.
    void setTreeMask(u32 mask) { tree_mask_ = mask; }
    u32 treeMask() const { return tree_mask_; }
    /// The preorder position of each entity, by entity index. Rebuilt once per collect, only while a layer is tree-ordered.
    void setTreeSequence(std::vector<u32>&& sequence) { tree_sequence_ = std::move(sequence); }
    void clearTreeSequence() { tree_sequence_.clear(); }
    u32 treeSequenceOf(Entity entity) const {
        const u32 index = entity.index();
        return index < tree_sequence_.size() ? tree_sequence_[index] : 0u;
    }

    // Bit i set ⇒ layer i resolves its contents by real depth: opaque draws write
    // the depth buffer and sort front-to-back, blended ones test against it without
    // writing and stay in painter's order. This is the 2.5D opt-in.
    void setDepthMask(u32 mask) { depth_mask_ = mask; }
    u32 depthMask() const { return depth_mask_; }

    /**
     * @brief Whether a frame holding these draws has to be handed a depth buffer.
     *
     * @details Two things resolve by depth and they are ONE question: a layer the
     *          project declared depth-resolved, and a draw that declared it for
     *          ITSELF (an opaque mesh). A depth test with no attachment behind it
     *          PASSES, and opaque sorts front-to-back — the furthest paints last.
     */
    bool needsDepth() const { return depth_mask_ != 0 || depth_required_; }

    // Bit i set ⇒ the camera being rendered draws layer i. A camera property, not a
    // scene one, so it is set per camera (RenderFrame::begin clears the list each time).
    void setCullingMask(u32 mask) { culling_mask_ = mask; }
    u32 cullingMask() const { return culling_mask_; }

    /** @brief Whether a draw belonging to @p layerBit survives this camera's mask.
     *         Bit 0 means "no layer" (outside 0..31) and is visible to every camera. */
    bool layerVisible(u32 layerBit) const {
        return layerBit == 0 || (culling_mask_ & layerBit) != 0;
    }

    /** @brief The mask bit of a sorting layer, or 0 when it has none (outside 0..31). */
    static u32 layerBit(i32 layer) {
        return (layer < 0 || layer >= 32) ? 0u : (1u << layer);
    }

    /** @brief How one sorting layer resolves the draws inside it. */
    enum class LayerOrder : u8 { Painter, YSort, Depth, Tree };

    /**
     * @brief The one answer for @p layer, from two masks that are two spellings of
     *        the same question.
     *
     * @details Y-sort is a depth PROJECTED from world Y and depth is the real thing;
     *          a layer declaring both has said two contradictory things, and there is
     *          no order that satisfies them. Y-sort wins so that a project which had
     *          it before renders exactly as it did — the resolution belongs here, in
     *          one pure function, rather than in each caller's idea of precedence.
     *          Layers outside 0..31 have no bit and are therefore painter-ordered.
     */
    LayerOrder layerOrder(i32 layer) const {
        if (layer < 0 || layer >= 32) return LayerOrder::Painter;
        const u32 bit = 1u << layer;
        if (ysort_mask_ & bit) return LayerOrder::YSort;
        // Tree order is a stated painter's order and depth is a measured one; a layer saying both has asked for the stated one.
        if (tree_mask_ & bit) return LayerOrder::Tree;
        if (depth_mask_ & bit) return LayerOrder::Depth;
        return LayerOrder::Painter;
    }

    /** @brief The sorting identity a SortingGroup imposes on one of its members. */
    struct GroupIdentity {
        /// What the whole group presents outward — the key's top two fields.
        i32 layer = 0;
        i32 order = 0;
        /// Set when an INNER group stands between this draw and the outer one: the inner
        /// group is one block inside the outer, so every draw under it shares the inner
        /// group's order and stops separating by its own.
        bool blockOrder = false;
        i32 block = 0;
    };

    /** @brief Resolved once per collect, by the one walk that knows the hierarchy —
     *         the draw path only reads it, exactly as it reads ClipState. */
    void setSortingGroup(u32 entity, const GroupIdentity& identity) {
        group_identities_[entity] = identity;
    }
    void clearSortingGroups() { group_identities_.clear(); }

    /** @brief The group @p entity belongs to, or null when it sorts on its own. */
    const GroupIdentity* sortingGroupOf(u32 entity) const {
        if (group_identities_.empty()) return nullptr;
        auto it = group_identities_.find(entity);
        return it != group_identities_.end() ? &it->second : nullptr;
    }

    /** @brief Where a draw sits in the frame's order, once any group has had its say. */
    struct SortIdentity {
        i32 layer = 0;
        i32 order = 0;
        bool operator<(const SortIdentity& o) const {
            return layer != o.layer ? layer < o.layer : order < o.order;
        }
        bool operator<=(const SortIdentity& o) const { return !(o < *this); }
    };

    /** @brief The one answer to "where does this draw sit". Asked by the draw path when it
     *         builds a key, and by anything that must reason about that order BEFORE the
     *         keys exist — a second implementation is a second order. */
    SortIdentity sortIdentity(u32 entity, i32 ownLayer, i32 ownOrder) const {
        if (const GroupIdentity* g = sortingGroupOf(entity)) return {g->layer, g->order};
        return {ownLayer, ownOrder};
    }

private:
    std::function<void(const char*)> shader_run_sink_;
    u32 skipped_for_program_ = 0;
    struct SortEntry {
        u64 key;
        u32 index;
    };

    std::vector<DrawCommand> commands_;
    std::array<u32, static_cast<u32>(RenderType::Trail) + 1> entity_counts_{};
    /// Every skinned draw's bone matrices for this frame, indexed by skin_offset.
    std::vector<glm::mat4> skin_matrices_;
    std::vector<MorphConstants> morph_shapes_;
    std::vector<ProbeConstants> probes_;
    std::vector<PlanarConstants> planar_;
    /// One entry per INSTANCE of every merged run, in the order the run draws
    /// them: the merge is where an instance's probe is still known, and the
    /// texture is packed from this afterwards.
    std::vector<u32> probe_slots_;
    /// Every merged draw's source entities, one contiguous run per draw
    /// starting at run_first_[draw]: a run only ever grows at the list's end.
    std::vector<Entity> run_entities_;
    std::vector<u32> run_first_;
    /// One draw's run of coefficients, rebuilt per draw — reused so a frame of
    /// merged draws does not allocate per draw.
    std::vector<glm::vec4> probe_run_;
    /// Each merged draw's per-draw blocks, staged for the pass before it draws.
    struct StagedBlocks {
        PerDrawBlocks::Range skin, morph, probe, instance, planar;
    };
    std::vector<StagedBlocks> staged_;
    /// Per merged draw: how many draws the run it heads holds (drawn as one call, see stageBlocks), 0 for a draw inside a run.
    std::vector<u32> run_length_;
    std::vector<u32> run_counts_, run_offsets_, run_instances_;
    std::vector<InstanceConstants> run_entries_;
    /** Whether @p next can be drawn in the same call as @p prev: everything but its geometry's range and its records the same. */
    static bool joinsRun(const DrawCommand& prev, const DrawCommand& next);
    void stageBlocks(const PerDrawBlockSet& blocks, bool runs);
    /// The sorted order of the last finalize and the keys, in emit order, it was sorted from. The order is a function of the keys alone (ties break on
    /// emit index), and in 2D the key holds no position, so a frame of moving sprites has the keys of the frame before it.
    std::vector<SortEntry> sort_entries_;
    std::vector<u64> sorted_keys_;
    std::vector<DrawCommand> sorted_scratch_;  // reused across frames to avoid a
                                               // per-frame heap alloc in finalize()
    std::vector<DrawCommand> stencil_commands_scratch_;
    std::vector<DrawCommand> stencil_stack_scratch_;
    std::vector<u32> stencil_level_first_;
    bool ui_stencil_required_ = false;
    /// @see setMask2DTexture — indexed by texture unit, 0 where that unit is not a mask.
    u32 mask_2d_textures_[MAX_CMD_TEXTURE_SLOTS] = {};
    /// @see reserveMask2DSlots
    bool gbuffer_pass_ = false;
    u32 mask_2d_slots_ = 0;
    u32 merged_draw_calls_ = 0;
    u32 merged_away_ = 0;
    u32 breaks_[static_cast<u32>(BatchBreak::Count)] = {};
    /// Members of a SortingGroup, by entity id — empty in the common frame.
    std::unordered_map<u32, GroupIdentity> group_identities_;
    u32 ysort_mask_ = 0;
    u32 tree_mask_ = 0;
    std::vector<u32> tree_sequence_;
    u32 depth_mask_ = 0;
    /// Any command pushed this collect that tests or writes depth — see needsDepth.
    bool depth_required_ = false;
    u32 culling_mask_ = 0xFFFFFFFFu;  // every layer, until a camera says otherwise
};

}  // namespace esengine