showcase

# ESP-GSP Experience Showcase

This example is the polished application demo for ESP-GSP. It is deliberately
different from `hello_world` (smallest integration) and `benchmark`
(machine-readable stress workload): the showcase presents the same features as
a coherent smart-space product UI.

The presentation has three user-controlled scenes:

- **Command** — retained vectors, images, gradients, clock, range controls,
  chart, spinner, typed property animation and a gesture-aware Drawer.
- **Gallery** — a scene-owned media wall whose six visible tiles are compiled
  as direct raw resources, avoiding first-use decode or runtime scaling.
- **Lab** — PageFlow, StackView, list-backed Wheel, controls, a static Canvas
  surface, TabView, Dropdown, Table, Keyboard and modal MsgBox.

The checked-in default never navigates or animates content by itself. Images
and Canvas content remain static until the user interacts; only the functional
clock advances once per second. This keeps the product demo focused on GSP's
compiled static UI without presenting a stopped clock as live data.

## Resolution strategy

The example provides two full-size layouts, not every `common` profile:

| Scene size | Target path | Pixel formats |
| --- | --- | --- |
| 1024x600 | ESP32-P4 MIPI-DSI | RGB565, RGB888-capable pipeline |
| 800x480 | ESP32-S31 RGB | RGB565 and native RGB888 |

The 240x240, 320x240 and 360x360 SPI/QSPI boards need a compact information
architecture rather than a mechanically scaled desktop layout. They are not
silently mapped to this example.

## Simulate

Compile all three 800x480 scenes into one interactive browser preview:

```sh
export GSPC_EXECUTABLE=/absolute/path/to/gspc
./preview_wasm.sh
```

Swipe horizontally inside the display to move between scenes. Set
`GSP_WASM_PREVIEW_NO_OPEN=1` for AI or headless environments; the command still
prints the local URL. A Component Registry copy of this example may need
`idf.py reconfigure` once to install ESP-GSP before previewing.

Render and interact with an individual scene without hardware:

```sh
../../tools/sim/run_scene.sh scene/showcase_command_800.json -- \
  --frames 30 --headless --dump /tmp/showcase-command.ppm
```

The host renderer validates authored layout, direct resources, controls,
component gestures and named fixed authored list items. The Showcase firmware
still owns its clock, dynamic data binding and application callbacks; use
hardware for those device/application paths.

## Build profiles

Run these commands from this directory after exporting ESP-IDF.

ESP32-P4 MIPI-DSI, 1024x600 RGB565:

```sh
idf.py -B build_esp32p4 \
  -D SDKCONFIG=build_esp32p4/sdkconfig \
  -D SDKCONFIG_DEFAULTS=sdkconfig.defaults \
  set-target esp32p4 build
```

ESP32-S31 RGB, 800x480 RGB565:

```sh
idf.py --preview -B build_esp32s31_rgb565 \
  -D SDKCONFIG=build_esp32s31_rgb565/sdkconfig \
  -D SDKCONFIG_DEFAULTS=sdkconfig.defaults \
  set-target esp32s31 build
```

ESP32-S31 24-bit RGB, 800x480 native RGB888:

```sh
idf.py --preview -B build_esp32s31_rgb888 \
  -D SDKCONFIG=build_esp32s31_rgb888/sdkconfig \
  -D 'SDKCONFIG_DEFAULTS=sdkconfig.defaults;sdkconfig.defaults.esp32s31_rgb888' \
  -D GSP_SHOWCASE_RGB888=ON \
  set-target esp32s31 build
```

ESP-IDF automatically applies `sdkconfig.defaults.<target>` after the base
file. The RGB888 command adds a product variant on top. See the
[Kconfig guide](../../docs/kconfig.md) for the loading and precedence rules.