Merge branch 'master' of https://gitea.sepcomet.xyz/basil/IMX6U-Game

2026-06-07 14:37:58 +08:00
parent 352a1233e6 d92b890528
commit 0defa04eef
13 changed files with 445 additions and 43 deletions
@@ -0,0 +1,262 @@
+# 应用层与图形库分层设计
+
+本项目后续包含三个应用层目标：两个游戏和一个启动器；同时还需要沉淀一套可复用的 IMX6U 轻量图形库。为了避免后期耦合和性能返工，必须明确区分“应用层”和“底层库”。
+
+## 1. 推荐总体结构
+
+推荐拆成四个逻辑层：
+
+```text
+IMX6U-Game/
+├─ src/
+│  ├─ Gfx/                 # 底层图形库：可复用、无具体游戏规则
+│  │  ├─ Draw2D/           # DrawContext 统一绘制入口（✅ 已实现）
+│  │  ├─ Core/             # FrameBuffer、DepthBuffer（✅ 已实现）
+│  │  ├─ Math/             # 向量、矩阵、数学工具（✅ 已实现）
+│  │  ├─ Rasterizer/       # 线段、三角形光栅化（✅ 已实现）
+│  │  ├─ RenderData/       # Color、Triangle 等数据结构（✅ 已实现）
+│  │  ├─ Scene/            # Camera、Transform（✅ 已实现）
+│  │  ├─ Shading/          # 着色器（预留）
+│  │  ├─ Platform/         # SDL2 / fb0 显示适配与独立时间源（✅ 已实现）
+│  │  └─ Asset/            # 资源加载（✅ 已实现）
+│  ├─ Apps/
+│  │  ├─ Demo/             # 当前板端性能 demo；历史上也用于 3D 立方体验证（✅ 已实现）
+│  │  ├─ Launcher/         # 启动器应用（待实现）
+│  │  ├─ GameA/            # 第一个游戏（待实现）
+│  │  └─ GameB/            # 第二个游戏（待实现）
+│  └─ Shared/              # 可选：应用层共享但不属于 Gfx 的东西
+│     ├─ Save/             # 存档格式、配置读写
+│     ├─ UI/               # 启动器和游戏共用 UI 组件
+│     └─ Assets/           # 应用层资源索引、资源命名约定
+├─ assets/
+│  ├─ font/                # 共享像素字体源文件与生成的 font_atlas
+│  ├─ sprite/              # 当前 demo/test sprite 源文件与生成头文件
+│  ├─ launcher/
+│  ├─ game_a/
+│  ├─ game_b/
+│  └─ shared/
+├─ tools/
+│  ├─ gen_font_atlas.py    # TTF -> bitmap font atlas/header
+│  └─ png_to_header.py     # PNG -> uint32_t RGBA header
+└─ docs/
+```
+
+~~当前项目已有 `Core/Math/Platform/Rasterizer/RenderData/Scene` 等目录，短期不必一次性搬迁；但新增代码应按上面的边界收敛。等功能稳定后，再把现有底层代码整体移动到 `src/Gfx/`。~~
+
+**已完成**：底层代码已整体迁移到 `src/Gfx/`，包括 Core、Math、Rasterizer、RenderData、Scene、Shading、Platform、Asset 和新增的 Draw2D。Demo 入口位于 `src/Apps/Demo/`。
+
+## 2. 四个层级的职责
+
+### 2.1 Gfx：底层图形库
+
+职责：
+
+- 管理 framebuffer、depthbuffer、渲染上下文。
+- 提供基础绘制接口：点、线、矩形、四边形、三角形、sprite、SpriteRegion、tilemap、简单文本等。
+- 提供颜色、矩形、定点数、纹理、裁剪区域等基础数据结构。
+- 封装 SDL2 / framebuffer 显示提交、输入轮询，并通过独立 `ITimeSource` 提供单调整数毫秒时间。
+- 使用离线转换后的紧凑资源数据（例如 PNG 转头文件、bitmap font atlas），运行时不直接依赖 PNG/TTF 解码。
+- 只关心“怎么画得快、怎么提交到屏幕”，不关心具体游戏规则。
+
+禁止：
+
+- 不依赖 `GameA`、`GameB`、`Launcher`。
+- 不包含具体关卡、角色、菜单流程、游戏状态机。
+- 不直接读取某个游戏专属资源路径。
+- 不在核心绘制接口中暴露 SDL2 类型。
+- 不在每帧热路径中执行图片/字体解码；资源转换应在构建前或工具阶段完成。
+
+### 2.2 Apps/GameA 与 Apps/GameB：两个游戏
+
+职责：
+
+- 各自维护自己的游戏规则、状态机、关卡、实体、碰撞、计分、胜负逻辑。
+- 通过 Gfx 提供的接口绘制画面。
+- 通过平台输入快照读取按键/触摸状态，而不是直接调用 SDL。
+- 管理自己的资源索引和场景切换。
+
+禁止：
+
+- 游戏之间互相 include 对方代码。
+- 游戏直接操作 SDL renderer / texture / window。
+- 游戏直接依赖 framebuffer 内存布局，除非是明确标注的性能特例。
+
+### 2.3 Apps/Launcher：启动器
+
+职责：
+
+- 展示游戏列表、图标、说明、版本信息。
+- 选择并启动 GameA 或 GameB。
+- 管理全局设置，例如音量、亮度、输入校准、语言等。
+- 可以复用 Shared/UI，但不承载具体游戏逻辑。
+
+启动方式有两种可选方案：
+
+1. **单进程多应用模式**：Launcher、GameA、GameB 编译成一个可执行文件，内部切换当前 App。
+2. **多进程模式**：Launcher 是独立程序，选择后启动另一个游戏可执行文件。
+
+对 IMX6U 初期开发，推荐先用 **单进程多应用模式**，原因：
+
+- 构建、部署、调试更简单。
+- SDL2 初始化、资源缓存、输入状态可以共用。
+- 避免频繁退出/启动进程带来的黑屏、资源重载和状态恢复问题。
+
+等项目成熟后，如果每个游戏体积较大，或者需要独立更新，再考虑多进程拆分。
+
+### 2.4 Shared：应用层共享模块
+
+Shared 只放“应用层共享，但不属于底层图形库”的内容，例如：
+
+- UI 控件：按钮、列表、九宫格面板、菜单焦点管理。
+- 存档/设置：配置文件、最高分、解锁状态。
+- 资源清单：多个应用共用的字体、图标、音效索引。
+
+Shared 可以依赖 Gfx；Gfx 不能依赖 Shared。
+
+## 3. 依赖方向
+
+必须保持单向依赖：
+
+```text
+Apps/GameA ─┐
+Apps/GameB ─┼─> Shared ─> Gfx ─> Platform(SDL2/fb0/ITimeSource)
+Launcher  ─┘
+
+Apps/GameA ─┐
+Apps/GameB ─┼──────────> Gfx
+Launcher  ─┘
+```
+
+禁止反向依赖：
+
+```text
+Gfx -> Apps        禁止
+Gfx -> Shared      禁止
+GameA -> GameB     禁止
+GameB -> GameA     禁止
+Platform -> Game   禁止
+```
+
+## 4. 应用统一接口
+
+推荐为 Launcher、GameA、GameB 提供统一应用接口，例如：
+
+```cpp
+class IApp
+{
+public:
+    virtual ~IApp() {}
+    virtual void on_enter() = 0;
+    virtual void on_exit() = 0;
+    virtual void update(uint32_t fixed_delta_ms) = 0;
+    virtual void render(Gfx::DrawContext& ctx) = 0;
+    virtual AppId next_app() const = 0;
+};
+```
+
+主循环只认识 `IApp`：
+
+```text
+poll input -> update current app -> render current app -> present framebuffer
+```
+
+这样三个应用层共用同一个主循环、同一套 SDL2 初始化、framebuffer 提交流程和独立时间源。
+
+注意：接口可以先保留虚函数，因为它只在每帧应用级调用，不在像素/顶点热路径中调用。像 `draw_rect`、`draw_quad`、`set_pixel_fast` 这类热路径函数不要虚化。
+
+## 5. 底层图形库优先提供的 API
+
+Gfx 初期建议先做 2D 基础能力，不要一开始就做复杂引擎：
+
+```cpp
+namespace Gfx
+{
+    struct RectI { int32_t x, y, w, h; };
+    struct PointI { int32_t x, y; };
+    struct Color32 { uint32_t rgba; };
+
+    class DrawContext
+    {
+    public:
+        void clear(Color32 color);
+        void draw_pixel(int32_t x, int32_t y, Color32 color);
+        void draw_line(PointI a, PointI b, Color32 color);
+        void draw_rect(RectI rect, Color32 color);
+        void fill_rect(RectI rect, Color32 color);
+        void draw_quad(PointI p0, PointI p1, PointI p2, PointI p3, Color32 color);
+        void fill_quad(PointI p0, PointI p1, PointI p2, PointI p3, Color32 color);
+        void draw_sprite(int32_t x, int32_t y, const RenderData::Image& image);
+        void draw_sprite_region(int32_t x, int32_t y,
+                                const RenderData::SpriteRegion& region);
+        void draw_text(const RenderData::BitmapFont& font, int32_t x, int32_t y,
+                       RenderData::Color color, const char* text);
+        void draw_tilemap(const RenderData::Tilemap& tilemap,
+                          int32_t screen_x, int32_t screen_y,
+                          int32_t viewport_w, int32_t viewport_h,
+                          int32_t camera_x, int32_t camera_y);
+    };
+}
+```
+
+后续再扩展：
+
+- `set_clip_rect`
+- `set_camera_2d`
+- `batch sprite/tile`
+
+## 6. 命名建议
+
+为了避免“项目名、库名、游戏名”混乱，建议：
+
+- 项目仓库仍叫 `IMX6U-Game`。
+- 底层图形库命名为 `Gfx` 或 `MiniGfx`。
+- 三个应用用明确名字：`Launcher`、`GameA`、`GameB`，后续再替换成真实游戏名。
+- CMake target 可以是：
+  - `imx6u_gfx` 静态库
+  - `imx6u_launcher`
+  - `imx6u_game_a`
+  - `imx6u_game_b`
+  - 或初期单可执行文件 `imx6u_suite`
+
+## 7. 推荐演进顺序
+
+1. ~~先抽出统一 `IApp` 和 `AppManager`，让当前 demo 成为一个 app。~~
+2. ~~把 SDL2 初始化、输入、present 固定在平台层，应用层不直接碰 SDL。~~
+3. ~~建立 `Gfx::DrawContext`，先封装 clear、pixel、line、rect、quad。~~ **已完成**（`Gfx::DrawContext` 封装了 clear、draw_line、draw_triangle、draw_sprite、draw_sprite_region、draw_text、draw_tilemap、present）
+4. ~~底层代码迁移到 `src/Gfx/`，Demo 入口迁移到 `src/Apps/Demo/`。~~ **已完成**
+5. 新增 Launcher app，只做最小菜单和应用切换。
+6. 新增 GameA/GameB 空壳，验证三应用切换。
+7. 再逐步把现有 3D demo 能力恢复为独立验证入口，或把 2D 游戏逻辑迁入对应 Game 目录。
+8. 最后重构 CMake，按 `imx6u_gfx` + 应用 target 拆分。
+
+## 8. 性能注意事项
+
+- 应用切换不应重复销毁/创建 SDL window、renderer、texture。
+- 三个应用共用 framebuffer、输入状态和 `Platform::ITimeSource` 时间源；Display 不承担计时职责。
+- 每个应用可以有自己的资源缓存，但必须有上限和释放策略。
+- Launcher 不应常驻消耗大量纹理/音频资源；进入游戏后可释放非必要启动器资源。
+- Gfx 的绘制函数要保持小而直接，优先内联和连续内存写入。
+- UI 控件层可以面向对象；像素/quad/sprite/tile 绘制层不要过度抽象。
+- 无 3D 内容的 2D 应用应使用只清颜色缓冲的路径，避免每帧清理 depth buffer。
+- `/dev/fb0` 后端提交可能是主要瓶颈；板端性能分析应拆分 `Frame` 和 `Present` 耗时，并确认 ARM 构建为 Release。
+- 直接写 framebuffer 不是原子换屏，LCD 扫描会让局部动画看起来比完整帧率更连续；判断性能应以计时数据为准。
+
+## 9. 资源转换约定
+
+- 运行时资源优先使用离线转换后的简单数组，不在 IMX6U 运行时解码 PNG/TTF。
+- `tools/png_to_header.py` 将 PNG 转为 `uint32_t` RGBA 数组，适用于 sprite、小图标、测试纹理等。
+- `tools/gen_font_atlas.py` 将共享像素字体转为 ASCII bitmap atlas，并输出同名 PNG 预览和 C++ 头文件。
+- 生成头文件、源 PNG/TTF 和转换脚本应一起纳入仓库，保证资源可追溯、可再生成。
+- 生成数据目前面向简单直接的调试/小型游戏资源；后续如果资源体积增长，应再评估 1-bit/8-bit mask、RLE 或自定义资源包格式。
+
+## 10. SpriteRegion 与 Tilemap 约定
+
+- `RenderData::SpriteRegion` 只描述某张 atlas 中的子区域，不拥有像素数据；它通过 `const Image* atlas` 引用源图。
+- `DrawContext::draw_sprite_ex` 是底层 sprite 绘制入口，负责源区域检查、目标屏幕裁剪、scale 和 flip；`draw_sprite_region` 系列只是对 atlas 子区域的语义包装。
+- `RenderData::Tilemap` 使用 `uint16_t` tile id 保存地图网格，`Tilemap::EmptyTile` (`0xFFFF`) 表示空 tile。
+- `Tilemap` 当前只支持一个 atlas、固定 tile 宽高和固定 `atlas_columns`；tile id 通过 `tile_id % atlas_columns` / `tile_id / atlas_columns` 映射到 atlas 中的源区域。
+- `DrawContext::draw_tilemap` 的裁剪分两层：
+  - tilemap 层按 tile 计算需要尝试绘制的可见范围；
+  - sprite 层按像素裁剪每个 tile，支持 camera 像素级滚动时显示半个 tile。
+- 带 `viewport_w` / `viewport_h` 的 `draw_tilemap` 重载用于子视口绘制，`screen_x` / `screen_y` 是视口左上角；旧重载默认视口延伸到 framebuffer 右下角。
+- 当前实现优先保证清晰语义和可验证行为；后续性能优化可增加 tile region 查表、不透明 tile 行拷贝、chunk/dirty rect 或专用 tile 快路径。
@@ -87,11 +87,31 @@
 ## 5. 渲染管线性能规范

 - FrameBuffer / DepthBuffer 清理必须优先考虑批量填充（如 `memset`、`std::fill`、平台优化路径），不要逐像素走复杂逻辑。
