TFT_eSPI 图形库全面指南：从 Arduino 配置、Sprite 到抗锯齿字体与多平台移植

TFT_eSPI 图形库全面指南：从 Arduino 配置、Sprite 到抗锯齿字体与多平台移植

【免费下载链接】TFT_eSPIArduino and PlatformIO IDE compatible TFT library optimised for the Raspberry Pi Pico (RP2040), STM32, ESP8266 and ESP32 that supports different driver chips项目地址: https://gitcode.com/GitHub_Trending/tf/TFT_eSPI

本篇技术指南围绕 README.md 展开，系统讲解 TFT_eSPI 这一面向 32 位处理器的 Arduino 图形与字体库：如何通过User_Setup.h/User_Setup_Select.h完成驱动、引脚与字体的配置，如何理解它对 RP2040、ESP32、ESP8266、STM32 等平台在 SPI / 并行接口与 DMA 上的支持边界，以及 Sprite 双缓冲、vlw 抗锯齿平滑字体、触摸与 8 位并行屏等核心特性的底层原理与实战用法。读者读完后，将能够独立完成一块 TFT 屏从接线、配置、编译到跑通示例的完整流程，并能依据源码证据深入理解性能优化的关键机制。

一、库定位：为 32 位处理器而生的 TFT 图形库

TFT_eSPI 是一个功能丰富的 Arduino IDE 兼容图形与字体库，专为 32 位处理器设计，并在 RP2040、STM32、ESP8266 和 ESP32 上做了性能优化；其他 32 位处理器也可使用，但会走较慢的通用 Arduino 接口调用。这一点在 TFT_eSPI.h 的头部注释中写得很清楚：该库是"独立的库"，本身既包含硬件驱动、图形函数，也包含比例字体。

它的几个关键设计决策值得注意：

• 配置必须写在库内而非 sketch 中：屏幕控制器、接口引脚和库配置必须在库内部定义，不能在 Arduino sketch 中定义，具体机制见 User_Setup_Select.h。这一设计让所有示例保持干净、无需为不同硬件修改示例代码——只要User_Setup.h配好，任意示例都能直接编译运行。
• PlatformIO 用户可逐项目配置：PlatformIO 用户可以通过platformio.ini按项目定义这些设置。User_Setup_Select.h中提供了TFT_ESPI_USER_SETUP_PATH宏支持（User_Setup_Select.h），例如在platformio.ini中写入-D TFT_ESPI_USER_SETUP_PATH=\"../configs/your_board/User_Setup.h\"即可指向外部配置文件。
• 基于 Adafruit GFX 兼容性扩展：库基于 Adafruit GFX 与 Adafruit 驱动库，旨在保持兼容，同时对不同处理器做了显著的速度提升（README 称"typically 3 to 10 times faster"），并增加了不同尺寸比例字体、格式化特性等新图形功能。

该库还支持一种特殊用法：通过__has_include探测 sketch 目录下的tft_setup.h文件，把配置放到 sketch 文件夹中（TFT_eSPI.h），适合希望"配置跟随 sketch 走"的用户。

二、支持的处理器、接口类型与 DMA 能力矩阵

README 用一张表格完整给出了不同处理器支持的接口类型与 DMA 能力，这是选型时最重要的依据：

结合仓库源码可以进一步确认几个要点：

• "4 线 SPI"的含义：指显示屏具有 SPI 兼容信号加上一根"数据/命令"控制线，该信号线有时标注为 DC、RS 或 A0（README.md）。这也是绝大多数入门级 TFT 屏的标准接口。
• DMA 的处理器差异：Direct Memory Access（DMA）可用于 ESP32、RP2040 和 STM32 处理器的 SPI 接口显示屏以提升渲染性能；而 8/16 位并行接口的 DMA仅 RP2040 支持。
• 处理器驱动分支：TFT_eSPI.h 展示了处理器特定驱动头文件的选择逻辑——ESP32-S3 / ESP32-C3 / ESP32 / ESP8266 / STM32 / RP2040 分别对应 Processors 目录下的专用文件，其他处理器则统一回退到TFT_eSPI_Generic.h，这正是 README 中"其他处理器走通用 Arduino 调用"的源码实现。

