注意

这是最新开发分支配套的文档，可能包含已发布版本中尚未提供的功能。如果您要查看特定版本的文档，请使用左侧的下拉菜单并选择所需要的版本。

Display 模块 API 手册

注意

该模块自固件版本 V0.7 起有较大更改，若您使用的是 V0.7 之前的固件，请参考旧版本文档。

概述

本手册旨在指导开发人员使用 Micro Python API 调用 CanMV Display 模块，实现图像显示功能。

如需增加自定义屏幕，可参考Display Debugger

API 介绍

init

描述

初始化 Display 通路，包括 VO 模块、 DSI 模块和 LCD/HDMI。

语法

init(type, width=0, height=0, fps=0, flag=0, osd_num=1, to_ide=False, quality=90)

参数

参数名称	描述	输入 / 输出	说明
type	显示设备类型	输入	必选
width	分辨率宽度	输入	可选参数，默认值根据 type 决定
height	分辨率高度	输入	可选参数，默认值根据 type 决定
fps	显示帧率	输入	仅部分显示设备类型支持指定帧率
flag	显示标志	输入
osd_num	在 show_image 时支持的 OSD 图层数量	输入	越大占用内存越多，默认值为1
to_ide	是否将屏幕显示传输到 IDE 显示	输入	开启时占用更多内存，通过 WBC 功能实现
quality	设置 JPEG 压缩质量	输入	仅在 to_ide=True 时有效，范围 [10-100]，默认90

返回值

返回值	描述
无

deinit

描述

执行反初始化，deinit 方法会关闭整个 Display 通路，包括 VO 模块、DSI 模块和 LCD/HDMI。

语法

deinit()

返回值

返回值	描述
无

inited

描述

查询 Display 模块是否已初始化。

语法

inited()

返回值

返回值	描述
bool	True 表示已初始化，False 表示未初始化

config_layer

描述

配置显示层的属性。此方法通常在绑定层之前调用，用于设置图层的显示参数。

语法

config_layer(rect, pix_format, layer, alpha=255, flag=0)

参数

参数名称	描述	输入 / 输出	说明
rect	显示区域 (x, y, w, h)	输入	必选，元组形式
pix_format	图像像素格式	输入	参见 pix_format
layer	显示层 ID	输入	必选，指定要配置的图层
alpha	图层混合透明度	输入	范围 0-255，默认255（不透明）
flag	显示标志	输入	默认0

返回值

返回值	描述
int	配置的图层 ID

bind_layer

描述

将 sensor 或 vdec 模块的输出绑定到屏幕显示。无需用户手动干预即可持续显示图像。

语法

bind_layer(src, rect, pix_format, layer, alpha=255, flag=0)

参数

参数名称	描述	输入 / 输出	说明
src	源通道信息 (mod, dev, chn)	输入	可通过 sensor.bind_info() 获取，格式为元组
rect	显示区域 (x, y, w, h)	输入	可通过 sensor.bind_info() 获取
pix_format	图像像素格式	输入	可通过 sensor.bind_info() 获取
layer	绑定到 Display 的显示层	输入	可绑定到 video 或 osd 层
alpha	图层混合透明度	输入	范围 0-255，默认255
flag	显示标志	输入	默认0

返回值

返回值	描述
无

unbind_layer

描述

解绑指定图层的绑定关系。

语法

unbind_layer(layer)

参数

参数名称	描述	输入 / 输出	说明
layer	显示层 ID	输入	必选

返回值

返回值	描述
bool	True 表示解绑成功，False 表示失败

disable_layer

描述

禁用指定的显示层。

语法

disable_layer(layer)

参数

参数名称	描述	输入 / 输出	说明
layer	显示层 ID	输入	必选

返回值

返回值	描述
无

show_image

描述

在屏幕上显示图像。

语法

show_image(img, x=0, y=0, layer=Display.LAYER_OSD0, alpha=None, pixel_format=None, flag=0)

参数

参数名称	描述	输入 / 输出	说明
img	要显示的图像对象	输入	必选
x	起始坐标的 x 值	输入	默认0
y	起始坐标的 y 值	输入	默认0
layer	显示到指定层	输入	仅支持 OSD 层，默认 LAYER_OSD0
alpha	图层混合透明度	输入	范围 0-255，None 表示使用图层原有设置
pixel_format	图像像素格式	输入	None 表示使用图像原有格式，参见 pix_format
flag	显示标志	输入	默认0

返回值

返回值	描述
无

width

描述

获取屏幕或某一图层的显示宽度。

语法

width(layer=None)

参数

参数名称	描述	输入 / 输出	说明
layer	指定获取显示层的宽度	输入	可选，如果不传则表示获取屏幕的分辨率宽度

返回值

