Files
lilygo-t-deck/tron-demo/README.md
T

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.