从源码结构看，ESP32 S2/C3/S3 的支持要求 ESP32 Arduino 板卡包 2.x.x 或更新版本（README.md 明确说明），新用户安装时需注意板卡包版本。

支持的屏幕控制器清单

README 列出了完整支持列表，仓库的 TFT_Drivers 目录为每个控制器提供了对应的_Defines.h、_Init.h、_Rotation.h三个文件（例如 ILI9341_Defines.h），User_Setup_Select.h 则按xxx_DRIVER宏将驱动文件与控制器 ID 对应起来。支持的控制器包括：

• GC9A01、ILI9163、ILI9225、ILI9341、ILI9342
• ILI9481、ILI9486、ILI9488（注意：这三个用 SPI 时不支持 DMA）
• HX8357B / HX8357C（16 位并行已在 RP2040 上测试）、HX8357D
• R61581、RM68120（支持文件已添加但未测试）、RM68140
• S6D02A1、SSD1351
• SSD1963（该控制器只有并行接口选项）
• ST7735、ST7789、ST7796

README 建议以ILI9341 和 ST7796 的 SPI 屏作为使用本库的起点，它们在示例和社区教程中资料最丰富。

RPi 型显示屏的特殊说明

库还支持部分专为树莓派（RPi）设计的 TFT 屏，它们基于 ILI9486 或 ST7796 驱动芯片，分辨率 480×320。需要特别注意的是：

• ILI9486 的 RPi 屏必须是 Waveshare 设计，使用基于 74HC04、74HC4040 和 2×74HC4094 逻辑芯片的 16 位串行接口；
• 由于这些屏之间存在设计差异，并非所有 RPi 屏都能与本库一起工作，README 明确建议不要仅为使用本库而专门购买这类 RPi 屏；
• 表现良好的选择是 MHS-4.0 英寸 Display-B 型 ST7796 屏，它配有专用控制器，ESP32 下最高可到 80MHz、超频 RP2040 下 125MHz、STM32 下 55MHz、ESP8266 下 40MHz 的时钟；MHS-3.5 英寸 RPi ILI9486 屏也受支持，但同型号的 MHS ILI9341 屏不能与本库配合使用。

三、配置体系：User_Setup.h 与 User_Setup_Select.h 的完整解读

配置是本库使用中最重要的环节，其核心脉络是：TFT_eSPI.h首先尝试加载 sketch 目录的tft_setup.h，随后无条件包含 User_Setup_Select.h，再由它去选择实际的用户配置头文件（TFT_eSPI.h）。

3.1 User_Setup_Select.h：一键切换硬件配置

User_Setup_Select.h 的核心设计是"只取消注释一行，即可切换整套硬件配置"。它默认包含库根目录的User_Setup.h，其余全部为注释掉的候选配置，覆盖了大量常见开发板与屏幕组合，例如：

• User_Setups/Setup25_TTGO_T_Display.h（TTGO T-Display ST7789V）
• User_Setups/Setup70_ESP32_S2_ILI9341.h、Setup70b_ESP32_S3_ILI9341.h、Setup70c_ESP32_C3_ILI9341.h、Setup70d_ILI9488_S3_Parallel.h（ESP32 S2/S3/C3 系列，User_Setup_Select.h）
• User_Setups/Setup100~107（RP2040 8 位/16 位并行系列，User_Setup_Select.h）
• Setup250_ESP32_S3_Box_Lite.h、Setup251_ESP32_S3_Box.h（ESP32 S3 Box 系列）
• Setup206_LilyGo_T_Display_S3.h、Setup210_LilyGo_T_Embed_S3.h、Setup211_LilyGo_T_QT_Pro_S3.h等 LilyGo 系列

