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.

11.2 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    BatchBuilder.hpp
 * @brief   The single submission face: the ONLY place a DrawCommand is assembled.
 * @details Every render path — the batch-quad plugins (sprite/UI/text), the dedicated
 *          streams (shape/particle/tilemap), and RenderFrame's spine/text/tile direct
 *          submits — describes its draw as a BatchDrawKey plus geometry, and this face
 *          does the rest: append vertices, offset indices by baseVertex, build the sort
 *          key, assemble the DrawCommand, apply clip state, push into the DrawList.
 *          Renderers only *generate* commands; sorting, merging, and GfxDevice submission
 *          live unified in DrawList. The invariant is CI-enforced
 *          (tools/check-draw-command-boundary.mjs): DrawCommand assembly outside this
 *          translation unit fails the build.
 *
 * @author  ESEngine Team
 * @date    2026
 *
 * @copyright Copyright (c) 2026 ESEngine Team
 *            Licensed under the Apache License, Version 2.0.
 */
#pragma once

// =============================================================================
// Includes
// =============================================================================

#include "../../core/Types.hpp"
#include "./BatchVertex.hpp"
#include "./BlendMode.hpp"
#include "./ClipState.hpp"
#include "./DrawCommand.hpp"
#include "./DrawList.hpp"
#include "./RenderItem.hpp"
#include "../frame/RenderStage.hpp"
#include "../rhi/TransientBufferPool.hpp"

#include <glm/glm.hpp>

namespace esengine {

// =============================================================================
// Shared quad geometry (single source of truth)
// =============================================================================

/** @brief Canonical centered unit-quad corner positions (CCW). */
inline constexpr glm::vec4 BATCH_QUAD_POSITIONS[4] = {
    { -0.5f, -0.5f, 0.0f, 1.0f },
    {  0.5f, -0.5f, 0.0f, 1.0f },
    {  0.5f,  0.5f, 0.0f, 1.0f },
    { -0.5f,  0.5f, 0.0f, 1.0f },
};

/** @brief Unit-quad texture coordinates matching BATCH_QUAD_POSITIONS. */
inline constexpr glm::vec2 BATCH_QUAD_TEX_COORDS[4] = {
    { 0.0f, 0.0f },
    { 1.0f, 0.0f },
    { 1.0f, 1.0f },
    { 0.0f, 1.0f },
};

/** @brief Canonical two-triangle quad winding shared by every batch path. */
inline constexpr u32 BATCH_QUAD_INDICES[6] = { 0, 1, 2, 2, 3, 0 };

/** @brief Rotates a point around @p center in the XY plane, carrying the center's z
 *         through untouched — the rotation a 2D renderer means is about z. */
inline glm::vec3 rotatePoint(const glm::vec3& center, f32 px, f32 py, f32 cosA, f32 sinA) {
    f32 dx = px - center.x;
    f32 dy = py - center.y;
    return { center.x + dx * cosA - dy * sinA,
             center.y + dx * sinA + dy * cosA,
             center.z };
}

// =============================================================================
// Batch submission
// =============================================================================

/** @brief Non-geometry attributes of a batch draw — everything needed to build the sort key + DrawCommand. */
struct BatchDrawKey {
    RenderStage stage = RenderStage::Transparent;
    i32 layer = 0;
    // Where this draw sits INSIDE its sorting layer; higher draws on top. Outranks depth
    // and y-sort alike, so it holds whatever ordering the layer was given. Clamped to
    // -128..127; 0 says nothing, leaving a renderable without such a field as it was.
    i32 order = 0;
    u32 shaderId = 0;
    // The program of the scene's depth prepass for this draw; 0 keeps it out of one. @see DrawCommand::depth_shader_id.
    u32 depthShaderId = 0;
    BlendMode blend = BlendMode::Normal;
    u32 textureId = 0;
    // A second sampler this draw needs for itself (a mesh's normal map), bound to
    // slot 1. Not the same thing as the Batch stream's extra slots, which are a
    // MERGE product chosen per vertex.
    u32 normalTextureId = 0;
    // The frame's shadow map, on the slot the injected Lit header samples. Per-draw
    // like the two above rather than a global unit: which draws receive a shadow is a
    // question the collect answers, and the device has no "bind for everyone" seam.
    u32 shadowTextureId = 0;
    // The frame environment's prefiltered reflection, one slot further on. Same
    // terms as the shadow map: per-draw, and only where a mesh vertex source asked.
    u32 envTextureId = 0;
    // How near the draw's anchor is to the viewer, larger = nearer —
    // CameraView::viewDepth, not a world coordinate. Only that orders blended draws
    // the way they composite once the camera has been turned off head-on.
    f32 depth = 0.0f;
    // World-space Y of the draw's anchor. Consumed only when the layer is y-sorted
    // (DrawList::ySortMask); layers outside 0..31 cannot y-sort.
    f32 y = 0.0f;
    // Mask bit of the layer this draw belongs to for camera culling; 0 derives it from
    // `layer`. UI sets it from its Canvas, whose `layer` is tree order, not membership.
    u32 cullBit = 0;
    Entity entity = INVALID_ENTITY;
    RenderType type = RenderType::Sprite;
    // Material handle + the render state resolved from it (defaults when materialId == 0).
    u32 materialId = 0;
    bool depthTest = false;
    bool depthWrite = true;
    u8 cull = 0;  ///< CullMode: 0 = none, 1 = back, 2 = front.
    i16 depthBias = 0;  ///< Depth-buffer units toward the eye. @see PipelineDesc.
    GfxTopology topology = GfxTopology::Triangles;  ///< How the indices assemble. @see PipelineDesc.
    // The transient stream this draw's geometry lives in. Only the Batch stream carries
    // a per-vertex texIndex, so only it participates in the multi-texture merge.
    LayoutId layoutId = LayoutId::Batch;
    // > 0 selects an instanced draw: indexCount indices drawn instanceCount times, with
    // per-instance attributes based at the vertex byte offset (see DrawCommand).
    u32 instanceCount = 0;
    // Bytes one instance record occupies. Needed to coalesce two such draws into
    // one: the merge relocates their records so they sit next to each other.
    u32 instanceStride = 0;
    // Instance records a compute kernel already wrote to the GPU (ParticleInstance layout): drawn from there instead
    // of from the stream, so the draw's vertexByteOffset means nothing.
    BufferHandle instanceBuffer = BufferHandle::Invalid;
    // Geometry the GPU already holds. Set together with a MeshInstance stream, whose
    // offset is the draw's vertexByteOffset: the mesh supplies the vertices and the
    // frame supplies only the transforms.
    BufferHandle vertexBuffer = BufferHandle::Invalid;
    BufferHandle indexBuffer = BufferHandle::Invalid;
    VertexLayoutHandle vertexLayout = VertexLayoutHandle::Invalid;

