46 KiB

Raw Blame History

基于 IMX6U 与光敏传感器的 2D 平台跳跃游戏设计

学生姓名：黄俊指导老师：⟨指导老师姓名⟩

摘要 本实训针对无 GPU 或 GPU 能力极弱的嵌入式 SoC（IMX6ULL/Cortex-A7）上如何构建可玩性完整的图形化游戏这一问题，设计并实现了一个纯 CPU 软光栅化 2D 渲染框架 Core，以及一款以光敏传感器（AP3216C）作为核心输入的平台跳跃游戏 LightGame。渲染层采用统一 RGB565 帧缓冲、RGBA5551 精灵图集、1-bit 透明与整数定点亮度调制，将像素格式转换控制在显示后端边界，热路径全部使用整数运算与预分配缓冲；显示层抽象为 Platform::IDisplay 接口，分别在 Linux /dev/fb0 与 PC SDL2 后端上实现，通过 CMake 选项和条件编译一键切换。游戏层实现了亚像素积分物理、有限状态角色控制器、整数平滑跟随相机、房间网格分区与检查点重生等系统。传感器层绕开出厂 ap3216c 字符设备驱动，直接通过 /dev/i2c-0 以 I2C_SLAVE_FORCE 抢占地址、将 AP3216C 重配置为 ALS-only 连续采样与最大增益模式，随后在应用层引入 Q8 定点一阶指数移动平均滤波，将 12 位光照值以约 0.3 Hz 截止频率平滑后驱动关卡对象通断、地形几何显隐与 HUD 反馈，形成"环境光即输入"的独特玩法。实验结果表明，在 IMX6U 板上以 1024×600、30 FPS 稳定运行，光照变化到游戏世界响应延迟约 0.7 s，能够支撑完整的关卡切换与死亡重生流程，验证了纯 CPU 渲染 + 环境传感器输入的技术路线在教学级嵌入式设备上的可行性。

关键词： IMX6ULL；软光栅化；RGB565；AP3216C；I²C；定点数；平台跳跃游戏；嵌入式 Linux

A 2D Platformer on IMX6U with a Photo-Sensor as Gameplay Input

Student name: Huang Jun　Advisor: ⟨Advisor Name⟩

Abstract This training addresses the problem of building a playable graphical game on an embedded SoC (IMX6ULL / Cortex-A7) that has no GPU or only extremely limited graphics acceleration. A pure-CPU software rasterisation 2D framework Core was designed and implemented, together with a platform-jumper game LightGame that uses an AP3216C ambient-light sensor as its primary gameplay input. The renderer standardises on an RGB565 framebuffer, RGBA5551 sprite atlases, 1-bit transparency and integer fixed-point brightness modulation, keeping pixel-format conversion at the display boundary and confining hot paths to integer math and pre-allocated buffers. The display layer is abstracted behind a Platform::IDisplay interface with Linux /dev/fb0 and PC SDL2 back-ends, selected by a CMake option and conditional compilation. The game layer implements sub-pixel-accumulator physics, a finite-state character controller, an integer smoothing follow-camera, a room-grid partition and checkpoint respawn. The sensor layer bypasses the vendor ap3216c character driver, taking over the I²C address via ioctl(I2C_SLAVE_FORCE) on /dev/i2c-0, reconfigures the AP3216C to ALS-only continuous mode at maximum gain, and applies a Q8 fixed-point first-order EMA (≈0.3 Hz cut-off) on top. The smoothed 12-bit reading drives object solidity, tilemap hot-swap and HUD feedback, realising an "ambient light is the input" mechanic. On the IMX6U board the system runs at 1024×600, a steady 30 FPS, with an end-to-end light-to-world response of about 0.7 s, supporting a complete level-transition and death-respawn flow, and confirming that a pure-CPU renderer plus an ambient sensor is a viable technical route for educational embedded devices.

Keywords: IMX6ULL; Software rasterisation; RGB565; AP3216C; I²C; Fixed-point; Platformer; Embedded Linux

目录

1 专业方向综合实训概述　1 　1.1 实训目的　1 　1.2 实训任务　1 　1.3 实训要求　1 　1.4 环境及可持续性发展　2 2 平台与总体设计　3 　2.1 IMX6U 平台约束　3 　2.2 分层架构与依赖方向　3 　2.3 关键技术选型　4 3 Core 底层渲染库设计　5 　3.1 平台抽象与显示后端　5 　3.2 FrameBuffer 与统一像素格式　6 　3.3 DrawContext 绘制入口　7 　3.4 Sprite 与 Tilemap 数据结构　7 　3.5 整数定点与热路径规则　8 　3.6 Timer 与固定帧率　9 4 LightGame 游戏系统实现　10 　4.1 主循环与初始化　10 　4.2 Physics2D：亚像素积分物理　10 　4.3 PlayerController：状态机与二段可变高跳跃　11 　4.4 Camera2D：整数平滑跟随　12 　4.5 Level / Room：数据驱动的关卡与房间网格　12 　4.6 LevelRenderer：分层合成顺序　13 　4.7 GameStateManager 与 HUD　13 5 光敏传感器与游戏机制耦合　14 　5.1 AP3216C 与出厂驱动的问题　14 　5.2 i2c 直读方案与 I2C_SLAVE_FORCE　14 　5.3 Q8 定点 EMA 滤波　15 　5.4 光照 → 对象通断（LightEffectSystem）　16 　5.5 光照 → 地形几何显隐　16 　5.6 光照 → HUD 视觉反馈与手动调试通道　17 6 跨平台构建与调试　18 　6.1 CMake 选项与条件编译　18 　6.2 LevelEditor：PC + Debug 独占的关卡编辑器　18 　6.3 调试流程与验证方法　19 7 功能测试与验证　20 　7.1 渲染性能与帧率测试　⟨待补⟩ 　7.2 传感器响应曲线测试　⟨待补⟩ 　7.3 关卡完整通关测试　⟨待补⟩ 8 工作总结与展望　21 参考文献　22

1. 专业方向综合实训概述

本节整体框架待课程正式发布"实训任务书"后按其标题与要点回填；当前保留与《MIPS 单周期处理器设计》一致的骨架。

1.1 实训目的

⟨待课程发布后按任务书表述回填；预期覆盖点：嵌入式 Linux 应用开发能力、外设驱动理解、软硬件协同的系统性思维、以中小型工程项目锻炼工程管理与文档能力。⟩

