简介这是一份Adafruit GFX图形库的完整源码包面向Arduino开发者和电子制作爱好者帮助解决在OLED、TFT等不同显示器上实现图形化界面时需分别适配底层驱动的问题。无论是ST7735、SSD1306还是ILI9341驱动的屏幕都可以借助这套源码快速实现基本图形与文本输出。压缩包内共72个文件以58个h头文件为核心另配cpp、c源文件、ino示例、Markdown说明、makefile及properties配置整体约309KB体积精巧、目录清晰。目前已有1628人学习下载是不少玩家入门图形显示编程的常用参考。内容既包括Adafruit_GFX基类、SPI接口封装等核心实现也收录了FreeSans、FreeSerif、TomThumb等大量预编译字体文件附带fontconvert工具和GFXcanvas画布示例。读者可对照完整源码理解坐标系统、RGB565颜色编码、setRotation旋转、滚动与裁剪实现也能直接复用现成字体与示例快速搭建自己的显示屏项目或二次开发驱动。1. Adafruit_GFX.h嵌入式绘图界面绕不开的那个图形库头文件Adafruit_GFX.h 是 Arduino 生态里 Adafruit GFX 图形库的主头文件。多数人认识它是在库管理器里顺手装了 Adafruit SSD1306 或 Adafruit ST7735 之后发现 include 链里躺着一个与具体屏幕型号无关的Adafruit_GFX.h。这个文件解决的问题不是“某颗屏幕芯片怎么初始化”而是把绘图原语统一封装画点、画线、画圆、画矩形、打印字符坐标计算和字符点阵由库代劳驱动层只需要回答一个最基本的问题——每个像素是什么颜色。对从 128×64 OLED 迁到 320×240 TFT、但不想重写菜单界面的工程师来说这个抽象能把迁移成本压到极低对写自制屏幕驱动的人而言它也是一个现成的软件光栅框架。下面从类结构、最小工程、驱动适配和验证手段四条线把它一次拆清。2. Adafruit_GFX 的类结构与从 drawPixel 派生整张画面的绘制管线2.1 Adafruit_GFX–Adafruit_SPITFT–具体控制器这个继承链的由来先看库文件里的典型继承关系以新版库为准class Adafruit_GFX : public Adafruit_GFX_V {}; class Adafruit_SPITFT : public Adafruit_GFX {}; class Adafruit_ST7735 : public Adafruit_SPITFT {}; class Adafruit_SSD1306 : public Adafruit_GFX {};Adafruit_GFX是绘图抽象层负责计算“像素应该在哪里”但不负责物理写屏。真正的像素写入被收敛到一个纯虚函数virtual void drawPixel(int16_t x, int16_t y, uint16_t color) 0;任何驱动子类只要实现drawPixel就能立刻获得整套绘图 API。新版库还增加了Adafruit_SPITFT这样的中间层把 SPI 事务、启动时序和颜色字节序塞进派生类让上层 APP 不感知硬件差异。这个分层的代价是纯软件计算像素坐标会占一点 CPU好处是代码可移植性极佳。Arduino 上常见的国产 LCD 驱动库很多也采用“自己的初始化 继承Adafruit_GFX”的路径原因就在这里。需要注意Adafruit_GFX_AS.h这个名字。它来自第三方 fork接口相似但针对 ST7735 等 SPI 屏做过速度优化。标题里的Adafruit_GFX.h指官方主线两者并非同一文件混用时会出现重复定义或 API 签名不一致的问题。2.2 六类最常调用的绘图原语的功能和渲染入口Adafruit_GFX.h公开的绘图方法很多但绝大多数不是新算法而是围绕少量底层操作组合出来的。下面是官方主线库中常见原语与底层实现的对应关系方法功能底层实现方式drawPixel画一个点唯一的纯虚函数子类必须实现drawLine两点连线Bresenham 直线算法逐点调用drawPixeldrawCircle空心圆八个对称点同时计算再逐点写像素drawRect空心矩形四条边分别调用快速横竖线fillRect实心矩形逐行调用drawFastHLine驱动可以重写drawChar画一个字符从字形表逐 bit 取点阵再调用drawPixeldrawFastHLine和drawFastVLine是设计上预留的加速口。如果一个驱动总线写入速度快重写这两个函数后fillRect的性能可以提升几个数量级。反过来如果驱动只有最原始的drawPixel屏幕上填充一个全屏矩形就会慢到肉眼可见。字符渲染默认使用内置于Adafruit_GFX.cpp的 5×7 点阵字体字体数据放在 PROGMEM不占用有限的 SRAM。更高分辨率的字体需要额外引入gfxfont.h和Fonts/目录下的字体文件再配合setFont()使用。2.3 print 与字体渲染默认参数Adafruit_GFX继承了 ArduinoPrint类所以display.print(temp:)、display.println(value)这种写法天然可用。这意味着调试信息可以不经串口直接打到屏幕上代价是数值型print内部要做进制转换频繁刷新数字会明显拖慢帧率。与字体相关的默认参数有几个容易混淆的点setTextColor(color)只设置前景色背景保持原样字符叠绘会产生残影setTextColor(fg, bg)会把字符背景也填掉适合菜单场景但刷新成本更高setTextSize(n)是整数倍放大不是任意缩放尺寸 2 表示每个字形点占 2×2 像素setTextWrap(true)在行尾自动换行绘制传感器图表时通常要关掉。提示在程序里直接写display.println(OK)会把字符串常量放进 SRAM长时间运行会挤占堆栈。习惯性写成display.println(F(OK))字符串会留在 Flash 中只有读取时才复制出来。3. 用 Adafruit_GFX.h 建立 SSD1306 与 ST7735 最小绘图工程3.1 OLED 缓冲屏最小示例与字符打印栈SSD1306 是自带 1KB 显存的单色 OLED 控制器库里面Adafruit_SSD1306的做法是先画到内部 buffer再统一display()刷屏。最小工程代码如下#include Wire.h #include Adafruit_GFX.h #include Adafruit_SSD1306.h #define SCREEN_WIDTH 128 #define SCREEN_HEIGHT 64 Adafruit_SSD1306 display(SCREEN_WIDTH, SCREEN_HEIGHT, Wire, -1); void setup() { display.begin(SSD1306_SWITCHCAPVCC, 0x3C); display.clearDisplay(); display.setTextSize(1); display.setTextColor(SSD1306_WHITE); display.setCursor(0, 0); display.println(F(Adafruit_GFX.h)); display.drawLine(0, 20, 127, 20, SSD1306_WHITE); display.drawCircle(64, 44, 10, SSD1306_WHITE); display.fillRect(20, 30, 30, 12, SSD1306_WHITE); display.display(); } void loop() {}构造函数里Wire表示使用 I2C最后一个-1表示不用复位引脚。begin()的0x3C是常见 OLED 地址如果你的模块实测地址是0x3D把这里改成0x3D即可。clearDisplay()只清 buffer不立刻上屏之后的绘制全部发生在内存里直到最后一行display()才把整帧推给 OLED。这意味着绘图顺序不敏感反复重绘同一区域不会产生屏幕闪烁。3.2 ST7735 TFT 的初始化参数和 setRotation 坐标换算ST7735 是 SPI 接口的 128×160 彩色 TFT 主流驱动芯片本身带显存所以库不需要再开一块大 buffer每画一个点都会实时走 SPI 总线。代码结构略有不同#include Adafruit_GFX.h #include Adafruit_ST7735.h #include SPI.h #define TFT_CS 10 #define TFT_DC 9 #define TFT_RST 8 Adafruit_ST7735 tft Adafruit_ST7735(TFT_CS, TFT_DC, TFT_RST); void setup() { tft.initR(INITR_BLACKTAB); tft.setRotation(1); tft.fillScreen(ST77XX_BLACK); tft.setTextColor(ST77XX_YELLOW); tft.setTextSize(2); tft.setCursor(0, 30); tft.print(F(GFX OK)); tft.drawRect(0, 0, 128, 160, ST77XX_RED); } void loop() {}initR(INITR_BLACKTAB)用于 1.8 英寸模块的初始化表选择红板、黑板、绿板的偏移参数不同。setRotation(1)表示顺时针旋转 90°旋转后_width和_height会互换后续所有drawRect、drawBitmap的坐标都基于新坐标系。四个旋转参数对应关系如下旋转值坐标起始宽高方向典型使用场景0左上角宽128高160竖屏默认1左上角宽160高128横屏面板2左下角宽128高160底边朝下的竖屏3右下角宽160高128反向横屏一个常见误区是旋转之后再按原分辨率计算画布中心。比如旋转 1 后横屏中心点是(80, 64)如果继续用(64, 80)画圆画矩形图案会明显偏移。画布中心坐标应该始终从tft.width() / 2、tft.height() / 2动态获取。3.3 四个必设文本参数setTextSize、setTextColor、setTextWrap、setFont在 Adafruit_GFX.h 的文本渲染里这四个参数几乎每个 UI 界面都要碰到参数写法影响字号setTextSize(1)1 表示 5×7 点阵原始大小2 为 10×14颜色setTextColor(RED)只改前景字符背景透出原画面前景背景setTextColor(RED, BLUE)每个字符先填背景再画字形适合菜单换行setTextWrap(false)关掉行尾自动换行图表模式更可控字体setFont(FreeMono9pt7b)切换到大字体或中文点阵字体使用大字体时必须#include Fonts/FreeMono9pt7b.h。切换字体后字符占宽不再是 5 的倍数setCursor的间距计算要改成previousCursorX textWidth(AB)否则手动做坐标对齐时会出现字符重叠。getTextBounds()可以拿到字符串的外接矩形动态 UI 里用它做右对齐或居中对齐比手工数像素可靠得多。4. 实现自己的 drawPixel内存缓冲、565 颜色与总线取舍的三个适配参数4.1 一个能满足 Adafruit_GFX 编译的最小继承类模板接手一块没有官方库的液晶屏时最常见做法是继承Adafruit_GFX只补初始化之外的像素写函数。模板如下#include Adafruit_GFX.h class MyPanel : public Adafruit_GFX { public: MyPanel(int16_t w, int16_t h) : Adafruit_GFX(w, h) {} void drawPixel(int16_t x, int16_t y, uint16_t color) override { if (x 0 || x _width || y 0 || y _height) return; if (hasFramebuffer) { framebuffer[y * _width x] color; } else { sendPixelToController(x, y, color); } } private: bool hasFramebuffer true; uint16_t *framebuffer nullptr; };构造函数传入逻辑宽高Adafruit_GFX会把这些值存到_width和_height。drawPixel里先做边界裁剪再决定写入本地缓冲还是直接发总线这是最稳妥的“先能亮”方案。之后fillRect、drawCircle等几十个 API 自动可用整套交互代码都不需要再改。库允许驱动重写drawFastHLine和drawFastVLine。如果你的面板支持“一次性写入连续水平区域”的命令哪怕只是把循环写成连续内存地址递加都能明显减少fillRect的调用开销。4.2 无缓冲与缓冲显示模式对内存和闪烁的影响彩色屏的显存需求按“宽×高×2 字节”计算。320×240 TFT 需要 153600 字节也就是 150KB普通 Arduino 的 SRAM 根本放不下。所以 ST7735 这类自带显存的控制器适合走无缓冲直写路径芯片内部已经存了整帧库侧不用再分配内存单片机每次只改一个点。单色 OLED 的情况相反。SSD1306 的 128×64 显示只有 1KB缓冲成本极低库直接分配 1024 字节作为 framebuffer。一次display()调用把整块显存推过去屏幕不会出现半截刷新的撕裂感。缓冲模式真正的坑在“局部更新”。很多开发者以为操作 buffer 很快就在 OLED 上高频刷新一块数字区域结果每帧都调用display()把整个屏幕都送过去。I2C 数据率限制下整屏传输会吃掉几毫秒。更好的做法是只刷新变化行批量拼接脏矩形而不是整屏重发。4.3 总线频率、颜色字节序、旋转参数在实际驱动适配中的调整自定义驱动适配时有三个参数最值得先确认。参数表现形式典型适配点SPI 时钟频率初始化SPISettings过高会在长线上形成信号畸变点距屏建议 8MHz带长排线降到 4MHz颜色字节序发送 16bit 时先高字节还是先低字节多数控制器是高位在前反过来会出现红蓝互换旋转坐标系setRotation映射芯片的扫描方向寄存器决定旋转是否必须由软件补偿16 位颜色在库内统一为uint16_t的 RGB565 格式五个红色位、六个绿色位、五个蓝色位uint8_t r (color 11) 0x1F; uint8_t g (color 5) 0x3F; uint8_t b (color) 0x1F;驱动在底层写寄存器时要按芯片手册再拼回实际寄存器布局。有的控制器在并行接口下使用 RGB666那就需要在drawPixel里把 16 位色拆成 8 位/通道。颜色格式不一致的症状是画线正常但fillScreen看起来色调奇怪红蓝互换尤其容易判断。先把fillScreen(0x001F)调成纯蓝文字颜色正常但底色偏色就说明高字节位序需要反转。提示调试自制驱动时不要一上来就画真实图案。先全屏填红、绿、蓝三色各停一秒能准确确认硬件通路和颜色格式再进入字符和图形测试。5. 用 micros 计时验证 Adafruit_GFX 渲染耗时并优化 fillRect 分组绘制5.1 给 fillScreen 和 drawLine 计时的最小测试代码对 Adafruit_GFX 这种纯软件光栅库性能瓶颈往往不在算法而在每次 API 调用产生的总线事务。验证办法是用micros()包住一段重复绘制uint32_t t0 micros(); for (int i 0; i 50; i) { tft.drawRect(0, 0, 127, 63, ST77XX_RED); } uint32_t dt1 micros() - t0; t0 micros(); for (int i 0; i 500; i) { tft.drawPixel(i % 128, i % 64, ST77XX_RED); } uint32_t dt2 micros() - t0; Serial.print(F(drawRect x50: )); Serial.println(dt1); Serial.print(F(drawPixel x500: )); Serial.println(dt2);把两次耗时打到串口能直观看到单点调用和批量图元之间的差距。如果drawPixel x500反而比drawRect x50更快说明驱动里drawRect并没有走原生加速路径仍在逐像素回调这时应该检查是否重写了drawFastHLine/drawFastVLine。计时数据还能验证总线频率调整是否真的生效同一个drawLine测试把 SPI 速率从 4MHz 提到 8MHz耗时应近似减半。5.2 把逐点绘制替换成整行填充的收益与适用条件Adafruit_GFX 的fillRect内部会反复调用横线填充横线填充在派生驱动里是连续写操作天然比逐点drawPixel高效。优化代码时记住一个原则能用矩形表达的区域不用多条线去拼能整行画的进度条不要逐点画。// 低效写法每次循环画 50 个点制造了 50 次总线事务 for (int x 0; x 50; x) { tft.drawPixel(x, barY, ST77XX_GREEN); } // 高效写法一条水平线一次事务 tft.drawFastHLine(0, barY, 50, ST77XX_GREEN);这个改动对不带缓冲的裸驱动效果最明显。对带 framebuffer 的 OLED差距隐藏在内存写入循环里缩小不明显但能减少display()后单色屏画面的边缘噪点。涉及动画时正确路径是维护一个“脏矩形”列表只更新变化区域再统一调display()这比每次改一个字符就刷一次全屏可靠得多。下一步可以继续封装的技巧是把整行数据放进 DMA 缓冲、用外设自动搬运像素让 CPU 在绘制长矩形时不再被 SPI 占用。本文还有配套的精品资源点击获取