VisualHMI 画图：on_draw/redraw/绘图 API 与分层绘制

LUA 画图 API 全套：直线、矩形、半透矩形、圆、椭圆、文字、图片、屏内/外部图片（SD/U 盘）、截图。核心机制是 on_draw(screen, control) 控件级自绘回调——所有 draw_xxx 指令必须在 on_draw 里调用才生效。适用 HMI&M 系列&Dx 系列。

1. 绘图 API 总表

2. on_draw 触发机制（必须先懂）

on_draw(screen_id, control_id) 是系统回调，用户不得直接调用。control_id 必须 ≠ 0，否则自绘功能无效。触发条件：

• 画面含动画、视频、RTC 等动态元素刷新
• 用户触摸/操作屏幕控件
• 脚本 set_xxx 更新控件属性
• 串口/LUA 改寄存器导致控件状态变化
• 主动调用 redraw()

多图层机制：HMI 用控件 Z 轴顺序（编辑器里控件叠放顺序）当图层管理。on_draw 对每个可重绘控件独立触发，按 control_id 判断往哪个图层画。示例：蓝色矩形 ID=10 在下层画「水果」，黄色矩形 ID=11 在上层画「小岛」，黄色会盖住蓝色部分。

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. 颜色：RGB565

所有颜色参数都是 16 位 RGB565：高 5 位 Red（0~31）、中 6 位 Green（0~63）、低 5 位 Blue（0~31），范围 0x0000~0xFFFF。

4. 应用案例：15 种绘制类型开关

4.1 工程配置

15 个字设置按钮全关联 LW6101，常量值 1~15 依次对应：直线/矩形/半透矩形/圆/椭圆/图片ID/文字/屏内图片/销毁图片/销毁所有图片/获取图大小/视频窗口截图/屏幕截图/画SD图/画U盘图片。15 个位状态指示灯关联 LW6100 切画笔颜色。

4.2 框架：mode 表 + switch 分发

penColor = {0xF800, 0x001F}      -- 红、蓝
CUR_COLOR = 0xF800                -- 初始颜色
draw_type = 0                     -- 当前绘制类型

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
    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)                    -- 默认宽度1
      draw_line(508, 128, 508, 378, 5)                 -- 宽度5
    end,
    [mode.rect] = function(control)                    -- 键值2
      draw_rect(225, 128, 225+180, 128+250, 0)         -- 不填充
      draw_rect(418, 163, 418+180, 128+180, 1)         -- 填充
    end,
    [mode.rect_alpha] = function(control)              -- 键值3
      draw_rect_alpha(225, 128, 225+180, 128+250, 200) -- 透明度200
      draw_rect_alpha(418, 163, 418+180, 128+180, 230) -- 透明度230
    end,
    [mode.circle] = function(control)                  -- 键值4
      draw_circle(300, 253, 100, 0)                    -- 实心
      draw_circle(450, 253, 150, 1)                    -- 空心(线宽1)
    end,
    [mode.ellipse] = function(control)                 -- 键值5
      draw_ellipse(225, 128, 225+180, 128+250, 0)      -- 实心
      draw_ellipse(418, 163, 418+180, 128+180, 1)      -- 空心
    end,
    [mode.text] = function(control)                    -- 键值7
      draw_text("VisualHMI", 100, 300, 200, 40,
                0, 24, CUR_COLOR, 1, 0)               -- 居中 UTF-8
    end,
  }
  if switch[draw_type] then
    switch[draw_type](control)
  end
end

5. 外部图片（SD/U 盘）与截图

-- 加载 SD 卡图片（load_surface 支持 JPEG/PNG）
if draw_type == mode.surface_pathsd then
  surface[1] = load_surface("1:/pic.png")
  redraw()
end

-- on_draw 里绘制
if draw_type == mode.surface_pathsd then
  if surface[1] then
    draw_surface(surface[1], 225, 128, 180, 250, 0, 0)
  end
end

-- 截图到 SD 卡
if draw_type == mode.screenShoot then
  screen_shoot("1:/shot.jpg")
end

用 load_surface 加载的外部图片不进工程 image.bin，是运行期从文件系统读。用完必须 destroy_surface 释放，否则内存泄漏；大图或带透明通道的 PNG 特别吃内存。

整理自 广州大彩科技 VisualHMI 开发文档（hmi-doc.gz-dc.com）LUA 教程「画图」，版权归大彩科技所有。