CEdev 图形编程完全指南：graphx 库调色板、精灵动画与 Tilemap 实战教程-育师

CEdev 图形编程完全指南：graphx 库调色板、精灵动画与 Tilemap 实战教程

【免费下载链接】toolchainToolchain and libraries for C/C++ programming on the TI-84+ CE calculator series项目地址: https://gitcode.com/gh_mirrors/too/toolchain

CEdev 是 TI-84+ CE 系列计算器的 C/C++ 编译工具链，而graphx 图形库是它最强大的可视化组件：从调色板管理、精灵（Sprite）动画到 Tilemap 地图，一个库全搞定 🎮。本教程面向新手，带你从零理解 graphx 的调色板模式，快速上手精灵动画与 Tilemap 实战，最终在计算器上跑出自己的游戏画面。

为什么 graphx 是 CEdev 图形编程的首选？

graphx 把计算器 LCD 切换为调色板模式（palettized mode）：屏幕上的每个像素并不直接存储颜色，而是存储一个"颜色索引"，真正的颜色存放在一张最多 256 色的调色板里。

这种设计有两个直接好处：

📦省内存：一个像素只占 1 字节（8bpp），320×240 的整屏只需约 75KB；
🎨改色轻松：想换配色方案？只需重写调色板条目，不用重画任何像素。

关键概念一览：

概念	说明
`gfx_palette`	调色板数组，`gfx_palette[16]`即可读写第 17 个颜色
`gfx_RGBTo1555(r, g, b)`	把普通 24 位 RGB 值转换成 1555 调色板颜色
`gfx_SetPalette()`	一次性批量设置多个调色板条目
坐标系	左上角为 (0, 0)，右下角为 (319, 239)，即 320×240 像素

⚠️ 两个必须记住的规矩：
程序开头必须调用gfx_Begin()，退出前必须调用gfx_End()恢复屏幕。忘记调用gfx_End()会看到系统界面在调色板模式下变成"花屏"——效果如下（这也是官方文档特意放出来提醒你的 😄）：

凡是名字带_NoClip的绘图函数（如gfx_Sprite_NoClip）会跳过越界检查、速度更快，但只有你能 100% 确定图形完全在屏幕内时才可以用，否则会写坏内存导致崩溃。

API 的完整定义可以在 src/graphx/graphx.h 中找到，图形例程的汇编实现位于src/graphx/graphx.asm。

快速搭建 CEdev 图形开发环境

如果你使用 CLion 等 IDE，需要先指向 CEdev 的 Make 工具，把 "Path to Make executable" 填成 CEdev 安装目录下的 make 可执行文件即可：

配置好之后，官方示例库是最好的老师。所有 graphx 示例都放在examples/library_examples/graphx/目录下，覆盖了调色板、精灵旋转缩放、RLE 压缩、缓冲拷贝等 20 多个场景，每个示例都自带makefile和readme.md，直接make就能编译出.8xp程序装进计算器。

调色板实战：用 convimg 自动转换图片为精灵

手写像素数组是噩梦，CEdev 自带convimg工具来解决这个问题：你只需准备 PNG 图片和一个 YAML 配置文件，convimg 会自动生成最接近的 256 色调色板，并输出可直接编译的 C 数组。

以精灵示例（examples/library_examples/graphx/sprites/）为例，流程只有三步：

把oiram.png和convimg.yaml放在src/gfx/目录；
运行make gfx，convimg 会读取配置、生成调色板、输出 C 文件；
正常make编译项目。

从终端输出可以看到：convimg 为图片生成了 15 色的global_palette（256 色中只用了 15 色），并写出global_palette.h/c、oiram.c和头文件gfx.h。之后代码里只需：

gfx_Begin(); gfx_SetPalette(global_palette, sizeof_global_palette, 0); gfx_SetTransparentColor(0); // 第 0 号色设为透明 gfx_Sprite_NoClip(oiram, 130, 110); // 画一个精灵 gfx_End();

完整代码见examples/library_examples/graphx/sprites/src/main.c，不到 30 行就能画出第一张图。

几个实用技巧：

