跳到主要内容

图片显示(JPG / PNG / 动画)

屏幕最终显示的永远是像素,不是"文件"。独角仙S1 的图片接口按解码方式分成三条路:jpg() 边解码边刷屏(最省事)、png() 逐行流式解码(最省内存、支持透明)、bitmap() 显示预先转换好的位图(最快)。所谓播放 GIF 动画,本质上就是按顺序把每一帧尽快显示出来,所以本页后面会给出三种可行的逐帧方案。

jpg() 要选模式

第三个参数是 st7789.FAST(默认)或 st7789.SLOW。小图用 FAST,全屏背景用 SLOW。

图片必须放得下

窗口越出屏幕边缘时整张图直接不显示(不是裁掉一半),而且不报错。

png() 最省内存

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:每个小块单独设窗口,越界的小块同样画不上去。

一旦越界,不会有任何报错,表现是图片完全不显示或者局部花屏。独角仙S1 的屏幕只有 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)
参数类型必填说明
srcstr 或 bytes是文件路径,或内存里的 JPEG 数据
x / yint是图片左上角在屏幕上的坐标
modeint否st7789.FAST(0,默认) 或 st7789.SLOW(1)

返回 None。图片越界、或内存不足时会失败(见排错表)。

png(filename, x, y[, mask])​

tft.png(filename, x, y, mask)
参数类型必填说明
filenamestr是文件路径,只支持路径
x / yint是图片左上角坐标
maskbool否默认 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)
参数类型必填说明
srcstr 或 bytes是文件路径或内存数据
x / yint否在源图里的裁剪起点,不是屏幕坐标
width / heightint否裁剪尺寸;返回缓冲区的尺寸就等于它

返回一个三元组 (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 / yint是显示位置
indexint否帧号,从 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 生成的字库
sstr—要显示的文字
x / yint—起始坐标
fgintWHITE字模为 1 的像素颜色
bgintBLACK字模为 0 且没有背景图时的颜色
bg_tuple元组无(背景缓冲, 宽, 高),通常来自 jpg_decode()
fillint0传 1 时每个字符按字体最宽字符宽度铺满,配背景图使用

返回实际打印的像素宽度。不在字库里的字符会被静默跳过。

常见坑点​

坑原因与正确写法
图片完全不显示x + 宽 或 y + 高 超出屏幕,窗口被整体拒绝且不报错 → 用 width() / height() 算好位置
全屏背景没铺满图片分辨率与屏幕(135 × 240 / 240 × 135)不一致 → 图片按屏幕分辨率做,或全屏不透明覆盖
大图报 out of memoryjpg() 需要 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 argumentsjpg_decode() 参数个数只能是 2 或 6(含 self);只解码整张图就不传裁剪参数
OSError: out of memory图片太大;jpg() 的 2×宽×高 申请失败
OSError: buffer too small. N bytes required.构造时传的 buffer_size 小于本次操作所需,调大或设为 0
OSError: index out of rangebitmap() 的帧号 ≥ 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,直接生成能在独角仙S1 上运行的完整程序。

比如直接对它说:

开机先显示一张全屏背景图,然后在右下角循环播放 12 帧的小动画,退出时清屏。

它就会把 jpg()、jpg_decode() / blit_buffer() 和 tft_config 组合成一个能跑的程序,并帮你放进 SD 卡的 /sd/apps/。

Agent 入口(即将上线)

入口链接会放在这里。上线后点一下,就能直接开始描述你想要的应用。