VisualHMI - 画图

本章节主要介绍LUA脚本使用API进行线、矩形、圆、椭圆、文字、图片等

适用范围：VisualHMI - HMI&M系列&Dx系列

例程下载链接：ViusalHMI - 画图(点击下载)

1.Lua API说明

3.1.on_draw(screen,control)

on_draw 是 HMI 系统提供的控件级自绘回调接口，用于在指定画面的特定控件区域上执行用户自定义的图形绘制。开发者可on_draw函数里调用各类 draw_xxx 图形 API，实现图片、文字、图形(点、线、几何图形)的绘制

📊 参数说明

⚠️ 注意：

1. 该函数为系统回调函数，用户不得直接调用；
2. 所有 draw_xxx 图形绘制指令（如 draw_line、draw_surface 等）必须在此函数内调用才能生效；
3. 控件ID ≠ 0 ，否则自绘功能无效。

3.1.1.触发条件 on_draw

• 界面包含动画、视频、RTC 时间等动态元素刷新；

• 用户触摸或操作屏幕控件；

• 脚本通过 set_xxx更新控件属性；

• 串口/LUA 指令修改寄存器，从而修改控件状态；

• 主动调用 redraw()

3.1.2. 多图层绘制机制

核心原理

HMI 系统采用控件 Z 轴顺序（即界面编辑器中的控件叠放顺序）作为天然的图层管理机制。on_draw(screen_id, control_id) 回调函数在每个可重绘控件独立触发，开发者可通过判断 control_id，将不同的图形内容绘制到对应控件图层（控件叠放上下关系），从而实现逻辑上的“分层叠加”。

✅ 关键设计：控件在界面中的上下排列顺序直接决定了最终视觉的图层叠加顺序。

典型图层结构示例

假设界面从底到顶包含以下元素（Z 轴顺序由低到高）：

📌 注意：

• 蓝色矩形（ID=10）在编辑器中位于黄色矩形（ID=11）下方，因此视觉上被后者部分覆盖；
• 两个矩形均启用自绘功能（ID ≠ 0），系统将在各自区域触发 on_draw。

当系统刷新界面时：

1. 遍历所有需重绘的控件（按 Z 轴从底到顶）；
2. 对每个支持自绘的控件，调用一次 on_draw(screen_id, control_id)；
3. 开发者通过 control_id判断当前绘制目标：
   • 若 control_id == 10 → 在蓝色矩形区域内绘制“水果图片”；
   • 若 control_id == 11 → 在黄色矩形区域内绘制“小岛图片”；
4. 最终合成效果： 原本画面（底） ← 蓝色背景 + 水果（中） ← 黄色背景 + 小岛（顶）

function on_draw(screen_id, control_id)
    if screen_id == 0 and control_id == 1
    then
        draw_surface(surface[1], 293, 88, 222, 353, 0, 0)  --裁剪显示

    elseif screen_id == 0 and control_id == 2
    then
        draw_surface(surface[2], 314, 158, 180, 250, 0, 0) --裁剪显示
    end
end

3.2.redraw()

全局界面重绘触发函数,redraw() 是 HMI 系统提供的全局重绘请求接口，用于主动触发当前画面所有支持自绘的控件执行 on_draw 回调函数，强制刷新界面显示内容。

3.3.set_pen_color(color)

设置绘图画笔颜色，set_pen_color(color) 是 HMI 系统提供的设置画笔颜色函数，用于设置后续所有绘图操作的前景色（画笔颜色），适用于线条、矩形边框、圆形轮廓、文本描边等非填充型或边框型图形的颜色。

📊 参数说明

RGB565 编码示例：

3.4.draw_line(x0,y0,x1,y1,width)

直线绘制函数，draw_line 是 HMI 绘制一条指定起点、终点及线宽的直线段。该线段颜色依赖当前画笔颜（由 set_pen_color 设定）

📊 参数说明

3.5.draw_rect(x0,y0,x1,y1,fill)

矩形绘制函数，draw_rect 函数是HMI（人机交互界面）开发中常用的绘图接口之一，通过定义左上角和右下角的坐标以及是否填充该矩形，在指定位置绘制一个矩形。

📊 参数说明

3.6.draw_rect_alpha(x0,y0,x1,y1,alpha)

半透明实心矩形绘制函数，draw_rect_alpha 是 HMI 图形系统提供的半透矩形填充绘图接口，用于指定位内绘制一个带有指定透明度的实心矩形。该函数常用于实现遮罩层