透明精灵：gfx_TransparentSprite()会保留背景原样；普通的gfx_Sprite()则用当前背景色填充透明区域，两者效果不同，按需选择；
压缩体积：convimg 支持把精灵和调色板数据存进 AppVar（变量），减小二进制体积，参考sprites_appvar示例；
RLE 压缩：sprites_rlet示例演示了用gfx_Sprite_RLE绘制运行时长解压的压缩精灵，适合图多内存少的游戏。

精灵动画：移动精灵与局部重绘

"动画"的本质就是每帧更新坐标并重画。但每帧重绘整屏会很慢，graphx 推荐**局部重绘（Partial Redraw）**思路：

画完静态背景后，用gfx_GetSprite()把精灵身后的背景存进一个临时精灵；
移动时，先用这个临时精灵"擦掉"旧位置的精灵；
更新坐标，再gfx_GetSprite()存新位置背后的背景，最后gfx_TransparentSprite()画出新位置的精灵。

examples/library_examples/graphx/sprites_moving/就是一个完整实现：用方向键控制精灵在画面上移动，配合keypadc库的kb_Scan()读取按键，并开启了绘制缓冲避免撕裂。核心循环大致是"扫描按键 → 擦除旧位置 → 更新坐标 → 绘制新位置 →gfx_BlitBuffer()刷新"，非常值得逐行阅读。

防闪烁三件套（几乎所有动画都会用到）：

函数	作用
`gfx_SetDrawBuffer()`	之后所有绘制都写到离屏缓冲区，用户看不到半成品画面
`gfx_BlitBuffer()`	把整个缓冲区一次性拷贝上屏（闪烁少、最省心）
`gfx_SwapDraw()`	屏幕与缓冲区交换，速度更快，适合每帧全重绘的场景

如果只是想体验缓冲效果，可以直接看blitting和buffered_cube两个示例。

Tilemap 实战：用一张 CSV 表格搭建游戏地图

Tilemap（瓦片地图）是 2D 游戏的灵魂：把大地图切成 16×16 像素的小瓦片，画一张"瓦片图集"（tileset），再用一张表格记录每个格子放哪块瓦片即可。

examples/library_examples/graphx/tilemap/示例的结构非常清晰：

src/gfx/tileset.png：瓦片图集，convimg 负责转换并生成tileset_tiles；
src/tilemap/tilemap.csv：纯文本表格，行列对应地图上每个格子的瓦片索引；
src/gfx/convimg.yaml：声明图集与调色板的转换规则。

代码里只需填充一个gfx_tilemap_t结构体，再交给gfx_Tilemap()绘制：

tilemap.map = tilemap_map; // CSV 生成的地图数据 tilemap.tiles = tileset_tiles; // 瓦片图集 tilemap.type_width = gfx_tile_16_pixel; tilemap.type_height = gfx_tile_16_pixel; tilemap.width = 32; tilemap.height = 25; // 地图尺寸（瓦片数） tilemap.draw_width = 20; tilemap.draw_height = 14; // 一次画多少

该示例还演示了地图滚动：根据方向键修改x_loc/y_loc偏移量，屏幕只显示地图的一个窗口，就能体验"角色在更大世界里行走"的效果。想要更省内存的版本，可以看tilemap_compressed（压缩地图数据）和tilemap_appvar（地图存进变量）。

学习路线与核心文件清单

按这个顺序学习，一周内就能上手：

👣examples/library_examples/graphx/hello_world/—— 最小图形程序，跑通gfx_Begin→ 填充屏幕 →gfx_End；
🖼️sprites/—— convimg 转换图片、调色板、普通与透明精灵；
🏓sprites_moving/—— 局部重绘 + 按键移动，做出第一个"会动的东西"；
🌀sprites_rotate_scale/、sprites_rotate_flip/—— 精灵旋转、缩放、翻转特效；
🗺️tilemap/—— 瓦片地图与滚动相机，正式开写你的游戏；
📚 需要查 API 时，直接阅读src/graphx/graphx.h（1800 多行、注释详尽），或参考官方文档 docs/libraries/graphx.rst。