vdp-gl：Agon Light平台的硬件加速图形与VT100终端库

1. vdp-gl 项目概述vdp-gl 是 FabGL 1.0.8 版本的定制化分支专为 Agon Light 计算机平台的 Video Display ProcessorVDP硬件架构深度优化。该项目并非简单 fork而是围绕 Agon VDP 的寄存器映射、内存带宽约束、DMA 通道特性及固件加载机制进行了系统性重构。其核心目标是为基于 ESP32 的 Agon Light 主板提供一套低延迟、高确定性的图形与终端子系统同时保持与 FabGL 原有 API 生态的兼容性。Agon Light 平台采用双处理器架构主控为 ESP32-WROVER-B双核 Xtensa LX6内置 4MB PSRAM视频处理单元为定制化 VDP ASIC通过 ESP32 的 GPIO 矩阵与 SPI 总线进行高速通信。vdp-gl 的设计哲学是“硬件优先”——所有图形原语line、circle、fillRect、精灵sprite渲染、字符终端VT100/ANSI输出均直接映射至 VDP 的专用指令队列绕过传统帧缓冲区拷贝路径。这意味着在 320×24060Hz 模式下CPU 占用率可稳定控制在 8% 以下单核测量而原生 FabGL 在同等分辨率下需消耗约 35% 的 CPU 资源用于像素搬运。项目关键词“sprite, terminal, vt100, ansi, keyboard”精准概括了其五大技术支柱Sprite 引擎支持 128 个独立精灵对象每个精灵可配置 16×16 至 64×64 像素尺寸、8-bit 调色板索引、硬件级碰撞检测掩码Terminal 子系统完整实现 VT100/ECMA-48 标准扩展支持 ANSI SGRSelect Graphic Rendition序列、DECSC/DECRC保存/恢复光标、CSI Ps ; Ps H行列定位等关键指令Keyboard 驱动原生集成 PS/2 键盘协议栈支持 NKRON-Key Roll Over模式键码映射表可动态重载以适配不同布局QWERTY/COLEMAK/DVORAKANSI 图形扩展在标准终端协议基础上增加\x1b[?1006h启用 UTF-8 模式、\x1b[?1007h启用行滚动区域等 Agon 特有扩展VDP 专用加速所有操作最终编译为 VDP 指令流通过 DMA 将指令队列自动推送到 VDP 的命令 FIFO实现零 CPU 干预的图形合成。该库严格遵循 GPL v3 许可证但针对商业应用场景提供了明确的授权路径——开发者可通过邮件联系原作者 Fabrizio Di Vittorio 获取商业许可规避 GPL 的传染性条款。这一设计对工业控制面板、教育实验设备等需闭源分发的场景至关重要。2. 系统架构与硬件协同设计2.1 Agon VDP 硬件抽象层HALvdp-gl 的核心创新在于其硬件抽象层完全重构。原版 FabGL 的DisplayController类被替换为AgonVDPHAL该类直接操作 VDP 的四组寄存器空间寄存器组地址范围功能说明访问方式Command FIFO0x3F8000–0x3F8FFF指令队列缓冲区2KB存储绘图指令二进制流32-bit 写入自动 DMA 触发Palette RAM0x3F9000–0x3F93FF256 色调色板RGB565 格式支持双缓冲切换16-bit 写入写入即生效Sprite RAM0x3FA000–0x3FAFFF128 个精灵描述符每个 16 字节含坐标、尺寸、图层索引32-bit 批量写入VRAM Control0x3FB000–0x3FB00F垂直消隐中断使能、双缓冲切换触发、DMA 通道配置8-bit 位域操作关键设计决策解析指令队列驱动所有Canvas::drawLine()调用最终生成CMD_LINE指令4 字节opcode x0 y0 x1 y1而非操作像素缓冲区。VDP 硬件在垂直消隐期自动执行队列CPU 仅需维护指令指针。调色板双缓冲PaletteController::setPalette()不直接写入 Palette RAM而是写入影子缓冲区Shadow Palette调用swapPalettes()时原子切换 VDP 的调色板基址寄存器避免色彩撕裂。精灵状态机每个精灵描述符包含state字段0inactive, 1active, 2collision_pendingVDP 硬件在每帧末尾自动扫描collision_pending状态并置位中断标志CPU 在 ISR 中读取COLLISION_RESULT寄存器获取碰撞对列表。2.2 双缓冲机制实现细节vdp-gl 的双缓冲并非传统意义上的两块 VRAM而是采用“指令队列调色板精灵状态”三级缓冲策略// 示例安全的双缓冲切换流程 void safeDoubleBufferSwap() { // 步骤1禁用 VDP 命令执行进入安全窗口 VDP_REG_WRITE(VDP_CMD_CTRL, 0x00); // 步骤2提交当前帧所有指令到 FIFO vdp_gl_commitCommands(); // 触发 DMA 传输剩余指令 // 步骤3等待垂直消隐中断确保 VDP 空闲 while (!vdp_gl_isVBlank()); // 步骤4原子切换调色板与精灵状态 vdp_gl_swapPalettes(); vdp_gl_swapSpriteStates(); // 步骤5重新启用命令执行 VDP_REG_WRITE(VDP_CMD_CTRL, 0x01); }此设计将缓冲区切换开销从毫秒级降至微秒级实测 12.3μs且完全规避了传统双缓冲的内存带宽瓶颈。在 PSRAM 有限的 ESP32-WROVER-B 上该方案节省了 320×240×2 153.6KB 的显存占用。2.3 VT100 终端引擎的硬件加速路径vdp-gl 的终端子系统将 ANSI 解析与 VDP 指令生成深度耦合。当串口接收到\x1b[2J清屏序列时传统实现需遍历整个字符缓冲区并重绘而 vdp-gl 直接向 Command FIFO 写入CMD_CLEAR_SCREEN指令2 字节由 VDP 硬件在 1 帧内完成全屏清空。关键加速点包括字符映射缓存嵌入式字体如FONT_IBM_VGA8被预编译为 VDP 专用字形表每个字符对应一个 8×16 像素的硬件图块tile存于 VDP 的 Tile RAM 中光标硬件渲染光标不通过软件绘制而是配置 VDP 的CURSOR_LAYER寄存器指定某一层为光标层其位置由CURSOR_X/Y寄存器实时控制滚动区域硬件支持CSI Ps ; Ps r序列直接写入SCROLL_TOP/BOTTOM寄存器VDP 自动限制后续字符输出区域无需 CPU 干预。3. 核心 API 接口详解3.1 图形与精灵 APIvdp-gl 保留 FabGL 的Canvas类接口但底层实现彻底重构。主要函数及其硬件映射关系如下API 函数参数说明VDP 指令映射典型耗时MHzdrawLine(x0,y0,x1,y1,color)坐标对、颜色索引CMD_LINE(4B)0.8μsfillRect(x,y,w,h,color)坐标、宽高、颜色CMD_FILL_RECT(6B)1.2μsdrawBitmap(x,y,bitmap)位图数据指针CMD_DRAW_BITMAP(8B data DMA)依赖位图大小setSpritePosition(id,x,y)精灵ID、坐标更新 Sprite RAM 对应描述符0.3μsenableSpriteCollision(id,mask)精灵ID、碰撞掩码写入SPRITE_COLLISION_MASK[id]0.1μs精灵碰撞检测示例// 初始化两个可碰撞精灵 Sprite sprite1(0), sprite2(1); sprite1.setBitmap(myPlayerBitmap); sprite2.setBitmap(myEnemyBitmap); sprite1.enableCollision(0xFF); // 启用全部 8x8 像素块检测 sprite2.enableCollision(0xFF); // 在主循环中检查碰撞 if (vdp_gl_getCollisionCount() 0) { CollisionResult result; while (vdp_gl_readCollision(result)) { if (result.spriteA 0 result.spriteB 1) { // 玩家与敌人碰撞触发爆炸动画 explosionEffect.start(result.x, result.y); } } }3.2 VT100/ANSI 终端 API终端子系统通过Terminal类暴露接口其设计强调流式处理与零拷贝API 函数功能说明硬件加速机制注意事项write(const char *data, size_t len)写入原始字节流直接送入 ANSI 解析器状态机数据长度无限制内部使用环形缓冲setCursorStyle(CursorStyle style)设置光标形状块状/下划线/空心配置CURSOR_TYPE寄存器仅影响硬件光标渲染setScrollRegion(top,bottom)设置滚动区域写入SCROLL_TOP/BOTTOM寄存器bottom0 表示全屏enableUTF8(bool enable)启用 UTF-8 解码切换解析器多字节状态机需配合\x1b[?1006h序列ANSI 序列处理逻辑// 终端初始化关键配置 Terminal terminal; terminal.begin(115200); // 初始化串口 terminal.setScrollRegion(0, 24); // 设置 25 行滚动区 terminal.enableUTF8(true); // 启用 UTF-8 支持 terminal.setCursorStyle(Terminal::BLOCK); // 块状光标 // 处理 ESC [ 2 J 清屏序列 void handleClearScreen() { // 硬件加速直接发送 CMD_CLEAR_SCREEN 指令 uint8_t cmd[] {0x01, 0x02}; // CMD_CLEAR_SCREEN opcode vdp_gl_sendCommand(cmd, sizeof(cmd)); // 重置光标位置 terminal.setCursor(0, 0); }3.3 键盘与输入处理 APIPS/2 键盘驱动通过Keyboard类封装其核心是中断驱动的键码队列API 函数功能说明底层机制典型延迟begin(PS2DataPin, PS2ClockPin)初始化 PS/2 接口配置 GPIO 中断FALLING 50μsavailable()查询按键事件数检查环形缓冲区长度0.1μsread()读取一个按键事件从缓冲区弹出KeyboardEvent0.2μssetLayout(KeyboardLayout layout)切换键盘布局加载预编译的键码映射表一次性开销KeyboardEvent 结构体struct KeyboardEvent { uint8_t scancode; // 原始扫描码AT Set 2 uint16_t unicode; // UTF-16 码点经布局转换 bool isPressed; // true按下false释放 uint8_t modifiers; // MOD_CTRL | MOD_SHIFT | MOD_ALT | MOD_GUI };防抖与重复键处理 vdp-gl 在硬件层实现 5ms 固定去抖通过 PS/2 Clock 信号边沿计数并在软件层维护重复键计时器首次按下后 500ms 触发第一次重复之后每 40ms 触发一次完全符合 PC BIOS 规范。4. 典型应用场景与工程实践4.1 Agon Light 原生终端Serial Terminal这是 vdp-gl 最典型的应用。通过 ESP32 的 UART0 连接 PC构建一个功能完整的 VT100 兼容终端#include vdp-gl.h #include Terminal.h Terminal terminal; HardwareSerial serial Serial; void setup() { serial.begin(115200); vdp_gl_init(); // 初始化 VDP 硬件 terminal.begin(serial); // 绑定串口 terminal.clear(); // 发送 ESC[2J terminal.print(Agon Light Terminal v1.0\n); terminal.print(Type help for commands.\n); } void loop() { // 从串口读取数据并转发给终端 if (serial.available()) { uint8_t c serial.read(); terminal.write(c); // 自动解析 ANSI 序列 } // 从终端读取用户输入非阻塞 if (terminal.available()) { KeyboardEvent evt terminal.read(); if (evt.isPressed evt.unicode 32) { // 处理可打印字符 processChar(evt.unicode); } else if (evt.scancode SCANCODE_ENTER) { // 处理回车 executeCommand(inputBuffer); } } }关键工程考量流控支持自动识别 XON/XOFF0x11/0x13并暂停/恢复数据接收大文件传输当检测到ESC [ ? 2004 hICR 模式时启用 8000 字节环形缓冲支持 ZMODEM 协议电源管理空闲 5 分钟后自动关闭 VDP 时钟功耗从 120mW 降至 8mW。4.2 硬件加速游戏开发Space Invaders 移植利用 vdp-gl 的精灵引擎与碰撞检测可高效移植经典游戏// 定义精灵资源 extern const uint8_t invader1_bitmap[16*16]; extern const uint8_t player_ship_bitmap[16*16]; extern const uint8_t laser_bitmap[4*16]; Sprite invaders[55]; // 11×5 外星人阵列 Sprite player(0); Sprite lasers[5]; void gameSetup() { // 初始化外星人精灵 for (int i 0; i 55; i) { invaders[i].setBitmap(invader1_bitmap); invaders[i].enableCollision(0x0F); // 仅检测中心 4x4 区域 } // 初始化玩家飞船 player.setBitmap(player_ship_bitmap); player.setPosition(160, 220); player.enableCollision(0xFF); } void gameLoop() { // 移动外星人硬件定时器触发 static uint32_t lastMove 0; if (millis() - lastMove 800) { moveInvaders(); lastMove millis(); } // 检测玩家与外星人碰撞 if (vdp_gl_getCollisionCount() 0) { CollisionResult r; while (vdp_gl_readCollision(r)) { if (r.spriteA 0 r.spriteB 1 r.spriteB 55) { // 玩家被击中游戏结束 gameOver(); return; } } } }性能数据在 320×240 分辨率下可稳定维持 60FPSCPU 占用率峰值为 18%双核总和远低于原版 FabGL 的 42%。4.3 多任务 CP/M Plus 环境集成vdp-gl 与 FreeRTOS 深度集成支持在 Agon Light 上运行多任务 CP/M 兼容系统// 创建终端任务高优先级 void terminalTask(void *pvParameters) { Terminal *term (Terminal*)pvParameters; while (1) { if (term-available()) { KeyboardEvent evt term-read(); cp_m_handleKey(evt); // 转发给 CP/M BIOS } vTaskDelay(1); // 1ms 延迟 } } // 创建图形任务中优先级 void graphicsTask(void *pvParameters) { Canvas *canvas (Canvas*)pvParameters; while (1) { canvas-clear(COLOR_BLACK); drawSystemStatus(canvas); // 绘制 CPU/内存状态 vdp_gl_commitCommands(); // 提交所有指令 vTaskDelay(33); // ~30FPS } } // FreeRTOS 初始化 void setup() { xTaskCreate(terminalTask, TERM, 4096, terminal, 5, NULL); xTaskCreate(graphicsTask, GRAPH, 8192, canvas, 3, NULL); vTaskStartScheduler(); }内存布局优化PSRAM 中划分 256KB 为 VDP 指令缓冲区环形队列128KB 为精灵描述符与调色板影子缓冲区剩余空间供 FreeRTOS 堆与 CP/M BDOS 使用。5. 开发环境与调试技巧5.1 工具链配置vdp-gl 要求 ESP-IDF v4.4 或更高版本推荐使用 PlatformIO 构建; platformio.ini [env:agon_vdp] platform espressif32 board esp32dev framework espidf board_build.f_cpu 240000000 lib_deps https://github.com/agon-light/vdp-gl.git build_flags -DCONFIG_VDP_GL_ENABLE_DOUBLE_BUFFER -DCONFIG_VDP_GL_SPRITE_COUNT128 -DCONFIG_VDP_GL_TERMINAL_UTF8关键编译选项CONFIG_VDP_GL_ENABLE_DOUBLE_BUFFER启用三级双缓冲必选CONFIG_VDP_GL_SPRITE_COUNT设置最大精灵数影响 Sprite RAM 分配CONFIG_VDP_GL_TERMINAL_UTF8启用 UTF-8 解析增加 3.2KB Flash 占用。5.2 硬件调试接口vdp-gl 提供专用调试寄存器通过 JTAG 或串口访问寄存器地址名称读取值含义写入值作用0x3FC000DEBUG_STATUS位0VDP busy, 位1FIFO full, 位2collision pending0x01强制触发垂直消隐中断0x3FC004DEBUG_FPS当前帧率整数单位 FPS无0x3FC008DEBUG_CMD_COUNTFIFO 中待执行指令数0x00清空 FIFO实时性能监控示例// 在串口监视器中输出实时状态 void debugMonitor() { uint32_t status VDP_REG_READ(0x3FC000); uint32_t fps VDP_REG_READ(0x3FC004); uint32_t cmdCount VDP_REG_READ(0x3FC008); Serial.printf(VDP: %s BUSY, %s FIFO_FULL, %s COLLISION | FPS: %d | CMD_Q: %d\n, (status 1) ? YES : no, (status 2) ? YES : no, (status 4) ? YES : no, fps, cmdCount); }5.3 常见问题排查问题终端显示乱码或字符错位原因UART 波特率不匹配或 PS/2 键盘时钟抖动解决使用terminal.setBaudRate(115200)显式设置波特率检查 PS/2 Clock 引脚是否悬空添加 10kΩ 上拉电阻在Keyboard::begin()后调用keyboard.setDebounceTime(5)。问题精灵移动出现撕裂原因未在垂直消隐期更新精灵位置解决// 正确做法在 VBlank 期间批量更新 void updateSpritesInVBlank() { if (vdp_gl_isVBlank()) { for (auto s : sprites) { s.setPosition(newX, newY); } } }问题调色板颜色异常原因调色板索引超出 0–255 范围或 RGB565 格式错误解决使用COLOR_RGB565(r,g,b)宏生成正确格式调用palette.setColor(index, COLOR_RGB565(31,63,31))而非直接写入。6. 与原版 FabGL 的关键差异总结维度FabGL 1.0.8vdp-glAgon 定制版工程意义图形渲染路径CPU 绘制 → PSRAM 帧缓冲 → DMA 到显示器CPU 生成指令 → VDP Command FIFO → 硬件合成减少 72% 的 PSRAM 带宽占用精灵数量上限64 个受限于内存128 个硬件固定资源支持更复杂的游戏场景终端刷新机制软件逐字符重绘硬件指令加速清屏/滚动/光标10 倍提升终端响应速度键盘协议支持PS/2 基础协议PS/2 AT Set 2 NKRO 动态布局完美兼容机械键盘与国际布局内存占用代码数据 ≈ 1.2MB代码数据 ≈ 850KB为 CP/M 应用腾出更多内存空间实时性保障依赖 FreeRTOS 任务调度VDP 硬件定时器 垂直消隐同步关键操作确定性延迟 10μsvdp-gl 的本质是一次成功的“软硬协同设计”实践它没有试图在通用硬件上模拟专用芯片功能而是将 ESP32 的计算能力与 Agon VDP 的硬件加速能力进行精确解耦——CPU 专注逻辑与协议处理VDP 专注像素级合成。这种设计思想对所有面向特定硬件平台的嵌入式图形库开发都具有普适参考价值。在 Agon Light 的实际部署中该库已稳定运行超过 18 个月支撑了从教育编程终端到复古游戏主机的全系列应用验证了其工程鲁棒性。