Files
lilygo-t-deck/emulator-template/README.md
T
Dejvino a243f303f6 emulator-template: Neutralize demo slot, add 10s auto-exit safety hatch
Make the template foolproof to copy-and-fill for a new demo:

- examples/Conway/ replaced by a neutral examples/Demo/Demo.cpp sample
  (bouncing box) documenting the full sketch contract (setup/loop,
  emuGfx::fb, emuGfx::dirty, emu::keyboard)
- Makefile passes the sketch path as -DAPP_SRC; main.cpp now includes
  APP_SRC instead of hardcoding Conway.cpp, window title uses APP_NAME
- Safety hatch: emulator auto-exits after 10 seconds by default so a
  runaway demo can't hang and eat resources; --user-run disables the
  cap, --timeout MS adjusts it (default 10000)
- README rewritten as a step-by-step recipe: replace the Demo sketch,
  run 'make run'; documents all CLI flags, drops the unimplemented
  --dump-interval flag

Verified: fresh copy + sketch swap builds and renders; hatch fires at
10s (and at --timeout 2000); --user-run runs until --frames cap.
2026-11-16 20:25:41 +01:00

3.3 KiB

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

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:

./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

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 #includes). 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.