1.2 实训任务

在 IMX6ULL 平台上，独立完成一款可交互的图形化应用：包含图形渲染、外设输入、状态管理三块能力，并至少集成一路板载传感器作为输入源。

1.3 实训要求

⟨待课程发布后按任务书回填。当前预设要点：⟩

使用 C/C++11，兼容嵌入式老工具链，代码经过 PC 与 ARM 交叉编译双路径验证；
界面运行分辨率不低于 1024×600，图形帧率不低于 30 FPS；
至少接入一路 I²C 或 SPI 外设并读取有效数据；
项目需具备明确的分层结构与文档，能够独立部署到板端运行；
提供实训报告与相关演示材料。

1.4 环境及可持续性发展

本次实训以 IMX6ULL 教学板 + PC 交叉开发环境为主，全过程使用软件仿真与实机验证结合。板端不需要额外硬件改造，桌面端使用 SDL2 模拟显示与输入，避免了反复烧写调试造成的电子元件损耗；同时项目采用离线资源转换（PNG → C 头文件、TTF → 位图字体 mask）方式，运行时不解码原始素材，减少 CPU 空转能耗，与嵌入式设备低功耗、长时运行的场景要求一致。项目分层清晰，Core 底层库可复用到后续其他嵌入式图形项目，符合可持续开发原则。

2. 平台与总体设计

2.1 IMX6U 平台约束

本项目的目标硬件为正点原子 IMX6ULL 教学开发板，其核心为 ARM Cortex-A7 单核处理器，未集成独立 GPU，显示输出通过直接向 /dev/fb0 写入帧缓冲完成，板载的 AP3216C 光/接近传感器则挂载在 I²C-0 总线上。与常见的移动 SoC 相比，该平台在图形计算、数值运算和输入通道三方面呈现出明显的资源约束，直接决定了后续渲染框架和游戏实现的技术路线。

在图形栈方面，IMX6ULL 不提供任何硬件加速，三角形填充、精灵位图、字体掩码等所有绘制操作都必须由 CPU 逐像素完成，因此渲染管线的热路径必须尽量降低计算开销。在数值运算方面，虽然 Cortex-A7 支持 VFPv4 浮点单元，但浮点指令的延迟和功耗均高于整数指令，在逐像素长循环中应避免使用浮点运算，以保证 30 FPS 的帧率预算。在输入通道方面，按键、触摸和传感器分别通过 evdev、tslib 和 i2c 字符设备或 sysfs 访问，内核并未提供统一的事件循环，应用层需要自行轮询各类设备状态。

上述约束共同决定了本项目的整体技术路线：核心渲染与游戏逻辑采用整数化计算，帧缓冲以单帧一次 memcpy 的方式提交，热路径避免堆分配，并将显示与输入细节完全抽象到平台层，从而使上层代码在 PC 与板端之间保持一致。

2.2 分层架构与依赖方向

为了保证代码在 PC 调试与 IMX6U 板端运行之间能够无缝迁移，项目采用严格的单向依赖分层，模块命名与目录结构一一对应（详见 docs/APP_AND_CORE_ARCHITECTURE.md），总体依赖方向为 Apps -> Shared -> Core -> Platform。其中，Platform 层位于最底层，负责屏蔽 SDL2、/dev/fb0、ALSA、evdev、I²C 等具体平台差异，向上以 IDisplay、ITimeSource、IButtonInput、IKeyboardState、IPointerInput、IPhotoSensor 等纯虚接口提供显示、时钟、按键、键盘、指针和光敏传感器能力；Core 层建立在 Platform 接口之上，包含 FrameBuffer、DepthBuffer、DrawContext、Rasterizer、Tilemap、Sprite、BitmapFont、Timer 等与具体游戏无关的运行时组件，为上层应用提供统一的 2D 渲染与定时服务；Apps 层位于最顶层，是各具体游戏的实现位置，本文的核心应用 LightGame 即位于 src/Apps/LightGame/，同项目中其他同学负责的 Game（Tom 游戏）与 Demo 也处于该层，但彼此独立、不存在直接依赖。需要说明的是，Shared 层按规划用于存放应用层共享的 UI、存档、配置等模块，当前目录结构中尚未填充具体实现，因此现有代码的实际依赖路径可视为 Apps -> Core -> Platform。

单向依赖通过 CMake target 与 include 路径共同约束：Core -> Apps、Platform -> Apps 以及 GameA -> GameB 这类反向引用都会在编译期直接暴露，从而避免平台代码或底层库被应用层细节污染。由于本文作者主要负责 Core 底层库与 Apps/LightGame 光敏平台跳跃游戏的实现，后续章节将围绕这两部分展开，仅在必要处引用另一位合作者负责的模块。

2.3 关键技术选型

在语言标准方面，项目选用 C++11，以兼容老旧的嵌入式交叉工具链（如 gcc-linaro-4.9.4），避免因引入 C++14/17 特性而导致板端编译失败。在帧缓冲格式方面，统一采用 RGB565，该格式与 IMX6ULL 板载 LCD 的物理显存布局一致，PC 端 SDL2 同样以 RGB565 streaming texture 接收，从而在全链路中省去像素格式转换。在精灵资源格式方面，采用 RGBA5551 的 1-bit 透明打包，足以表达像素风素材，同时把 5 位通道扩展到 RGB565 的转换成本限制在已知范围内。

在数值系统方面，核心路径统一使用整数运算，并在亮度调制和光敏滤波等场景引入 Q8/Q7 定点数，以屏蔽 VFP 浮点开销并消除浮点精度抖动。在显示后端方面，通过 Platform::IDisplay 抽象出 FBDisplay 与 SDLDisplay 两套实现，PC 与 ARM 共用同一份游戏和渲染代码。在输入抽象方面，按键、键盘、指针和光敏传感器分别对应 IButtonInput、IKeyboardState、IPointerInput 和 IPhotoSensor 接口，DefaultHardware.h 按平台做 typedef 切换，使得上层应用无需使用 #ifdef。在传感器读取方面，AP3216C 不依赖出厂字符设备驱动，而是直接通过 /dev/i2c-0 抢占地址并重配置寄存器，以获得稳定可用的 ALS 数据。

上述选型共同服务于一个目标：在嵌入式路径上保持整数化和固定像素格式，在 PC 路径上通过接口复用同一份实现，从而保证双平台下画面等价、行为一致，同时降低跨平台验证与后续维护的成本。