返回值	描述
width	屏幕或显示层的宽度信息，单位像素

height

描述

获取屏幕或某一图层的显示高度。

语法

height(layer=None)

参数

参数名称	描述	输入 / 输出	说明
layer	指定获取显示层的高度	输入	可选，如果不传则表示获取屏幕的分辨率高度

返回值

返回值	描述
height	屏幕或显示层的高度信息，单位像素

fps

描述

获取当前的显示帧率。

语法

fps()

返回值

返回值	描述
int	当前的显示帧率，单位 fps

writeback

描述

查询或设置 WriteBack (WBC) 功能状态。WBC 功能用于将屏幕显示内容回传，通常用于传输到 IDE 显示。

语法

writeback(enable=None)

参数

参数名称	描述	输入 / 输出	说明
enable	设置 WBC 功能状态	输入	可选，True 表示开启，False 表示关闭。不传参时表示查询当前状态

返回值

返回值	描述
bool	查询时返回当前 WBC 状态；设置时返回操作结果

writeback_dump

描述

从 WBC 抓取一帧显示内容。需要在 init 时设置 to_ide=True 且 WBC 功能已开启。

语法

writeback_dump(timeout=1000)

参数

参数名称	描述	输入 / 输出	说明
timeout	超时时间（毫秒）	输入	默认1000ms

返回值

返回值	描述
object	返回包含视频帧信息的对象

数据结构描述

type

类型	参数取值	备注
VIRT	640x480@90	默认值 IDE 调试专用，不在外接屏幕上显示内容 用户可自定义设置分辨率 (64x64)-(4096x4096) 和帧率 (1-200)
DEBUGGER		调试屏幕专用
ST7701	Display.init(Display.ST7701, width = 800, height = 480)	默认值 800x480
	Display.init(Display.ST7701, width = 480, height = 800)	480x800
	Display.init(Display.ST7701, width = 854, height = 480)	854x480
	Display.init(Display.ST7701, width = 480, height = 854)	480x854
	Display.init(Display.ST7701, width = 640, height = 480)	640x480
	Display.init(Display.ST7701, width = 480, height = 640)	480x640
	Display.init(Display.ST7701, width = 368, height = 544)	368x544
	Display.init(Display.ST7701, width = 544, height = 368)	544x368
HX8399	Display.init(Display.HX8399, width = 1920, height = 1080)	默认值 1920x1080
	Display.init(Display.HX8399, width = 1080, height = 1920)	1920x1080
ILI9806	Display.init(Display.ILI9806, width = 800, height = 480)	默认值 800x480
	Display.init(Display.ILI9806, width = 480, height = 800)	480x800
LT9611	Display.init(Display.LT9611, width = 1920, height = 1080, fps = 30)	默认值 1920x1080@30
	Display.init(Display.LT9611, width = 1920, height = 1080, fps = 60)	1920x1080@60
	Display.init(Display.LT9611, width = 1280, height = 720, fps = 60)	1280x720@60
	Display.init(Display.LT9611, width = 1280, height = 720, fps = 50)	1280x720@50
	Display.init(Display.LT9611, width = 1280, height = 720, fps = 30)	1280x720@30
	Display.init(Display.LT9611, width = 640, height = 480, fps = 60)	640x480@60
ILI9881	Display.init(Display.ILI9881, width = 1280, height = 800)	默认值 1280x800
	Display.init(Display.ILI9881, width = 800, height = 1280)	800x1280
NT35516	Display.init(Display.NT35516, width=960, height=536)	默认值 960x536
	Display.init(Display.NT35516, width=536, height=960)	536x960
NT35532	Display.init(Display.NT35532, width=1920, height=1080)	默认值 1920x1080
	Display.init(Display.NT35532, width=1080, height=1920)	1080x1920
GC9503	Display.init(Display.GC9503, width=800, height=480)	默认值 800x480
	Display.init(Display.GC9503, width=480, height=800)	480x800
ST7102	Display.init(Display.ST7102, width=640, height=480)	默认值 640x480
	Display.init(Display.ST7102, width=480, height=640)	480x640
AML020T	Display.init(Display.AML020T, width=480, height=360)	默认值 480x360
	Display.init(Display.AML020T, width=360, height=480)	360x480
JD9852	Display.init(Display.JD9852, width=320, height=240)	默认值 320x240
	Display.init(Display.JD9852, width=240, height=320)	240x320

layer

K230 提供 3 层视频图层支持和 4 层 OSD 图层支持。分类如下：

