espressif2022/esp-gsp

Readme

# ESP-GSP

English | [中文](README_CN.md)

ESP-GSP (Espressif Graphics Scene Processor) compiles JSON scenes and assets
into an embedded bundle plus a typed C API for ESP-IDF. The device renders a
bounded runtime model through ESP-LCD instead of maintaining a general-purpose
UI object tree.

```text
JSON + assets -> ESP-IDF build -> generated C API -> ESP-GSP -> display
```

## Highlights

| Capability | What it provides |
|---|---|
| Build-time UI | Schema validation, asset compilation, deterministic bundles |
| Generated API | Typed setters and event predicates for named elements |
| Embedded runtime | Configurable fixed pools, dirty rendering, RGB565/RGB888 |
| UI features | Controls, layouts, lists, grids, templates, navigation, media and Canvas |
| Input | Tap, drag, scroll, flick and optional application-owned two-contact pinch |
| Display paths | RGB, MIPI-DSI, SPI and QSPI with safe software fallbacks |

ESP-GSP suits products whose screen structure is known at build time while
text, values, media, collections and visibility change at runtime.

## Requirements and installation

- ESP-IDF 6.0 or later.
- Python 3.10 or later with Pillow in the active ESP-IDF environment.
- An application or BSP that initializes an `esp_lcd` display target.

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

## Quick start

Give application-controlled elements a stable `name` and application actions a
`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"}
  ]
}
```

Register it in the application component:

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

The build embeds the bundle and generates `bundle_gsp.h`. Start with
`gsp_bundle_config()`, `ESP_GSP_ESP_LCD_CONFIG_INIT()`, and the generated
`gsp_<scene>_<name>_*()` helpers. The
[Getting started guide](docs/getting-started.md) contains the complete runnable
integration.

## Recommended use

1. Lock the target, logical resolution, pixel format and BSP display path.
2. Keep layout and declarative behavior in JSON; keep product state and
   blocking work in application tasks.
3. Keep Kconfig defaults until compiler output or measurement justifies a
   product-wide change.
4. Rebuild before using generated APIs; never edit generated headers.
5. Preview first, then report target build, board operation and visual
   acceptance separately.

Setters are asynchronous on ESP-IDF. Use `esp_gsp_flush()` only at explicit
synchronization boundaries and call `esp_gsp_stop()` from an application task.

## Documentation

- [Getting started](docs/getting-started.md)
- [Scene JSON guide](docs/scene-json.md) and generated
  [field reference](docs/authoring.md)
- [Recommended development workflow](docs/recommended-workflow.md)
- [Configuration](docs/configuration.md) and [Kconfig usage](docs/kconfig.md)
- [Documentation index](docs/README.md) for media, lifecycle, display and APIs

Examples in the project repository:
[`hello_world`](https://github.com/espressif/esp-gsp/tree/master/examples/hello_world)
for the minimum integration,
[`showcase`](https://github.com/espressif/esp-gsp/tree/master/examples/showcase)
for product UI, and
[`benchmark`](https://github.com/espressif/esp-gsp/tree/master/examples/benchmark)
for repeatable measurement.

## Current limitations

- Scene structure is fixed at build time; use properties, templates,
  collections, runtime media or Canvas for dynamic content.
- Pinch reports two contacts but does not automatically zoom a control.
- A bundle uses one logical scene resolution and one output pixel format.
- Right-to-left layout and complex-script shaping are not supported.

## License

Espressif Modified MIT License. See [LICENSE](LICENSE).