面向嵌入式/裸机优先的跨平台 GUI 库，C99 + GNU 扩展。软件光栅化 + 保留模式 + 分块刷新，桌面(Linux/SDL)开发、裸机(MCU + LCD)部署，两者共用同一套渲染代码，只换一个显示驱动回调。Windows、Android 和真实硬件的平台逻辑集中在 SDL_LCD/ 或应用桥接层，不进入控件核心。
当前能力、配置和验证基线见 当前状态；跨平台显示、输入与构建实践见 跨平台移植。
27 个具名控件 + base 容器 · 5 类图元 · 38 个 CTest · 49 个独立 demo · 15 个完整应用。 （Button/Label/Checkbox/Switch/Slider/Bar/Image/Arc/Spinner/Meter/TextInput/TextView/EditView/List/Chart/Dropdown/Table/Tabview/TreeView/Grid/Canvas/ColorPicker/Roller/BarChart/MsgBox/FileDialog/Joystick + base 容器）
抗锯齿(4bpp 灰度字体 + Wu 斜线 + 距离场圆弧，YMGUI_ANTIALIAS 可裁)、中文/CJK(UTF-8 回退链 + 稀疏字模 + 外部 flash 回调，YMGUI_FONT_CJK 可裁)、状态/数据绑定和 context 级 UI 属性动画均已落地。
每个 demo 展示一张代表性运行截图。控件及常规应用截图由 ./capture_shots.sh 一键生成（SDL dummy 驱动无头渲染，产物落 docs/shots/）；视频剪辑器展示导入 卖瓜.mp4 后的时间线，音乐工坊展示当前版本的鼓机与多轨编排工作区。
用真实小应用验证"库够不够用"，每个都催生或压榨了一批控件。
闹钟 三滚轮设时 + 到点弹阻塞模态(MsgBox) |
实时监控面板 Tabview/Meter/Arc/Chart + 数据绑定 |
电子表格 Grid + 公式引擎(SUM/AVG，定点) |
文件管理器 TreeView 懒加载 + 预览 + 沙箱增删改 |
图层画板 Canvas + ColorPicker + 图层融合/工具 |
音乐播放器 BarChart 频谱 + Roller 歌词 + ffmpeg 解码 |
多行编辑器 EditView 选区/剪贴板/撤销/查找替换 + 菜单栏 |
视频播放器 Image 缩放模式 + 流式解码 + A/V 同步 |
上下文手势实验室 右键/触摸长按菜单 + 捕获式卡片拖动 |
插件管理器 动态加载/卸载 + 插件自建 UI + 生命周期日志 |
Pocket Tasks 320×480 竖屏任务应用，完成进度与底部详情面板动效 |
Yaomi Phone 320×480 中文手机界面：三页桌面、16 个模块化应用、统一输入法、双列后台与开关机 |
视频剪辑器 · 卖瓜.mp4 已加入 V1 轨道，显示项目预览、片段属性和入出点缩略图。
音乐工坊 · 中文多轨编排、九声部采样鼓机、钢琴卷帘、基础混音与 WAV 导出，附可编辑曲库。下图为“午后律动”工程的实际运行界面，详见 使用说明。
 button |
 form（复选/开关/滑块） |
 list |
 chart |
 dropdown（浮层展开） |
 table |
 tabview |
 treeview |
 msgbox（模态弹窗） |
 roller |
 barchart |
 dashboard（表盘簇） |
 canvas |
 colorpicker |
 image（缩放模式） |
 draw（图元） |
 textinput |
 textview |
 editview |
 layout（Stack/Align） |
 bind（数据绑定） |
 font_cjk |
 font_gb2312 |
 flush_band（分块刷新） |
 anim（属性补间） |
 anim_drawer（抽屉导航） |
 anim_dialog（模态弹窗） |
 anim_cards（错峰卡片） |
 anim_progress（进度反馈） |
 anim_canvas（播放头画布） |
 anim_tabs（页签切换） |
 anim_accordion（折叠面板） |
 anim_toast（通知入场） |
 anim_scroll（滚动视口） |
 anim_theme（主题过渡） |
|
 anim_focus（焦点跟随） |
 anim_validation（表单校验） |
 anim_batch（批量操作栏） |
|
 anim_list_ops（列表增删重排） |
 anim_drag_snap（拖拽吸附） |
 anim_submit（提交反馈） |
 anim_loading（加载切换） |
 anim_detail（侧边详情） |
 anim_pull_refresh（下拉刷新） |
 anim_carousel（轮播吸附） |
