88 lines
3.3 KiB
Markdown
88 lines
3.3 KiB
Markdown
# 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)
|
|
|
|
1. Copy this whole folder and give it your demo's name.
|
|
2. Replace `examples/Demo/Demo.cpp` with your own sketch (keep the file
|
|
and folder name `Demo`, or rename both and pass `APP=YourName` to make).
|
|
3. Your sketch must provide `setup()` and `loop()` and may use:
|
|
- `millis()`, `delay()`, `random()`, `randomSeed()` — timing/randomness
|
|
- `emuGfx::fb[320*240]` — 320x240 ABGR8888 framebuffer (`uint32_t` pixels)
|
|
- `emuGfx::dirty = true` — set this every frame you want presented
|
|
- `emu::keyboard` — ASCII key queue (`' '`, `'a'`…, `0x08` backspace)
|
|
- `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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
./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
|
|
|
|
```bash
|
|
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 `#include`s). 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.
|