Files
lilygo-t-deck/emulator-template/README.md
T
Dejvino c331b55d82 emulator-template: Add full emulator-only template package, fix Conway starting paused
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.
2026-11-16 20:22:03 +01:00

103 lines
3.3 KiB
Markdown

# 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
```bash
# 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:
```bash
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)
```bash
make smoke
```
This runs the emulator for 240 frames and saves the last frame to `smoke_frame.bmp`.
## Build & Run
```bash
make run
```
This will:
1. Compile the sketch (`examples/Conway/Conway.cpp`) alongside the emulator host
2. Build `Conway-emu` binary
3. 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()` and `loop()` functions are available directly
- The emulator shim (`shim.h`) provides `millis()`, `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
1. **Replace** `examples/Conway/Conway.cpp` with your own sketch
2. **Ensure** your sketch provides `setup()` and `loop()` functions
3. **Use** these emulator APIs from `shim.h`:
- `millis()`, `random()`, `randomSeed()` — timing and randomness
- `emu::keyboard` — ASCII key queue (populated by SDL key events)
- `emuGfx::fb[320*240]` — 320x240 ABGR8888 framebuffer
- `emuGfx::dirty` — mark framebuffer as changed
- `pinMode()`, `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.