这些文件全部位于仓库 User_Setups 目录，可直接选用或复制后修改。文件头部强调：更新 TFT_eSPI 时，存放在库文件夹内的自定义 setup 文件会被覆盖，务必保留副本（User_Setup_Select.h）。

3.2 User_Setup.h：驱动、引脚、字体的分区配置

默认配置文件 User_Setup.h 采用分区结构，每个分区解决一类配置问题：

Section 1：驱动与显示选项

• 定义唯一的驱动宏，如#define ILI9341_DRIVER，其余驱动必须注释掉（User_Setup.h）；
• 并行模式开关：TFT_PARALLEL_8_BIT、TFT_PARALLEL_16_BIT（后者仅限 RP2040，User_Setup.h）；
• 颜色顺序修正：TFT_RGB_ORDER TFT_RGB/TFT_RGB_ORDER TFT_BGR用于解决蓝红交换问题（User_Setup.h）；
• ST7735 专属的屏类型宏（ST7735_INITB、ST7735_GREENTAB、ST7735_REDTAB等），屏幕显示异常（颜色错误、镜像、边缘杂点）时逐个尝试（User_Setup.h）；
• 颜色反转修正：TFT_INVERSION_ON/TFT_INVERSION_OFF；
• 半双工 SDA 读取模式：TFT_SDA_READ（仅 ESP32，已用 ST7789 和 GC9A01 测试），启用后库会把 MISO 强制置为 -1（TFT_eSPI.h）。

Section 2：引脚定义

• SPI 屏最少需要 3 个 GPIO 引脚（SCLK、MOSI、DC，加上可选的 CS/RST）；
• 示例中给出了 ESP8266 NodeMCU 的典型接法：SDO/MISO→D6、SCK→D5、SDI/MOSI→D7、DC→D3、RESET→D4、CS→D8（User_Setup.h）；
• 关键提示：ILI9341 等屏幕在无其他 SPI 设备时，TFT_CS 可直接接 GND 并将#define TFT_CS注释掉；但 ST7735 在初始化时需要 CS 翻转，必须定义并连接 TFT_CS（User_Setup.h）；
• 背光控制：定义TFT_BL与TFT_BACKLIGHT_ON后，tft.begin()会自动点亮背光；PWM 调光或手动开关需在 sketch 中处理（User_Setup.h）；
• ESP32 并行接口示例给出 D0~D7 数据总线（必须使用 0-31 号引脚以便单寄存器写入）、TFT_WR 写选通、TFT_RD 读选通（User_Setup.h）。

Section 3：字体加载

• 通过注释/取消注释控制哪些内建字体被编译进来，全部启用约多占 17Kbytes FLASH（User_Setup.h）：
  • LOAD_GLCD：Font 1，Adafruit 原始 8 像素字体，约 1820 字节；
  • LOAD_FONT2：Font 2，16 像素高小字体，约 3534 字节，96 字符；
  • LOAD_FONT4：Font 4，26 像素高中等字体，约 5848 字节，96 字符；
  • LOAD_FONT6：Font 6，48 像素大字体，约 2666 字节，仅含1234567890:-.apm；
  • LOAD_FONT7：Font 7，7 段数码管 48 像素字体，约 2438 字节，仅含1234567890:-.；
  • LOAD_FONT8/LOAD_FONT8N：Font 8，75 像素超大字体，后者更窄、160 像素屏可放下 3 位数字；
  • LOAD_GFXFF：启用 48 个 Adafruit_GFX FreeFonts（FF1~FF48）与自定义字体；
  • SMOOTH_FONT：加载 SPIFFS 文件系统与平滑字体代码，注释掉可省约 20Kbytes FLASH。
• 从 TFT_eSPI.h 可以看到字体宏到实际.c/.h文件（如 Font16.h、Font32rle.c）的映射，其中 Font 4/6/7/8 使用 Run Length Encoding（RLE）压缩以减小 FLASH 占用——这是库头注释中特别说明的设计。

