class SPIDisplay -- SPI 显示驱动¶

SPIDisplay 类驱动小型 SPI 连接的 TFT 和 OLED 面板——最常见的是 OpenMV LCD Shield 上的 SSD1351 128x160 RGB OLED。驱动在内部独占 SPI 总线以及一条 GPIO 片选 / DC 线，因此调用者只需配置面板几何尺寸、刷新率以及任何方向标志。面板专用的初始化（寄存器序列、RAM 写入帧格式）通过 controller 关键字参数提供——传入 SSD1351 实例以驱动 LCD Shield，或为其他面板实现你自己的控制器类。

通过调用 write() 并传入 image.Image 来呈现帧。驱动会将源转换为 RGB565，并在内部应用缩放、ROI、调色板和方向变换，因此调用者无需预先调整图像尺寸。背光亮度可保持为简单的开/关 GPIO（默认），或通过将 DACBacklight / PWMBacklight 作为 backlight 关键字参数传入来驱动。

示例——将摄像头镜像到 OpenMV LCD Shield 的 SSD1351 OLED 上:

import csi
import display

csi0 = csi.CSI()
csi0.reset()
csi0.pixformat(csi.RGB565)
csi0.framesize((128, 160))        # matches the SSD1351 panel

lcd = display.SPIDisplay(controller=display.SSD1351())

while True:
    lcd.write(csi0.snapshot())

构造函数¶

class display.SPIDisplay(width: int = 128, height: int = 160, refresh: int = 60, bgr: bool = False, byte_swap: bool = False, hmirror: bool = True, vflip: bool = True, triple_buffer: bool | None = None, *, controller: object | None = None, backlight: object | None = None)¶

width SPI LCD 宽度，单位为像素（1..32767）。

height SPI LCD 高度，单位为像素（1..32767）。

refresh LCD 刷新率，单位为赫兹（1..120）。控制 SPI 时钟速率。

bgr 设置为 True 以交换红色和蓝色通道。

byte_swap 设置为 True 以交换发送到 LCD 的 RGB565 像素字节。

hmirror 设置为 True 以水平镜像显示输出。

vflip 设置为 True 以垂直翻转显示输出。

triple_buffer 如果为 True，则使屏幕更新变为非阻塞，代价是占用 3 倍显示尺寸的 RAM。默认值取决于开发板（带 SDRAM 的开发板默认开启）。

controller 仅限关键字参数。传入控制器芯片类实例，以便在初始化显示器时一并将其初始化。提供后，将调用该控制器的 init、display_on、display_off 和 ram_write 方法（若存在），而不是内置命令。

backlight 仅限关键字参数。传入要使用的背光控制器模块。默认情况下，背光通过 GPIO 引脚控制。

width() → int¶: 返回屏幕的宽度。

height() → int¶: 返回屏幕的高度。

refresh() → int¶: 返回刷新率。

bgr() → bool¶: 返回红色和蓝色通道是否被交换。

byte_swap() → bool¶: 返回 RGB565 像素是否以字节反转方式发送。

triple_buffer() → bool¶: 返回是否启用了三重缓冲。

framesize() → int¶: 返回配置的 framesize 标识符。

write(image: image.Image, x: int = 0, y: int = 0, x_scale: float = 1.0, y_scale: float = 1.0, roi: Tuple[int, int, int, int] | None = None, rgb_channel: int = -1, alpha: int = 255, color_palette: int | image.Image | None = None, alpha_palette: image.Image | None = None, hint: int = 0) → None¶

显示 image，其左上角位于 (x, y)。可以传入路径字符串代替图像，从而一步完成加载和绘制。

x_scale x 轴缩放因子。负值会水平翻转。如果省略 y_scale，它将跟随 x_scale 以保持纵横比。

y_scale y 轴缩放因子。负值会垂直翻转（需要 triple_buffer=True）。如果省略 x_scale，它将跟随 y_scale。

roi 要绘制的源图像的感兴趣区域矩形 (x, y, w, h)。

rgb_channel 要从 RGB565 源图像中提取的 RGB 通道（0=R，1=G，2=B，-1=全部）。范围：-1..2。

alpha 图像的不透明度。0 为完全透明（黑色），255 为不透明。范围：0..255。

color_palette 颜色调色板枚举（例如 image.PALETTE_RAINBOW），或一张 256 像素的 RGB565 图像，用作针对源图像灰度值的颜色查找表。在 rgb_channel 提取之后应用。

alpha_palette 一张 256 像素的灰度图像，用作逐像素 alpha 查找表，根据源图像灰度值调制 alpha。

hint 以下标志的逻辑或：

image.AREA：在缩小时使用面积缩放。

image.BILINEAR：使用双线性缩放。

image.BICUBIC：使用双三次缩放。

image.CENTER：在显示器上居中图像（缩放后）。

image.HMIRROR：水平镜像图像。

image.VFLIP：垂直翻转图像。

image.TRANSPOSE：转置图像（交换 x/y）。

image.EXTRACT_RGB_CHANNEL_FIRST：在缩放之前应用 rgb_channel 提取。

image.APPLY_COLOR_PALETTE_FIRST：在缩放之前应用 color_palette。

image.SCALE_ASPECT_KEEP：缩放以适应显示器内部。

image.SCALE_ASPECT_EXPAND：缩放以填满显示器（裁剪）。

image.SCALE_ASPECT_IGNORE：缩放以填满显示器（拉伸）。

image.ROTATE_90：旋转 90 度（VFLIP | TRANSPOSE）。

image.ROTATE_180：旋转 180 度（HMIRROR | VFLIP）。

image.ROTATE_270：旋转 270 度（HMIRROR | TRANSPOSE）。

clear(display_off: bool = False) → None¶

将 LCD 屏幕清为黑色。

display_off 如果为 True，则关闭显示逻辑，而不是清除帧缓冲区。此后还应禁用背光。

backlight(value: int | None = None) → int | None¶

带有 value 时，设置背光强度（0=关闭..100=全亮）。不带参数时，返回当前背光值。

除非在构造时传入了 DACBacklight 或 PWMBacklight 控制器，否则背光将作为 GPIO 引脚驱动，只能在 0（关闭）和非零（开启）之间切换。

bus_write(cmd: int, args: int | bytes | None = None, *, dcs: bool = False) → None¶: 通过 SPI 总线向显示器发送 cmd，可选地后跟 args（一个整数字节或一个字节缓冲区）。dcs 在控制器支持时选择 DCS 帧格式。

bus_read(cmd: int, len: int, args: int | bytes | None = None, *, dcs: bool = False) → bytearray¶: 通过 SPI 总线发送 cmd 并读回 len 个字节，以 bytearray 形式返回。args 可选地在读取之前写入（一个整数字节或一个字节缓冲区）。dcs 在控制器支持时选择 DCS 帧格式。

ioctl(cmd: int, arg: object | None = None) → object¶: 发出控制器专用的 ioctl cmd，并带可选的 arg。如果底层显示器不支持 ioctl，则引发 ValueError。