📊 参数说明

3.7.draw_circle(x,y,r,fill)

圆形绘制函数，draw_circle 是用于绘制圆形的函数。此函数可以基于提供的中心坐标 (x, y)、半径 r 以及填充标志 fill 来绘制一个指定大小和样式的圆形。根据 fill 参数的不同，该函数可以绘制出轮廓圆（非填充）或实心圆（填充）

📊 参数说明

3.8.draw_ellipse(x0,y0,x1,y1,fill)

椭圆绘制函数，draw_ellipse 是 HMI 图形系统提供椭圆绘图接口，用于绘制一个内切于指定矩形区域的椭圆。通过控制填充模式与边框表现，可灵活实现从实心椭圆到带厚度轮廓的空心椭圆

📊 参数说明

3.9.draw_image(image_id,frame_id,dstx,dsty,width,height,srcx,srcy)

图片绘制函数，draw_image 是 HMI系统提供绘制图片资源的接口。此函数允许开发者通过指定图片资源ID、显示位置与大小，以及可选的裁剪区域来灵活地控制图像显示。

📊 参数说明

[!note|tip:如何确定image_id] 1.在工程目录下的../build/文件夹，打开image.xml文件，image id = "xx"表示第一个参数

3.10.draw_text(text,x,y,w,h,font_id,size,color,align,charcode)

文本绘制函数，draw_text 是 HMI 图形系统提供的文字绘制接口，用于在指定区域内绘制字符串。支持自定义字体、字号、颜色、对齐方式及字符编码。

📊 参数说明

3.11.load_surface (filename)

图像加载函数,load_surface 用于从指定路径加载 JPEG 或 PNG 格式的图片文件(外部图形,非工程打包的image.bin里的图片资源)，并将其作为句柄（surface）返回。surface后续绘图操作中被引用。

📊 参数说明

⚠️ 关键注意事项

• 路径准确性：确保提供的 filename 路径准确无误，指向有效的 JPEG 或 PNG 文件。
• 内存占用：大尺寸图像或大量图像的同时加载会占用较多内存，应注意资源管理。
• 透明度处理：对于带有透明度信息的 PNG 图像，占用内存比较大

3.12.destroy_surface (surface)

图层资源销毁函数，destroy_surface(surface) 用于释放“由 load_surface ”申请的图形资源。调用后，该图层指针失效，不可再用于任何绘图操作

📊 参数说明

✅ 核心用途：

• 防止内存泄漏，尤其在动态加载/卸载图片的场景中；
• 释放 GPU 或帧缓冲区中缓存的图像数据；
• 管理有限的嵌入式系统图形资源。

3.13.destroy_all_surface()

批量销毁所有图层资源函数,destroy_all_surface() 是 HMI 图形系统提供的全局图层资源清理接口，用于一次性释放当前脚本上下文中所有已加载的图层（surface）所占用的内存资源。调用后，所有通过 load_surface创建的图层句柄均失效

✅ 核心用途：

• 快速回收全部图像资源，避免逐个管理；
• 简化资源管理逻辑，防止因遗漏导致的内存泄漏。

3.14.draw_surface (surface,dstx,dsty,width,height,srcx,srcy)

draw_surface是绘制由load_surface 申请的图片资源 的接口，将已加载的图层资源（如 JPEG/PNG 图片）绘制到指定位置。支持区域裁剪与尺寸缩放。该函数必须在 on_draw 回调中调用才能生效。

📊 参数说明

3.15.get_surface_size (surface)

获取图层尺寸函数，get_surface_size(surface) 是 HMI 图形系统提供的图层属性查询接口，用于获取已加载图层（surface）的原始像素尺寸。该函数返回图像的宽度和高度

📊 参数说明

3.16.clear_image_buffer()

清除内部图片资源缓存函数，clear_image_buffer() 是 HMI 系统提供的全局图像缓存管理接口，用于强制释放图形的图片数据，以降低内存占用

3.17.screen_shoot(filepath)

屏幕截图函数，screen_shoot(filepath) 是 HMI 系统提供的屏幕内容捕获接口，用于将当前显示画面（或指定区域）保存为图像文件（ JPEG 格式）

📊 参数说明

2.工程配置

2.1.绘制键设置

添加15个字设置按钮，用于触发Lua绘制按钮，以“直线”按钮为例，控件配置如下所示：

