Files
Dejvino c58f31d02c emulator-template: RGB565 wire-order contract + ready-to-build HW twin
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).
2026-11-16 22:51:44 +01:00

6.9 KiB

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)

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).

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:

./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

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 #includes). 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.