Make the template foolproof to copy-and-fill for a new demo: - examples/Conway/ replaced by a neutral examples/Demo/Demo.cpp sample (bouncing box) documenting the full sketch contract (setup/loop, emuGfx::fb, emuGfx::dirty, emu::keyboard) - Makefile passes the sketch path as -DAPP_SRC; main.cpp now includes APP_SRC instead of hardcoding Conway.cpp, window title uses APP_NAME - Safety hatch: emulator auto-exits after 10 seconds by default so a runaway demo can't hang and eat resources; --user-run disables the cap, --timeout MS adjusts it (default 10000) - README rewritten as a step-by-step recipe: replace the Demo sketch, run 'make run'; documents all CLI flags, drops the unimplemented --dump-interval flag Verified: fresh copy + sketch swap builds and renders; hatch fires at 10s (and at --timeout 2000); --user-run runs until --frames cap.
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)
- Copy this whole folder and give it your demo's name.
- Replace
examples/Demo/Demo.cppwith your own sketch (keep the file and folder nameDemo, or rename both and passAPP=YourNameto make). - Your sketch must provide
setup()andloop()and may use:millis(),delay(),random(),randomSeed()— timing/randomnessemuGfx::fb[320*240]— 320x240 ABGR8888 framebuffer (uint32_tpixels)emuGfx::dirty = true— set this every frame you want presentedemu::keyboard— ASCII key queue (' ','a'…,0x08backspace)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
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:
./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
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 #includes). 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.