Section 4：其他选项

• SPI 时钟：SPI_FREQUENCY（默认 20MHz，TFT_eSPI.h）。注释中给出实测参考：ILI9341 用 40MHz 正常、80MHz 偶发失败；ST7735 超过 27MHz 可能出现杂点；ILI9163 用 27MHz 正常（User_Setup.h）；
• SPI_READ_FREQUENCY：读取 TFT 时可选降低的频率（默认 10MHz）；
• SPI_TOUCH_FREQUENCY：XPT2046 触摸控制器要求较低 SPI 时钟 2.5MHz（User_Setup.h）；
• USE_HSPI_PORT：ESP32 的 VSPI 被占用（如 TTGO T-Beam）时切换到 HSPI 端口；
• SUPPORT_TRANSACTIONS：需要与其他 SPI 设备（如 SD 卡）共存时启用 SPI Transactions；ESP32 上库会自动启用（使用 HAL mutex），此宏在 ESP32 上无效（User_Setup.h）；
• RP2040 PIO 相关：RP2040_PIO_SPI让 SPI 屏也走 PIO 接口；RP2040_PIO_CLK_DIV调整并行写周期，公式为写周期 = CPU 时钟 / (4 * 分频)（User_Setup.h）。

3.3 SPI 与 SD 卡共用总线的关键坑

README 特别强调：如果想在 Arduino 上同时使用本库和 SD 卡（同一 SPI 总线），必须在 User_Setup.h 中显式定义TFT_MISO、TFT_MOSI和TFT_SCLK，即使你用的是该板卡的默认 SPI 引脚。否则 SD 卡在屏幕初始化后可能无法使用——这是大量用户实测踩过的坑，值得在配置时优先检查。

3.4 防止升级覆盖自定义配置的 Tips

由于库升级会覆盖库文件夹内的文件，README 给出两条实用经验：

1. 在 Arduino 库文件夹中新建TFT_eSPI_Setups文件夹，放入自定义 setup 文件，然后在User_Setup_Select.h中指向它：

#include <../TFT_eSPI_Setups/my_custom_setup.h>

../表示向上退出一级目录，且必须保证同时只调用一个 setup 文件。

2. 更进一步：自定义自己的 select 文件，升级后只需修改一行引用：

#include <../TFT_eSPI_Setups/my_setup_select.h>

之后切换硬件只需编辑自己的my_setup_select.h，升级永远不会覆盖它。

四、Sprite：RAM 中的隐形屏幕与无闪烁渲染

Sprite（精灵）是本库最具价值的特性之一，README 用专门章节进行了说明，源码 Extensions/Sprite.h 与 Extensions/Sprite.cpp 提供了完整实现。

4.1 核心概念与内存计算

Sprite 概念上是一块保存在处理器 RAM 中的"隐形图形屏幕"：图形可以像画到屏幕上一样画进 Sprite，画完后在任意位置整体贴到屏幕。若 RAM 充足，Sprite 可以与屏幕同尺寸并充当帧缓冲——先完整绘制再一次性提交，从而消除复杂图形的闪烁（README.md）。

Sprite 默认使用 16 位颜色，也可设为 8 位（256 色）或 1 位（任意 2 色）以减少 RAM。内存计算公式（README.md）：

• 16 位色深：2 × 宽度 × 高度字节；
• 8 位色深：宽度 × 高度字节；
• 1 位色深：320×240 全屏缓冲仅需 9600 字节，非常适合双色位图字体。

README 给出的实测参考尺寸：ESP8266 上最大 16 位色 Sprite 约 160×128（40KB RAM）；ESP32 的工作 RAM 比数据手册暗示的更紧张，16 位色 Sprite 约限 200×200（约 80KB），8 位 Sprite 可达 320×240（约 76KB）。若 ESP32 带 SPIRAM（PSRAM），Sprite 会使用 PSRAM，可创建全屏缓冲 Sprite，但全屏渲染更慢（320×240 的 16 位 Sprite 约 45ms）。