1. 写入地址：LW6100

2. 操作模式：写入常量

   • 常量值：1/2/3/4/5/6/7/8/9/10/11/12/13/14/15(依次为直线/矩形/半透矩形/圆/椭圆/图片ID/文字/屏内图片/销毁图片/销毁所有图片/获取图大小/视频窗口截图/屏幕截图/画SD图/画U盘图片)
3. 使用图库：√
4. 使用文字：√

2.2.画笔设置

添加15个位状态指示灯，用来设置画笔颜色，黄色/蓝色之前切换，如下所示：

1. 写入地址：LW6100
2. 切换开关：√
3. 开关类型：切换开关

2.3.文本设置

添加一个文本控件，用于显示图片大小，配置如下所示：

3.Lua 脚本

3.1.画笔

在on_update里面，判断触发地址和键值，若地址为LW6100，值为0画笔为蓝色，值为1画笔为红色，代码如下所示：

penColor = {0xF800, 0x001F}
CUR_COLOR = 0xF800 --初始颜色，

function on_update(slave,vtype,addr)

    if addr == 0x6100
    then
        CUR_COLOR = penColor[get_uint16(VT_LW, addr) + 1]
    end
    redraw()
end

function on_draw(screen_id,control_id)
    set_pen_color(CUR_COLOR)
end

3.2.直线

3.2.1.Lua

在on_update里面，判断触发地址和键值，若地址为LW6101，值为1，绘制直线，代码如下所示：

mode = {  --绘制类型表
    line          = 1,
    rect          = 2,
    rect_alpha    = 3,
    circle        = 4,
    ellipse       = 5,
    imageId       = 6,
    text          = 7,
    surface_path3 = 8,
    destroyOne    = 9,
    destroyAll    = 10,
    getSurface    = 11,
    videoShoot    = 12,
    screenShoot   = 13,

    surface_pathsd  = 14,
    surface_pathusb = 15

}

function on_update(slave,vtype,addr)

    if addr == 0x6100
    then
        CUR_COLOR = penColor[get_uint16(VT_LW, addr) + 1]

    elseif addr == 0x6101
    then
        local msg = ''
        draw_type = get_uint16(VT_LW, addr) -- 键值
    end
    redraw()
end

function on_draw(screen_id,control_id)

    set_pen_color(CUR_COLOR)

    local switch = {
        [mode.line] = function(control) -- 键值为1
            draw_line(225, 253, 405, 253)
            draw_line(508, 128, 508, 378, 5)
        end,
    }

    if switch[draw_type]
    then
        switch[draw_type](control)
    end
end

3.2.2.预览

运行预览，点击直线按钮，绘制宽度为1，和宽度为5的直线，设置画笔颜色，直线颜色随着改变，如下所示：

3.3.矩形

3.3.1.Lua

在on_update里面，判断触发地址和键值，若地址为LW6101，值为2，绘制矩形，代码如下所示：

mode = {  --绘制类型表
    line          = 1,
    rect          = 2,
    rect_alpha    = 3,
    circle        = 4,
    ellipse       = 5,
    imageId       = 6,
    text          = 7,
    surface_path3 = 8,
    destroyOne    = 9,
    destroyAll    = 10,
    getSurface    = 11,
    videoShoot    = 12,
    screenShoot   = 13,

    surface_pathsd  = 14,
    surface_pathusb = 15

}

function on_update(slave,vtype,addr)

    if addr == 0x6100
    then
        CUR_COLOR = penColor[get_uint16(VT_LW, addr) + 1]

    elseif addr == 0x6101
    then
        local msg = ''
        draw_type = get_uint16(VT_LW, addr) -- 键值
    end
    redraw()
end

function on_draw(screen_id,control_id)

    set_pen_color(CUR_COLOR)

    local switch = {
        [mode.rect] = function(control) --键值2
            draw_rect(225, 128, (225+180), (128+250), 0)--填充
            draw_rect(418, 163, (418+180), (128+180), 1)--不填充
        end,
    }

    if switch[draw_type]
    then
        switch[draw_type](control)
    end
end

3.3.2.预览

运行预览，点击矩形按钮，绘制1个填充，1个不填充的矩形，设置画笔颜色，矩形颜色随着改变，如下所示：

3.4.半透矩形

3.4.1.Lua

在on_update里面，判断触发地址和键值，若地址为LW6101，值为3，绘制半透矩形，代码如下所示：

