IMX6U-Game

一个从 CPU 软光栅化渲染器向嵌入式游戏图形库迁移的项目。

核心目标是在 IMX6U（ARM Cortex-A7，无 GPU 或极弱 GPU）上运行纯 CPU 渲染的 2D/3D 图形。为此，代码保持 C++11 兼容，显示后端可切换（SDL2 窗口 vs Linux Framebuffer），以支持跨平台开发和嵌入式部署。

编译目标与验证目的

本项目支持三套编译目标，分别对应开发流程的不同阶段：

目标平台	显示后端	验证目的
Windows (x86/x64)	SDL2 窗口	验证渲染逻辑、算法正确性、快速迭代调试
Linux x86_64	SDL2 窗口	验证 Linux 兼容性、CMake 构建、SDL2 系统依赖
ARM Linux (交叉编译)	/dev/fb0 直接写屏	最终在 IMX6U 开发板上运行的版本

为什么分三套？

• Windows 编译：开发主力机通常是 Windows，有 IDE 调试、有图形窗口，渲染算法对不对一眼就能看到。这个阶段完全不关心嵌入式细节。
• Linux x86 编译：验证代码在 GCC/Clang 下有无警告、CMake 配置是否跨平台、系统 SDL2 依赖是否正确。很多嵌入式工具链的问题在 x86 Linux 上就能提前暴露。
• ARM 交叉编译：最终在 IMX6U 上跑。这个版本去掉 SDL2，直接 mmap /dev/fb0 写屏，减少依赖和内存开销。

构建说明

通用前置

# 克隆仓库后，确保子目录完整
cd IMX6U-Game

Windows（Visual Studio / MSVC）

仓库已自带 SDL2 开发库（libs/Win/SDL2），无需额外安装。

cmake -B build-win .
cmake --build build-win --config Release

运行：

./build-win/Release/IMX6U-Game.exe

Linux x86_64（Ubuntu / WSL2）

需要系统 SDL2：

sudo apt-get install libsdl2-dev cmake g++

构建：

cmake -B build-linux .
cmake --build build-linux

运行：

./build-linux/IMX6U-Game

ARM 交叉编译（IMX6U）

需要交叉编译工具链：

sudo apt-get install gcc-arm-linux-gnueabihf g++-arm-linux-gnueabihf

构建（启用 Framebuffer 后端）：

cmake -B build-arm \
    -DCMAKE_TOOLCHAIN_FILE=cmake/toolchain-arm-linux-gnueabihf.cmake \
    -DUSE_FRAMEBUFFER=ON .
cmake --build build-arm

部署到开发板：

scp build-arm/IMX6U-Game root@imx6u:/tmp/

板子上运行（需要 root 权限访问 /dev/fb0）：

sudo /tmp/IMX6U-Game

ARM 版本启动后会打印 framebuffer 参数（分辨率、bpp、像素格式）。按 q 键或 Ctrl+C 退出。

显示后端架构

显示层通过抽象接口 Platform::IDisplay 与渲染逻辑解耦：

┌──────────────────────────────────────┐
│ 游戏/渲染逻辑（Camera、Rasterizer 等） │
├──────────────────────────────────────┤
│ Core::FrameBuffer（CPU 颜色缓冲区）    │
├──────────────────────────────────────┤
│ Platform::IDisplay                   │
│  - SDLDisplay   : SDL2 窗口（PC）     │
│  - FBDisplay    : /dev/fb0（ARM）     │
└──────────────────────────────────────┘

切换后端不需要修改任何渲染代码，只需要在 CMake 配置时开关 USE_FRAMEBUFFER。

目录结构

IMX6U-Game/
├─ cmake/
│  └─ toolchain-arm-linux-gnueabihf.cmake  # ARM 交叉编译工具链
├─ libs/
│  └─ Win/
│     ├─ SDL2/                             # Windows 用 SDL2 库（头文件 + lib + DLL）
│     └─ SDL_image/                        # SDL2_image 库（头文件 + lib + DLL）
├─ src/
│  ├─ Platform/
│  │  ├─ Display.h                         # 显示抽象接口
│  │  ├─ SDLDisplay.cpp                    # SDL2 窗口后端
│  │  └─ FBDisplay.cpp                     # Linux Framebuffer 后端
│  ├─ Core/
│  │  ├─ FrameBuffer.h/.cpp                # CPU 颜色缓冲
│  │  ├─ DepthBuffer.h/.cpp                # 深度缓冲
│  │  └─ Renderer.h/.cpp                   # 渲染调度（预留）
│  ├─ Math/
│  │  ├─ Vector2.h / Vector3.h / Vector4.h
│  │  ├─ Matrix4x4.h
│  │  └─ MathUtil.h
│  ├─ Rasterizer/
│  │  ├─ Rasterizer.h/.cpp                 # 线段光栅化
│  │  └─ TriangleRasterizer.h/.cpp         # 三角形填充
│  ├─ RenderData/
│  │  ├─ Color.h
│  │  ├─ BoundingBox.h
│  │  └─ Triangle.h
│  ├─ Scene/
│  │  ├─ Camera.h/.cpp
│  │  ├─ Vertex.h / Mesh.h / Model.h / Transform.h
│  ├─ Asset/
│  │  └─ ObjLoader.h/.cpp                  # OBJ 模型加载（预留）
│  ├─ Shading/
│  │  └─ BlinnPhongShader.h/.cpp           # 着色（预留）
│  ├─ test_fb.cpp                          # 独立 fb 测试（最小示例）
│  └─ main.cpp
├─ CMakeLists.txt
└─ README.md

模块说明

Core

• FrameBuffer：CPU 侧颜色缓冲，渲染结果先写在这里
• DepthBuffer：深度测试用 Z-buffer

Math

• 通用数学类型：Vector2/3/4、Matrix4x4
• 纯头文件实现，无动态分配

Rasterizer

• Rasterizer：Bresenham 线段光栅化
• TriangleRasterizer：扫描线三角形填充 + 深度测试

Platform

• IDisplay：显示后端抽象，解耦渲染与输出
• SDLDisplay：PC 端用 SDL2 窗口实时查看效果
• FBDisplay：ARM 端直接写 /dev/fb0

当前状态与后续

已完成：

• 可旋转立方体的 3D 渲染（MVP 变换、背面剔除、扫描线填充、深度测试）
• 双平台显示后端（SDL2 / Framebuffer）
• C++11 兼容代码
• CMake 跨平台构建

待完成（按优先级）：

1. FrameBuffer 性能优化（memset 清屏、去掉 at()、定点数/NEON）
2. 输入抽象（键盘/触摸屏 evdev）
3. 纹理贴图
4. 2D 游戏层封装（Sprite、Tilemap）
5. OBJ 模型加载与完整光照

说明

• 代码标准：C++11，确保兼容嵌入式老工具链
• test_fb.cpp 是一个完全独立的 Linux framebuffer 最小测试，不依赖项目其他代码，用于快速验证板子显示通路
• Windows 和 Linux x86 版本共享 SDLDisplay，ARM 版本单独使用 FBDisplay