4.2 常用 API 与源码印证

Sprite 的动态创建/删除机制允许在需要时申请 RAM、贴完屏后释放，之后可运行更占内存的 WiFi 代码而图形功能不受影响。核心 API 在 Extensions/Sprite.cpp 中可逐一验证：

• createSprite(w, h, frames)：创建任意尺寸 Sprite，宽度或高度小于 1 时返回nullptr（Extensions/Sprite.cpp）；
• setColorDepth(b)：设置色深，b > 8时按 16 位处理，b > 4按 8 位，b > 1按 4 位（Extensions/Sprite.cpp）；
• deleteSprite()：释放位图与调色板内存（Extensions/Sprite.cpp）；
• pushSprite(x, y)：把整个 Sprite 贴到屏幕，16 位色深时内部通过pushImage实现（Extensions/Sprite.cpp）；
• pushSprite(x, y, transp)：贴图时指定一种颜色为"透明色"（Extensions/Sprite.cpp），对应示例Transparent_Sprite_Demo。

经典用法见 examples/Sprite/Sprite_draw/Sprite_draw.ino：

tft.init(); // 可选：设置 8 或 16 位色深，不设默认 16 位 // spr.setColorDepth(8); // 创建指定尺寸的 Sprite spr.createSprite(WIDTH, HEIGHT); tft.fillScreen(TFT_BLUE); // ...在 Sprite 中绘制各种图形、字符串... spr.drawString("Sprite", WIDTH / 2, HEIGHT / 2, 4); // 把 Sprite 贴到屏幕任意位置（支持负坐标裁切） spr.pushSprite(-40, -40); spr.pushSprite(tft.width() / 2 - WIDTH / 2, tft.height() / 2 - HEIGHT / 2); spr.pushSprite(tft.width() - WIDTH + 40, tft.height() - HEIGHT + 40);

Animated_dial示例展示了用旋转 Sprite 制作仪表指针的思路（examples/Sprite/Animated_dial）：表盘外圈和刻度是绘图软件生成的 jpeg 图像，指针是旋转的 Sprite；运行该示例要求 TFT 接口支持从屏幕 RAM 读取数据（并非所有屏都支持）。

五、抗锯齿（平滑）字体：vlw 格式与 Unicode 渲染

5.1 vlw 字体的生成与存储方式

抗锯齿（平滑）字体以vlw格式保存，由 Tools/Create_Smooth_Font/Create_font/Create_font.pde 这个 Processing IDE 草图生成。该草图可以从电脑字体集或任何 TrueType（.ttf）字体生成字体文件，可包含任意 16 位 Unicode 字符组合——希腊文、日文及其他 UCS-2 字形都能渲染；字符数组与 UTF-8 格式的 String 均受支持。

源码中的关键点（Create_font.pde）：

• 字体参数（点大小、要包含的 Unicode 区间等）在代码内注释说明，可以按区间或单个字形控制包含的字符；
• 生成的字体保存在草图FontFiles文件夹；
• SPIFFS 文件名最大 31 字符（含前导/），且SPIFFS 不接受文件名中的下划线——README 提到生成示例文件名Final-Frontier，其命名刻意避开了下划线。

vlw 文件的存放/使用有两条路线：

1. 上传到 FLASH 文件系统（SPIFFS、LittleFS 或 SD 卡），运行时加载；
2. 转换为 C 数组直接编入 FLASH，见Smooth Font -> FLASH_Array系列示例。数组方式方便、有性能提升，适合不想用文件系统、或处理器类型（如 STM32）不支持基于 FLASH 的文件系统的场景。

