Files
lilygo-t-deck/emulator-template/README.md
T
Dejvino c331b55d82 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.
2026-11-16 20:22:03 +01:00

3.3 KiB

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

# 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:

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)

make smoke

This runs the emulator for 240 frames and saves the last frame to smoke_frame.bmp.

Build & Run

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.