3. Core 底层渲染库设计

3.1 平台抽象与显示后端

Platform::IDisplay 是一个仅包含四个方法的纯虚接口：init(width, height)、present(const Core::FrameBuffer*)、poll_events(bool& should_quit) 与 shutdown()。它的核心思想是把“如何把像素缓冲送到屏幕”这一平台相关细节完全隔离到平台层，游戏逻辑只关心一块 RGB565 帧缓冲的内容。

3.1.1 FBDisplay（IMX6U 板端）

在 IMX6ULL 板端，FBDisplay 打开 /dev/fb0，通过 ioctl 读取 FBIOGET_FSCREENINFO 与 FBIOGET_VSCREENINFO 获取像素格式和行步长，随后用 mmap 将整块显存映射到用户空间指针 fb_mem。present() 根据 vinfo 中的 R/G/B 位掩码分三条路径提交：若面板本身就是 RGB565 且 line_length == width * 2，则一次性 memcpy 完成提交；若行步长不等，则改为逐行 memcpy。对于 ARGB8888 或 RGBA8888 面板，则对每个像素做 5→8 位扩展并重新排列字段。其余配置统一走 convert_pixel()，根据运行时读取的位掩码构造输出像素，保证对未知 fb 格式的兼容性。

板端没有 SDL 事件循环，poll_events 使用 select(STDIN_FILENO, timeout=0) 非阻塞检测 q 或 Q 键，使主循环不会被输入阻塞。shutdown 在 munmap 前先用 memset 清屏，避免程序退出后屏幕残留最后一帧画面。

3.1.2 SDLDisplay（PC 端）

PC 端 SDLDisplay 创建 SDL_Window、SDL_Renderer(SDL_RENDERER_ACCELERATED) 以及格式为 SDL_PIXELFORMAT_RGB565、访问模式为 STREAMING 的 SDL_Texture，与核心 FrameBuffer 的像素格式严格一一对应。present() 只需一次 SDL_UpdateTexture、SDL_RenderCopy 与 SDL_RenderPresent。这种设计让 PC 侧无需为像素格式转换编写第二条路径，确保 PC 与 ARM 的可见画面完全等价。

3.1.3 时间源与输入

Platform::ITimeSource 独立于显示层，提供单调递增的整数毫秒时钟：Windows 实现基于 std::chrono::steady_clock，Linux 实现基于 clock_gettime(CLOCK_MONOTONIC)，返回值均为 uint32_t，49 天回绕在一次游戏运行中可以忽略。按键、键盘与指针输入也采用同样模式——接口定义位于 Core/Platform/，ARM 端由 Evdev 系列实现，PC 端由 Sdl 系列实现，DefaultHardware.h 通过 typedef 决定调用点看到的具体类型。这种方式使得 LightGameApp 中不存在任何用于选择平台输入实现的 #ifdef TARGET_IMX。

3.2 FrameBuffer 与统一像素格式

Core::FrameBuffer 在构造时一次性分配大小为 width * height 的 std::vector<uint16_t> 作为 RGB565 像素缓冲，整个运行期间不再进行堆扩展。为了服务热路径绘制，它对外提供 set_pixel_unsafe(x, y, rgba32) 接口，调用方需自行保证坐标落在合法范围内，函数内部仅执行一次数组写入。颜色转换由头文件中的内联函数 rgba_to_frame_pixel 完成，其表达式仅包含 R 右移 3 位、G 右移 2 位、B 右移 3 位后的位或，编译器能够将这一短转换折叠进精灵和瓦片的内层循环。get_buffer() 返回缓冲区的原始指针，供 FBDisplay 或 SDLDisplay 直接 memcpy 或 SDL_UpdateTexture 使用，避免额外的数据拷贝。

与 FrameBuffer 配套的还有 Core::DepthBuffer，它同样使用 uint16_t 存储每个像素的深度值，清空时写入 0xFFFF 表示最远，语义为“值越小越近”。该缓冲主要服务于三角形光栅化路径，虽然 LightGame 作为纯 2D 游戏并不使用其内容，但 DrawContext 仍统一持有它，以保持渲染 API 的完整性和未来向 3D 扩展的可能性。

3.3 DrawContext 绘制入口

Core::DrawContext 是整个渲染管线的门面对象，构造时创建 FrameBuffer、DepthBuffer、Rasterizer 与 TriangleRasterizer 各一份，禁止拷贝和移动，所有动态分配集中在构造与析构阶段完成，运行期不再出现 new/delete。游戏层通过它访问的接口包括清屏、绘制线段与三角形、精灵与瓦片绘制、填充矩形与位图文本，以及最终的 present(IDisplay*) 帧提交。

在精灵绘制热路径上，源图集以 RGBA5551 格式存放，blit_sprite_pixels 在外层根据目标矩形完成一次屏幕裁剪，确定 start_dx / dy 与 end_dx / dy 区间；内层则是一个紧凑的 for(sy) for(sx) 双循环，行指针 dst_row 在外层预先算出，水平/垂直翻转通过对读索引的三元表达式实现，编译器可将其优化为条件传送，避免在内层引入分支。此外，scale == 1 与 scale > 1 两条路径分开实现，前者内层不含除法。1-bit 透明通过 rgba5551_is_opaque 的位测试跳过，路径上没有任何 alpha 混合或乘法，最短流程每像素仅一次读取、一次测试和一次写入。

瓦片绘制同样遵循整数化原则。draw_tilemap_shaded 以 shade_numerator / (1 << shade_shift) 的整数比例对每个颜色通道做定点缩放，具体实现细节见 §3.5。

3.4 Sprite 与 Tilemap 数据结构

RenderData::Sprite 被设计为一个轻量视图，仅保存指向源图集的 const Image* atlas 以及一个 (x, y, w, h) 子矩形，不持有像素数据本身。Image 则保存 const void* pixels 指针与宽高信息，像素默认按 RGBA5551 格式解释。所有精灵源图集在离线阶段由 tools/png_to_header.py 转换为 C 头文件中的 RGBA5551 uint16_t 数组，运行时不解码 PNG，也不进行格式转换，从而消除了运行时解析开销。

