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.

10.0 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    ImmediateDraw.hpp
 * @brief   Immediate mode 2D drawing API
 * @details Provides simple, immediate mode drawing primitives (lines, rectangles,
 *          circles, polygons) with automatic batching for efficient rendering.
 *          All draw commands are cleared each frame.
 *
 *          Backed by the same TransientBufferPool + GfxDevice pipeline machinery
 *          as RenderFrame — there is no separate batch renderer.
 *
 * @author  ESEngine Team
 * @date    2026
 *
 * @copyright Copyright (c) 2026 ESEngine Team
 *            Licensed under the Apache License, Version 2.0.
 */
#pragma once

#include "../../core/Types.hpp"
#include "../../math/Math.hpp"
#include "../../resource/Handle.hpp"
#include "../rhi/PipelineState.hpp"
#include "../rhi/TransientBufferPool.hpp"

#include <glm/glm.hpp>
#include <vector>
#include <span>

namespace esengine {

class GfxDevice;
class RenderContext;

namespace resource {
    class ResourceManager;
}

/**
 * @brief Immediate mode 2D drawing API
 *
 * @details Provides a simple API for drawing 2D primitives. All commands
 *          submitted between begin() and end() are batched (per texture) and
 *          drawn in submission order. The buffer is cleared each frame.
 *
 * @code
 * ImmediateDraw draw(device, state, context, resourceManager);
 * draw.init();
 *
 * draw.begin(viewProjection);
 * draw.line({0, 0}, {100, 100}, {1, 0, 0, 1});
 * draw.rect({50, 50}, {30, 30}, {0, 1, 0, 1});
 * draw.circle({150, 150}, 25, {0, 0, 1, 1});
 * draw.end();
 * @endcode
 */
class ImmediateDraw {
public:
    /**
     * @brief Constructs an immediate draw instance
     * @param device  Graphics device (GPU command sink)
     * @param context Render context for shared resources (white texture)
     * @param resource_manager Resource manager for shader access
     */
    ImmediateDraw(GfxDevice& device, RenderContext& context,
                  resource::ResourceManager& resource_manager);
    ~ImmediateDraw();

    ImmediateDraw(const ImmediateDraw&) = delete;
    ImmediateDraw& operator=(const ImmediateDraw&) = delete;

    // =========================================================================
    // Lifecycle
    // =========================================================================

    void init();

    void shutdown();

    // =========================================================================
    // Frame Management
    // =========================================================================

    /** @brief Begins a new draw frame */
    void begin(const glm::mat4& viewProjection, i32 viewportWidth = 0, i32 viewportHeight = 0);

    /** @brief Ends the frame and submits all draw commands */
    void end();

    /** Close collection now and submit it when the owning scene pass executes. */
    void deferEnd();

    /** Submit a collection closed by deferEnd inside the active render pass. */
    void flushDeferred();

    /**
     * @brief Flushes pending draw commands without ending the frame
     * @details Use before operations that change GL state to ensure accumulated
     *          primitives are rendered with the correct state.
     */
    void flush();

    // =========================================================================
    // Line Drawing
    // =========================================================================

    void line(const glm::vec2& from, const glm::vec2& to,
              const glm::vec4& color, f32 thickness = 1.0f);

    /**
     * @brief A line between two points in SPACE, widened across the view.
     * @details Widened along `cross(direction, view forward)` rather than in a
     *          plane, so it reads as a line from wherever the camera is.
     *          Thickness is in WORLD units, so a distant line thins out with the
     *          geometry beside it.
     */
    void line3D(const glm::vec3& from, const glm::vec3& to,
                const glm::vec4& color, f32 thickness = 1.0f);

    /** A world-space line with an explicit framebuffer-pixel thickness. */
    void line3DScreen(const glm::vec3& from, const glm::vec3& to,
                      const glm::vec4& color, f32 thickness = 1.0f);

    /**
     * @brief A framebuffer-sized line attached to one world-space anchor.
     * @details Offsets use framebuffer pixels (+X right, +Y up). The anchor is
     *          projected through the active draw frame, so editor handles keep a
     *          stable size without sampling a second camera.
     */
    void line3DScreenOffset(const glm::vec3& anchor,
                            const glm::vec2& fromOffset,
                            const glm::vec2& toOffset,
                            const glm::vec4& color, f32 thickness = 1.0f);

    void polyline(std::span<const glm::vec2> vertices, const glm::vec4& color,
                  f32 thickness = 1.0f, bool closed = false);

    // =========================================================================
    // Rectangle Drawing
    // =========================================================================

    void rect(const glm::vec2& position, const glm::vec2& size,
              const glm::vec4& color, bool filled = true);

