Merge pull request #14 from indevn/main

TBR Pipeline Implementation & Pipeline Optimization

Author: ZzzhHe

README-cn.md

@@ -85,7 +85,7 @@ cmake --build build-macos --target all
 #### 3. 运行示例应用程序
 
 ```bash
-./build/bin/system_test ../obj
+./build/bin/system_test ./obj
 ```
 
 ---

README.md

@@ -86,7 +86,7 @@ cmake --build build-macos --target all
 #### 3. Run the Example Application
 
 ```bash
-./build/bin/system_test ../obj
+./build/bin/system_test ./obj
 ```
 
 ---

src/include/face.hpp

@@ -40,7 +40,7 @@ class Face {
   // Get functions
   // 获取函数
   inline const std::array<size_t, 3>& GetIndices() const { return indices_; }
-  inline const size_t GetIndex(size_t index) const { return indices_[index]; }
+  inline size_t GetIndex(size_t index) const { return indices_[index]; }
   inline const Material& GetMaterial() const { return material_; }
 
  private:

src/include/log_system.h

@@ -17,6 +17,9 @@
 #ifndef SIMPLERENDER_SRC_INCLUDE_LOG_SYSTEM_H_
 #define SIMPLERENDER_SRC_INCLUDE_LOG_SYSTEM_H_
 
+#ifndef SPDLOG_ACTIVE_LEVEL
+#define SPDLOG_ACTIVE_LEVEL SPDLOG_LEVEL_INFO
+#endif
 #include <spdlog/spdlog.h>
 
 namespace simple_renderer {

src/include/rasterizer.hpp

@@ -3,6 +3,7 @@
 
 #include "config.h"
 #include "shader.hpp"
+#include "vertex.hpp"
 
 namespace simple_renderer {
 
@@ -15,21 +16,80 @@ class Rasterizer {
   auto operator=(Rasterizer&& rasterizer) -> Rasterizer& = default;
   ~Rasterizer() = default;
 
+  /**
+   * @brief 构造具有指定尺寸的光栅化器
+   * @param width 光栅化器宽度
+   * @param height 光栅化器高度
+   */
   Rasterizer(size_t width, size_t height);
 
+  /**
+   * @brief 光栅化三角形，生成片段列表
+   * @param v0 三角形第一个顶点
+   * @param v1 三角形第二个顶点
+   * @param v2 三角形第三个顶点
+   * @return 生成的片段向量
+   */
   std::vector<Fragment> Rasterize(const Vertex& v0, const Vertex& v1,
                                   const Vertex& v2);
 
+  /**
+   * @brief 非分配版本：将片段直接写入调用方提供的容器
+   * 
+   * 可选的裁剪区域为半开区间 [x0, x1) × [y0, y1)
+   * 用于 TBR：将光栅化限制在 tile 边界内，便于复用外部 scratch 容器
+   * 
+   * @param v0 三角形第一个顶点
+   * @param v1 三角形第二个顶点
+   * @param v2 三角形第三个顶点
+   * @param x0 裁剪区域左边界（包含）
+   * @param y0 裁剪区域上边界（包含）
+   * @param x1 裁剪区域右边界（不包含）
+   * @param y1 裁剪区域下边界（不包含）
+   * @param out 输出片段容器
+   */
+  void RasterizeTo(const Vertex& v0, const Vertex& v1, const Vertex& v2,
+                   int x0, int y0, int x1, int y1,
+                   std::vector<Fragment>& out);
+
+  /**
+   * @brief SoA 版本：按顶点索引从 SoA 读取三角形三顶点
+   * @param soa 结构体数组格式的顶点数据
+   * @param i0 三角形第一个顶点索引
+   * @param i1 三角形第二个顶点索引
+   * @param i2 三角形第三个顶点索引
+   * @param x0 裁剪区域左边界（包含）
+   * @param y0 裁剪区域上边界（包含）
+   * @param x1 裁剪区域右边界（不包含）
+   * @param y1 裁剪区域下边界（不包含）
+   * @param out 输出片段容器
+   */
+  void RasterizeTo(const VertexSoA& soa, size_t i0, size_t i1, size_t i2,
+                   int x0, int y0, int x1, int y1,
+                   std::vector<Fragment>& out);
+
  private:
   size_t width_, height_;
 
+  // 透视矫正结果
+  struct PerspectiveCorrectionResult {
+    Vector3f corrected_barycentric;
+    float interpolated_z;
+  };
+
+  // 透视矫正helper函数
+  PerspectiveCorrectionResult PerformPerspectiveCorrection(
+      float w0, float w1, float w2,
+      float z0, float z1, float z2,
+      const Vector3f& original_barycentric) const;
+
   template <typename T>
   T Interpolate(const T& v0, const T& v1, const T& v2,
-                const Vector3f& barycentric_coord);
+                const Vector3f& barycentric_coord) const;
 
   Color InterpolateColor(const Color& color0, const Color& color1,
                          const Color& color2,
-                         const Vector3f& barycentric_coord);
+                         const Vector3f& barycentric_coord) const;
 
   std::pair<bool, Vector3f> GetBarycentricCoord(const Vector3f& p0,
                                                 const Vector3f& p1,

src/include/renderer.h

@@ -18,57 +18,95 @@
 #define SIMPLERENDER_SRC_INCLUDE_RENDERER_H_
 
 #include <cstdint>
-#include <functional>
-#include <span>
+#include <memory>
+#include <string>
 
-#include "buffer.hpp"
-#include "light.h"
 #include "log_system.h"
-#include "math.hpp"
 #include "model.hpp"
-#include "rasterizer.hpp"
 #include "shader.hpp"
+#include "renderers/renderer_base.hpp"
 
 namespace simple_renderer {
 
+// 渲染模式枚举
+/**
+ * @brief 渲染模式
+ * - PER_TRIANGLE: 逐三角形（triangle-major）前向渲染
+ * - TILE_BASED: 基于 tile（tile-major）前向渲染
+ * - DEFERRED: 延迟渲染（片段收集后再着色）
+ */
+enum class RenderingMode {
+  PER_TRIANGLE,  //!< 逐三角形（triangle-major）
+  TILE_BASED,    //!< 基于 tile（tile-major）
+  DEFERRED       //!< 延迟渲染
+};
+
+/**
+ * @brief 将渲染模式枚举转为可读字符串
+ * @param mode 渲染模式
+ * @return 可读字符串（PER_TRIANGLE/TILE_BASED/DEFERRED）
+ */
+std::string RenderingModeToString(RenderingMode mode);
+
+/**
+ * @brief 渲染门面（Facade）
+ *
+ * 职责：
+ * - 仅作为模式选择与调用入口；
+ * - 根据 `RenderingMode` 构造并持有具体渲染器；
+ * - 对外暴露统一的 `DrawModel` 接口。
+ */
 class SimpleRenderer {
  public:
   /**
-   * 构造函数
-   * @param width
-   * @param height
-   * @param buffer 要进行绘制的内存区域，大小为 width*height*sizeof(uint32_t)
-   * @param
+   * @brief 构造渲染器门面
+   * @param width 画布宽度（像素）
+   * @param height 画布高度（像素）
    */
   SimpleRenderer(size_t width, size_t height);
+  ~SimpleRenderer() = default;
 
-  /// @name 默认构造/析构函数
-  /// @{
-  SimpleRenderer(const SimpleRenderer &_simplerenderer) = default;
-  SimpleRenderer(SimpleRenderer &&_simplerenderer) = default;
-  auto operator=(const SimpleRenderer &_simplerenderer) -> SimpleRenderer & =
-                                                               default;
-  auto operator=(SimpleRenderer &&_simplerenderer) -> SimpleRenderer & =
-                                                          default;
-  virtual ~SimpleRenderer() = default;
-  /// @}
+  /**
+   * @brief 绘制单个模型
+   * @param model 模型
+   * @param shader 着色器（含 uniform）
+   * @param buffer 输出颜色缓冲（width*height）
+   * @return 是否成功
+   */
+  bool DrawModel(const Model &model, const Shader &shader, uint32_t *buffer);
 
-  bool Render(const Model &model, const Shader &shader, uint32_t *buffer);
+  /**
+   * @brief 设置渲染模式
+   */
+  void SetRenderingMode(RenderingMode mode);
+  /**
+   * @brief 获取当前渲染模式
+   */
+  RenderingMode GetRenderingMode() const;
+
+  // 可选：配置参数（仅对 TileBasedRenderer 生效；运行中修改将重建 TBR 实例）
+  /**
+   * @brief 启用或禁用 Early‑Z（仅 TBR 有效）
+   */
+  void SetEarlyZEnabled(bool enabled);
+  /**
+   * @brief 设置 Tile 大小（仅 TBR 有效）
+   */
+  void SetTileSize(size_t tile_size);
+
+ private:
+  void EnsureRenderer();
 
  private:
   const size_t height_;
   const size_t width_;
   LogSystem log_system_;
+  RenderingMode current_mode_;
+  std::unique_ptr<RendererBase> renderer_;
 
-  std::shared_ptr<Shader> shader_;
-  std::shared_ptr<Rasterizer> rasterizer_;
-
-  /**
-   * 绘制模型
-   * @param model 模型
-   */
-  void DrawModel(const Model &model, uint32_t *buffer);
-  void DrawModelSlower(const Model &model, uint32_t *buffer);
+  // TBR 配置缓存：在创建 TileBasedRenderer 时下发
+  bool tbr_early_z_ = true;
+  size_t tbr_tile_size_ = 64;
 };
 }  // namespace simple_renderer
 

src/include/renderers/deferred_renderer.hpp

@@ -0,0 +1,31 @@
+#ifndef SIMPLERENDER_SRC_INCLUDE_RENDERERS_DEFERRED_RENDERER_HPP_
+#define SIMPLERENDER_SRC_INCLUDE_RENDERERS_DEFERRED_RENDERER_HPP_
+
+#include "renderers/renderer_base.hpp"
+
+namespace simple_renderer {
+
+/**
+ * @brief 延迟渲染器（Deferred）
+ * 
+ * 组织处理方式模拟 OpenGL 在 GPU上的工作原理，模仿 GPU管线。
+ * 但相比于另外两个前向渲染实现，导致内存使用增加和渲染速度变慢。
+ * 
+ * 特点：
+ * - AoS 顶点路径；
+ * - 首先按像素收集所有片段并选择最近深度；
+ * - 再对选择的片段执行片段着色（模拟经典 GPU 管线的一种教学实现）。
+ * - 
+ */
+class DeferredRenderer final : public RendererBase {
+ public:
+  using RendererBase::RendererBase;
+  /**
+   * @copydoc RendererBase::Render
+   */
+  bool Render(const Model& model, const Shader& shader, uint32_t* out_color) override;
+};
+
+}  // namespace simple_renderer
+
+#endif  // SIMPLERENDER_SRC_INCLUDE_RENDERERS_DEFERRED_RENDERER_HPP_

src/include/renderers/per_triangle_renderer.hpp

@@ -0,0 +1,28 @@
+#ifndef SIMPLERENDER_SRC_INCLUDE_RENDERERS_PER_TRIANGLE_RENDERER_HPP_
+#define SIMPLERENDER_SRC_INCLUDE_RENDERERS_PER_TRIANGLE_RENDERER_HPP_
+
+#include "renderers/renderer_base.hpp"
+
+namespace simple_renderer {
+
+/**
+ * @brief 逐三角形渲染器（Triangle‑Major）
+ *
+ * 特点：
+ * - AoS 顶点路径；
+ * - 每线程本地 framebuffer（depth/color）合并；
+ * - 背面剔除在屏幕空间完成；
+ * - 接近“传统”栈式前向渲染教学实现。
+ */
+class PerTriangleRenderer final : public RendererBase {
+ public:
+  using RendererBase::RendererBase;
+  /**
+   * @copydoc RendererBase::Render
+   */
+  bool Render(const Model& model, const Shader& shader, uint32_t* out_color) override;
+};
+
+}  // namespace simple_renderer
+
+#endif  // SIMPLERENDER_SRC_INCLUDE_RENDERERS_PER_TRIANGLE_RENDERER_HPP_

src/include/renderers/renderer_base.hpp

@@ -0,0 +1,66 @@
+// Renderer base and options
+#ifndef SIMPLERENDER_SRC_INCLUDE_RENDERERS_RENDERER_BASE_HPP_
+#define SIMPLERENDER_SRC_INCLUDE_RENDERERS_RENDERER_BASE_HPP_
+
+#include <cstdint>
+#include <memory>
+
+#include "rasterizer.hpp"
+#include "vertex.hpp"
+#include "model.hpp"
+#include "shader.hpp"
+
+namespace simple_renderer {
+
+
+/**
+ * @brief 渲染器抽象基类
+ *
+ * 约定：
+ * - Render 负责完成完整的渲染过程（顶点变换 + 光栅化 + 着色 + 写入输出缓冲）。
+ * - 子类选择不同的“组织单元”：（按照并行组织单元）逐三角形、按 tile、或延迟管线。
+ * - 公共的透视除法与视口变换在此提供，子类按需复用。
+ */
+class RendererBase {
+ public:
+  RendererBase(size_t width, size_t height)
+      : width_(width), height_(height), rasterizer_(std::make_shared<Rasterizer>(width, height)) {}
+  virtual ~RendererBase() = default;
+
+  RendererBase(const RendererBase&) = delete;
+  RendererBase& operator=(const RendererBase&) = delete;
+
+  /**
+   * @brief 执行一次渲染
+   * @param model 模型数据
+   * @param shader 着色器（包含材质/光照/矩阵等 uniform）
+   * @param out_color 输出颜色缓冲（大小为 width*height）
+   * @return 是否渲染成功
+   */
+  virtual bool Render(const Model& model, const Shader& shader, uint32_t* out_color) = 0;
+
+ protected:
+  /**
+   * @brief 透视除法：裁剪空间 -> NDC
+   * @param vertex 裁剪空间顶点
+   * @return NDC 顶点（保留 1/w 以供透视校正）
+   */
+  Vertex PerspectiveDivision(const Vertex& vertex);
+  /**
+   * @brief 视口变换：NDC -> 屏幕坐标
+   * @param vertex NDC 顶点
+   * @return 屏幕空间顶点
+   */
+  Vertex ViewportTransformation(const Vertex& vertex);
+
+ protected:
+  size_t width_;
+  size_t height_;
+  std::shared_ptr<Rasterizer> rasterizer_;
+
+  static constexpr float kMinWValue = 1e-6f;
+};
+
+}  // namespace simple_renderer
+
+#endif  // SIMPLERENDER_SRC_INCLUDE_RENDERERS_RENDERER_BASE_HPP_