RenderData::Tilemap 用 uint16_t tile_id 表示地图网格，0xFFFF 作为空瓦片哨兵；当前实现支持单一 atlas 与固定 tile 尺寸，结构内同时保存地图宽高、tile 宽高和 atlas 列数。draw_tilemap 的裁剪分两层执行：首先在瓦片层根据相机位置计算 start_tile_x = camera_x / tile_w，并向左右、上下各多取一格，以覆盖像素级滚动时露出的一半瓦片；然后在像素层对每个瓦片按视口子矩形做进一步裁剪，只绘制实际可见部分。DrawContext 还提供了带 viewport_w / viewport_h 的重载，允许把地图渲染限制在屏幕上的任意子矩形内，LightGame 利用这一能力在屏幕顶部留出 24 px 的 HUD 黑边。

3.5 整数定点与热路径规则

为了在 IMX6ULL 上稳定达到 30 FPS，项目对核心渲染与游戏逻辑制定了严格的整数化约束：除导入导出、调试打印和上层表示等非热路径外，核心代码禁止使用浮点类型。这一约束贯穿于绘制、物理、光照滤波等各个环节。

在亮度调制场景中，draw_tilemap_shaded 接收 (numerator, shift) 参数，对每个颜色通道计算 (component * numerator) >> shift，其中绿通道还需做 5→6 位扩展 (g << 1) | (g >> 4)，以高位补齐低位的方式保持亮度分布均匀。整个乘法链仅包含整数乘法和右移，没有浮点参与。光敏值的平滑滤波采用 Q8 定点实现，HUD 光条颜色渐变同样使用纯整数运算，具体内容分别见 §5.3 和 §4.7。物理系统则以 int32 px/s 存储速度，并通过亚像素累加器完成位移积分，从而避免浮点累积误差。

3.6 Timer 与固定帧率

Core::Timer 负责控制主循环节奏，只接受 30、45、60 FPS 三档目标帧率，其它值会回退到 30。为了避免整数除法 1000 / 30 = 33 带来的截断误差累积，它采用余数累积法计算每帧的固定时间片：

tick_remainder_ += 1000;
fixed_delta_ms_  = tick_remainder_ / fps;
tick_remainder_ %= fps;

在 30 FPS 下，上述代码会依次产生 33、33、34、33、33、34……毫秒的 tick，每 30 帧累加恰好为 1000 ms，与真实时间保持零漂移。remaining_frame_ms(now_ms) 则给出当前帧剩余的睡眠预算，主循环通过一次 std::this_thread::sleep_for 消化这部分时间，从而把帧率稳定在目标值附近。

4. LightGame 游戏系统实现

4.1 主循环与初始化

src/Apps/LightGame/src/main.cpp 中的主循环遵循“初始化 → 固定时间片更新 → 绘制 → 帧提交 → 睡眠等待”的朴素结构。初始化阶段首先根据 TARGET_IMX 或 TARGET_PC 宏创建对应的 Platform::IDisplay 实现，随后实例化 DefaultButtonInput、DefaultKeyboardState、DefaultPointerInput 与 DefaultPhotoSensor，这些具体类型由 DefaultHardware.h 按平台 typedef 决定。Core::DrawContext 和 Core::Timer 随后以 1024×600 分辨率和 30 FPS 目标创建，LightGameApp 拿到输入、显示和时间源的指针后进入主循环。

Platform::IDisplay* display = CreateDisplay();        // 后端由 TARGET_IMX/PC 决定
display->init(ScreenWidth, ScreenHeight);
Platform::DefaultButtonInput buttonInput;
Platform::DefaultKeyboardState keyboardState;
Platform::DefaultPointerInput pointerInput;
Platform::DefaultPhotoSensor photoSensor;
// ... 初始化每个输入设备
Core::DrawContext ctx(ScreenWidth, ScreenHeight);
Core::Timer timer(30);
Platform::SteadyTimeSource time_source;
LightGame::LightGameApp app(...);

while (!should_quit) {
    timer.begin_frame(time_source.get_time_ms());
    display->poll_events(should_quit);
    buttonInput.update();
    pointerInput.update();
    app.update(timer.fixed_delta_ms());
    app.draw(ctx);
    // 帧提交：IMX 走 ctx.present(display)，PC 直接 SDL_UpdateTexture
    SleepRemainingFrameTime(timer, time_source);
}

app.draw 完成所有游戏对象的绘制，ctx.present(display) 在板端通过 FBDisplay 一次性提交到 /dev/fb0。PC 端的主循环则直接使用 SDL_UpdateTexture 与 SDL_RenderCopy 上传帧缓冲，以便与 SDL 渲染器和调试用的 ImGui 叠加；这是为 PC 调试生态刻意保留的分层例外，板端代码路径仍然严格遵守 IDisplay 抽象。SleepRemainingFrameTime 在每帧末尾消耗由 timer.remaining_frame_ms 计算出的剩余时间，从而把实际帧率稳定在 30 FPS 附近。

4.2 Physics2D：亚像素积分物理

Physics2D 是 LightGame 的物理层，默认参数为重力 800 px/s²、最大下落速度 600 px/s、地面摩擦力 900 px/s²。所有速度均以 int32 px/s 为单位存储，位移积分通过亚像素累加器完成。Physics2D 内部维护两个 int32_t 余数 sub_pixel_x_ 与 sub_pixel_y_，每帧先把 velocity * dt_ms 累加到余数上，再除以 1000 得到整像素位移并保留余数：

sub_pixel_x_ += velocity.x * dt_ms;   // 单位：px·ms/s
int32_t dx = sub_pixel_x_ / 1000;
sub_pixel_x_ -= dx * 1000;            // 保留亚像素余数

以 50 px/s 的速度、33 ms 的帧时间为例，一帧的理论位移仅为 1.65 像素，若没有亚像素累加器，整除截断会导致物体静止或出现帧率相关的抖动；引入累加器后，这些微小位移会在多帧间累积并正确兑现。

碰撞解算采用最小分离轴策略。对于 Tilemap 碰撞，Physics2D 先根据 world_collider 算出覆盖的 tile 范围，再遍历每个 solid tile，分别计算左右上下四个方向的穿透深度，选择绝对值最小的方向将物体推出，同时清零该轴的速度和亚像素余数，防止冲量遗留。动态实体之间的碰撞同样使用四方向最小分离，但仅清零速度而保留亚像素余数，这样当多个移动平台轻微重叠时，余数可以在下一帧帮助抵消抖动。若对象掉出地图底端 128 像素以外的安全裕量，则会被标记为 active = false，避免进入无限下坠的死循环。