仓库中两种方式都有大量可直接参考的示例，例如 examples/Smooth Fonts/FLASH_Array（含NotoSansBold15.h、NotoSansBold36.h等生成好的字体数组）与 examples/Smooth Fonts/LittleFS、examples/Smooth Fonts/SPIFFS（含.vlw数据文件）。

5.2 平滑字体的渲染特性

• 平滑字体不能用setTextSize缩放，每种需要的字号都要单独生成字体文件（README 明确说明，示例可参考）；
• 平滑字体可以绘制在渐变背景上：通过回调获取每个像素的背景色，颜色可由渐变算法设置，或（若支持读屏）回读 TFT 屏幕内存得到；
• 支持 Unicode 块示例：README 展示了 Microsoft Yahei 字体 24pt 的平假名 Unicode 块（0x3041~0x309F）渲染效果。

5.3 快速刷新与背景渲染（breaking change）

README 的 News 部分提到一个重要的 API 变更：平滑字体现在可以逐行、逐块地更新字形区域（不重复绘制像素），从而以极低闪烁直接渲染到 TFT，适合快速变化的值。这带来一个breaking change：setTextColor需要新增一个布尔参数控制是否渲染背景，缺省为false：

tft.setTextColor(TFT_WHITE, TFT_BLUE, true); spr.setTextColor(TFT_BLUE, TFT_BLACK, true);

注意：平滑字体的背景渲染在使用 print 流（如tft.println("Hello World");）时同样可用。

5.4 相关生态与 TrueType 渲染

README 提到一个优秀的配套库 OpenFontRender，可在 TFT 屏幕（或 Sprite）中渲染 TrueType 字体：使用紧凑字体文件、全尺寸可缩放的抗锯齿字形、支持左/中/右对齐文本。TFT_eSPI 已为其添加了专用示例并在 RP2040 和 ESP32 上测试；ESP8266 因字形渲染复杂度导致 RAM 不足而不支持。一个约 12KB 的字体文件即可在 320×480 屏幕上渲染逐渐增大的全抗锯齿字形。

六、平滑图形：抗锯齿弧、圆与圆角矩形

README 的 News 部分重点介绍了新增的抗锯齿（平滑）图形函数，用于绘制线、楔形线、圆和圆角矩形轮廓。这些函数在 TFT_eSPI.h 中都有明确声明（TFT_eSPI.h）：

• drawSmoothArc(x, y, r, ir, startAngle, endAngle, fg_color, bg_color, roundEnds = false)：抗锯齿弧，r/ir为外/内半径，roundEnds控制端点是否圆头；
• drawArc(...)：与drawSmoothArc相同但弧端不做抗锯齿，适合动态改变弧长的场景（如仪表表盘随数值伸缩），通过smoothArc = true参数控制是否启用平滑；
• fillSmoothCircle(x, y, r, color, bg_color)：抗锯齿填充圆；
• drawWideLine(ax, ay, bx, by, wd, fg_color, bg_color)：楔形宽线。

弧线绘制算法使用优化的定点sqrt()函数，在没有硬件浮点单元（FPU）的处理器（如 RP2040）上性能更好——这是针对嵌入式处理器特性做的关键优化。

配套示例位于 examples/Smooth Graphics 目录，包括：

• Draw_Smooth_Circles：演示drawSmoothCircle，其注释说明圆周边约 3 像素"厚度"以最小化窄抗锯齿线的"编织"效应；更粗/更细的圆轮廓使用drawArc（Draw_Smooth_Circles.ino）；
• Draw_Arc、Smooth_Arc、Arc_meter_demo：弧与仪表绘制；
• Smooth_Rounded_Rectangles：抗锯齿圆角矩形；
• Anti-aliased_Clock、Colour_Wheel、Smooth_Graphics_Demo：综合演示。

README 展示的两张 240×240 对比图直观说明了平滑（抗锯齿圆头弧）与关闭平滑（同分辨率下出现明显锯齿）的差异；随后展示的 320×240 仪表图说明平滑弧足以构建抗锯齿仪表盘界面。