二十个动效场景的操作和代码入口见 动效 Demo 说明；其中只有播放头示例使用 Canvas，其余均是 YMGUI 标准控件的动效。动效模块可用 -DYMGUI_ANIM=OFF 整体裁剪；动效 Demo 桌面窗口使用 SDL 原生 1:1 像素显示，不再将 480×272 画面放大两倍。
sudo apt-get install libsdl2-dev # 仅桌面开发/demo 需要，库本体不依赖 SDL
cmake -S . -B build/rgb565/Demo -DYMGUI_COLOR_DEPTH=16
cmake --build build/rgb565/Demo -j8
ctest --test-dir build/rgb565/Demo --output-on-failure # 跑全部单测
./build/rgb565/Demo/demo_dashboard # 看效果(需显示器)
./build/rgb565/Demo/demo_font_gb2312 # 中文字体(GB2312 全集走外部 flash 回调)
SDL_VIDEODRIVER=dummy ./build/rgb565/Demo/demo_plugin 120 # 插件系统宿主 demo（无头跑 120 帧）
./build_all.sh # 一键建库 + 全部 Demo + 15 个 project_Demo 项目
./capture_shots.sh -b # 先构建再批量截图到 docs/shots/(无头,需 ffmpeg)
./build/rgb565/project_Demo/video_stidio/video_stidio # 视频剪辑器（build_all 后）
tools/check_repo.sh # 文档/字库/计数/路径快速检查
tools/test_matrix.sh # RGB565 + RGB888 构建和 38 个 CTest默认构建按色深和类型归档：build/rgb565/Demo/ 集中放控件演示、核心库和根工程测试；build/rgb565/project_Demo/<项目名>/ 分别放完整应用。RGB888 对应 build/rgb888/，用 ./build_all.sh --depth 24 构建（跳过仅支持 RGB565 的视频剪辑器）。详见 构建目录说明。
extern_lib/ 用于存放 project_Demo/ 应用所需的第三方依赖，各应用按需引用；构建产物放在对应的 build/ 目录。YMGUI 核心库的依赖与移植范围保持在 YMGUI/ 内。
视频剪辑器需额外准备 extern_lib/FFmpeg 源码（或系统 FFmpeg 开发包）和 FFmpeg 命令行，仅支持 Linux/RGB565。独立构建、操作和测试见 video_stidio。
直接使用预编译库可从 releases 分发目录 获取 Linux x86_64 压缩包；该目录随仓库提交。build/ 是被 Git 忽略的本地构建目录。
运行 ./sdk/build.sh 生成 build/sdk/YMGUI_libs/ 和对应的压缩包，包含 RGB565 / RGB888 核心静态库、独立 SDL 适配库、头文件、CMake 接口、示例和字模。外部工程通过 find_package(YMGUI CONFIG REQUIRED) 接入，无需携带库实现。当前打包支持原生 Linux；核心与 SDL 分开，--without-sdl 可生成纯核心包。详见 SDK 说明 和 接入手册。
构建产物按色深、SDK、专项检查和日志分类，详见 构建目录说明。发布包生成后可用 ./sdk/verify.sh 复验，临时产物自动清理，日志保留于 build/logs/sdk/。
project_Demo/ymgui_app.cmake 原生支持 Android：YMGUI 核心编译为静态库，SDL 假 LCD
作为 SDL2 目标链接，应用目标构建为 shared library。需要 Android NDK、CMake 和 SDL2
导出的 CMake package，也可以通过 SDL2_SOURCE_DIR 直接构建 SDL2 源码；再用 NDK
toolchain 指定 ABI：
cmake -S project_Demo/alarm_clock \
-B build/android/arm64-v8a/alarm_clock \
-DCMAKE_TOOLCHAIN_FILE="$ANDROID_NDK_HOME/build/cmake/android.toolchain.cmake" \
-DANDROID_ABI=arm64-v8a \
-DANDROID_PLATFORM=android-24 \
-DSDL2_DIR=/path/to/SDL2/lib/cmake/SDL2 \
-DYMGUI_COLOR_DEPTH=24
cmake --build build/android/arm64-v8a/alarm_clock使用 SDL2 源码时，将 -DSDL2_DIR=... 替换为
-DSDL2_SOURCE_DIR=/path/to/SDL2。Android native 目标会自动启用 PIC，并构建为 shared
library，适合由 Gradle/SDL Activity 打包进 APK/AAB。
将 -DYMGUI_COLOR_DEPTH=16 改为 24 即可在 Android 构建 RGB565 或 RGB888 framebuffer。
应用层仍需由 Java/Kotlin 或 SDL Activity 桥接生命周期、触摸/软键盘和资源路径；动态插件
按 ABI 放入 APK/AAB 的 native library 目录。完整的显示、输入、资源和插件移植约定见
跨平台移植。
YMGUI/PLUGIN/ 提供一个面向嵌入式约束的轻量插件注册表：插件通过版本化的
YMGUI_PluginHost 获取上下文、创建控件和日志能力，支持 init/tick/deinit 生命周期。
固件可直接调用 YMGUI_PluginRegistry_Add 静态注册；有操作系统的平台还可用
YMGUI_Plugin_LoadDynamic 加载导出 YMGUI_Plugin_Get 的动态插件（Linux/Android
为 .so，Windows 为 .dll，macOS 为 .dylib），并用
YMGUI_Plugin_InspectDynamic 在管理器中筛除 ABI 不兼容或并非插件的动态库。
示例 demo_plugin 中的 system-info 插件会创建标签并显示运行时间。
完整应用见 project_Demo/plugin_host/：宿主提供插件管理界面，动态插件通过宿主
函数表创建自己的指标页和交互按钮，并支持运行时安全卸载、重载。
| 想做什么 | 读哪份 |
|---|---|
| 第一次接触，先搞懂现状 | docs/当前状态.md |
| AI 助手接手、选控件、查使用技巧 | docs/AI_GUIDE.md |
| 理解架构、扩展库 | docs/ARCHITECTURE.md |
| 写代码，查控件怎么用 | docs/API.md |
| 写代码，守规范 | docs/代码风格.md |
| 移植到 Windows、Android 或真机 | docs/CROSS_PLATFORM_PORTING.md |
| 了解当前开发进程 | docs/DEVLOG_V3.md |
| 查看全部文档的分层与归档 | docs/README.md |
- 最窄腰部：整个库对硬件只要一个回调
flush(area, buf)把像素推到面板。移植 = 把YMGUI/整个拷走 + 改YMGUI/CONFIG/+ 照SDL_LCD/写真实 LCD 的 flush。 - 分块刷新：draw buffer 可远小于整屏，逐块渲染逐块 flush，同一套代码覆盖几十 KB 的 MCU 到桌面。
- 保留模式 + 脏矩形：控件树持久存在，只重绘变化区域，空闲不耗 —— LCD 的 blit 是最贵操作，这样降到最低。
- 无 FPU 友好：几何用 int16，三角/渐变查表(Q15 定点)，不走 float 必经路径。
- 中文三轴可裁：CJK 开关是编译期宏(轴1)，字集范围(精简/GB2312)是字模生成期参数(轴2)，字模存放(内部/外部 flash)是运行期
glyph_read回调(轴3)——各归其位，方案切换不改控件代码。 - 目录对齐前作 YMCV：可移植的 11 层全收在
YMGUI/库根下（对齐 YMCV 的OpenSrc-YMCV/YMCV/，拷一个文件夹即移植）；CONFIG/DEBUG/COMMON/OPOBJ/CORE 与 YMCV 同名，GUI/HAL/WIDGET/STATE/ANIM/PLUGIN 为 GUI 新增。
YMGUI 采用 Apache License 2.0（Apache-2.0），完整条款见 LICENSE。顶部协议徽章可直接打开许可证，徽章图片随仓库保存。
extern_lib/ 中的第三方依赖与音源、音乐工坊曲库素材，分别遵循各自附带的许可与来源说明；详见 第三方依赖说明 和 曲库来源与许可。本地 参考/ 目录和其他位置的 WAV 音频不纳入提交；extern_lib/ 中运行必需的采样 WAV 随仓库提供。
验证工程的通用回流与无 SDL phone 入口见 回流清单 和 跨平台移植。
当前事实统一维护在 docs/当前状态.md，每轮开发过程续写到 docs/DEVLOG_V3.md。公开 API、架构、移植或规范变化时，再更新对应专题文档。docs/history/ 只保留冻结的 V1/V2 和旧快照，需要追溯决策或排查回归时才阅读。具体规则见 AGENTS.md。
tests/test_*.c 里的断言即行为规格 —— 改机制先看对应测试，改完让它继续过。