    // A skinned draw's pose, already in the frame's matrix pool. Passed through
    // like the buffers above: what deforms a draw is the draw's, not the batch's.
    u32 skinOffset = 0;
    u32 skinCount = 0;

    // The shapes this draw is blended towards: the block in the frame's pool
    // (1-based, 0 = none) and the mesh's own delta texture behind it.
    u32 morphIndex = 0;
    u32 morphTextureId = 0;
    /// The indirect light where this draw stands: 1 + its block in the frame's
    /// pool (0 = no volume holds it). Not part of the key — a volume does not
    /// change what program or buffer a draw needs, only what it reads.
    u32 probeIndex = 0;
    u32 planarIndex = 0;
    /// The baked atlas this draw reads, on the last slot a draw's own stream has.
    /// Part of the key and not only of the command: two objects sharing a mesh but
    /// baked into different atlases are two draws.
    u32 lightmapTextureId = 0;
    /// The frame's probe atlas, for a draw that reads its probe volume per pixel. On the lightmap's unit,
    /// which such a draw never needs: a draw reading a bake asks no volume for its light.
    u32 probeGridTextureId = 0;
};

/// Check before formatting caller-owned vertices, using the same group layer,
/// explicit camera bit and empty-scissor rules as batch submission.
bool batchEntityVisible(const DrawList& drawList, const ClipState& clips,
                        Entity entity, i32 layer, u32 cullBit = 0);

/**
 * @brief Atomic primitive: assemble + clip + push one DrawCommand for an index range ALREADY
 *        written into (or, for instanced draws, static in) the key's stream.
 * @details The single piece every render path used to duplicate. Use directly when the caller
 *          streams both vertices and indices in place, or for instanced draws over a static
 *          index range (the particle emitter's unit quad).
 */
void pushBatchDraw(DrawList& drawList, const ClipState& clips,
                   u32 vertexByteOffset, u32 vertexCount, u32 indexOffset, u32 indexCount,
                   const BatchDrawKey& key);

/**
 * @brief Pushes a DrawCommand for vertices ALREADY resident in the Batch stream at @p vertexByteOffset.
 * @details Offsets @p localIndices (0-based within the primitive) by the stream's baseVertex,
 *          appends them, then delegates to pushBatchDraw. Use when the caller formatted vertices
 *          in place via allocVertices()+vertexData() (the spine path). The u16/u32 overloads
 *          cover both index source widths.
 */
void pushBatchCommand(TransientBufferPool& pool, DrawList& drawList, const ClipState& clips,
                      u32 vertexByteOffset, u32 vertexCount, const u32* localIndices, u32 indexCount,
                      const BatchDrawKey& key);
void pushBatchCommand(TransientBufferPool& pool, DrawList& drawList, const ClipState& clips,
                      u32 vertexByteOffset, u32 vertexCount, const u16* localIndices, u32 indexCount,
                      const BatchDrawKey& key);

/**
 * @brief Copies raw vertices into the key's stream, then pushes one DrawCommand spanning them.
 * @details The layout-generic bulk form: @p verts must be @p vertexCount records of the
 *          stream's vertex stride (TransientBufferPool::vertexStride). This is the whole
 *          face a renderer with its own vertex format needs (shape today; any future
 *          trail/mesh2d stream).
 */
void appendIndexedDraw(TransientBufferPool& pool, DrawList& drawList, const ClipState& clips,
                       const void* verts, u32 vertexCount,
                       const u32* localIndices, u32 indexCount,
                       const BatchDrawKey& key);

/**
 * @brief Copies @p verts into the Batch stream, then pushes one DrawCommand spanning them.
 * @details Typed convenience over appendIndexedDraw for the shared BatchVertex format
 *          (tilemap chunk, single tile); the key must target the Batch stream.
 */
void appendIndexedBatch(TransientBufferPool& pool, DrawList& drawList, const ClipState& clips,
                        const BatchVertex* verts, u32 vertexCount,
                        const u32* localIndices, u32 indexCount,
                        const BatchDrawKey& key);

/** @brief Convenience for a single 4-vertex quad with the canonical 6-index winding. */
inline void appendQuad(TransientBufferPool& pool, DrawList& drawList, const ClipState& clips,
                       const BatchVertex quad[4], const BatchDrawKey& key) {
    appendIndexedBatch(pool, drawList, clips, quad, 4, BATCH_QUAD_INDICES, 6, key);
}

}  // namespace esengine