七、触摸控制器与按钮组件

7.1 XPT2046 触摸支持

库内建支持 XPT2046 触摸控制器，仅限 SPI 接口显示屏。触摸控制器的 SPI 总线与 TFT 共享，只需额外一根片选线即可。README 表示该支持未来在合适的触摸库出现后会被弃用。

从 User_Setup.h 看，只需定义一个引脚即可启用触摸：

#define TOUCH_CS 21 // 触摸屏的片选引脚（T_CS）

触摸时钟频率由SPI_TOUCH_FREQUENCY控制（默认 2.5MHz，User_Setup.h）。相关示例包括 examples/Generic/Touch_calibrate（校准）、examples/Test and diagnostics/Test_Touch_Controller 以及带触摸的 RPi 屏配置（Setup10/11/36系列）。第三方触摸库也可用于并行接口显示屏的触摸方案。

7.2 Button 组件

库内置了来自 Adafruit_GFX 的 Button 类，并做了增强：按钮标签可以使用任意字体。相关演示见 examples/GUI Widgets/Buttons/Button_demo。

此外 README 提到新增的 GUI 示例（滑条、按钮、图表、仪表）需要配套的 TFT_eWidget 目录（Graphs、Meters、Sliders等）。

八、ESP8266 overlap 模式与 8 位并行屏

8.1 ESP8266 SPI overlap 模式

库支持 ESP8266 的 SPI overlap 模式：TFT 与程序 FLASH 共享 MOSI、MISO、SCLK 引脚，从而释放 GPIO 供其他用途。约束条件：

• FLASH 引脚上只能连接一个 SPI 设备；
• TFT 的片选必须接在 D3（GPIO0）引脚。

配置只需在User_Setup.h中启用：

//#define TFT_SPI_OVERLAP //#define TFT_CS PIN_D3 // overlap 模式下片选必须为 D3

overlap 模式共享 ESP8266 FLASH 的 SPI 总线，因此有性能影响；且由于部分屏在片选拉高时 MISO 线不进入高阻态，README 建议最好不要接 MISO（User_Setup.h）。

8.2 ESP32 / STM32 的 8 位并行接口

常见的 8 位 "Mcufriend" 盾板支持 STM32 Nucleo 64/144 与 ESP32 UNO 式板卡；STM32 "Blue/Black Pill" 也可用于 8 位并行屏。由于 GPIO 引脚不足，ESP8266 不支持 8 位并行接口。

README 给出了一个非常实用的硬件改造经验：典型 UNO/mcufriend 屏把LCD_RD、LCD_CS、LCD_RST映射到 ESP32 的模拟引脚 35、34、36，而这三个引脚是仅输入的。解决办法是在板底飞线：

• IO15 接到 IO35
• IO33 接到 IO34
• IO32 接到 IO36

对应的示例配置见 User_Setups/Setup14_ILI9341_Parallel.h（已包含这块 UNO 板的正确 GPIO）。另外，若屏幕带电阻式触摸，可通过仓库提到的修改方案配合 Adafruit_TouchScreen 的 fork 库使用。

8 位并行下 STM32 还有专门的性能优化：若并行数据总线使用 Port A 或 B 的 0-7 号引脚，定义STM_PORTA_DATA_BUS或STM_PORTB_DATA_BUS可提升约 8 倍渲染性能（User_Setup.h）。

九、RP2040 的 PIO 并行接口与 16 位并行支持

RP2040 是 README 反复强调的重点平台，其并行接口使用 PIO（可编程 I/O）实现：

