# T-Deck Emulator-Only Template A minimal, self-contained SDL3 emulator template for prototyping 320x240 graphics/engine experiments without any hardware. No TFT_eSPI, no SPI, no I2S, no GPIO — just SDL3 and a framebuffer. ## Creating a new demo (the only thing you need to do) 1. Copy this whole folder and give it your demo's name. 2. Replace `examples/Demo/Demo.cpp` with your own sketch (keep the file and folder name `Demo`, or rename both and pass `APP=YourName` to make). 3. Your sketch must provide `setup()` and `loop()` and may use: - `millis()`, `delay()`, `random()`, `randomSeed()` — timing/randomness - `emuGfx::fb[320*240]` — 320x240 ABGR8888 framebuffer (`uint32_t` pixels) - `emuGfx::dirty = true` — set this every frame you want presented - `emu::keyboard` — ASCII key queue (`' '`, `'a'`…, `0x08` backspace) - `pinMode()`/`digitalRead()` — stubs, idle HIGH That is the whole contract. The bundled `Demo.cpp` shows it with a bouncing box — use it as a starting skeleton or delete everything in it. **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 ```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 ``` ## 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 ``` ## 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, String…) ├── src/ │ └── main.cpp # SDL3 host loop — window, framebuffer, setup()/loop() ├── examples/ │ └── Demo/ │ └── Demo.cpp # ← your sketch goes here ├── 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 pixels into `emuGfx::fb[]`, and the host presents the framebuffer via SDL3. ## License MIT — free to use, modify, and copy-paste for your own experiments.