mode = {  --绘制类型表
    line          = 1,
    rect          = 2,
    rect_alpha    = 3,
    circle        = 4,
    ellipse       = 5,
    imageId       = 6,
    text          = 7,
    surface_path3 = 8,
    destroyOne    = 9,
    destroyAll    = 10,
    getSurface    = 11,
    videoShoot    = 12,
    screenShoot   = 13,

    surface_pathsd  = 14,
    surface_pathusb = 15

}

function on_update(slave,vtype,addr)

    if addr == 0x6100
    then
        CUR_COLOR = penColor[get_uint16(VT_LW, addr) + 1]

    elseif addr == 0x6101
    then
        local msg = ''
        draw_type = get_uint16(VT_LW, addr) -- 键值
    end
    redraw()
end

function on_draw(screen_id,control_id)

    set_pen_color(CUR_COLOR)

    local switch = {
        [mode.rect_alpha] = function(control)--键值3
            draw_rect_alpha(225, 128, (225+180), (128+250), 200)--0~255透明度
            draw_rect_alpha(418, 163, (418+180), (128+180), 230)--0~255透明度
        end,
    }

    if switch[draw_type]
    then
        switch[draw_type](control)
    end
end

3.4.2.预览

运行预览，点击矩形按钮，绘制两个半透矩形，1个200透明度，1个230透明度，设置画笔颜色，半透矩形颜色随着改变，如下所示：

3.5.圆形

3.5.1.Lua

在on_update里面，判断触发地址和键值，若地址为LW6101，值为4，绘制圆形，代码如下所示：

mode = {  --绘制类型表
    line          = 1,
    rect          = 2,
    rect_alpha    = 3,
    circle        = 4,
    ellipse       = 5,
    imageId       = 6,
    text          = 7,
    surface_path3 = 8,
    destroyOne    = 9,
    destroyAll    = 10,
    getSurface    = 11,
    videoShoot    = 12,
    screenShoot   = 13,

    surface_pathsd  = 14,
    surface_pathusb = 15

}

function on_update(slave,vtype,addr)

    if addr == 0x6100
    then
        CUR_COLOR = penColor[get_uint16(VT_LW, addr) + 1]

    elseif addr == 0x6101
    then
        local msg = ''
        draw_type = get_uint16(VT_LW, addr) -- 键值
    end
    redraw()
end

function on_draw(screen_id,control_id)

    set_pen_color(CUR_COLOR)

    local switch = {
        [mode.circle] = function(control)--键值4
            draw_circle(300, 253, 100, 0) --填充
            draw_circle(450, 253, 150, 1) --不填充
        }        
    end,

    if switch[draw_type]
    then
        switch[draw_type](control)
    end
end

3.5.2.预览

运行预览，点击圆形按钮，绘制1个填充，1个不填充的圆形，设置画笔颜色，圆形颜色随着改变，如下所示：

3.6.椭圆

3.6.1.Lua

在on_update里面，判断触发地址和键值，若地址为LW6101，值为5，绘制椭圆，代码如下所示：

mode = {  --绘制类型表
    line          = 1,
    rect          = 2,
    rect_alpha    = 3,
    circle        = 4,
    ellipse       = 5,
    imageId       = 6,
    text          = 7,
    surface_path3 = 8,
    destroyOne    = 9,
    destroyAll    = 10,
    getSurface    = 11,
    videoShoot    = 12,
    screenShoot   = 13,

    surface_pathsd  = 14,
    surface_pathusb = 15

}

function on_update(slave,vtype,addr)

    if addr == 0x6100
    then
        CUR_COLOR = penColor[get_uint16(VT_LW, addr) + 1]

    elseif addr == 0x6101
    then
        local msg = ''
        draw_type = get_uint16(VT_LW, addr) -- 键值
    end
    redraw()
end

function on_draw(screen_id,control_id)

    set_pen_color(CUR_COLOR)

    local switch = {
        [mode.ellipse] = function(control)--键值5
            draw_ellipse(225, 128, (225+180), (128+250), 0)--填充
            draw_ellipse(418, 163, (418+180), (128+180), 1)--不填充
        }        
    end,

    if switch[draw_type]
    then
        switch[draw_type](control)
    end
end

3.6.2.预览

运行预览，点击椭圆按钮，绘制1个填充，1个不填充的椭圆，设置画笔颜色，椭圆颜色随着改变，如下所示：