• PIO 接管 setWindow 与块填充操作：当屏幕区域被填充颜色时，PIO 释放处理器去处理其他任务（README.md）。这解释了为什么 RP2040 的并行屏填充性能优异。
• PIO 也可用于 SPI 屏：在 setup 文件中定义RP2040_PIO_SPI即可。使用 PIO 接口时不支持触摸屏与像素读取操作。
• 仅兼容 Earle Philhower 的板卡包：RP2040 PIO 功能只适用于 earlephilhower/arduino-pico 板卡包，不适用于 Arduino Mbed 版本；用 PIO 驱动 SPI 时 RP2040 可超频至 250MHz 同时保持高 SPI 时钟。
• 16 位并行支持（v2.4.70 起）：RP2040 支持 16 位并行屏，实测 320×480 屏用 HX8357C 清屏仅 4ms；PIO 让写周期时序调整变得容易；16 位传输的 DMA 同样受支持。
• 写周期分频：并行接口写周期 =CPU 时钟 / (4 × RP2040_PIO_CLK_DIV)。超频时可能需要增大分频；不同控制器（ILI9341、HX8357C 等）要求不同，若周期太短会导致屏幕无法初始化或图形损坏（User_Setup.h）。

RP2040 的示例配置覆盖 SPI、8 位并行与 16 位并行三种接口，见 User_Setups 中的Setup60~62、Setup100~108系列（如 Setup105_RP2040_ST7796_16bit_parallel.h）。

十、典型启动流程与示例生态

综合以上内容，一块新屏 + 新板卡从零到跑通的典型流程是：

1. 安装库：通过 Arduino IDE 的 Library Manager 加载本库（README 明确说明支持该方式）；PlatformIO 用户参考 docs/PlatformIO 下的配置说明，其中 External setup for Platform_IO.txt 详细介绍了TFT_ESPI_USER_SETUP_PATH的用法。
2. 接线：按User_Setup.h注释中的接法表连接 SPI（SCLK/MOSI/MISO/DC/CS/RST）或并行总线。
3. 配置：编辑 User_Setup.h（或复制 User_Setups 中对应板卡文件到自定义文件夹后修改）：选择驱动宏、填写引脚、选择字体。
4. 验证配置：运行 examples/Test and diagnostics/Read_User_Setup 与 examples/Test and diagnostics/Colour_Test，确认USER_SETUP_INFO与颜色输出正常。
5. 跑图形测试：运行 examples/320 x 240/TFT_graphicstest_one_lib 等综合示例；README 还提供了与 Adafruitgraphicstest的对比数据：整个测试在 160×128 Sprite 中 18ms 完成（README.md）。
6. 进阶功能：按需引入 Sprite（examples/Sprite）、平滑字体（examples/Smooth Fonts）、平滑图形（examples/Smooth Graphics）、PNG 解码（examples/PNG Images，注意需要约 40KB RAM）与触摸校准。

README 还提到一些实用特性：部分屏允许读取内部 TFT 屏幕 RAM，examples/Generic/TFT_Screen_Capture 示例可将整屏捕获并发送到 PC，便于制作程序文档；DMA 相关示例集中在 examples/DMA test（Bouncy_Circles、Flash_Jpg_DMA、boing_ball 等）。

结语

TFT_eSPI 的价值在于把"配置驱动化、渲染性能化、字体平滑化"三者统一在一个与 Adafruit GFX 兼容的接口之下：User_Setup.h一处配置即可适配从 ESP8266 到 RP2040 的数十种控制器与接口组合；Sprite 提供了 RAM 内双缓冲的无闪烁渲染路径；vlw 平滑字体配合防闪烁刷新机制让中文、日文等任意 Unicode 字形也能在低端 32 位 MCU 上流畅呈现。无论你是想驱动一块入门 ILI9341，还是在 RP2040 上玩转 16 位并行 DMA，本文梳理的配置脉络与源码证据都能帮助你快速定位正确的做法，并借助仓库 examples 目录中丰富的示例进一步深入实践。

【免费下载链接】TFT_eSPIArduino and PlatformIO IDE compatible TFT library optimised for the Raspberry Pi Pico (RP2040), STM32, ESP8266 and ESP32 that supports different driver chips项目地址: https://gitcode.com/GitHub_Trending/tf/TFT_eSPI