Complete self-contained SDL3 emulator-only template for prototyping sketches without hardware: - Makefile: single-TU build (host + sketch), run/smoke/clean targets - shim.h: minimal Arduino API shim (millis, random, String, GPIO stubs) - src/main.cpp: SDL3 host loop presenting emuGfx::fb, CLI frame dumps - examples/Conway: Conway.cpp sketch + .ino reference copy - .gitignore: exclude built binaries and captured BMP frames The Conway sketch previously started with paused=true, which prevented render() from being called each frame, leaving the framebuffer all-black and resulting in a black SDL3 window. Changed to paused=false so the simulation runs immediately.
T-Deck Emulator-Only Concept Exploration Template
A minimal, copy-paste template for prototyping graphics and engine experiments using the SDL3 emulator (no hardware required).
Quick Start
# From the template directory, build and run:
make run
# Or from the main emulator directory:
make -C /var/home/dejvino/workspace/T-Deck/emulator APP=Conway run
📸 Screenshot / Frame Capture
Capture the current frame as a BMP file:
make smoke # captures 240 frames to smoke_frame.bmp
./Conway-emu --dump screenshot.bmp # capture single frame
./Conway-emu --dump-interval 60 # capture every 60th frame
The emulator supports these command-line options:
| Flag | Description |
|---|---|
--frames N |
Run for N frames then exit |
--dump PATH |
Save the current frame to PATH (BMP format) |
--dump-interval N |
Save every Nth frame to sequential BMP files |
Smoke Test (frame capture)
make smoke
This runs the emulator for 240 frames and saves the last frame to smoke_frame.bmp.
Build & Run
make run
This will:
- Compile the sketch (
examples/Conway/Conway.cpp) alongside the emulator host - Build
Conway-emubinary - Run the SDL3 emulator window showing a Game of Life simulation
Folder Structure
emulator-template/
├── README.md # This file
├── shim.h # Minimal Arduino API emplementation (millis, random, etc.)
├── src/
│ └── main.cpp # SDL3 host loop — sets up window, presents framebuffer,
# and calls setup() / loop() from the sketch
├── examples/
│ └── Conway/ # Your experiment sketch lives here
│ ├── Conway.cpp # The main sketch (compiled jointly with main.cpp)
│ └── Conway.ino # .ino file kept as reference (not compiled)
├── Makefile # Self-contained build — just type `make run`
└── Conway-emu # Built binary (removed by `make clean`)
How It Works
The Makefile's single rule compiles src/main.cpp together with
examples/Conway/Conway.cpp as one translation unit. This means:
- The sketch's
setup()andloop()functions are available directly - The emulator shim (
shim.h) providesmillis(),random(),randomSeed() - The sketch writes to
emuGfx::fb[](ABGR8888 framebuffer), which the host presents each frame via SDL3 - Input comes through
emu::keyboard(populated by SDL key events) - No hardware dependencies: no TFT_eSPI, no SPI, no I2S, no GPIO matrix
Adding Your Own Experiment
- Replace
examples/Conway/Conway.cppwith your own sketch - Ensure your sketch provides
setup()andloop()functions - Use these emulator APIs from
shim.h:millis(),random(),randomSeed()— timing and randomnessemu::keyboard— ASCII key queue (populated by SDL key events)emuGfx::fb[320*240]— 320x240 ABGR8888 framebufferemuGfx::dirty— mark framebuffer as changedpinMode(),digitalRead()— minimal GPIO (idle HIGH)
Controls (emulator)
| Key | Action |
|---|---|
Space |
Toggle pause |
P / Tab |
Switch view mode (both render same grid in this template) |
Esc |
Quit |
License
MIT — free to use, modify, and copy-paste for your own experiments.