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.
103 lines
3.3 KiB
Markdown
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. |