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 "./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