Propagate the lessons from tron-room-demo's hardware bring-up back into the canonical template, so demos are hardware-testable from day one: - Contract change: the sketch renders into emuGfx::fb565 (320x240 uint16_t, RGB565 in PANEL WIRE ORDER - big-endian, the byte sequence the ST7789 receives over SPI, the same convention TFT_eSprite's primitives use). The host expands 565 to 8888 for SDL only. Native little-endian writes look right in the emulator but show byte-swapped on the panel (seen on hardware: BG 0x0002 -> green, fogged floor 0x0882 -> pink) - the new contract makes that bug impossible. - Recommended sketch structure: examples/APP/Core.h holds all rendering/logic device-agnostically (demoInit/demoInput/demoFrame); the .cpp is a thin emulator shell. Bundled sample demonstrates it. - New fw/ scaffold: standalone PlatformIO project (shared boards/lib, T-Deck pin map) with DemoHW.ino driving the same core through a TFT_eSprite frameBuffer() and reporting true fps + render/push split over USB serial every 2 s. -O2 explicitly (pio default -Os skews benchmarks). - shim.h gains rgb565()/wire565() helpers; Makefile deps now include the sketch's headers; --dump now also fires on safety-hatch exit (a long --frames run was silently losing its dump before). Verified: template builds + smoke renders correct 565 colors; DemoHW builds clean for ESP32-S3 (328 KB flash).
171 lines
6.9 KiB
Markdown
171 lines
6.9 KiB
Markdown
# T-Deck Emulator-Only Template
|
|
|
|
A minimal, self-contained SDL3 emulator template for prototyping 320x240
|
|
graphics/engine experiments without any hardware — with a ready-made
|
|
firmware twin so the same code can be benchmarked on the real T-Deck.
|
|
No TFT_eSPI, no SPI, no I2S, no GPIO on the desktop side — just SDL3
|
|
and a framebuffer.
|
|
|
|
## The color contract (RGB565, panel wire order)
|
|
|
|
The T-Deck's ST7789 panel receives 16-bit RGB565 pixels **high byte
|
|
first** over SPI, and on hardware your framebuffer is pushed raw. So
|
|
the emulator's contract matches the panel exactly:
|
|
|
|
- render into `emuGfx::fb565[]` — 320x240 `uint16_t`, RGB565 in **panel
|
|
wire order** (big-endian: store `wire565(c)`, a byte swap)
|
|
- build colors with `rgb565(r, g, b)` (5/6/5 channels)
|
|
- set `emuGfx::dirty = true` when a frame is ready
|
|
|
|
The host expands 565 → 8888 for the desktop window only. On the device
|
|
that step doesn't exist — the buffer goes to the panel as-is. Anything
|
|
you see in the emulator, including 5-bit color banding, is what the
|
|
panel would show.
|
|
|
|
**Why wire order:** `TFT_eSprite`'s own primitives store colors
|
|
byte-swapped (`drawPixel`: `color = color>>8 | color<<8`) because
|
|
`pushSprite` sends the buffer raw. If your software rasterizer writes
|
|
native little-endian values into a hardware sprite buffer, colors show
|
|
up byte-swapped on the panel while the emulator looks fine. Storing in
|
|
wire order from day one makes that bug impossible.
|
|
|
|
## Sketch structure (for hardware-testable demos)
|
|
|
|
```
|
|
examples/$(APP)/$(APP)Core.h <- all rendering + logic. Device-agnostic:
|
|
no shim, no SDL, no Arduino. Renders
|
|
RGB565 (wire order) into a caller-
|
|
supplied buffer.
|
|
examples/$(APP)/$(APP).cpp <- thin emulator shell: keyboard pump,
|
|
delta time, set dirty.
|
|
fw/$(APP)HW.ino <- firmware twin (copy of DemoHW.ino):
|
|
TFT_eSprite + free-running fps report.
|
|
```
|
|
|
|
The bundled sample implements exactly this split. Because the core is
|
|
shared 1:1, whatever fps the hardware reports is the fps of exactly
|
|
your code.
|
|
|
|
## Creating a new demo (the only thing you need to do)
|
|
|
|
1. Copy this whole folder and give it your demo's name.
|
|
2. Put your rendering + logic in `examples/Demo/DemoCore.h` (keep the
|
|
file and folder name `Demo`, or rename both and pass `APP=YourName`
|
|
to make).
|
|
3. The core's API contract (mirrored by the twin in `fw/`):
|
|
- `demoInit(uint16_t *fb)` — receive the 320x240 RGB565 buffer
|
|
- `demoInput(uint8_t key)` — one ASCII key (`0x1b` = ESC)
|
|
- `demoQuitRequested()` — ask the host to exit
|
|
- `demoFrame(float dt, unsigned long nowMs)` — simulate + render
|
|
4. The shell (`examples/Demo/Demo.cpp`) may use:
|
|
- `millis()`, `delay()`, `random()`, `randomSeed()` — timing/randomness
|
|
- `emuGfx::fb565[320*240]` — the RGB565 buffer (wire order)
|
|
- `emuGfx::dirty = true` — set this every frame you want presented
|
|
- `emu::keyboard` — ASCII key queue (`' '`, `'a'`…, `0x08` backspace)
|
|
- `pinMode()`/`digitalRead()` — stubs, idle HIGH
|
|
|
|
**Do not** edit `src/main.cpp`, `shim.h`, or the Makefile — they are
|
|
the host and are app-agnostic. Do not leave references to the bundled
|
|
demo in your sketch.
|
|
|
|
## Build & Run (emulator)
|
|
|
|
```bash
|
|
make run # builds examples/$(APP)/$(APP).cpp and opens a window
|
|
make run APP=MyDemo # build a differently-named sketch in examples/MyDemo/
|
|
make smoke # headless: 240 frames, dumps smoke_frame.bmp
|
|
make clean # removes the built binary
|
|
```
|
|
|
|
## On the real T-Deck (ESP32-S3) — free-running benchmark
|
|
|
|
The `fw/` scaffold drives the same core on the hardware, drawing
|
|
straight into a `TFT_eSprite`'s `frameBuffer()` (16-bit RGB565, PSRAM —
|
|
the same full-frame pipeline as NetDeck's M1 anti-flicker pattern) and
|
|
presenting with `startWrite()/pushSprite(0,0)/endWrite()`.
|
|
|
|
The loop is deliberately **free-running** — no pacing — and prints a
|
|
report over USB serial every 2 s:
|
|
|
|
```
|
|
DemoHW: 120 frames in 2001ms = 60.0 fps | render 12.3 ms, push 14.8 ms
|
|
```
|
|
|
|
`render` is your core's rasterizer; `push` is the SPI transfer to the
|
|
panel (at 80 MHz a full 320x240 frame costs ~15 ms — that is the
|
|
physical floor for full-frame 30 fps).
|
|
|
|
```bash
|
|
pio run -d emulator-template/fw -t upload # flash the T-Deck
|
|
pio device monitor # 115200 baud
|
|
```
|
|
|
|
(`fw/platformio.ini` points at the repo's shared `boards/`, `lib/` and
|
|
the T-Deck pin map in `src/netdeck` — NetDeck's own builds are
|
|
untouched. Rename the demo: adjust `[env:DemoHW]`'s `-I` and the
|
|
`demo::` calls in the .ino.)
|
|
|
|
## Safety hatch
|
|
|
|
By default the emulator **exits automatically after 10 seconds** so a
|
|
runaway demo can never hang around and eat resources. Flags:
|
|
|
|
```bash
|
|
./Demo-emu --user-run # run indefinitely (interactive play)
|
|
./Demo-emu --timeout 30000 # different auto-exit time (ms)
|
|
./Demo-emu --frames 600 # exit after N frames instead
|
|
```
|
|
|
|
## Frame capture
|
|
|
|
```bash
|
|
make smoke # 240 frames -> smoke_frame.bmp
|
|
./Demo-emu --dump shot.bmp # dump the last frame to a BMP
|
|
```
|
|
|
|
Note: `--dump` fires when the run ends — via `--frames N` completing or
|
|
the safety hatch exiting. A run longer than the default 10 s hatch needs
|
|
`--timeout` raised (e.g. `--frames 900 --timeout 20000`), or the hatch
|
|
cuts it short.
|
|
|
|
## CLI options
|
|
|
|
| Flag | Description |
|
|
|------|-------------|
|
|
| `--user-run` | Disable the 10 s auto-exit (interactive use) |
|
|
| `--timeout MS` | Auto-exit after MS milliseconds (default 10000) |
|
|
| `--frames N` | Exit after N frames (overrides the timeout) |
|
|
| `--dump PATH` | Save the last frame to PATH (BMP) |
|
|
|
|
## Folder Structure
|
|
|
|
```
|
|
emulator-template/
|
|
├── README.md # This file
|
|
├── shim.h # Minimal Arduino API shim (millis, random, rgb565…)
|
|
├── src/
|
|
│ └── main.cpp # SDL3 host loop — window, 565→8888 expand, setup()/loop()
|
|
├── examples/
|
|
│ └── Demo/
|
|
│ ├── DemoCore.h # ← your rendering + logic (device-agnostic)
|
|
│ └── Demo.cpp # ← emulator shell
|
|
├── fw/
|
|
│ ├── platformio.ini # Hardware twin project (shared boards/lib)
|
|
│ └── DemoHW.ino # T-Deck firmware with fps report
|
|
├── Makefile # Self-contained build — just `make run`
|
|
└── .gitignore # ignores built binaries and captured frames
|
|
```
|
|
|
|
## How It Works
|
|
|
|
The Makefile's single rule compiles `src/main.cpp` together with
|
|
`examples/$(APP)/$(APP).cpp` as **one translation unit** (the Makefile
|
|
passes the path as `-DAPP_SRC=…`, which main.cpp `#include`s). The
|
|
sketch's `setup()`/`loop()` are called directly; each frame it writes
|
|
RGB565 pixels into `emuGfx::fb565[]`, the host expands them to 8888 and
|
|
presents via SDL3.
|
|
|
|
## License
|
|
|
|
MIT — free to use, modify, and copy-paste for your own experiments.
|