# 项目概述与特点

## 什么是 EmbeddedGUI

EmbeddedGUI (EGUI) 是一个专为资源受限的嵌入式系统设计的轻量级 C 语言 GUI 框架。它的目标运行环境为 RAM 不足 8KB、ROM 不足 64KB、CPU 主频约 100MHz 且无需浮点运算单元的微控制器。通过局部帧缓冲 (PFB) 设计，EGUI 在极低的内存占用下实现了丰富的 UI 功能，包括触控交互、流畅动画和类 Android 的应用开发模式。

项目仓库地址:

- Gitee: [EmbeddedGUI (gitee.com)](https://gitee.com/embeddedgui/EmbeddedGUI)
- GitHub: [EmbeddedGUI (github.com)](https://github.com/EmbeddedGUI/EmbeddedGUI)

项目采用 **MIT 许可证**，可自由使用于商业和非商业项目。

## 设计理念

EGUI 的核心设计围绕四个关键理念展开:

### 局部帧缓冲 (PFB)

传统 GUI 框架需要一整块屏幕大小的帧缓冲区 (例如 240x320 RGB565 需要约 150KB RAM)，这在大多数 MCU 上是不可承受的。EGUI 采用局部帧缓冲方案，仅使用一小块缓冲区 (如 30x40 像素 = RGB565 下仅 2400 字节)，通过分块渲染来绘制整个屏幕，将 RAM 需求降低到 4KB 以下。

PFB 的宽度和高度建议优先选成屏幕尺寸的整数约数。例如对于 240x320 的屏幕，PFB 可以设为 30x40 (各除以 8)。如果不能整除，框架也会处理边界块。PFB 越大，单次渲染覆盖的面积越大，刷新次数越少；PFB 越小，RAM 占用越低。EGUI 对 PFB 做了特别优化，使得小 PFB 和大 PFB 之间的性能差异不大，开发者可以根据可用 RAM 灵活选择。

### 脏矩形机制

EGUI 追踪界面上发生变化的区域，仅重绘这些"脏"区域而非整个屏幕。当界面上只有一个按钮状态变化时，框架只会重绘该按钮所在的矩形区域，而非刷新整个屏幕。这不仅大幅降低了 CPU 负载和功耗，还能在局部刷新场景下实现更高的帧率，非常适合电池供电的嵌入式设备。

### 定点数运算

所有数学计算 (三角函数、插值、贝塞尔曲线等) 均使用定点数实现，完全避免浮点运算。定点数运算库 `egui_fixmath` 提供了 sin、cos、atan2、sqrt 等常用数学函数的定点版本。这确保了在没有 FPU 的低端 MCU (如 Cortex-M0/M0+) 上也能高效运行，不会因为软件浮点模拟而出现卡顿。

### 类 Android API

EGUI 借鉴了 Android 的 UI 开发模式，提供了开发者熟悉的编程范式:

- **Activity**: 管理页面生命周期 (onCreate、onResume、onPause、onDestroy)，支持页面栈导航
- **ViewPage**: 实现左右滑动切页，搭配 PageIndicator 显示当前页码
- **LinearLayout / GridLayout**: 自动布局容器，按垂直/水平方向或网格排列子控件
- **Dialog / Toast**: 弹窗和消息提示，与 Android 用法一致

对于熟悉 Android 开发的工程师来说，上手成本极低。即使没有 Android 经验，这套直觉式的 API 设计也很容易理解。

## 核心特点

1. **极低资源占用**: 不到 4KB RAM (含帧缓冲) + 64KB ROM 即可运行，适合 Cortex-M0/M0+ 等低端 MCU。
2. **局部帧缓冲 (PFB)**: 无需全屏帧缓冲，小 PFB 和大 PFB 性能差异不大，灵活适配不同 RAM 容量。
3. **脏矩形优化**: 仅重绘变化区域，省电省算力，静态页面几乎零 CPU 开销。
4. **定点数运算**: 全部代码使用定点运算，无需 FPU 支持，兼容最低端 MCU。
5. **抗锯齿渲染**: 基本图形 (线、圆、圆环、圆角矩形、扇形等) 均支持高质量抗锯齿。
6. **60+ UI 控件**: 包括按钮、标签、滑块、进度条、图表、时钟、日历、列表等丰富控件。
7. **完整动画系统**: 支持 Android 的全部动画类型 (平移、缩放、透明度、颜色)，提供 9 种插值器。
8. **主题系统**: 内置主题支持，可统一控制控件的外观风格。
9. **图表控件**: 支持折线图、柱状图、饼图、散点图，满足数据可视化需求。
10. **UTF-8 字体支持**: 支持多语言文本渲染，包括中文等 Unicode 字符。
11. **图片透明通道**: 支持带 Alpha 通道的图片渲染，实现图片半透明叠加效果。
12. **双缓冲支持**: 可充分利用 SPI/DMA 写入屏幕的间隙时间，提升刷新效率。
13. **Mask 支持**: 支持遮罩绘制，实现圆角图片、异形裁剪等效果。
14. **多色深支持**: 支持 RGB8 (8-bit)、RGB565 (16-bit)、RGB32 (32-bit) 多种显示色深。
15. **纯 C 实现**: 全部由 C99 代码编写，支持 C++ 调用，无第三方依赖库。
16. **轮询结构**: 基于轮询驱动，无需 OS 支持，可在裸机环境直接运行。
17. **跨平台开发**: 可在 PC (Windows/Linux/macOS) 上开发调试，代码直接部署到 MCU 上运行。

## 与其他嵌入式 GUI 框架的定位对比

嵌入式 GUI 领域有多个优秀的开源框架，它们各有侧重:

| 特性 | EmbeddedGUI | LVGL | GuiLite | Arm-2D |
|------|-------------|------|---------|--------|
| 最低 RAM 需求 | <4KB | ~32KB | ~4KB | <1KB |
| 最低 ROM 需求 | <64KB | ~100KB | <10KB | ~6KB |
| PFB 支持 | 原生支持 | v9+ 支持 | 不支持 | 原生支持 |
| 抗锯齿 | 内置支持 | 内置支持 | 不支持 | 部分支持 |
| 控件数量 | 60+ | 30+ | ~5 | 无内置 |
| API 风格 | 类 Android | 自定义 | 极简 | 底层绘图 |
| 动画系统 | Android 风格 | 内置 | 无 | 场景播放器 |
| 浮点依赖 | 无 (定点) | 可选 | 无 | 无 (定点) |

EGUI 的定位介于 LVGL 的功能丰富和 GuiLite/Arm-2D 的极致精简之间: 它在保持低资源占用的同时，提供了丰富的控件和完善的动画系统，特别适合那些"资源不足以跑 LVGL，但又需要复杂 UI"的场景。

> **注意**: 以上对比仅供参考，各框架都在持续演进。建议根据具体项目需求选择最合适的方案。

## 适用场景

EGUI 适合以下类型的嵌入式产品:

- **可穿戴设备**: 智能手表、手环、运动追踪器等小屏幕设备，内置模拟时钟、数字时钟、心率、活动环等专用控件
- **工业仪表**: 仪表盘、传感器监控面板，利用图表控件 (折线图、柱状图) 展示实时数据
- **家电控制面板**: 空调、洗衣机、电饭煲、热水器等产品的触控界面
- **医疗设备**: 便携式医疗监测设备的显示界面
- **物联网终端**: 智能家居网关、环境监测终端等
- **教育和原型**: 快速搭建嵌入式 GUI 原型，PC 上开发验证，直接部署到 MCU

总结来说，任何需要在 RAM <8KB、ROM <64KB 的 MCU 上实现图形界面的场景，EGUI 都是一个值得考虑的选择。

## 支持的平台

EGUI 采用分层架构，应用代码与平台无关，仅 Porting 层需要适配:

- **PC 模拟器**: Windows, Linux, macOS (基于 SDL2)，用于日常开发和调试
- **ARM Cortex-M**: STM32G0 等 MCU (通过 ARM GCC 交叉编译)，项目提供了完整的移植参考
- **QEMU**: ARM 虚拟化环境，用于自动化测试和性能基准测试，提供微秒级计时精度
- **WebAssembly**: 通过 Emscripten 编译，可在浏览器中直接体验 EGUI 的各种示例

PC 上编写的应用代码和资源文件可以直接在 MCU 上使用，真正实现"PC 开发，MCU 部署"的工作流。

## 快速体验

如果你已经配置好了开发环境 (参见 [环境搭建](environment_setup.md))，可以立即编译运行:

```bash
# 编译并运行最简单的示例
make all APP=HelloSimple
make run

# 体验更多控件
make all APP=HelloBasic APP_SUB=slider
make run

# 查看图表控件（HelloChart 内含 line / scatter / bar / pie 四页）
make all APP=HelloChart
make run
```

## 下一步

- [环境搭建](environment_setup.md): 配置开发环境，编译运行第一个示例
- [第一个应用](first_app.md): 深入理解 HelloSimple 示例代码
- [项目目录结构](project_structure.md): 了解项目的整体组织方式
- [构建系统详解](build_system.md): 掌握 Makefile 构建系统的使用方法