完成一个主界面开发流程

2026-09-03 23:08:16 +08:00
parent 52d7dc7d4d
commit 89462d8aa1
21 changed files with 2177 additions and 198 deletions
@@ -0,0 +1,227 @@
+# LVGL PC 模拟器（simulator/）
+
+> 在 PC 上编译运行与 MCU **同一份** UI 源码（`Drivers/BSP/UI/ui_menu.c` + `ui_font_cn_12.c`），
+> 实时预览 160×160 1bpp 单色菜单界面，**无需烧录 MCU**。
+>
+> 部署细节与完整 FAQ 见 `docs/UI 设计/LVGL模拟器部署与使用说明.md`；本文聚焦**本目录的内容与架构**。
+
+---
+
+## 一、目录内容
+
+```
+simulator/
+├── CMakeLists.txt          # 构建脚本（CMake + MSVC，x64）
+├── main.c                  # 入口：SDL 初始化 → LVGL → 菜单 → 主循环
+├── sim_port.c / sim_port.h # 模拟器显示/输入端口（SDL 窗口 + 键盘），替代 MCU 端 ui_port.c
+├── lv_conf.h               # 模拟器专用 LVGL 配置（与 MCU 端 Lib/lv_conf.h 相互独立）
+├── i1_to_png.py            # 截图转 PNG：把 --screenshot 的 I1(1bpp) 原始位图转成 PNG（见 §3.5）
+├── dbg_log.h               # 调试日志 stub：DBG_* 映射到 printf（覆盖 MCU 版头文件）
+├── SDL2/
+│   └── SDL2-2.32.10/       # SDL2 预编译 SDK（随仓库提供，无需安装）
+│       ├── include/        # SDL2 头文件
+│       │   └── SDL2/       # ★ 头文件副本（LVGL SDL 驱动写死 #include "SDL2/SDL.h"）
+│       └── lib/
+│           ├── x64/        # SDL2.lib / SDL2main.lib / SDL2.dll（构建使用）
+│           └── x86/        # 32 位库（当前未使用）
+└── build/                  # CMake 生成物（可整体删除重建，勿提交）
+    └── Debug/lvgl_sim.exe  # 可执行文件（SDL2.dll 由 POST_BUILD 自动复制到同目录）
+```
+
+### 文件职责
+
+| 文件 | 说明 |
+|------|------|
+| `main.c` | 程序入口。`SDL_Init(TIMER\|EVENTS)` → `lv_init()` → `sim_port_init(160,160)` → `ui_menu_init()`（共享代码）→ 主循环（SDL 事件 + `lv_timer_handler` + `lv_refr_now`） |
+| `sim_port.c` | 创建 SDL 窗口显示设备（`lv_sdl_window_create`）、初始化 **mono 主题**（`lv_theme_mono_init`，1bpp 必需）、创建键盘输入设备并挂默认输入组。**不创建鼠标**（纯键盘导航，与 MCU 端 keypad 一致） |
+| `lv_conf.h` | 模拟器专用 LVGL 配置。与 MCU 端 `Lib/lv_conf.h` 的关键差异见 §3.3 |
+| `dbg_log.h` | MCU 版 `dbg_log.h` 依赖 `sys_clock.h`（RTC 时间戳），PC 无法编译。此 stub 把 `DBG_INFO/ERROR/DEBUG` 映射到 `printf`；因 `simulator/` 在 include 路径最前，**优先生效**覆盖 MCU 版 |
+| `CMakeLists.txt` | 收集 LVGL 源码（`../Lib/lvgl`）+ 共享 UI 源码（`../Drivers/BSP/UI`）+ 本目录端口代码，链接预编译 SDL2，产出 `lvgl_sim.exe` |
+| `i1_to_png.py` | 把 `--screenshot` 产出的 I1(1bpp) 原始位图转成 PNG，便于离线比对设计稿。详见 §3.5 |
+
+> **共享代码不复制**：`ui_menu.c` / `ui_font_cn_12.c` 直接引用 `Drivers/BSP/UI/` 下的原件，
+> MCU 与 PC 两端永远同步。**不要**在本目录内复制 UI 源码。
+
+---
+
+## 二、架构框架
+
+### 2.1 运行架构
+
+```
+main.c
+  │
+  ├─ SDL_Init(TIMER | EVENTS)              # 仅初始化计时/事件，视频由 LVGL SDL 驱动内部接管
+  ├─ lv_init()                             # LVGL v9.3.0 内核
+  ├─ sim_port_init(160, 160)
+  │    ├─ lv_group_create + set_default   # 默认输入组
+  │    ├─ lv_sdl_window_create(160,160)   # SDL 窗口 = 显示设备（I1 单色）
+  │    ├─ lv_theme_mono_init(disp, true,  # mono 主题（白字黑底），1bpp 下不初始化 = 黑屏
+  │    │              LV_FONT_DEFAULT)
+  │    └─ lv_sdl_keyboard_create           # 键盘 → 默认输入组（方向键/Enter/Esc）
+  ├─ ui_menu_init()                        # ★ 与 MCU 共用（Drivers/BSP/UI/ui_menu.c）
+  │                                        #   基元控件页面导航，节点表驱动
+  └─ 主循环
+       ├─ SDL_PollEvent                    # SDL_QUIT → 退出
+       ├─ lv_timer_handler()               # 驱动 LVGL 定时器/重绘
+       ├─ lv_refr_now(NULL)                # 强制整屏刷新（PARTIAL 模式下保证首帧输出）
+       └─ Sleep(lv_timer_handler 返回值)   # 自适应休眠
+```
+
+### 2.2 渲染链路（1bpp 单色）
+
+```
+LVGL 场景（基元控件页面/label，LV_COLOR_FORMAT_I1）
+  → SW 渲染器（仅启用 I1，LV_DRAW_SW_SUPPORT_I1=1）
+  → SDL 窗口 blit（LV_SDL_RENDER_MODE_PARTIAL，1bpp 强制要求）
+  → 屏幕（160×160 物理像素，Windows 高 DPI 可能放大显示，属正常）
+```
+
+对照 MCU 端链路（`ui_port.c`）：
+
+```
+LVGL 场景（同一份 ui_menu.c）
+  → SW 渲染器（I1）
+  → flush 回调 memcpy 到内存帧缓冲 g_ui_fbuf（3200 B）
+  → RemoDispBus 协议（TCP 7003）按需推给远端客户端显示
+```
+
+两端**场景层完全相同**，只有"渲染结果去向"不同：模拟器进 SDL 窗口，MCU 进内存帧缓冲再走网络。
+
+### 2.3 MCU 端 vs 模拟器 对照
+
+| 项 | MCU（Keil MDK） | 模拟器（CMake + MSVC） |
+|----|----------------|------------------------|
+| LVGL 编译 | `.uvprojx` 工程添加 `Lib/lvgl` 源文件 | `Lib/lvgl/CMakeLists.txt`（最小 CMake，**仅模拟器用**，不影响 Keil 编译） |
+| lv_conf.h | `Lib/lv_conf.h` | `simulator/lv_conf.h`（独立，互不影响） |
+| 显示端口 | `ui_port.c`（离屏 framebuffer + flush 回调） | `sim_port.c`（SDL 窗口） |
+| 输入 | 远端 keypad（`ui_port_queue_key`，网络回传键码） | SDL 键盘（`lv_sdl_keyboard_create`） |
+| 主题 | 无主题（`LV_USE_THEME_* = 0`），控件用内置基础样式 | **mono 主题必须开启**（否则 1bpp 黑底黑字） |
+| 日志 | `Drivers/BSP/dbg_log.h`（USART1 + RTC 时间戳） | `simulator/dbg_log.h`（printf stub） |
+| 业务任务 | netTask / ftpTask / timeSyncTask 等 | 无，纯 UI |
+| 时钟 | `lv_tick_inc` 由 ui_task 手动喂（10ms 周期） | SDL 驱动内部 `lv_tick_set_cb(SDL_GetTicks)`，**不可再手动喂** |
+
+### 2.4 关键设计决策
+
+1. **SDL2**：LVGL 官方 PC 端口同款显示方案；使用仓库内预编译 SDK（`SDL2/SDL2-2.32.10/`），无需系统安装
+2. **CMake + MSVC**：`Visual Studio 16 2019` 生成器，`-A x64`；MSVC 下加 `/utf-8` 消除中文注释的 C4819 警告
+3. **共享 UI 源码**：`ui_menu.c` / `ui_font_cn_12.c` 直接编译 `Drivers/BSP/UI/` 原件，改一处两端同时生效
+4. **纯键盘导航**：不创建鼠标/触摸设备，与 MCU 端 keypad 操作语义一致（↑↓←→ / Enter / Esc）
+5. **仅 UI 预览**：不含网络/存储/ADC 等硬件业务，无法验证与外设相关的逻辑
+
+---
+
+## 三、构建与运行
+
+### 3.1 环境要求
+
+| 依赖 | 版本 | 说明 |
+|------|------|------|
+| CMake | ≥ 3.15 | 本机验证 4.3.0-rc1 |
+| MSVC | VS2019 BuildTools | `Visual Studio 16 2019` 生成器，Hostx64/x64 |
+| SDL2 | 2.32.10 | 已内置于 `SDL2/`，无需安装 |
+| 操作系统 | Windows | 已验证 win32 |
+
+### 3.2 构建命令
+
+```powershell
+# 首次（配置 + 构建）
+cd simulator
+cmake -B build -G "Visual Studio 16 2019" -A x64
+cmake --build build --config Debug
+
+# 日常（仅改 .c/.h 时增量编译）
+cmake --build build --config Debug
+
+# 运行
+.\build\Debug\lvgl_sim.exe
+# 或：cmake --build build --config Debug --target run
+```
+
+> 改 `CMakeLists.txt` 后需重新 `cmake -B build`；遇到奇怪问题先删 `build/` 全量重建。
+
+### 3.3 `lv_conf.h` 与 MCU 端的关键差异
+
+| 配置 | MCU 端（`Lib/lv_conf.h`） | 模拟器（本目录） | 原因 |
+|------|--------------------------|------------------|------|
+| `LV_USE_SDL` | 0 | **1** | SDL 显示/键盘驱动 |
+| `LV_SDL_RENDER_MODE` | — | **`PARTIAL`** | 1bpp + SDL 非 PARTIAL 会 `#error` |
+| `LV_SDL_INCLUDE_PATH` | — | `"SDL2/SDL.h"` | 对应 `include/SDL2/` 头文件副本 |
+| `LV_USE_THEME_MONO` | 0 | **1** | 1bpp 无主题 = 黑底黑字不可见 |
+| `LV_DRAW_SW_SUPPORT_I1` | 1 | 1 | 仅启用 I1 渲染，裁掉其余色深 |
+| `LV_MEM_SIZE` | 40 KB | 40 KB | 保持一致（PC 内存充足，可放宽） |
+| `LV_FONT_DEFAULT` | `&ui_font_cn_12` | 同 | 共用同一字体 |
+| 其余控件/驱动 | 裁剪 | 基本一致（另开 `LV_USE_TEXTAREA/KEYBOARD/BUTTONMATRIX`） | 模拟器略宽松，便于调试 |
+
+### 3.4 键盘操作
+
+| 按键 | 功能 |
+|------|------|
+| ↑ / ↓ | 菜单项上下移动 |
+| → | 进入子页 |
+| Enter | 确认 / 进入子页 |
+| ← / Escape | 返回上级 |
+
+### 3.5 截图比对设计稿（离线出图）
+
+窗口模式只适合人工目检。要把渲染结果存成 PNG 与设计稿（`docs/UI 设计/mockups/render_01.png`）逐像素比对，用离屏截图 + 转 PNG：
+
+```powershell
+cd simulator
+# 1) 离屏渲染首帧，输出 I1(1bpp) 原始位图（已剥离 8 字节调色板，纯像素数据）
+.\build\Debug\lvgl_sim.exe --screenshot shot.bin
+# 2) 转 PNG（默认 160x160；--scale 放大便于查看）
+python i1_to_png.py shot.bin                # -> shot.png
+python i1_to_png.py shot.bin -o 预览.png --scale 6
+```
+
+**I1 位图格式**（`i1_to_png.py` 据此解析）：1 位/像素，每字节 MSB 在左（bit7 = 该行最左像素），`bit=1` 前景 / `bit=0` 背景，每行 `宽/8` 字节、行内无填充。
+
+`i1_to_png.py` 常用参数：
+
+| 参数 | 说明 |
+|------|------|
+| `-o, --output` | 输出 PNG 路径（默认与输入同名 `.png`） |
+| `-W, -H` | 宽高（默认 160/160，非默认分辨率时必填） |
+| `--scale N` | 最近邻放大 N 倍，便于查看小图 |
+| `--invert` | 前/背景互换 |
+| `--fg / --bg` | 自定义前/背景色 `R,G,B`（默认黑白） |
+| `--no-auto-palette` | 关闭调色板自动识别（按纯像素解析） |
+
+> 依赖 Pillow（`pip install pillow`，本仓库已验证）。`shot.bin`/`shot*.png` 均已列入 `.gitignore`，可随时删除重生成。
+
+---
+
+## 四、已知坑（构建/运行）
+
+1. **`cannot open include file "SDL2/SDL.h"`**
+   LVGL SDL 驱动写死 `#include "SDL2/SDL.h"`，而原版 SDK 头文件平铺在 `include/` 下。
+   必须把头文件复制一份到 `include/SDL2/` 子目录（本仓库已做好）：
+   ```powershell
+   $inc = "simulator\SDL2\SDL2-2.32.10\include"
+   New-Item -ItemType Directory -Path "$inc\SDL2" -Force
+   Copy-Item "$inc\*.h" "$inc\SDL2\"
+   ```
+2. **`cannot open include file "lv_conf.h"`**
+   `LV_CONF_DIR` / `SDL2_INCLUDE_DIR` 两个 CMake 变量必须在 `add_subdirectory(lvgl)` **之前**定义（见 `CMakeLists.txt` 中的顺序注释），勿随意调整。
+3. **运行后窗口全黑**，按序排查：
+   - `LV_USE_THEME_MONO = 1` 且 `sim_port_init` 中调用了 `lv_theme_mono_init`
+   - 主循环调用了 `lv_refr_now(NULL)`（PARTIAL 模式保证首帧）
+   - 没有重复设置 tick（SDL 驱动内部已 `lv_tick_set_cb`，**不要**再 `SDL_AddTimer` + `lv_tick_inc`）
+4. **中文显示空白**：字体 `ui_font_cn_12` 是子集字体（当前 78 字），缺字渲染为空白。
+   补字流程见 `docs/UI 设计/UI_中文字体生成与配置.md`（`tools/font_gen/` 两步脚本）。
+5. **改了 UI 代码但模拟器没变化**：确认改的是 `Drivers/BSP/UI/ui_menu.c`（共享原件）而非本目录副本（本目录无副本），然后重新 `cmake --build`。
+6. **编码**：UI 源码为 UTF-8（带 BOM），MSVC 已加 `/utf-8`。**不要**用 PowerShell `Set-Content` 等重写含中文的文件（编码铁律，见根目录 `AGENTS.md`）。
+7. **键盘输入无响应（方向键/Enter 无效）**：`main.c` 主循环**不得**调用 `SDL_PollEvent`。
+   LVGL SDL 驱动内部有 5ms 定时器（`lv_sdl_window.c` 的 `sdl_event_handler`）统一轮询分发 SDL 事件；
+   主循环若先轮询会消费掉事件队列，键盘输入永远到不了 LVGL（现象：画面正常但按键全部无效）。
+   关窗退出由驱动 `LV_SDL_DIRECT_EXIT=1` 自动 `exit(0)`，主循环无需处理 SDL_QUIT。
+
+---
+
+## 五、边界说明
+
+- 模拟器**只跑 UI**：不含 CH395F 网络、NAND 存储、ADC、RS-485 等硬件业务，
+  也**不含** `ui_net_sink`（推流服务端）——远端推流链路只能在 MCU 上验证
+- `build/` 为生成物，可随时删除重建（已在 `.gitignore` 中忽略）
+- `Lib/lvgl/CMakeLists.txt` 仅被本模拟器引用，**不影响** Keil 的 MCU 编译
@@ -0,0 +1,189 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+i1_to_png.py — 将 LVGL 模拟器 `--screenshot` 产出的 I1(1bpp) 原始位图转换为 PNG。
+
+输入格式（模拟器 main.c 的 --screenshot 模式输出）：
+  - 1 位/像素，每字节 MSB 在左（bit7=该行最左像素），bit=1 为前景、bit=0 为背景
+  - 每行 stride = 宽 / 8 字节，行内无填充
+  - 模拟器当前已剥离 8 字节调色板，文件即纯像素数据（宽/8 × 高 字节）
+  - 若遇到仍含调色板的旧文件（像素数据 + 8 字节），--auto-palette 会自动识别并跳过
+
+用法示例：
+  python i1_to_png.py shot.bin                       # -> shot.png（默认 160x160）
+  python i1_to_png.py shot.bin -o out.png            # 指定输出
+  python i1_to_png.py shot.bin --scale 6            # 放大 6 倍便于查看（最近邻，保持像素感）
+  python i1_to_png.py shot.bin -W 320 -H 240        # 非默认分辨率
+  python i1_to_png.py shot.bin --fg 0,0,0 --bg 255,255,255   # 自定义前/背景色（RGB 模式）
+  python i1_to_png.py shot.bin --invert             # 前景/背景互换
+
+依赖：Pillow（pip install pillow）。本仓库环境已验证 PIL 12.2.0。
+退出码：0 成功；1 参数/数据错误。
+"""
+
+import argparse
+import os
+import sys
+
+# DTU 屏幕默认分辨率（160x160，1bpp）
+DEFAULT_W = 160
+DEFAULT_H = 160
+# I1 调色板大小（2 色 × 4 字节）。模拟器新版已剥离，旧文件可能残留。
+I1_PALETTE_BYTES = 2 * 4
+
+
+def _decode_i1(data, width, height):
+    """把原始 I1 数据解成 (height, width) 的 0/1 矩阵。MSB 在左。"""
+    stride = width // 8
+    if width % 8 != 0:
+        raise ValueError("宽度必须是 8 的整数倍（I1 按字节打包），当前 %d" % width)
+    need = stride * height
+    if len(data) < need:
+        raise ValueError("数据不足：%d 字节 < 需要 %d 字节（%dx%d I1）"
+                         % (len(data), need, width, height))
+    px = []
+    for y in range(height):
+        base = y * stride
+        row = [0] * width
+        for x in range(width):
+            byte_i = x >> 3
+            bit_i = 7 - (x & 7)
+            row[x] = (data[base + byte_i] >> bit_i) & 1
+        px.append(row)
+    return px
+
+
+def _pick_palette_offset(data, width, height, auto):
+    """返回像素数据在文件中的起始偏移（跳过调色板）。"""
+    stride = width // 8
+    need = stride * height
+    sizes = [len(data)]
+    if auto:
+        # 像素数据前可能带 I1 调色板（8 字节）
+        if len(data) == need + I1_PALETTE_BYTES:
+            return I1_PALETTE_BYTES
+    if len(data) < need:
+        raise ValueError("数据不足：%d 字节 < 像素所需 %d 字节" % (len(data), need))
+    return 0
+
+
+def i1_to_png(input_path, output_path=None, width=DEFAULT_W, height=DEFAULT_H,
+              scale=1, invert=False, auto_palette=True,
+              fg=None, bg=None):
+    """核心转换函数，可被其他脚本直接 import 调用。
+
+    fg / bg 形如 (r,g,b)；为 None 时用黑白（L 模式）。
+    返回输出文件路径。
+    """
+    from PIL import Image
+
+    if not os.path.isfile(input_path):
+        raise FileNotFoundError(input_path)
+
+    with open(input_path, "rb") as f:
+        data = f.read()
+
+    off = _pick_palette_offset(data, width, height, auto_palette)
+    px = _decode_i1(data[off:], width, height)
+
+    nw, nh = width, height
+
+    if fg is None and bg is None:
+        # 灰度：bit=1 -> 白(255)，bit=0 -> 黑(0)
+        img = Image.new("L", (nw, nh))
+        ipx = img.load()
+        for y in range(nh):
+            for x in range(nw):
+                bit = px[y][x]
+                if invert:
+                    bit ^= 1
+                ipx[x, y] = 255 if bit else 0
+    else:
+        fgc = fg if fg is not None else (255, 255, 255)
+        bgc = bg if bg is not None else (0, 0, 0)
+        if invert:
+            fgc, bgc = bgc, fgc
+        img = Image.new("RGB", (nw, nh), bgc)
+        ipx = img.load()
+        for y in range(nh):
+            for x in range(nw):
+                bit = px[y][x]
+                ipx[x, y] = fgc if bit else bgc
+
+    # 放大（最近邻，保持 1bpp 像素感）
+    if scale and scale > 1:
+        img = img.resize((nw * scale, nh * scale), Image.NEAREST)
+
+    if output_path is None:
+        output_path = os.path.splitext(input_path)[0] + ".png"
+    img.save(output_path, "PNG")
+    return output_path
+
+
+def _parse_rgb(s):
+    if s is None:
+        return None
+    parts = s.split(",")
+    if len(parts) != 3:
+        raise argparse.ArgumentTypeError("颜色格式应为 R,G,B，如 255,0,0")
+    try:
+        r, g, b = (int(p) for p in parts)
+    except ValueError:
+        raise argparse.ArgumentTypeError("颜色分量必须是整数")
+    for v in (r, g, b):
+        if not (0 <= v <= 255):
+            raise argparse.ArgumentTypeError("颜色分量需在 0~255")
+    return (r, g, b)
+
+
+def _ensure_utf8_console():
+    """Windows 控制台默认 GBK，中文会乱码；统一切到 UTF-8（不支持则静默跳过）。"""
+    for stream in (sys.stdout, sys.stderr):
+        try:
+            stream.reconfigure(encoding="utf-8")
+        except (AttributeError, ValueError):
+            pass
+
+
+def main(argv=None):
+    _ensure_utf8_console()
+    ap = argparse.ArgumentParser(
+        description="将模拟器 I1(1bpp) 原始截图转换为 PNG",
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+    )
+    ap.add_argument("input", help="I1 原始位图文件（.bin）")
+    ap.add_argument("-o", "--output", default=None,
+                    help="输出 PNG 路径（默认与输入同名 .png）")
+    ap.add_argument("-W", "--width", type=int, default=DEFAULT_W, help="图像宽度")
+    ap.add_argument("-H", "--height", type=int, default=DEFAULT_H, help="图像高度")
+    ap.add_argument("--scale", type=int, default=1,
+                    help="放大倍数（最近邻，便于查看小图）")
+    ap.add_argument("--invert", action="store_true", help="前景/背景互换")
+    ap.add_argument("--no-auto-palette", action="store_true",
+                    help="不做调色板自动识别（按纯像素数据解析）")
+    ap.add_argument("--fg", type=_parse_rgb, default=None, help="前景色 R,G,B（bit=1）")
+    ap.add_argument("--bg", type=_parse_rgb, default=None, help="背景色 R,G,B（bit=0）")
+    args = ap.parse_args(argv)
+
+    try:
+        out = i1_to_png(
+            args.input,
+            output_path=args.output,
+            width=args.width,
+            height=args.height,
+            scale=args.scale,
+            invert=args.invert,
+            auto_palette=not args.no_auto_palette,
+            fg=args.fg,
+            bg=args.bg,
+        )
+    except (ValueError, FileNotFoundError) as e:
+        print("错误：%s" % e, file=sys.stderr)
+        return 1
+
+    print("已生成：%s" % out)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
@@ -49,11 +49,11 @@
 #define LV_DRAW_BUF_STRIDE_ALIGN 1
 #define LV_DRAW_BUF_ALIGN 4

-/** 关闭复杂绘制，省代码 */
-#define LV_DRAW_SW_COMPLEX 0
+/** 复杂绘制：主界面顶部开口浅 V 装饰含斜线（lv_line 斜段依赖 LV_DRAW_SW_COMPLEX），须与 MCU 端一致保持开启，否则两腿不渲染 */
+#define LV_DRAW_SW_COMPLEX 1
 #define LV_DRAW_SW_COMPLEX_GRADIENTS 0
 #define LV_DRAW_SW_SHADOW_CACHE_SIZE 0
-#define LV_DRAW_SW_CIRCLE_CACHE_SIZE 0
+#define LV_DRAW_SW_CIRCLE_CACHE_SIZE 4   /* LV_DRAW_SW_COMPLEX 依赖非零（零长数组 C2466）；与 MCU 端默认一致 */
 #define LV_DRAW_LAYER_SIMPLE_BUF_SIZE 0
 #define LV_DRAW_LAYER_MAX_MEMORY 0

@@ -87,7 +87,8 @@
 #define LV_USE_THORVG 0
 #define LV_USE_VECTOR_GRAPHIC 0
 #define LV_USE_MATRIX 0
-#define LV_USE_SNAPSHOT 0
+/* 离屏截图（--screenshot）用 lv_snapshot 取整屏，需要开启 */
+#define LV_USE_SNAPSHOT 1

 /*============================================================================
 * INPUT DEVICES
@@ -229,10 +230,10 @@
 #define LV_LABEL_LONG_TXT_HINT 0
 #define LV_LABEL_WAIT_CHAR_COUNT 0
 #define LV_USE_LED 0
-#define LV_USE_LINE 0
+#define LV_USE_LINE 1
 #define LV_USE_LIST 0
 #define LV_USE_LOTTIE 0
-#define LV_USE_MENU 1
+#define LV_USE_MENU 0
 #define LV_USE_MSGBOX 0
 #define LV_USE_QRCODE 0
 #define LV_USE_RLOTTIE 0
@@ -7,10 +7,16 @@
 *   ↑/↓/←/→  → 方向键导航
 *   Enter     → 确认/进入
 *   Escape    → 返回
+ *
+ * 截图模式（无窗口离屏渲染，导出像素供比对）：
+ *   lvgl_sim.exe --screenshot shot.bin
+ *   走与 MCU 端一致的离屏软件渲染（ARGB8888 缓冲 + mono 主题），
+ *   渲染首帧后将 160x160 像素按 BGRA 顺序写入 shot.bin（102400 字节），随即退出。
 */

 #include <stdlib.h>
 #include <stdio.h>
+#include <string.h>

 #ifdef _MSC_VER
  #include <Windows.h>
@@ -29,13 +35,104 @@
 #define SIM_SCREEN_W  160
 #define SIM_SCREEN_H  160

+/* 离屏截图缓冲：I1（1bpp，与 MCU/模拟器窗口一致；软件渲染器仅支持 I1），160x160/8 */
+static uint8_t g_shot_buf[SIM_SCREEN_W * SIM_SCREEN_H / 8];
+
+/*
+ * @brief 离屏截图用空 delay 回调
+ * @note  默认 lv_delay_ms 会忙等 tick 前进，但离屏渲染时 tick 不会在等待期间推进，
+ *        导致死循环挂死。window 模式经 SDL 设了真实 delay，离屏这里用空实现代替。
+ */
+static void shot_delay_cb(uint32_t ms)
+{
+    (void)ms;
+}
+
+/*
+ * @brief 离屏截图 flush 回调（不写真实设备，直接标记就绪）
+ */
+static void shot_flush_cb(lv_display_t * disp, const lv_area_t * area, uint8_t * color_p)
+{
+    (void)area;
+    (void)color_p;
+    lv_display_flush_ready(disp);
+}
+
+/*
+ * @brief 无窗口离屏渲染并导出首帧像素
+ * @param path 输出文件（写入 160x160 BGRA 原始像素）
+ * @return 0 成功，非 0 失败
+ */
+static int run_screenshot(const char * path)
+{
+    setvbuf(stdout, NULL, _IONBF, 0);
+    lv_init();
+    lv_delay_set_cb(shot_delay_cb);
+
+    lv_display_t *disp = lv_display_create(SIM_SCREEN_W, SIM_SCREEN_H);
+    if (disp == NULL) {
+        return 1;
+    }
+    lv_display_set_default(disp);
+    lv_display_set_color_format(disp, LV_COLOR_FORMAT_I1);
+    lv_display_set_buffers(disp, g_shot_buf, NULL, sizeof(g_shot_buf),
+                           LV_DISPLAY_RENDER_MODE_FULL);
+    lv_display_set_flush_cb(disp, shot_flush_cb);
+
+    lv_group_t *g = lv_group_create();
+    if (g == NULL) {
+        return 1;
+    }
+    lv_group_set_default(g);
+
+#if LV_USE_THEME_MONO
+    lv_theme_t *th = lv_theme_mono_init(disp, true, LV_FONT_DEFAULT);
+    if (th != NULL) {
+        lv_display_set_theme(disp, th);
+    }
+#endif
+
+    if (ui_menu_init() != 0) {
+        return 1;
+    }
+
+    /* 用 snapshot 把整屏渲进独立 I1 draw_buf（避开 I1+FULL 的渲染死循环） */
+    lv_draw_buf_t *snap = lv_snapshot_take(lv_screen_active(), LV_COLOR_FORMAT_I1);
+    if (snap == NULL) {
+        fprintf(stderr, "[shot] snapshot failed\n");
+        return 1;
+    }
+
+    uint32_t snap_w = snap->header.w;
+    uint32_t snap_h = snap->header.h;
+    /* I1 缓冲区布局：[palette 8B][pixel data]，跳过 palette 只写像素 */
+    uint32_t pal_bytes = LV_COLOR_INDEXED_PALETTE_SIZE(LV_COLOR_FORMAT_I1) * (uint32_t)sizeof(lv_color32_t);
+    uint8_t * px = snap->data + pal_bytes;
+    uint32_t px_bytes = (uint32_t)snap->header.stride * (uint32_t)snap_h;
+    FILE *fp = fopen(path, "wb");
+    if (fp == NULL) {
+        lv_draw_buf_destroy(snap);
+        fprintf(stderr, "fopen failed: %s\n", path);
+        return 1;
+    }
+    size_t n = fwrite(px, 1, px_bytes, fp);
+    fclose(fp);
+    lv_draw_buf_destroy(snap);
+    printf("screenshot: %s (%zu bytes, %ux%u I1)\n", path, n, snap_w, snap_h);
+    return 0;
+}
+
 /**
 * @brief 程序入口
 */
 int main(int argc, char **argv)
 {
-    (void)argc;
-    (void)argv;
+    /* 截图模式：lvgl_sim.exe --screenshot <path> */
+    for (int i = 1; i < argc; i++) {
+        if (strcmp(argv[i], "--screenshot") == 0 && (i + 1) < argc) {
+            return run_screenshot(argv[i + 1]);
+        }
+    }

    /* 初始化 SDL2（仅 timer + events，视频由 lv_sdl_window 内部初始化） */
    if (SDL_Init(SDL_INIT_TIMER | SDL_INIT_EVENTS) != 0) {
@@ -71,22 +168,12 @@ int main(int argc, char **argv)
    printf("Keyboard: ↑↓←→ navigate, Enter confirm, Escape back\n");
    printf("Press Ctrl+C or close window to exit\n\n");

-    /* 主循环：处理 SDL 事件 + 驱动 LVGL 刷新 */
+    /* 主循环：驱动 LVGL 定时器与刷新
+     * 注意：SDL 事件（键盘/窗口/退出）由 LVGL SDL 驱动内部 5ms 定时器
+     * （lv_sdl_window.c 的 sdl_event_handler）统一轮询分发，
+     * 本循环不得再调 SDL_PollEvent，否则会先消费事件队列，
+     * 导致键盘输入永远到不了 LVGL */
    while (1) {
-        /* 处理 SDL 事件（窗口关闭等） */
-        SDL_Event event;
-        while (SDL_PollEvent(&event)) {
-            if (event.type == SDL_QUIT) {
-                printf("SDL_QUIT received, exiting...\n");
-                SDL_Quit();
-                return 0;
-            }
-            if (event.type == SDL_KEYDOWN && event.key.keysym.sym == SDLK_ESCAPE) {
-                /* Escape 键：如果在子页面则返回上一级 */
-                /* LVGL keyboard 驱动已自动处理 LV_KEY_ESC */
-            }
-        }
-
        /* 驱动 LVGL 定时器与刷新 */
        uint32_t sleep_ms = lv_timer_handler();
        if (sleep_ms == LV_NO_TIMER_READY) {