    void rectOutline(const glm::vec2& position, const glm::vec2& size,
                     const glm::vec4& color, f32 thickness = 1.0f);

    // =========================================================================
    // Circle Drawing
    // =========================================================================

    void circle(const glm::vec2& center, f32 radius,
                const glm::vec4& color, bool filled = true, i32 segments = 32);

    void circleOutline(const glm::vec2& center, f32 radius,
                       const glm::vec4& color, f32 thickness = 1.0f, i32 segments = 32);

    // =========================================================================
    // Polygon Drawing
    // =========================================================================

    void polygon(std::span<const glm::vec2> vertices, const glm::vec4& color);

    // =========================================================================
    // Texture Drawing
    // =========================================================================

    void texture(const glm::vec2& position, const glm::vec2& size,
                 u32 textureId, const glm::vec4& tint = glm::vec4(1.0f));

    void textureRotated(const glm::vec2& position, const glm::vec2& size,
                        f32 rotation, u32 textureId,
                        const glm::vec4& tint = glm::vec4(1.0f));

    // =========================================================================
    // Configuration
    // =========================================================================

    void setLayer(i32 layer) { currentLayer_ = layer; }
    i32 getLayer() const { return currentLayer_; }
    void setDepth(f32 depth) { currentDepth_ = depth; }
    f32 getDepth() const { return currentDepth_; }

    /** Switches the blend mode for subsequent primitives (flushes pending geometry). */
    void setBlendMode(BlendMode mode);
    /** Toggles depth testing for subsequent primitives (flushes pending geometry). */
    void setDepthTest(bool enabled);
    /** Changes depth testing and writes together, flushing the previous batch. */
    void setDepthState(bool test, bool write);
    BlendMode blendMode() const { return current_desc_.blend; }
    bool depthTest() const { return current_desc_.depthTest; }
    bool depthWrite() const { return current_desc_.depthWrite; }
    /** Collects all following primitive batches for the owning scene pass. */
    void deferBegin() { recording_ = true; }

    // =========================================================================
    // Statistics
    // =========================================================================

    u32 getDrawCallCount() const { return drawCallCount_; }
    u32 getPrimitiveCount() const { return primitiveCount_; }

private:
    /** Emits a (optionally rotated) textured quad into the current batch. */
    void emitQuad(const glm::vec2& center, const glm::vec2& size, f32 rotation,
                  const glm::vec4& color, u32 textureId,
                  const glm::vec2& uvOffset = glm::vec2(0.0f),
                  const glm::vec2& uvScale = glm::vec2(1.0f));
    /** Emits a flat triangle (white texture) into the current batch. */
    void emitTriangle(const glm::vec2& p0, const glm::vec2& p1, const glm::vec2& p2,
                      const glm::vec4& color);
    /** Switches the batch texture, flushing first if it changed. */
    void useTexture(u32 textureId);

    GfxDevice& device_;
    RenderContext& context_;
    resource::ResourceManager& resource_manager_;

    TransientBufferPool pool_;
    /// The handle is the identity; batch_shader_ caches the program id it
    /// currently resolves to, re-read when the device rebuilds the program.
    resource::ShaderHandle batch_shader_ref_;
    ShaderHandle batch_shader_ = ShaderHandle::Invalid;
    PipelineDesc base_desc_{};
    PipelineDesc current_desc_{};
    PipelineHandle pipeline_ = PipelineHandle::Invalid;
    u32 white_texture_id_ = 0;
    u32 currentTexture_ = 0;
    bool pendingGeometry_ = false;
    bool deferredGeometry_ = false;
    struct DeferredBatch {
        PipelineHandle pipeline;
        u32 texture;
        u32 firstIndex;
        u32 indexCount;
    };
    std::vector<DeferredBatch> deferredBatches_;
    u32 recordedIndices_ = 0;
    bool recording_ = false;

    /// Where the camera looks, from the view-projection this frame began with —
    /// what a 3D line is widened across.
    glm::vec3 viewForward_{0.0f, 0.0f, -1.0f};
    /// Canonical (OpenGL-depth) lens for cutting 3D lines before ribbon expansion.
    glm::mat4 viewProjection_{1.0f};
    glm::mat4 inverseViewProjection_{1.0f};
    f32 viewportWidth_ = 1.0f;
    f32 viewportHeight_ = 1.0f;

    i32 currentLayer_ = 0;
    f32 currentDepth_ = 0.0f;
    u32 primitiveCount_ = 0;
    u32 drawCallCount_ = 0;
    bool initialized_ = false;
    bool inFrame_ = false;
};

}  // namespace esengine