4.3 PlayerController：状态机与二段可变高跳跃

PlayerController 的运动参数默认值如表所示。

项	值	说明
move_speed	200 px/s	水平最大速度
acceleration	1200 px/s²	起步加速度
deceleration	1600 px/s²	松开方向后的减速
jump_velocity	−420 px/s	一次跳跃的初速
jump_cut_multiplier	40 %	松开跳跃时上升速度按 40% 截断

角色状态机在 Idle、Running、Jumping、Falling、Dead 五个状态之间转移，每帧根据 grounded、move_dir 和 velocity.y 的组合确定下一状态，没有隐藏状态。输入处理同时支持键盘与触摸屏：键盘使用 ←/→ 控制水平移动、↑ 控制跳跃；触摸屏则将屏幕上半区映射为跳跃，左三分之一和右三分之一分别映射为向左和向右移动。当两者同时存在时键盘优先覆盖触摸，因此同一份 PlayerController 既能在 PC 上调试，也能在 IMX6U 触摸屏上直接运行，无需平台分支。

可变高跳跃通过检测跳跃键的按下沿和释放沿实现。起跳时若按键按住，角色获得 −420 px/s 的初速度；在上升阶段（velocity.y < 0）一旦检测到按键释放，立即将竖直速度按 jump_cut_multiplier / 100 截断为原来的 40%。轻按即小跳、长按即高跳，这是平台跳跃类游戏的常见手感设计。

死亡判定分为两种情况。第一种是角色位置越过关卡底部边界，立即进入 Dead 状态。第二种是碰到尖刺 tile，此时只有碰撞体进入 tile 顶部向下 14 px 的区域内才会判定死亡，边缘擦过不会触发。这一 14 px 的杀伤区在源码中以注释明确说明，是刻意保留的手感缓冲。

4.4 Camera2D：整数平滑跟随

Camera2D 是一个完全整数化的死区跟随相机。其实际视口为 1024 × (600 − 24) 像素，顶部留出 24 px 给 HUD 黑边；水平与垂直死区分别为 60 与 40 像素，平滑系数 smooth_shift_ 固定为 3。跟随算法的核心思想是：先计算目标点与视口中心的偏移，若偏移超出死区的一半，则将偏移右移 3 位作为本次移动步长；由于右移结果可能为 0，此时用 ±1 像素兜底，防止相机停留在 1~7 像素的残余距离上无法追齐。

int32_t dx = target.x - (position.x + viewport.w / 2);
if (abs(dx) > dead_zone.w / 2) {
    int32_t step = dx >> smooth_shift_;      // 整数近似指数平滑
    if (step == 0) step = (dx > 0 ? 1 : -1); // 避免残余不动
    position.x += step;
}
// y 轴同理
clamp_to_bounds();

用右移代替除法（dx >> 3 等价于 dx / 8）不仅避免了浮点运算，在 ARM 上也是最廉价的分频方式。每帧更新后，相机位置还会被钳制到当前房间的边界内；当房间尺寸小于视口时，相机会直接吸附到房间的左上角，形成类似“回信箱”的取景效果，常用于竖直井道等狭小空间。

4.5 Level / Room：数据驱动的关卡与房间网格

