Extra2D/include/renderer/rhi/rhi_command_list.h

#pragma once

#include <renderer/rhi/rhi_types.h>
#include <renderer/rhi/rhi_buffer.h>
#include <renderer/rhi/rhi_shader.h>
#include <renderer/rhi/rhi_framebuffer.h>

namespace extra2d {

/**
 * @brief RHI 命令列表接口
 *
 * 抽象 GPU 命令录制和执行
 */
class RHICommandList {
public:
    virtual ~RHICommandList() = default;

    //===========================================================================
    // 命令列表生命周期
    //===========================================================================

    /**
     * @brief 开始录制命令
     */
    virtual void begin() = 0;

    /**
     * @brief 结束录制命令
     */
    virtual void end() = 0;

    /**
     * @brief 提交命令到 GPU
     */
    virtual void submit() = 0;

    //===========================================================================
    // 渲染通道
    //===========================================================================

    /**
     * @brief 开始渲染通道
     * @param framebuffer 帧缓冲
     * @param clearFlags 清除标志
     * @param clearColor 清除颜色（当包含 Color 标志时）
     * @param clearDepth 清除深度值（当包含 Depth 标志时）
     * @param clearStencil 清除模板值（当包含 Stencil 标志时）
     */
    virtual void beginRenderPass(RHIFramebuffer* framebuffer,
                                  ClearFlags clearFlags = ClearFlags::Color,
                                  const Color& clearColor = Color::Black,
                                  float clearDepth = 1.0f,
                                  uint8_t clearStencil = 0) = 0;

    /**
     * @brief 结束渲染通道
     */
    virtual void endRenderPass() = 0;

    //===========================================================================
    // 状态设置
    //===========================================================================

    /**
     * @brief 设置视口
     * @param viewport 视口
     */
    virtual void setViewport(const Viewport& viewport) = 0;

    /**
     * @brief 设置裁剪矩形
     * @param scissor 裁剪矩形
     */
    virtual void setScissor(const ScissorRect& scissor) = 0;

    /**
     * @brief 设置图形管线
     * @param pipeline 管线
     */
    virtual void setPipeline(RHIPipeline* pipeline) = 0;

    //===========================================================================
    // 资源绑定
    //===========================================================================

    /**
     * @brief 设置顶点缓冲区
     * @param slot 槽位
     * @param buffer 缓冲区
     * @param offset 偏移（字节）
     * @param stride 步长（字节，0表示使用布局中的步长）
     */
    virtual void setVertexBuffer(uint32_t slot, RHIBuffer* buffer, uint32_t offset = 0, uint32_t stride = 0) = 0;

    /**
     * @brief 设置索引缓冲区
     * @param buffer 缓冲区
     * @param type 索引类型
     * @param offset 偏移（字节）
     */
    virtual void setIndexBuffer(RHIBuffer* buffer, IndexType type, uint32_t offset = 0) = 0;

    /**
     * @brief 设置 Uniform 缓冲区
     * @param slot 槽位
     * @param buffer 缓冲区
     */
    virtual void setUniformBuffer(uint32_t slot, RHIBuffer* buffer) = 0;

    /**
     * @brief 设置 Uniform 缓冲区（带偏移）
     * @param slot 槽位
     * @param buffer 缓冲区
     * @param offset 缓冲区偏移（字节）
     * @param size 绑定大小（字节，0 表示整个缓冲区）
     */
    virtual void setUniformBuffer(uint32_t slot, RHIBuffer* buffer, uint32_t offset, uint32_t size = 0) = 0;

    /**
     * @brief 设置纹理
     * @param slot 槽位
     * @param texture 纹理
     */
    virtual void setTexture(uint32_t slot, RHITexture* texture) = 0;

    /**
     * @brief 设置采样器
     * @param slot 槽位
     * @param minFilter 最小过滤
     * @param magFilter 最大过滤
     * @param wrapS S 轴环绕
     * @param wrapT T 轴环绕
     */
    virtual void setSampler(uint32_t slot,
                            TextureFilter minFilter,
                            TextureFilter magFilter,
                            TextureWrap wrapS,
                            TextureWrap wrapT) = 0;

    /**
     * @brief 设置 float 类型的 uniform 变量
     * @param name 变量名
     * @param value 值
     */
    virtual void setUniform(const char* name, float value) = 0;

    /**
     * @brief 设置 vec2 类型的 uniform 变量
     * @param name 变量名
     * @param value 值
     */
    virtual void setUniform(const char* name, const Vec2& value) = 0;

    /**
     * @brief 设置 vec3 类型的 uniform 变量
     * @param name 变量名
     * @param value 值
     */
    virtual void setUniform(const char* name, const Vec3& value) = 0;

    /**
     * @brief 设置 vec4/Color 类型的 uniform 变量
     * @param name 变量名
     * @param value 值
     */
    virtual void setUniform(const char* name, const Color& value) = 0;

    /**
     * @brief 设置 mat4 类型的 uniform 变量
     * @param name 变量名
     * @param value 值
     */
    virtual void setUniform(const char* name, const Mat4& value) = 0;

    //===========================================================================
    // 绘制命令
    //===========================================================================

    /**
     * @brief 绘制顶点
     * @param vertexCount 顶点数量
     * @param firstVertex 起始顶点
     * @param instanceCount 实例数量
     * @param firstInstance 起始实例
     */
    virtual void draw(uint32_t vertexCount,
                      uint32_t firstVertex = 0,
                      uint32_t instanceCount = 1,
                      uint32_t firstInstance = 0) = 0;

    /**
     * @brief 绘制索引
     * @param indexCount 索引数量
     * @param firstIndex 起始索引
     * @param vertexOffset 顶点偏移
     * @param instanceCount 实例数量
     * @param firstInstance 起始实例
     */
    virtual void drawIndexed(uint32_t indexCount,
                             uint32_t firstIndex = 0,
                             int32_t vertexOffset = 0,
                             uint32_t instanceCount = 1,
                             uint32_t firstInstance = 0) = 0;

    //===========================================================================
    // 工具方法
    //===========================================================================

    /**
     * @brief 清除当前帧缓冲
     * @param flags 清除标志
     * @param color 清除颜色
     * @param depth 清除深度值
     * @param stencil 清除模板值
     */
    virtual void clear(ClearFlags flags,
                       const Color& color = Color::Black,
                       float depth = 1.0f,
                       uint8_t stencil = 0) = 0;

    /**
     * @brief 检查是否在录制状态
     * @return 是否在录制
     */
    virtual bool isRecording() const = 0;
};

} // namespace extra2d