From 189072ba4ebec633ef0687af86c508153ca40562 Mon Sep 17 00:00:00 2001 From: SepComet <2428390463@qq.com> Date: Tue, 9 Jun 2026 10:39:10 +0800 Subject: [PATCH] =?UTF-8?q?=E6=9B=B4=E6=96=B0=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 62 ++++++++++++++++++++----------- docs/APP_AND_CORE_ARCHITECTURE.md | 8 ++++ docs/CONVENTIONS.md | 13 +++---- 3 files changed, 53 insertions(+), 30 deletions(-) diff --git a/README.md b/README.md index 6a7d395..f925527 100644 --- a/README.md +++ b/README.md @@ -167,14 +167,10 @@ Framebuffer 对照版本可能需要 root 权限访问 `/dev/fb0`。SDL2 版本 项目运行时不依赖 PNG/TTF 解码库。图片和字体资源在离线阶段转换成 C++ 头文件，但运行时格式按资源类型区分： -- sprite / atlas：`uint16_t` `RGBA5551` +- sprite / atlas：`uint16_t` `RGBA5551`（5-bit R/G/B + 1-bit A） - bitmap font：`uint8_t` 1-bit mask（8 个像素打包为 1 个字节） -sprite 相关像素格式约定为： - -```text -(R << 24) | (G << 16) | (B << 8) | A -``` +sprite 运行时像素格式统一为 `RGBA5551`（16-bit），内部 backbuffer 统一为 `RGB565`；透明仅支持 1-bit alpha test（`A=0` 跳过，`A=1` 覆写）。 当前转换工具位于 `tools/`，需要 Python 和 Pillow： @@ -195,10 +191,10 @@ python tools/png_to_header.py assets/sprite/test_sprite.png assets/sprite/test_s ```cpp test_sprite_width test_sprite_height -test_sprite_pixels +test_sprite_pixels // uint16_t RGBA5551 数组 ``` -透明像素仍保留 alpha；当前 demo 通过 `RenderData::Image(..., 0x00000000)` 把全透明像素作为 color key 跳过。 +透明像素转换为 RGBA5551 后，alpha 仅 1-bit（`A=0` 透明，`A=1` 不透明）。当前 demo 通过 `RenderData::Image` 的 color_key 机制跳过指定颜色值。 Tom 游戏资源使用 `SpriteAssetTool` 从固定目录 `src/Apps/Game/assets/raw/` 读取原始 PNG，一步生成 atlas 头文件。主机侧构建 `IMX6U-Game` 时 CMake 会自动执行 `GenerateTomAtlasHeader`；也可以单独执行： @@ -214,7 +210,7 @@ src/Apps/Game/generated/tom_atlas.h 该头文件包含 `tom_atlas_pixels` 和每张图的 `RenderData::Sprite`，因此板端运行 Tom 游戏时不需要额外部署图片资源文件。尺寸规则、region 名称和 PNG 文件名统一记录在 `src/Apps/Game/tools/asset_pipeline/SpriteAssetTool.cpp` 顶部的 `Sources` 表里；CMake 不再重复维护每张 PNG 的路径。 -`src/Apps/Game/assets/sprites/` 属于旧的 `.sprite` 文件部署流程，Tom 主游戏现在不再依赖它。只有旧的手动测试或未迁移工具还可能引用该目录；清理这些旧入口后可以删除这个目录。 +`assets/sprite/` 用于存放测试用 PNG sprite 源文件及转换后的头文件，Tom 主游戏不依赖它。Tom 游戏的 atlas 资源由 `src/Apps/Game/tools/asset_pipeline/SpriteAssetTool.cpp` 从 `src/Apps/Game/assets/raw/` 读取原始 PNG 生成。 ### Bitmap Font 转换 @@ -281,20 +277,32 @@ IMX6U-Game/ │ └─ sprite/ # PNG sprite 源文件及转换后的头文件 ├─ tools/ │ ├─ gen_font_atlas.py # TTF -> bitmap font atlas/header -│ └─ png_to_header.py # PNG -> uint32_t RGBA header +│ └─ png_to_header.py # PNG -> uint16_t RGBA5551 header ├─ src/ │ ├─ Core/ # 底层图形库：可复用、无具体游戏规则 │ │ ├─ Draw2D/ # DrawContext 统一绘制入口 -│ │ ├─ Core/ # FrameBuffer、DepthBuffer +│ │ ├─ Core/ # FrameBuffer、DepthBuffer、Renderer、Timer │ │ ├─ Math/ # 向量、矩阵、数学工具 │ │ ├─ Rasterizer/ # 线段、三角形光栅化 -│ │ ├─ RenderData/ # Color、Triangle 等数据结构 -│ │ ├─ Scene/ # Camera、Transform、Mesh -│ │ ├─ Shading/ # 着色器（预留） +│ │ ├─ RenderData/ # Color、Image、Sprite、Tilemap、BitmapFont 等数据结构 +│ │ ├─ Scene/ # Camera、Transform、Mesh、Model +│ │ ├─ Shading/ # BlinnPhongShader 等着色器 │ │ ├─ Platform/ # IDisplay、SDLDisplay、FBDisplay、ITimeSource -│ │ └─ Asset/ # ObjLoader 等资源加载 +│ │ │ # IAudioInput/Output、IButtonInput、IPointerInput +│ │ │ # ALSA / evdev / SDL2 后端、DefaultHardware +│ │ └─ Asset/ # ObjLoader、SpriteAssetLoader │ ├─ Apps/ -│ │ └─ Demo/ # 当前 3D 立方体 demo 入口 +│ │ ├─ Demo/ # 2D sprite/tilemap 性能测试入口 +│ │ └─ Game/ # Tom 游戏 +│ │ ├─ Main.cpp # 游戏入口 +│ │ ├─ generated/tom_atlas.h # 自动生成的 atlas 头文件 +│ │ ├─ tools/asset_pipeline/ # SpriteAssetTool（离线资源转换） +│ │ └─ src/ +│ │ ├─ app/ # TomGameApp +│ │ ├─ audio/ # VoiceEffect、VoicePlayer、VoiceRecorder +│ │ ├─ components/ # SpriteAnimator +│ │ ├─ scenes/ # TomScene +│ │ └─ systems/ # AnimationSystem │ └─ test_fb.cpp # 独立 fb 测试（最小示例） ├─ docs/ │ ├─ DEVELOPMENT_GUIDELINES.md # IMX6U 性能红线 @@ -307,13 +315,19 @@ IMX6U-Game/ ## 模块说明 ### Draw2D -- **DrawContext**：统一绘制入口，封装 FrameBuffer、DepthBuffer、Rasterizer、TriangleRasterizer，对外提供 `clear`、`draw_line`、`draw_triangle`、`draw_sprite`、`draw_text`、`draw_tilemap`、`present` 接口 -- **Sprite**：描述 atlas 中的子区域，是对外 sprite 绘制单位；`draw_sprite` / `draw_sprite_ex` 读取其 atlas 子区域并写入 RGB565 framebuffer -- **Tilemap**：使用 `uint16_t` tile id 引用 atlas 中的固定大小 tile，`draw_tilemap` 按视口可见范围遍历 tile，并在视口边缘做像素级裁剪 +- **DrawContext**：统一绘制入口，封装 FrameBuffer、DepthBuffer、Rasterizer、TriangleRasterizer，对外提供 `clear`、`clear_color`、`clear_depth`、`draw_line`、`draw_triangle`、`draw_sprite`、`draw_sprite_ex`、`draw_text`、`draw_tilemap`、`fill_rect`、`present` 接口 + +### RenderData +- **Image**：通用图像数据结构，持有 `const void* pixels` 和 `PixelFormat`（当前统一 `RGBA5551`），支持 color_key 透明跳过 +- **Sprite**：描述 atlas 中的子区域，通过 `const Image* atlas` 引用源图，是对外 sprite 绘制单位 +- **Tilemap**：使用 `uint16_t` tile id 引用 atlas 中的固定大小 tile，`EmptyTile` (`0xFFFF`) 表示空 tile +- **BitmapFont**：bitmap 字体数据，持有 `uint8_t* mask_bits`（row-major、MSB-first 1-bit mask），支持 ASCII 范围字符绘制 +- **Color**：RGBA8888 颜色值，用于绘制接口参数和调试；sprite 运行时像素格式仍为 RGBA5551 ### Core -- **FrameBuffer**：CPU 侧颜色缓冲，渲染结果先写在这里 +- **FrameBuffer**：CPU 侧 RGB565 颜色缓冲，渲染结果先写在这里 - **DepthBuffer**：深度测试用 Z-buffer +- **Renderer**：渲染器辅助工具 - **Timer**：整数毫秒固定步长 tick 生成器，支持 30/45/60 FPS 档位和每帧剩余时间计算 ### Math @@ -321,14 +335,18 @@ IMX6U-Game/ - 纯头文件实现，无动态分配 ### Rasterizer -- **Rasterizer**：Bresenham 线段光栅化 -- **TriangleRasterizer**：扫描线三角形填充 + 深度测试 +- **Rasterizer**：Bresenham 线段光栅化，入口做快速全屏可见性检查，屏幕内走 `set_pixel_unsafe` 快路径，屏幕外走 Cohen-Sutherland 裁剪 +- **TriangleRasterizer**：扫描线三角形填充 + 定点深度插值（增量式整数边缘函数，内层循环无 float 运算） ### Platform - **IDisplay**：显示后端抽象，解耦渲染与输出 - **SDLDisplay**：SDL2 后端，PC 调试和 IMX6U SDL2 目标路径共用这一类适配思想 - **FBDisplay**：`/dev/fb0` 对照后端，用于极简显示通路验证 - **ITimeSource / SteadyTimeSource**：独立时间源接口与单调时钟实现；Linux/IMX6U 使用 `clock_gettime(CLOCK_MONOTONIC)`，Windows 使用 `std::chrono::steady_clock`，Display 不再承担计时职责 +- **IAudioInput / IAudioOutput**：音频输入/输出抽象接口，SDL2 和 ALSA 两套后端 +- **IButtonInput**：按键输入抽象接口，SDL2 键盘和 Linux evdev 两套后端 +- **IPointerInput**：触摸/指针输入抽象接口，SDL2 和 Linux evdev 两套后端 +- **DefaultHardware**：根据编译配置自动选择默认音频、按键、指针后端的 typedef ### Framebuffer 性能说明 diff --git a/docs/APP_AND_CORE_ARCHITECTURE.md b/docs/APP_AND_CORE_ARCHITECTURE.md index c6ed3d0..ef6e837 100644 --- a/docs/APP_AND_CORE_ARCHITECTURE.md +++ b/docs/APP_AND_CORE_ARCHITECTURE.md @@ -21,6 +21,14 @@ src/ Apps/ Demo/ # 2D sprite/tilemap 性能测试入口 Game/ # Tom 游戏 + generated/ # 自动生成的 tom_atlas.h + tools/ # SpriteAssetTool（离线资源转换） + src/ + app/ # TomGameApp + audio/ # VoiceEffect、VoicePlayer、VoiceRecorder + components/ # SpriteAnimator + scenes/ # TomScene + systems/ # AnimationSystem ``` `src/Core/Core` 这个二级目录保留的是原底层库里的核心运行时对象。它和顶层 `src/Core` 名称重复，但含义不同： diff --git a/docs/CONVENTIONS.md b/docs/CONVENTIONS.md index 731fb76..d29f597 100644 --- a/docs/CONVENTIONS.md +++ b/docs/CONVENTIONS.md @@ -125,7 +125,7 @@ 当前项目已经接入 `Core::DepthBuffer`，并采用以下规则： -- `DepthBuffer` 存储类型为 `float` +- `DepthBuffer` 存储类型为 `float`；`TriangleRasterizer` 内部使用定点深度插值（`depth_fp += depth_fp_per_pixel`，提取时 `>> 16`），内层循环无 float 运算 - 每帧开始时必须调用 `depthBuffer->clear()`，默认清为 `INFINITY` - 当前约定为“深度值越小，离相机越近” - 深度测试通过后，必须同时更新 `DepthBuffer` 和 `FrameBuffer` @@ -133,17 +133,14 @@ 当前三角形光栅化里的深度流程为： -- 在屏幕空间遍历三角形包围盒 -- 以像素中心 `x + 0.5, y + 0.5` 作为采样点 -- 用屏幕空间 `x/y` 计算重心坐标 -- 用同一组重心坐标判断点是否在三角形内，并插值顶点 `z` +- 使用增量式整数边缘函数替代每像素 float 重心计算和除法 +- 深度插值使用定点算术：`depth_fp += depth_fp_per_pixel`，提取时 `>> 16` - 若新深度更近，则写入 `DepthBuffer` 和 `FrameBuffer` 也就是说： -- 重心坐标的计算是二维问题，只使用屏幕空间 `x/y` -- 顶点 `z` 的插值使用这组重心权重完成 -- 当前实现是屏幕空间线性插值，后续如果引入纹理、法线或更严格的属性插值，需要进一步考虑透视校正插值 +- 当前实现已定点化，内层循环无 float 运算，符合 `DEVELOPMENT_GUIDELINES.md` 性能红线 +- 后续如果引入纹理、法线或更严格的属性插值，需要进一步考虑透视校正插值 ## 10. Demo 中的可见性规则