显示层	常量名	说明	支持格式
视频层1	Display.LAYER_VIDEO1	建议用来显示视频数据	仅支持 YUV420SP
视频层2	Display.LAYER_VIDEO2	建议用来显示视频数据	仅支持 YUV420SP
视频层3	Display.LAYER_VIDEO3	建议用来显示视频数据	仅支持 YUV420SP
OSD层0	Display.LAYER_OSD0	图形叠加层	仅支持 RGB 颜色空间
OSD层1	Display.LAYER_OSD1	图形叠加层	仅支持 RGB 颜色空间
OSD层2	Display.LAYER_OSD2	图形叠加层	仅支持 RGB 颜色空间
OSD层3	Display.LAYER_OSD3	图形叠加层	仅支持 RGB 颜色空间

flag

标志	常量名	说明
不旋转	Display.FLAG_ROTATION_NONE 或 0	不进行旋转
旋转0度	Display.FLAG_ROTATION_0	旋转 0 度
旋转90度	Display.FLAG_ROTATION_90	旋转 90 度
旋转180度	Display.FLAG_ROTATION_180	旋转 180 度
旋转270度	Display.FLAG_ROTATION_270	旋转 270 度
无镜像	Display.FLAG_MIRROR_NONE 或 0	不进行镜像
水平镜像	Display.FLAG_MIRROR_HOR	水平镜像
垂直镜像	Display.FLAG_MIRROR_VER	垂直镜像
水平和垂直镜像	Display.FLAG_MIRROR_BOTH	同时进行水平和垂直镜像

pix_format

颜色格式	常量名	说明
灰度图	image.GRAYSCALE 或 PIXFORMAT_GRAYSCALE	8位灰度格式，每个像素1字节
RGB565	image.RGB565 或 PIXFORMAT_RGB565	RGB格式，16位/像素 (5:6:5)
ARGB8888	image.ARGB8888 或 PIXFORMAT_ARGB8888	ARGB格式，32位/像素 (A:R:G:B)
ABGR8888	image.ABGR8888 或 PIXFORMAT_ABGR8888	ABGR格式，32位/像素 (A:B:G:R)
RGBA8888	image.RGBA8888 或 PIXFORMAT_RGBA8888	RGBA格式，32位/像素 (R:G:B:A)
BGRA8888	image.BGRA8888 或 PIXFORMAT_BGRA8888	BGRA格式，32位/像素 (B:G:R:A)
RGB888	image.RGB888 或 PIXFORMAT_RGB888	RGB格式，24位/像素 (R:G:B)
BGR888	image.BGR888 或 PIXFORMAT_BGR888	BGR格式，24位/像素 (B:G:R)

注意事项

1. 图层支持：show_image 仅支持 OSD 图层，如需使用多个 OSD 图层，请在 init 时设置 osd_num 参数。

2. 图像尺寸：调用 show_image 时，图像的尺寸不能超过屏幕分辨率。

3. 旋转处理：某些屏幕类型（如 ST7701 的 368x544 模式）存在硬件尺寸和应用尺寸的差异，API 会自动处理这种转换。

4. WBC 功能：如需使用 writeback_dump 抓取屏幕内容，必须在 init 时设置 to_ide=True。

示例程序

基础显示示例

from media.display import *
from media.media import *
import os, time, image

# 使用 LCD 作为显示输出
Display.init(Display.ST7701, width=800, height=480, to_ide=True)
# 初始化媒体管理器
MediaManager.init()

# 创建用于绘图的图像
img = image.Image(800, 480, image.RGB565)
img.clear()
img.draw_string_advanced(0, 0, 32, "Hello World!，你好世界！！！", color=(255, 0, 0))

Display.show_image(img)

try:
    while True:
        time.sleep(1)
        os.exitpoint()
except KeyboardInterrupt as e:
    print("用户停止：", e)
except BaseException as e:
    print(f"异常：{e}")

Display.deinit()
MediaManager.deinit()

绑定 Sensor 示例

from media.display import *
from media.sensor import *
from media.media import *
import time

# 初始化 sensor
sensor = Sensor()
sensor.reset()
sensor.set_framesize(width=800, height=480)
sensor.set_pixformat(Sensor.RGB565)

# 获取 sensor 绑定信息
bind_info = sensor.bind_info()

# 配置并绑定显示层
Display.config_layer(rect=(0, 0, 800, 480), 
                     pix_format=bind_info[2], 
                     layer=Display.LAYER_VIDEO1)
Display.bind_layer(src=bind_info[0], 
                   rect=bind_info[1], 
                   pix_format=bind_info[2], 
                   layer=Display.LAYER_VIDEO1)

# 初始化显示
Display.init(Display.ST7701, width=800, height=480)
MediaManager.init()

# 启动 sensor
sensor.run()

try:
    while True:
        time.sleep(1)
except KeyboardInterrupt:
    print("用户停止")
finally:
    sensor.stop()
    Display.deinit()
    MediaManager.deinit()