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.
This commit is contained in:
@@ -0,0 +1,103 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user