图片显示(JPG / PNG / 动画)
屏幕最终显示的永远是像素,不是"文件"。萤火虫T1 的图片接口按解码方式分成三条路:jpg() 边解码边刷屏(最省事)、png() 逐行流式解码(最省内存、支持透明)、bitmap() 显示预先转换好的位图(最快)。所谓播放 GIF 动画,本质上就是按顺序把每一帧尽快显示出来,所以本页后面会给出三种可行的逐帧方案。
第三个参数是 st7789.FAST(默认)或 st7789.SLOW。小图用 FAST,全屏背景用 SLOW。
窗口越出屏幕边缘时整张图直接不显示(不是裁掉一半),而且不报错。
png() 逐行解码,只需"一行像素"的缓冲区;jpg() 需要整张图的内存。
快速开始
先把图片放进 SD 卡,比如 /sd/apps/myapp/logo.jpg,然后:
import st7789
import tft_config
tft = tft_config.config(1) # 1 = 横屏 240×135
tft.init()
tft.fill(st7789.BLACK)
tft.jpg('/sd/apps/myapp/logo.jpg', 10, 10, st7789.FAST)
运行现象:图片左上角贴在屏幕 (10, 10) 处。
想用一张图铺满整个屏幕,任何旋转下都能贴满的写法是这样:
tft.jpg('/sd/apps/myapp/bg.jpg', 0, 0, st7789.SLOW)
显示 JPG 图片
tft.jpg('/sd/apps/myapp/logo.jpg', 10, 10, st7789.FAST)
jpg() 的第一个参数可以是文件路径字符串,也可以是内存里的 bytes 缓冲(比如从网络下载回来的图片数据)。
FAST 与 SLOW 怎么选
st7789.FAST(值为 0) | st7789.SLOW(值为 1) | |
|---|---|---|
| 解码方式 | 一次性把整张图解码到内存,再整屏刷入 | 按 8×8(或 16×16)的小块边解码边刷入 |
| 内存占用 | 2 × 宽 × 高 字节,必须连续可用 | 2 × 补齐到 8 的宽 × 补齐到 8 的高 字节 |
| 速度 | 小图更快(一次 SPI 传输) | 大图 / 全屏背景更稳(分块推进) |
| 适用 | 小图标、逐帧动画 | 全屏背景图 |
省略第三个参数时默认就是 FAST。官方光绘 App 的用法正好印证这条分界线:全屏背景用 SLOW,小图用 FAST。
tft.jpg('/sd/apps/light-painter/main.jpg', 0, 0, st7789.SLOW) # 全屏背景
tft.jpg('/sd/image/photo.jpg', (tft.width() - 100) // 2, 20, st7789.FAST) # 小图
图片尺寸必须放得下
这是最容易踩的坑。驱动在刷屏前会设置显示窗口,而窗口只要越界就会被整体拒绝:
- FAST:窗口是
(x, y)到(x + 宽 - 1, y + 高 - 1),所以要求x + 宽 ≤ 屏幕宽且y + 高 ≤ 屏幕高。 - SLOW:每个小块单独设窗口,越界的小块同样画不上去。
一旦越界,不会有任何报错,表现是图片完全不显示或者局部花屏。萤火虫T1 的屏幕只有 135 × 240(横屏 240 × 135),很容易撞上这个限制,所以摆放前先用 width() / height() 算一遍:
w, h = 100, 100
x = (tft.width() - w) // 2
y = (tft.height() - h) // 2
tft.jpg('/sd/image/logo.jpg', x, y, st7789.FAST)
显示 PNG 图片
tft.png('/sd/apps/myapp/logo.png', 10, 10) # 不透明,忽略透明通道
tft.png('/sd/apps/myapp/logo.png', 10, 10, True) # 开启透明,透明像素保留屏幕原内容
png() 只接受文件路径(不像 jpg() 还能传 bytes)。它逐行解码,缓冲区只需一行像素(图片宽 × 2 字节),所以比 jpg() 更省内存,适合大图。
第四个参数是透明开关:
False(默认):忽略 alpha 通道,透明像素按它自带的 RGB 画成不透明。True:alpha 为 0 的像素跳过不画,屏幕上原本的内容会透出来——这样就能把 PNG 的图标叠在别的背景上。
落在屏幕外的像素会被跳过,不会报错。
播放逐帧动画(GIF)
固件没有内置 GIF 解码器。播放动画的做法是提前把 GIF 拆成一张张静态帧(或用工具生成位图帧),再用下面三种方式之一循环显示。
方式一:连续的 JPG 帧(最省事)
把 GIF 拆成 frame-0.jpg、frame-1.jpg……放进 SD 卡,循环显示即可。
import os
import time
import st7789
import tft_config
tft = tft_config.config(1)
tft.init()
tft.fill(st7789.BLACK)
frame_dir = '/sd/apps/myapp/frames/'
frames = sorted(os.listdir(frame_dir))
delay = 0.05 # 每帧 50 毫秒 ≈ 20 fps
try:
while True:
for name in frames:
tft.jpg(frame_dir + name, 17, 70, st7789.FAST)
time.sleep(delay)
except KeyboardInterrupt:
tft.fill(st7789.BLACK)
- 优点:不需要任何转换,改帧率只要改
delay。 - 缺点:每帧都要重新解码,帧率高时跟不上。
- 适合:帧数多、单帧像素少的动画。
方式二:jpg_decode() + blit_buffer()(解码与显示分开)
jpg_decode() 把图片解码成一块可以直接贴到屏幕上的像素缓冲,再用 blit_buffer() 贴到任意位置。适合"一帧解码、多位置复用"的场景。
import time
import st7789
import tft_config
tft = tft_config.config(1)
tft.init()
# 不传裁剪参数时解码整张图,返回 (缓冲区, 宽, 高)
frame, w, h = tft.jpg_decode('/sd/apps/myapp/hero.jpg')
for i in range(20):
tft.fill_rect(i * 6, 20, w, h, st7789.BLACK) # 擦掉上一帧
tft.blit_buffer(frame, i * 6, 20, w, h) # 贴这一帧
time.sleep(0.03)
jpg_decode(path, x, y, width, height) 传 6 个参数时,x, y, width, height 指的是在源图里裁剪哪一块(不是贴到哪里),返回的缓冲区尺寸就是 width × height。
源码里 jpg_decode() 每次调用都会新申请 2 × 宽 × 高 字节,并且不会释放。所以在循环里反复调用它会把堆内存耗尽。正确做法是解码一次、反复 blit_buffer(),或者改用方式一 / 方式三。
方式三:位图帧 bitmap()(最快)
用 PC 端的 sprites2bitmap.py 把帧序列(雪碧图)预先转成 Python 模块,运行时只需把调色板展开,不用解码 JPEG。
python3 sprites2bitmap.py frames.bmp 64 64 4 > sprites.py
生成的模块里带有 WIDTH / HEIGHT / BPP / PALETTE / BITMAPS / BITMAP,拷进 SD 卡直接 import 后交给 bitmap():
import time
import st7789
import tft_config
import sprites # 上面生成的位图帧模块
tft = tft_config.config(1)
tft.init()
tft.fill(st7789.BLACK)
while True:
for i in range(sprites.BITMAPS): # BITMAPS 是总帧数
tft.bitmap(sprites, 30, 30, i) # 第三个参数是帧号
time.sleep(0.06)
- 优点:运行时无解码开销,帧率上限最高。
- 缺点:需要预先转换,且整个帧序列都要放进内存。
PALETTE里的颜色必须是字节交换后的 RGB565(转换脚本已经处理好,自己手写时要注意)。- 帧号超出
BITMAPS会抛OSError: index out of range;省略帧号则显示第 0 帧。
在背景图片上写字
text() 只能"前景色 + 背景色"两色写字,会把背景盖住。想在背景图上叠加文字且保留背景细节,要用 write() 的 bg_tuple 和 fill 参数:
import st7789
import tft_config
import NotoSans_32 as font
tft = tft_config.config(1)
tft.init()
tft.jpg('/sd/apps/myapp/main.jpg', 0, 0, st7789.SLOW) # 1. 铺背景
# 2. 把文字要出现的那块背景,按字体大小裁剪出来
bg, w, h = tft.jpg_decode('/sd/apps/myapp/main.jpg', 10, 10, font.MAX_WIDTH, font.HEIGHT)
# 3. write(字体, 文字, x, y, 前景色, 背景色, (背景缓冲, 宽, 高), fill)
tft.write(font, "Hello", 10, 10, st7789.WHITE, st7789.BLACK, (bg, w, h), 1)
原理(来自驱动源码):字模里为 1 的像素画成前景色,为 0 的像素保留 bg_tuple 里对应位置的背景颜色;fill 传 1 时每个字符都按字体最宽字符的宽度铺满,这样背景贴片才对得齐。背景缓冲的尺寸要正好是 font.MAX_WIDTH × font.HEIGHT。
write()用的是font2bitmap生成的字库(含MAX_WIDTH/WIDTHS/OFFSETS/BITMAPS),不能用vga*那种等宽字库。详情见 字库应用与制作。
API 参考
tft 就是 tft_config.config() 返回的 st7789.ST7789 实例,图片接口全部挂在它上面。
jpg(src, x, y[, mode])
tft.jpg(src, x, y, st7789.FAST)
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
src | str 或 bytes | 是 | 文件路径,或内存里的 JPEG 数据 |
x / y | int | 是 | 图片左上角在屏幕上的坐标 |
mode | int | 否 | st7789.FAST(0,默认) 或 st7789.SLOW(1) |
返回 None。图片越界、或内存不足时会失败(见排错表)。
png(filename, x, y[, mask])
tft.png(filename, x, y, mask)
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
filename | str | 是 | 文件路径,只支持路径 |
x / y | int | 是 | 图片左上角坐标 |
mask | bool | 否 | 默认 False。True 时 alpha=0 的像素不画,保留屏幕原内容 |
返回 None。逐行解码,内存占用低。
jpg_decode(src[, x, y, width, height])
buffer, width, height = tft.jpg_decode(src)
buffer, width, height = tft.jpg_decode(src, x, y, width, height)
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
src | str 或 bytes | 是 | 文件路径或内存数据 |
x / y | int | 否 | 在源图里的裁剪起点,不是屏幕坐标 |
width / height | int | 否 | 裁剪尺寸;返回缓冲区的尺寸就等于它 |
返回一个三元组 (buffer, width, height):buffer 是 RGB565(字节已交换)的 bytearray,可直接交给 blit_buffer()。只传 1 个参数(合计 2 个,含 self)就是解码整张图;参数个数不是 2 或 6 时抛 TypeError: jpg_decode requires either 2 or 6 arguments。
blit_buffer(buffer, x, y, width, height)
tft.blit_buffer(buffer, x, y, width, height)
把一块 RGB565 像素缓冲贴到屏幕 (x, y),必须传满 6 个参数。实际发送的字节数是 min(缓冲区长度, 宽 × 高 × 2),所以缓冲区小了只会显示一部分,不会报错。
bitmap(bitmap_module, x, y[, index])
tft.bitmap(bitmap_module, x, y, index)
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
bitmap_module | 模块 | 是 | 需含 WIDTH HEIGHT BPP PALETTE BITMAP,多帧还需要 BITMAPS |
x / y | int | 是 | 显示位置 |
index | int | 否 | 帧号,从 0 开始,默认 0 |
index 超出 BITMAPS 抛 OSError: index out of range;x + WIDTH 超出屏幕时整帧不显示。
write(font, s, x, y[, fg, bg, bg_tuple, fill])
tft.write(font, s, x, y, fg, bg, (buffer, width, height), fill)
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
font | 模块 | — | font2bitmap 生成的字库 |
s | str | — | 要显示的文字 |
x / y | int | — | 起始坐标 |
fg | int | WHITE | 字模为 1 的像素颜色 |
bg | int | BLACK | 字模为 0 且没有背景图时的颜色 |
bg_tuple | 元组 | 无 | (背景缓冲, 宽, 高),通常来自 jpg_decode() |
fill | int | 0 | 传 1 时每个字符按字体最宽字符宽度铺满,配背景图使用 |
返回实际打印的像素宽度。不在字库里的字符会被静默跳过。
常见坑点
| 坑 | 原因与正确写法 |
|---|---|
| 图片完全不显示 | x + 宽 或 y + 高 超出屏幕,窗口被整体拒绝且不报错 → 用 width() / height() 算好位置 |
| 全屏背景没铺满 | 图片分辨率与屏幕(135 × 240 / 240 × 135)不一致 → 图片按屏幕分辨率做,或全屏不透明覆盖 |
大图报 out of memory | jpg() 需要 2 × 宽 × 高 连续内存 → 缩小图片,或改用 png() |
初始化时设了 buffer_size 就报错 | buffer_size 是常驻缓冲,比图片需求小时抛 OSError: buffer too small. N bytes required. → 一般保持默认 0 |
循环里用 jpg_decode() 一会儿就内存不足 | 源码里它申请的内存不释放 → 解码一次后反复 blit_buffer(),或改用 jpg(FAST) 逐帧 |
bitmap() 花屏 / 颜色不对 | PALETTE 必须是字节交换后的 RGB565 → 用配套的 sprites2bitmap.py / imgtobitmap.py 生成 |
write() 显示不出中文 | 用错字库了:write() 要 font2bitmap 生成的库(含 MAX_WIDTH),text() 才是 vga* 等宽库 |
| 动画闪烁 | 每帧先清屏再画 → 改成"只擦上一帧、只画这一帧",或用不透明背景的整帧覆盖 |
| 逐帧动画卡顿 | 每帧都要重新解码 JPEG → 缩小帧尺寸、降低帧率,或改用位图帧方案 |
排错
| 报错 / 现象 | 处理 |
|---|---|
TypeError: jpg_decode requires either 2 or 6 arguments | jpg_decode() 参数个数只能是 2 或 6(含 self);只解码整张图就不传裁剪参数 |
OSError: out of memory | 图片太大;jpg() 的 2×宽×高 申请失败 |
OSError: buffer too small. N bytes required. | 构造时传的 buffer_size 小于本次操作所需,调大或设为 0 |
OSError: index out of range | bitmap() 的帧号 ≥ BITMAPS |
RuntimeError: jpg prepare failed. | 文件不是有效 JPEG,或路径不存在 |
RuntimeError: jpg decompress failed. | JPEG 数据损坏 |
RuntimeError: png decompress failed: ... | PNG 损坏或用了不支持的格式 |
| 显示全黑 / 花屏 | 图片越界(窗口被拒绝),或 buffer_size 与图片尺寸不匹配 |
| 图片只有一部分画出来 | blit_buffer() 的缓冲区比 宽 × 高 × 2 小 → 用 jpg_decode() 返回的 w / h 原样传 |
相关模块:显示屏(ST7789) · 字库应用与制作 · USB串口控制(CDC)
AI 用法(即将上线)
以后你不用记 FAST 和 SLOW 的区别、也不用算图片会不会出界:用自然语言描述你想要的画面,Agent 会照着本文档里的 API,直接生成能在萤火虫T1 上运行的完整程序。
比如直接对它说:
开机先显示一张全屏背景图,然后在右下角循环播放 12 帧的小动画,退出时清屏。
它就会把 jpg()、jpg_decode() / blit_buffer() 和 tft_config 组合成一个能跑的程序,并帮你放进 SD 卡的 /sd/apps/。
入口链接会放在这里。上线后点一下,就能直接开始描述你想要的应用。