LightGame 的关卡数据完全离线烘焙，运行时不需要任何文件 I/O。LevelData 是一个 POD 结构，包含前景/背景 tile 数组指针、ObjectSpawn 对象生成表、TileLightRule 光照规则表、出生点坐标与地图边界。所有这些内容都在 src/Apps/LightGame/src/levels/*.h 中以 C 数组形式给出，编译期即定案。

Level 类在内存中持有三份 tile 缓冲区视图：original_tiles_ 保存只读的原始地图，tile_buffer_ 作为可写的运行时前景，background_tiles_ 作为可写背景。LightEffectSystem::update_tilemap 根据 TileLightRule 在这三份视图之间操作：当光照落在规则窗口内时，从 original_tiles_ 恢复对应格子；否则写入 EmptyTile（0xFFFF）。由于每次操作只涉及规则数量而非整张地图，其复杂度为 O(rules)。

RoomLayout 则用整数网格把大关卡切分成若干矩形房间。RoomGrid 包含列数、行数、每个房间的像素宽高以及 RoomDef 数组，查询 room_index_of(grid, world_pos) 只需两次整除加上边界钳制即可得到当前房间索引。每个 RoomDef 携带 RoomBounds 与 default_spawn，切换房间时相机会立即更新边界，其它房间的检查点自动失效，从而形成类似 Metroidvania 的分区探索体验，同时避免了运行时加载关卡的额外开销。

4.6 LevelRenderer：分层合成顺序

LevelRenderer 每帧按照从远到近的顺序合成画面。首先绘制可选的背景 tilemap，调用 draw_tilemap_shaded 并指定 shade_numerator=80、shade_shift=7，即以 80/128 的整数比例将背景压暗到约 0.625 倍亮度，全部通过定点乘法完成，不引入浮点。接着绘制前景 tilemap，使用未经调暗的 draw_tilemap 快路径。然后遍历对象数组绘制非玩家对象，绘制前通过 LightEffectSystem::should_render 判断可见性：对于 LightPlatform、ShadowPlatform 和 Door，无论其当前 solid 状态如何都保持渲染，以便玩家读取光照规则；其它对象则以 obj.solid 作为是否绘制的依据。最后绘制玩家精灵，使其始终位于最上层。

在 IMX6U_DEBUG 调试构建中，LevelRenderer 还会追加一层 draw_debug，调用 Rasterizer::DrawLine 为每个活动对象绘制轴对齐碰撞盒，不同对象类型使用不同颜色。这也是当前项目中 Rasterizer::DrawLine 的主要使用场景。

4.7 GameStateManager 与 HUD

GameStateManager 管理游戏的高层状态机，包含 Title、Playing、Paused、GameOver、LevelComplete 五个状态。ESC 键通过 esc_was_down_ 进行边沿检测，确保每次按键只触发一次状态切换；Title 状态下开始提示以 500 ms 为周期闪烁，引导玩家按键进入游戏。

HUD 由 GameStateManager 与 LightGameApp 协作绘制。屏幕左上角有一条宽 80 px 的光照指示条，其填充宽度为 light_level * 78 / max_light_level，填充颜色使用整数线性梯度：红色分量随光照增强而减小、绿色分量随光照增强而增大，黑暗时偏红、明亮时偏绿，玩家可以一眼判断当前光照区间。右上角显示当前关卡号 LV{n}，左下角显示金币数 × n，左侧还以小红块阵列表示剩余生命数。暂停时屏幕中央绘制一个半透明遮罩，当前使用 Color(0, 0, 0, 200)，但由于 RGB565 帧缓冲没有 alpha 通道，实际显示为纯黑遮罩，这是渲染管线带来的已知表现限制。

5. 光敏传感器与游戏机制耦合

本节是本次实训中作者认为最有信息含量的部分：光敏传感器不是简单的"控件"，而是一条完整的传感-滤波-语义映射链。

5.1 AP3216C 与出厂驱动的问题

AP3216C 是一颗集环境光（ALS）、接近（PS）和红外（IR）于一体的三合一传感器芯片。IMX6ULL 教学板的出厂内核提供了 ap3216c 字符设备驱动，用户空间理论上可以通过 open("/dev/ap3216c") 再 read() 获取 ALS/PS/IR 三个字节的数据。但在实测中，这条路径并不可靠，主要表现为两个方面。

一方面，read() 经常返回 EINVAL 或读到全零。其根本原因在于出厂驱动将 SysConfig(0x00) 配置为 0x03，即 ALS、PS、IR 同时开启，而 ALS 采样与 PS 中断共用同一 ADC 通道；当 PS 触发中断采样时，会打断 ALS 的转换过程，用户空间如果在两次触发之间读取，就可能拿到未完成转换的旧值或全零。

另一方面，该内核驱动已经占用了 I²C-0 总线上 0x1E 地址，i2cdetect -y -r 0 会显示该地址为 UU（被内核持有）。此时普通的 ioctl(I2C_SLAVE, 0x1E) 会返回 EBUSY，用户态程序无法再通过标准 I²C 从设备接口与该地址通信。

因此，为了获得稳定、随环境变化的 ALS 数据，项目选择绕开出厂字符设备驱动，直接通过 /dev/i2c-0 与 AP3216C 芯片寄存器对话。这也是后续 i2c 直读方案的设计出发点。

5.2 i2c 直读方案与 I2C_SLAVE_FORCE

Ap3216cPhotoSensor 的实现思路是直接打开 I²C 总线节点 /dev/i2c-0，然后使用 ioctl(fd_, I2C_SLAVE_FORCE, 0x1E) 强制占用 0x1E 地址，从而跳过内核驱动的锁检查。初始化阶段向 AP3216C 写入两组配置：一是将 SysConfig(0x00) 设为 0x01，切换到 ALS-only 连续采样模式，避免 PS 中断打断 ALS；二是将 AlsConfig(0x10) 设为 0x30，使增益位 gain[5:4]=11，选择 323 lux 满量程的最大增益档位，以充分利用 12 位 ADC 的室内光分辨率。

fd_ = open("/dev/i2c-0", O_RDWR);
ioctl(fd_, I2C_SLAVE_FORCE, 0x1E);        // 强占地址，忽略 UU 状态
// SysConfig(0x00) = 0x01 → ALS-only 连续采样
write(fd_, {0x00, 0x01}, 2);
// AlsConfig(0x10) = 0x30 → gain[5:4]=11，full scale 323 lux，最大增益
write(fd_, {0x10, 0x30}, 2);

之后，每帧 update() 执行两次“写寄存器地址再读一字节”的事务，分别读取 0x0C（ALS 低字节）和 0x0D（ALS 高字节），组合成 uint16_t als = (hi << 8) | lo 并钳制到 4095。如果某次读取失败，驱动层保留上一次的值，防止单次 ETIMEDOUT 造成亮度归零跳变，其余平滑处理交由应用层完成。

这一方案有几个关键点。首先，I2C_SLAVE_FORCE 是必须的，因为普通 I2C_SLAVE 在地址已被内核驱动持有时会返回失败，只有 _FORCE 版本能跳过锁检查，实现用户态与内核驱动共享同一 I²C 地址。其次，ALS-only 模式让 ADC 只服务 ALS 通道，采样率稳定在数据手册标称的连续模式（约 100 ms/次），足以满足 30 Hz 主循环的需求。再次，最大增益 323 lux 的满量程比 20 kLux 低增益档位更适合室内环境，能把台灯、手电或手遮挡产生的光强变化映射到 12 位 ADC 的有效区间。最后，驱动层仅做“读失败保持上值”这一最小容错，不做额外平滑，避免在板端引入不必要的计算。

5.3 Q8 定点 EMA 滤波

原始 ALS 值在手指快速晃过或荧光灯高频闪烁时抖动明显，直接在 12 位裸值上驱动游戏会导致对象和地形频繁通断。为此，项目在 LightGameApp 中引入了一级 Q8 定点一阶指数移动平均（EMA）滤波，核心代码如下：

// 状态：smoothed_light_q8_（int32，= real 值 × 256）
int32_t target_q8 = static_cast<int32_t>(raw) << 8;   // 12-bit → Q8
smoothed_light_q8_ += (target_q8 - smoothed_light_q8_) >> 4;  // α = 1/16
uint16_t light = static_cast<uint16_t>(clamp(smoothed_light_q8_ >> 8, 0, 4095));

该滤波器的平滑系数 α 等于 2⁻⁴，即 1/16。在 30 Hz 采样率下，其截止频率约为 f_c ≈ f_s · α / (2π) ≈ 0.30 Hz，从 10% 上升到 90% 的响应时间约为 0.7 秒。这一速度对“举起手电”或“用手遮挡”这类交互而言较为舒适：既能滤除手指抖动和 ADC 量化噪声，又不会让玩家感到明显延迟。

采用 Q8 定点表示而非在 12 位裸值上直接滤波，是为了保留足够的头部空间。若直接对原始值执行 smoothed += (raw - smoothed) >> 4，当误差绝对值小于 16 时右移结果会归零，滤波器将停在错误值上不再更新。将数值左移 8 位到 Q8 后，即使差分很小也能被逐步吸收，从而保证缓慢变化的光照（例如拉窗帘）不会失锁。

在 PC 调试通道中，W/S 键以 ±256 的步长直接调节 manual_light_level_，并将 smoothed_light_q8_ 同步设置到对应值，因此手动模式与传感器模式之间切换时不需要额外过渡，光照变化保持连续。

5.4 光照 → 对象通断（LightEffectSystem）

LightEffectSystem::update(objects, light) 将滤波后的光照值映射到三类关卡对象的实体状态，具体规则如下表所示。

对象类型	逻辑	直觉解释
`LightPlatform`	`solid = light >= threshold.min_level`	被点亮时才凝固的平台
`ShadowPlatform`	`solid = light <= threshold.max_level`	只在阴影里存在的平台
`Door`	`solid = !(min ≤ light ≤ max)`	在给定亮度窗口内才开门

对象的 solid 字段直接决定 Physics2D 是否将其纳入碰撞解算：当 solid == false 时，玩家可以像穿过空气一样穿过该对象。视觉上，LightPlatform 和 ShadowPlatform 分别拥有 on/off 两组精灵，Door 拥有 closed/open 两组精灵，LevelRenderer 每帧根据当前 solid 状态切换贴图，实现“随光照凝固或消失”的效果。

这一设计的优势在于复用了 GameObject 已有的 solid 字段，物理层不需要为光敏对象编写特殊分支，代码路径保持统一；同时，关卡编辑器只需要为对象填写 min_level 和 max_level 两个 12 位整数，即可表达“在多亮时能够踩上去”的规则，制作过程直观且不易出错。

5.5 光照 → 地形几何显隐

除了移动对象的实体状态，光照还可以改变地形几何本身。TileLightRule 由 tile_x、tile_y、light_min 和 light_max 四个字段组成，LightEffectSystem::update_tilemap(level, light) 逐条规则进行判断：若当前光照值落在规则窗口内，则将 tile_buffer_[y*w + x] 恢复为 original_tiles_[y*w + x] 中的真实 tile；否则写入 Tilemap::EmptyTile（0xFFFF），使该格从前景中消失。

这里采用“原始 + 可变”双缓冲而不是原地翻转，是因为同一格子可能在不同光照窗口下多次进出，必须以 original_tiles_ 作为权威真相。这种设计让地图本身能够随光照消失或浮现，例如光下才显形的桥、暗中才崩塌的地板等效果，都可以通过规则配置实现。由于每次更新只涉及规则数量而非整张地图，其时间复杂度为 O(rules)，与地图尺寸无关。

Tilemap::EmptyTile 同时被渲染层和物理层识别：渲染层遇到空瓦片跳过绘制，物理层的 is_solid_tile 对空瓦片返回 false。因此一次写入即同时完成“看不见”和“走得过去”两种语义，无需在其它系统中进行额外同步。

5.6 光照 → HUD 视觉反馈与手动调试通道

光照不仅影响游戏逻辑，也是玩家感知当前环境状态的第一视觉线索。HUD 左上角的光照指示条以颜色渐变实时展示当前 light 值，具体实现已在 §4.7 中说明。

在 PC 端开发时，由于没有真实的光敏传感器硬件，项目提供了手动调试通道：按下 W 或 S 键可以以 ±256 的步长调节 manual_light_level_，并置位 has_manual_override_ 标志，使游戏绕过传感器读取而使用手动值。这样开发者可以在桌面环境中验证所有光敏关卡逻辑，这也是关卡编辑器在无硬件条件下的主要测试手段。

此外，IPhotoSensor 的 PC 实现 SdlPhotoSensor 默认返回 2048，即 12 位量程的中点。该默认值保证桌面构建启动时处于“中等亮度”，避免开局黑屏或过度曝光，使调试体验与板端真实光照环境保持接近。

6. 跨平台构建与调试

6.1 CMake 选项与条件编译

顶层 CMakeLists.txt 通过两组开关驱动条件编译。第一组是 TARGET_IMX，默认关闭；开启时定义 TARGET_IMX 宏，将 FBDisplay、AlsaAudioInput、EvdevButtonInput 和 Ap3216cPhotoSensor 等板端实现编入核心库；关闭时则定义 TARGET_PC 宏，编入 SDLDisplay、SdlAudioInput、SdlKeyboardButtonInput、SdlPhotoSensor 等 PC 实现，同时把 third_party/imgui 一并加入构建。第二组是 $<CONFIG:Debug> 生成器表达式，仅在 Debug 构建中定义 IMX6U_DEBUG，用于门控关卡编辑器、ImGui、F1 切换、调试 HUD 与碰撞盒可视化等调试功能。

Apps/LightGame/CMakeLists.txt 复用了同一套开关，并通过生成器表达式把 LevelEditor.cpp 限制在 NOT TARGET_IMX AND CONFIG:Debug 的条件下，确保编辑器只在 PC + Debug 构建中进入源码列表，Release 或 ARM 交叉编译构建中连相关符号都不会产生：

set(LIGHTGAME_EDITOR_GUARD "$<AND:$<NOT:$<BOOL:${TARGET_IMX}>>,$<CONFIG:Debug>>")
target_sources(IMX6U-LightGame PRIVATE
    "$<${LIGHTGAME_EDITOR_GUARD}:${CMAKE_CURRENT_SOURCE_DIR}/src/editor/LevelEditor.cpp>")

DefaultHardware.h 把平台差异收敛到类型定义处，因此 LightGameApp 中没有任何用于选择输入或传感器实现的 #ifdef。唯一的平台分支保留在 main.cpp 中，围绕显示帧提交与 ImGui 叠加这一调试需求展开，属于为 PC 调试生态刻意保留的分层例外。

6.2 LevelEditor：PC + Debug 独占的关卡编辑器

LevelEditor 是一个基于 ImGui 的关卡编辑器，直接在内存中编辑 Level 实例。它提供四类主要功能：工具切换，包括 TileBrush、ObjectPlace、Select 和 Eraser；图层切换，可在 Foreground 与 Background 之间选择；属性面板，用于修改选中对象的类型以及光照阈值 min_level / max_level；导出功能，通过 export_to_header(name) 将当前 tile 数组与对象列表按 LevelData 期望的 C 头文件结构序列化后写入磁盘。

由于 LevelData 是编译期常量，编辑器的“导出”实际上是“生成新头文件 → 重新编译”的循环。这一权衡的好处是运行时零 I/O、零解码；代价是快速迭代时需要重新编译，时间约为几十秒。

在主循环中，F1 键用于切换编辑器可见性。ImGui_ImplSDL2_ProcessEvent 与 LightGameApp 的输入并行处理，当编辑器处于活动状态时，ImGui 焦点会接管键盘和鼠标事件，从而避免点击面板时误操作角色。

6.3 调试流程与验证方法

项目推荐分四步完成开发与验证。第一步是 PC + Debug：在 VS Code 或 MSVC 中编辑代码后，执行 cmake --build build-win --config Debug 并直接 F5 调试；此阶段利用 W/S 手动光照通道遍历所有光敏关卡逻辑，并通过 F1 打开关卡编辑器修关。第二步是 PC + Release：使用 --config Release 构建，验证发布态下的帧率与关键路径行为是否稳定。第三步是 ARM 交叉编译：执行 cmake -B build-arm-fb -DCMAKE_TOOLCHAIN_FILE=cmake/toolchain-arm-linux-gnueabihf.cmake -DTARGET_IMX=ON，随后将二进制通过 scp 传到板上，chmod +x 后直接运行；TARGET_IMX=ON 会自动启用 framebuffer 后端，/dev/fb0 与 /dev/i2c-0 在设备节点权限已配置好的情况下无需 root。第四步是板端验证：主循环内已包含光照读取失败时保持上次值的容错，观察重点包括光条是否随环境变化、检查点重生是否正常、跳过尖刺的 14 px 手感是否合理，以及房间切换时相机吸附是否到位。

7. 功能测试与验证

⟨本节等课程要求出来后再回填详细数据。以下先给测试项模板与预期指标。⟩

7.1 渲染性能与帧率测试

目标平台：IMX6U 教学板，1024×600，30 FPS 目标；
度量方法：主循环中埋点 time_source.get_time_ms() 记录每帧的 update / draw / present / sleep 四段时长，采样若干秒的均值/最大值；
预期结果：全场景稳定 30 FPS，sleep 阶段应占多数（说明未跑满 CPU）；无掉帧、无撕裂。

7.2 传感器响应曲线测试

度量方法：以已知光源分别做 (a) 覆盖—打开、(b) 缓慢遮挡两组动作，记录 raw 与 smoothed 曲线；
预期结果：raw 抖动明显，smoothed 上升到 90% 的时间约 0.7 s，无过冲、无稳态偏差。

7.3 关卡完整通关测试

步骤：从 Title 开始，走过所有房间，触发若干 LightPlatform / ShadowPlatform / Door 与 TileLightRule，中途死亡 ≥ 1 次以验证检查点重生，最终触达 LevelComplete；
预期结果：状态机无死锁，房间切换无穿墙，检查点在预期位置激活，HUD 计数正确。

8. 工作总结与展望

本次实训完成了两块相互支撑的工作。其一是 Core 底层渲染库，它将“在 IMX6ULL 这类无 GPU 平台上，用 RGB565 帧缓冲和整数运算实现可玩 2D 画面”的实践，固化为 IDisplay、DrawContext、Tilemap、Sprite、BitmapFont、Timer 等可移植接口。其二是 LightGame 光敏平台跳跃游戏，围绕板载 AP3216C 光敏传感器，实现了从 i2c 直读、Q8 定点 EMA 滤波，到光照驱动对象通断、地形几何显隐与 HUD 反馈的完整闭环，并支持检查点重生与房间切换。

从技术层面看，本次实训有三点关键收获。第一，在嵌入式实践中，当出厂驱动的默认配置无法满足应用需求时，直接通过 I2C_SLAVE_FORCE 抢占地址并重配置传感器寄存器，是获得稳定输入的最短路径。第二，无 GPU 平台的热路径必须保持整数化与定点化：RGB565 帧缓冲、RGBA5551 1-bit 透明、Q8 EMA、Q7 亮度缩放、亚像素累加物理等任何环节引入浮点，都会给 CPU 带来不必要的额外开销。第三，通过接口加 typedef 隔离平台差异，比在主逻辑中大量使用 #ifdef 更易于维护；DefaultHardware.h 使得 LightGameApp 基本保持平台无关，PC 端的 W/S 手动光照、F1 关卡编辑器等调试通道也因此能够与板端代码 cleanly 共存。

当前实现仍存在一些局限，也为后续工作指明了方向。HUD 的半透明渲染受限于 RGB565 缺少 alpha 通道，暂停遮罩目前只能退化为不透明黑色，未来可以在 DrawContext 中增加 dither 或整数混合的 fill_rect_blend 路径。关卡数据全部编译期烘焙意味着修改关卡需要重新编译，后续可考虑将 LevelData 打包为板上可读的紧凑二进制并在启动时 mmap，以换取运行时改关能力，代价是增加一次 I/O 与解析。音频链路 IAudioInput / IAudioOutput 虽已抽象，但 LightGame 尚未接入，后续可让光照状态驱动音效，进一步强化“环境即输入”的沉浸感。此外，Launcher、LightGame 与合作者的 Game 目前仍是独立可执行文件，docs/APP_AND_CORE_ARCHITECTURE.md 中已规划 IApp 接口与单进程多应用切换，尚待落地。

总体来看，本次实训验证了在 IMX6U 这类无 GPU 嵌入式教学板上构建完整图形化游戏的可行性。通过把渲染、输入、传感器等每一层细节重新掌握在应用代码中，项目不仅实现了稳定的 1024×600@30 FPS 画面，也加深了对软硬件协同设计的理解。

参考文献

[1] Freescale Semiconductor. i.MX 6UltraLite Applications Processor Reference Manual. Rev. 2, 2016. [2] LiteON. AP3216C Ambient Light and Proximity Sensor Datasheet. Rev. 1.5, 2015. [3] Linux Kernel Documentation. i2c/dev-interface — I²C/SMBus Character Device Interface. https://www.kernel.org/doc/Documentation/i2c/dev-interface (accessed 2026-07). [4] Linux Kernel Documentation. fb/api.txt — The Linux Frame Buffer Device API. https://www.kernel.org/doc/Documentation/fb/api.txt (accessed 2026-07). [5] SDL Community. Simple DirectMedia Layer 2.0 — Documentation Wiki. https://wiki.libsdl.org/SDL2/ (accessed 2026-07). [6] ⟨可选：正点原子.《I.MX6U 嵌入式 Linux 驱动开发指南》. 2020. ——若指导老师推荐加入⟩ [7] ⟨可选：唐佐林. 现代 C++ 嵌入式实战. 电子工业出版社, 2019. ——补充 C++11 相关引用⟩

46 KiB Raw Blame History Unescape Escape