# 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` 写屏，减少依赖和内存开销。

## 构建说明

### 通用前置

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

### Windows（Visual Studio / MSVC）

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

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

运行：
```bash
./build-win/Release/IMX6U-Game.exe
```

### Linux x86_64（Ubuntu / WSL2）

需要系统 SDL2：

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

构建：
```bash
cmake -B build-linux .
cmake --build build-linux
```

运行：
```bash
./build-linux/IMX6U-Game
```

### ARM 交叉编译（IMX6U）

需要交叉编译工具链：

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

构建（启用 Framebuffer 后端）：
```bash
cmake -B build-arm \
    -DCMAKE_TOOLCHAIN_FILE=cmake/toolchain-arm-linux-gnueabihf.cmake \
    -DUSE_FRAMEBUFFER=ON .
cmake --build build-arm
```

部署到开发板：
```bash
scp build-arm/IMX6U-Game root@imx6u:/tmp/
```

板子上运行（需要 root 权限访问 `/dev/fb0`）：
```bash
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`。

## 目录结构

```text
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`