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