espressif2022/esp-gsp

Readme (zh)

# ESP-GSP

[English](README.md) | 中文

ESP-GSP（Espressif Graphics Scene Processor）面向 ESP-IDF，将 JSON 场景和
资源编译成内嵌 Bundle 与类型化 C API。设备端通过 ESP-LCD 渲染有界运行时
状态，不需要维护通用 UI 对象树。

```text
JSON + 资源 -> ESP-IDF 构建 -> 生成 C API -> ESP-GSP -> 显示屏
```

## 主要特性

| 能力 | 说明 |
|---|---|
| 构建期 UI | Schema 校验、资源编译和确定性 Bundle |
| 生成 API | 为命名元素生成类型化 setter 与事件判断函数 |
| 嵌入式运行时 | 可配置固定资源池、脏区渲染、RGB565/RGB888 |
| UI 能力 | 控件、布局、List/Grid、模板、导航、媒体与 Canvas |
| 输入 | 点击、拖动、滚动、滑动以及可选的应用层双点 pinch |
| 显示路径 | RGB、MIPI-DSI、SPI、QSPI，并保留安全的软件回退 |

ESP-GSP 适用于界面结构在构建期确定，而文字、数值、媒体、集合和可见性需要在
运行时变化的产品。

## 要求与安装

- ESP-IDF 6.0 或更高版本。
- ESP-IDF Python 环境使用 Python 3.10 或更高版本，并安装 Pillow。
- 应用或 BSP 能初始化一个 `esp_lcd` 显示目标。

```sh
idf.py add-dependency --registry-url https://components-staging.espressif.com \
  "espressif2022/esp-gsp^0.1.1"
```

## 快速使用

需要由应用控制的元素设置稳定 `name`，需要交给应用处理的动作设置
`callback`：

```json
{
  "screen": "main", "w": 320, "h": 240,
  "objects": [
    {"type": "progress", "parent": -1, "name": "load",
     "x": 24, "y": 80, "w": 272, "h": 18,
     "value": 0, "fg_color": "#4CC9F0"},
    {"type": "toggle", "parent": -1, "name": "power",
     "callback": "power_changed",
     "x": 128, "y": 140, "w": 64, "h": 32,
     "fg_color": "#4361EE"}
  ]
}
```

在应用组件中注册场景：

```cmake
idf_component_register(SRCS "app_main.c" PRIV_REQUIRES esp-gsp)
gsp_add_bundle(${COMPONENT_LIB} SCENES "../ui/main.json")
```

构建会内嵌 Bundle 并生成 `bundle_gsp.h`。使用 `gsp_bundle_config()`、
`ESP_GSP_ESP_LCD_CONFIG_INIT()` 和生成的 `gsp_<scene>_<name>_*()` API。
完整可运行集成见[快速入门](docs/getting-started.md)。

## 推荐用法

1. 先锁定芯片、逻辑分辨率、像素格式和 BSP 显示路径。
2. 布局与声明式行为留在 JSON，产品状态和阻塞工作留在应用任务。
3. 保持 Kconfig 默认值，直到编译器输出或测量结果证明需要产品级修改。
4. 重新构建后再使用生成 API，不要修改生成头文件。
5. 先预览，再分别记录目标构建、板级运行和视觉验收结果。

ESP-IDF 上的 setter 为异步提交。仅在明确同步边界使用 `esp_gsp_flush()`，并从
应用任务调用 `esp_gsp_stop()`。

## 文档

- [快速入门](docs/getting-started.md)
- [场景 JSON 指南](docs/scene-json.md)与生成的[字段参考](docs/authoring.md)
- [推荐开发工作流](docs/recommended-workflow.md)
- [配置参考](docs/configuration.md)与 [Kconfig 使用](docs/kconfig.md)
- [文档索引](docs/README.md)：媒体、生命周期、显示和 API

项目仓库中的示例：
[`hello_world`](https://github.com/espressif/esp-gsp/tree/master/examples/hello_world)
展示最小集成，
[`showcase`](https://github.com/espressif/esp-gsp/tree/master/examples/showcase)
展示产品 UI，
[`benchmark`](https://github.com/espressif/esp-gsp/tree/master/examples/benchmark)
用于可复现测量。

## 当前限制

- 场景结构在构建期固定；动态内容使用属性、模板、集合、运行时媒体或 Canvas。
- 双点 pinch 只上报触点，不会自动缩放控件。
- 一个 Bundle 使用一种逻辑场景分辨率和一种输出像素格式。
- 不支持从右到左布局和复杂文字塑形。

## 许可证

Espressif Modified MIT License，见 [LICENSE](LICENSE)。