+- 2D-only 或不使用深度测试的场景应只清颜色缓冲，例如使用 `DrawContext::clear_color()`；不要每帧无意义清理 depth buffer。
 - 像素写入路径应尽量减少分支和函数调用层级。
+- 像素级写入的 Release 快路径不要使用带额外边界检查的容器访问（例如 `std::vector::at()`）；边界检查应在外层完成。
 - 裁剪、剔除、包围盒收缩要尽早执行，避免把不可见数据送入像素级循环。
 - 三角形属性插值、深度测试、纹理采样等未来功能必须先定义定点/整数方案，再接入热路径。
 - PC 调试版可以保留更易读的检查与可视化代码，但 ARM release 路径必须能关闭这些额外成本。

+### 5.1 `/dev/fb0` 提交路径
+
+Framebuffer 后端是 IMX6U 上最容易误判性能的路径。`FBDisplay::present()` 需要把 CPU 侧 framebuffer 写入 `/dev/fb0`，如果逐像素走通用格式转换，整屏 1024x600 提交会成为主瓶颈。
+
+规范：
+
+- ARM / framebuffer 性能测试必须使用 Release 构建；单配置生成器应确认 `CMAKE_BUILD_TYPE=Release`。
+- 性能结论必须拆分 `Frame` 和 `Present` 耗时；如果 `Present` 接近 `Frame`，优先优化显示提交，而不是游戏逻辑。
+- fb0 像素格式应在初始化时打印并据此走专用路径，常见格式包括 RGB565、ARGB8888/XRGB8888、RGBA8888。
+- 避免每帧重复做不必要的通用 RGBA 转换；可考虑目标格式 backbuffer、预转换资源、行拷贝、dirty rect 和局部提交。
+- 直接写 `/dev/fb0` 不是原子换屏；LCD 控制器可能边扫描边显示正在写入的内存，因此肉眼流畅度不等同于完整帧率。
+
+已观察到的板端测试结论：
+
+- 未优化 ARM 构建下，轻量 2D demo 曾出现约 `Frame:81ms / Present:69ms`。
+- 改为 Release 构建后，同一类 framebuffer 测试最高约 76 FPS。
+- 因此板端性能测试首先检查构建类型，再判断算法或硬件瓶颈。
+
 ## 6. STL 与标准库使用边界

 允许：
@@ -129,6 +149,7 @@

 新增或修改核心代码前，至少检查：

+- [ ] ARM / framebuffer 性能测试是否确认使用 Release 构建？
 - [ ] 是否在热路径新增了 `float` / `double`？如果是，是否能改成整数/定点？
 - [ ] 是否在每帧或内层循环创建了 `std::vector` / `std::string` / 其他堆分配对象？
 - [ ] 容器是否提前 `reserve()`，或由上层复用？
@@ -214,3 +235,11 @@
 - 总帧时间、最低 FPS、峰值帧时间

 性能日志默认低频输出，例如每 60 帧汇总一次；ARM release 中不得逐帧大量打印。
+
+Framebuffer 对照后端同样需要至少显示或记录：
+
+- `Frame`：从帧开始到提交完成的总耗时；
+- `Present`：`IDisplay::present()` 的耗时；
+- 当前 FPS。
+
+当前 Demo 的板端测试 UI 已包含这些信息，后续正式 profiler 可替代该临时显示。