emulator-template: RGB565 wire-order contract + ready-to-build HW twin

Propagate the lessons from tron-room-demo's hardware bring-up back into
the canonical template, so demos are hardware-testable from day one:

- Contract change: the sketch renders into emuGfx::fb565 (320x240
  uint16_t, RGB565 in PANEL WIRE ORDER - big-endian, the byte sequence
  the ST7789 receives over SPI, the same convention TFT_eSprite's
  primitives use). The host expands 565 to 8888 for SDL only. Native
  little-endian writes look right in the emulator but show byte-swapped
  on the panel (seen on hardware: BG 0x0002 -> green, fogged floor
  0x0882 -> pink) - the new contract makes that bug impossible.
- Recommended sketch structure: examples/APP/Core.h holds all
  rendering/logic device-agnostically (demoInit/demoInput/demoFrame);
  the .cpp is a thin emulator shell. Bundled sample demonstrates it.
- New fw/ scaffold: standalone PlatformIO project (shared boards/lib,
  T-Deck pin map) with DemoHW.ino driving the same core through a
  TFT_eSprite frameBuffer() and reporting true fps + render/push split
  over USB serial every 2 s. -O2 explicitly (pio default -Os skews
  benchmarks).
- shim.h gains rgb565()/wire565() helpers; Makefile deps now include
  the sketch's headers; --dump now also fires on safety-hatch exit (a
  long --frames run was silently losing its dump before).

Verified: template builds + smoke renders correct 565 colors; DemoHW
builds clean for ESP32-S3 (328 KB flash).
This commit is contained in:
Dejvino
2026-11-16 22:51:44 +01:00
parent 23b3c88caa
commit c58f31d02c
8 changed files with 440 additions and 96 deletions
+3 -2
View File
@@ -41,9 +41,10 @@ all: $(EMU)
# Compile + link: main.cpp includes the sketch .cpp, forming one TU. # Compile + link: main.cpp includes the sketch .cpp, forming one TU.
# -DAPP_INO makes the sketch's .ino filename available to #ifdef EMULATOR. # -DAPP_INO makes the sketch's .ino filename available to #ifdef EMULATOR.
# Depend on the sketch too, or sketch edits won't trigger a rebuild. # Depend on the sketch AND its headers too (e.g. the device-agnostic
# $(APP)Core.h), or core edits won't trigger a rebuild.
SKETCH := $(APP_DIR)/$(APP).cpp SKETCH := $(APP_DIR)/$(APP).cpp
$(EMU): $(EMU_MAIN) $(SHIMS) $(SKETCH) $(EMU): $(EMU_MAIN) $(SHIMS) $(SKETCH) $(wildcard $(APP_DIR)/*.h)
$(CXX) $(CXXFLAGS) $(SDLFLAGS) $(INC) $(DEFS) \ $(CXX) $(CXXFLAGS) $(SDLFLAGS) $(INC) $(DEFS) \
$(EMU_MAIN) -o $@ $(LIBS) $(EMU_MAIN) -o $@ $(LIBS)
+102 -19
View File
@@ -1,29 +1,74 @@
# T-Deck Emulator-Only Template # T-Deck Emulator-Only Template
A minimal, self-contained SDL3 emulator template for prototyping 320x240 A minimal, self-contained SDL3 emulator template for prototyping 320x240
graphics/engine experiments without any hardware. No TFT_eSPI, no SPI, graphics/engine experiments without any hardware — with a ready-made
no I2S, no GPIO — just SDL3 and a framebuffer. firmware twin so the same code can be benchmarked on the real T-Deck.
No TFT_eSPI, no SPI, no I2S, no GPIO on the desktop side — just SDL3
and a framebuffer.
## The color contract (RGB565, panel wire order)
The T-Deck's ST7789 panel receives 16-bit RGB565 pixels **high byte
first** over SPI, and on hardware your framebuffer is pushed raw. So
the emulator's contract matches the panel exactly:
- render into `emuGfx::fb565[]` — 320x240 `uint16_t`, RGB565 in **panel
wire order** (big-endian: store `wire565(c)`, a byte swap)
- build colors with `rgb565(r, g, b)` (5/6/5 channels)
- set `emuGfx::dirty = true` when a frame is ready
The host expands 565 → 8888 for the desktop window only. On the device
that step doesn't exist — the buffer goes to the panel as-is. Anything
you see in the emulator, including 5-bit color banding, is what the
panel would show.
**Why wire order:** `TFT_eSprite`'s own primitives store colors
byte-swapped (`drawPixel`: `color = color>>8 | color<<8`) because
`pushSprite` sends the buffer raw. If your software rasterizer writes
native little-endian values into a hardware sprite buffer, colors show
up byte-swapped on the panel while the emulator looks fine. Storing in
wire order from day one makes that bug impossible.
## Sketch structure (for hardware-testable demos)
```
examples/$(APP)/$(APP)Core.h <- all rendering + logic. Device-agnostic:
no shim, no SDL, no Arduino. Renders
RGB565 (wire order) into a caller-
supplied buffer.
examples/$(APP)/$(APP).cpp <- thin emulator shell: keyboard pump,
delta time, set dirty.
fw/$(APP)HW.ino <- firmware twin (copy of DemoHW.ino):
TFT_eSprite + free-running fps report.
```
The bundled sample implements exactly this split. Because the core is
shared 1:1, whatever fps the hardware reports is the fps of exactly
your code.
## Creating a new demo (the only thing you need to do) ## Creating a new demo (the only thing you need to do)
1. Copy this whole folder and give it your demo's name. 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 2. Put your rendering + logic in `examples/Demo/DemoCore.h` (keep the
and folder name `Demo`, or rename both and pass `APP=YourName` to make). file and folder name `Demo`, or rename both and pass `APP=YourName`
3. Your sketch must provide `setup()` and `loop()` and may use: to make).
3. The core's API contract (mirrored by the twin in `fw/`):
- `demoInit(uint16_t *fb)` — receive the 320x240 RGB565 buffer
- `demoInput(uint8_t key)` — one ASCII key (`0x1b` = ESC)
- `demoQuitRequested()` — ask the host to exit
- `demoFrame(float dt, unsigned long nowMs)` — simulate + render
4. The shell (`examples/Demo/Demo.cpp`) may use:
- `millis()`, `delay()`, `random()`, `randomSeed()` — timing/randomness - `millis()`, `delay()`, `random()`, `randomSeed()` — timing/randomness
- `emuGfx::fb[320*240]` — 320x240 ABGR8888 framebuffer (`uint32_t` pixels) - `emuGfx::fb565[320*240]` — the RGB565 buffer (wire order)
- `emuGfx::dirty = true` — set this every frame you want presented - `emuGfx::dirty = true` — set this every frame you want presented
- `emu::keyboard` — ASCII key queue (`' '`, `'a'`…, `0x08` backspace) - `emu::keyboard` — ASCII key queue (`' '`, `'a'`…, `0x08` backspace)
- `pinMode()`/`digitalRead()` — stubs, idle HIGH - `pinMode()`/`digitalRead()` — stubs, idle HIGH
That is the whole contract. The bundled `Demo.cpp` shows it with a **Do not** edit `src/main.cpp`, `shim.h`, or the Makefile — they are
bouncing box — use it as a starting skeleton or delete everything in it. the host and are app-agnostic. Do not leave references to the bundled
demo in your sketch.
**Do not** edit `src/main.cpp`, `shim.h`, or the Makefile — they are the ## Build & Run (emulator)
host and are app-agnostic. Do not leave references to the bundled demo
in your sketch.
## Build & Run
```bash ```bash
make run # builds examples/$(APP)/$(APP).cpp and opens a window make run # builds examples/$(APP)/$(APP).cpp and opens a window
@@ -32,6 +77,34 @@ make smoke # headless: 240 frames, dumps smoke_frame.bmp
make clean # removes the built binary make clean # removes the built binary
``` ```
## On the real T-Deck (ESP32-S3) — free-running benchmark
The `fw/` scaffold drives the same core on the hardware, drawing
straight into a `TFT_eSprite`'s `frameBuffer()` (16-bit RGB565, PSRAM —
the same full-frame pipeline as NetDeck's M1 anti-flicker pattern) and
presenting with `startWrite()/pushSprite(0,0)/endWrite()`.
The loop is deliberately **free-running** — no pacing — and prints a
report over USB serial every 2 s:
```
DemoHW: 120 frames in 2001ms = 60.0 fps | render 12.3 ms, push 14.8 ms
```
`render` is your core's rasterizer; `push` is the SPI transfer to the
panel (at 80 MHz a full 320x240 frame costs ~15 ms — that is the
physical floor for full-frame 30 fps).
```bash
pio run -d emulator-template/fw -t upload # flash the T-Deck
pio device monitor # 115200 baud
```
(`fw/platformio.ini` points at the repo's shared `boards/`, `lib/` and
the T-Deck pin map in `src/netdeck` — NetDeck's own builds are
untouched. Rename the demo: adjust `[env:DemoHW]`'s `-I` and the
`demo::` calls in the .ino.)
## Safety hatch ## Safety hatch
By default the emulator **exits automatically after 10 seconds** so a By default the emulator **exits automatically after 10 seconds** so a
@@ -50,6 +123,11 @@ make smoke # 240 frames -> smoke_frame.bmp
./Demo-emu --dump shot.bmp # dump the last frame to a BMP ./Demo-emu --dump shot.bmp # dump the last frame to a BMP
``` ```
Note: `--dump` fires when the run ends — via `--frames N` completing or
the safety hatch exiting. A run longer than the default 10 s hatch needs
`--timeout` raised (e.g. `--frames 900 --timeout 20000`), or the hatch
cuts it short.
## CLI options ## CLI options
| Flag | Description | | Flag | Description |
@@ -64,12 +142,16 @@ make smoke # 240 frames -> smoke_frame.bmp
``` ```
emulator-template/ emulator-template/
├── README.md # This file ├── README.md # This file
├── shim.h # Minimal Arduino API shim (millis, random, String…) ├── shim.h # Minimal Arduino API shim (millis, random, rgb565…)
├── src/ ├── src/
│ └── main.cpp # SDL3 host loop — window, framebuffer, setup()/loop() │ └── main.cpp # SDL3 host loop — window, 565→8888 expand, setup()/loop()
├── examples/ ├── examples/
│ └── Demo/ │ └── Demo/
│ └── Demo.cpp # ← your sketch goes here │ ├── DemoCore.h # ← your rendering + logic (device-agnostic)
│ └── Demo.cpp # ← emulator shell
├── fw/
│ ├── platformio.ini # Hardware twin project (shared boards/lib)
│ └── DemoHW.ino # T-Deck firmware with fps report
├── Makefile # Self-contained build — just `make run` ├── Makefile # Self-contained build — just `make run`
└── .gitignore # ignores built binaries and captured frames └── .gitignore # ignores built binaries and captured frames
``` ```
@@ -78,9 +160,10 @@ emulator-template/
The Makefile's single rule compiles `src/main.cpp` together with The Makefile's single rule compiles `src/main.cpp` together with
`examples/$(APP)/$(APP).cpp` as **one translation unit** (the Makefile `examples/$(APP)/$(APP).cpp` as **one translation unit** (the Makefile
passes the path as `-DAPP_SRC=…`, which main.cpp `#include`s). The sketch's passes the path as `-DAPP_SRC=…`, which main.cpp `#include`s). The
`setup()`/`loop()` are called directly; each frame it writes pixels into sketch's `setup()`/`loop()` are called directly; each frame it writes
`emuGfx::fb[]`, and the host presents the framebuffer via SDL3. RGB565 pixels into `emuGfx::fb565[]`, the host expands them to 8888 and
presents via SDL3.
## License ## License
+20 -34
View File
@@ -1,10 +1,15 @@
/** /**
* Demo sketch — replace this file with your own experiment. * Demo sketch — replace this file with your own experiment.
* *
* This is the EMULATOR SHELL only. The actual demo lives in DemoCore.h
* (device-agnostic: RGB565 in panel wire order) so the same core can be
* driven by the firmware twin in fw/DemoHW.ino for hardware benchmarks.
*
* Contract with the emulator host (src/main.cpp): * Contract with the emulator host (src/main.cpp):
* - implement setup() — called once at launch * - implement setup() — called once at launch
* - implement loop() — called once per frame (host paces at ~60 fps) * - implement loop() — called once per frame (host paces at ~60 fps)
* - write pixels into emuGfx::fb[] (320x240, ABGR8888 uint32) * - the host provides emuGfx::fb565[] (320x240, RGB565 in panel wire
* order) — render into it, or hand your own buffer to the core
* - set emuGfx::dirty = true each frame you want presented * - set emuGfx::dirty = true each frame you want presented
* - read keys from emu::keyboard (ASCII queue, filled from SDL events) * - read keys from emu::keyboard (ASCII queue, filled from SDL events)
* *
@@ -18,56 +23,37 @@
*/ */
#include "shim.h" #include "shim.h"
#include "DemoCore.h"
// Emulator state provided by the host (src/main.cpp) // Emulator state provided by the host (src/main.cpp)
extern uint32_t emuGfx::fb[320 * 240]; extern uint16_t emuGfx::fb565[320 * 240];
extern bool emuGfx::dirty; extern bool emuGfx::dirty;
extern std::deque<uint8_t> emu::keyboard; extern std::deque<uint8_t> emu::keyboard;
static constexpr int W = 320;
static constexpr int H = 240;
// --- Demo state -----------------------------------------------------------
static float boxX = 40, boxY = 30;
static float velX = 100.0f, velY = 70.0f; // pixels per second
static unsigned long lastMs = 0;
static constexpr float BOX = 24.0f;
void setup() void setup()
{ {
randomSeed(millis()); demo::demoInit(emuGfx::fb565);
velX = 60.0f + random(100) * 1.2f; // 60..180 px/s
velY = 60.0f + random(100) * 1.2f;
} }
void loop() void loop()
{ {
// Keyboard pump
while (!emu::keyboard.empty()) {
uint8_t k = emu::keyboard.front();
emu::keyboard.pop_front();
demo::demoInput(k);
}
// Delta time: seconds since the previous frame. // Delta time: seconds since the previous frame.
static unsigned long lastMs = 0;
unsigned long now = millis(); unsigned long now = millis();
float dt = lastMs ? (now - lastMs) / 1000.0f : 1.0f / 60.0f; float dt = lastMs ? (now - lastMs) / 1000.0f : 1.0f / 60.0f;
lastMs = now; lastMs = now;
if (dt > 0.1f) dt = 0.1f; // clamp after stalls (drag, breakpoint) if (dt > 0.1f) dt = 0.1f; // clamp after stalls (drag, breakpoint)
// Move and bounce // Render one frame into the 565 buffer
boxX += velX * dt; demo::demoFrame(dt, now);
boxY += velY * dt;
if (boxX < 0 || boxX + BOX > W) { velX = -velX; boxX += velX * dt; }
if (boxY < 0 || boxY + BOX > H) { velY = -velY; boxY += velY * dt; }
// Clear the framebuffer (opaque black, alpha = 0xFF) // Present: the host expands 565 -> 8888 for the desktop window
for (int i = 0; i < W * H; i++) emuGfx::fb[i] = 0xFF000000;
// Draw a filled box with a color that drifts over time
uint8_t r = (uint8_t)(128 + 127 * sinf(millis() / 900.0f));
uint32_t color = 0xFF000000u | ((uint32_t)r << 16) | 0x0000CC66u;
for (int y = (int)boxY; y < (int)(boxY + BOX); y++) {
if (y < 0 || y >= H) continue;
for (int x = (int)boxX; x < (int)(boxX + BOX); x++) {
if (x < 0 || x >= W) continue;
emuGfx::fb[y * W + x] = color;
}
}
// Present the frame
emuGfx::dirty = true; emuGfx::dirty = true;
} }
@@ -0,0 +1,94 @@
/**
* DemoCore — the device-agnostic part of the bundled sample demo.
*
* This is the recommended structure for template sketches that will also
* run on real hardware:
*
* examples/$(APP)/$(APP)Core.h <- THIS FILE: all rendering + logic.
* Device-agnostic: no shim, no SDL,
* no Arduino. Renders RGB565 in
* panel wire order into a buffer the
* owner supplies.
* examples/$(APP)/$(APP).cpp <- thin emulator shell (keyboard, dt)
* fw/$(APP)HW.ino <- firmware twin (TFT_eSprite + fps report)
*
* Because the core is shared 1:1, whatever fps the hardware reports is
* the fps of exactly this code.
*
* COLOR CONTRACT: the buffer holds 16-bit RGB565 pixels in PANEL WIRE
* ORDER — big-endian, i.e. the byte sequence the ST7789 receives over
* SPI. On hardware the buffer IS the TFT_eSprite payload pushed raw.
* Store every pixel through wire565() or you will see byte-swapped
* colors on the panel while the emulator looks fine.
*/
#pragma once
#include <cstdint>
#include <cstdlib>
#include <cmath>
namespace demo {
static constexpr int W = 320;
static constexpr int H = 240;
static uint16_t *g_fb = nullptr;
// --- RGB565 helpers (also in shim.h for shell-side use) ----------------------
static inline uint16_t rgb565(int r, int g, int b) {
return (uint16_t)(((r & 31) << 11) | ((g & 63) << 5) | (b & 31));
}
// Panel wire order: the ST7789 receives the high byte first, and the
// sprite/push path sends buffer bytes raw — so store byteswapped values.
static inline uint16_t wire565(uint16_t c) {
return (uint16_t)((c << 8) | (c >> 8));
}
// --- Demo state --------------------------------------------------------------
static float boxX = 40, boxY = 30;
static float velX = 100.0f, velY = 70.0f; // pixels per second
static constexpr float BOX = 24.0f;
static bool quitRequested = false;
// --- Public API ---------------------------------------------------------------
static inline void demoInit(uint16_t *fb) {
g_fb = fb;
velX = 60.0f + (rand() % 100) * 1.2f;
velY = 60.0f + (rand() % 100) * 1.2f;
}
static inline void demoInput(uint8_t k) {
if (k == 'q' || k == 0x1b) quitRequested = true;
}
static inline bool demoQuitRequested() { return quitRequested; }
static void demoFrame(float dt, unsigned long nowMs) {
// Move and bounce
boxX += velX * dt;
boxY += velY * dt;
if (boxX < 0 || boxX + BOX > W) { velX = -velX; boxX += velX * dt; }
if (boxY < 0 || boxY + BOX > H) { velY = -velY; boxY += velY * dt; }
// Clear (dark 565 background, stored in wire order)
{
uint16_t bg = wire565(rgb565(2, 2, 6));
for (int i = 0; i < W * H; i++) g_fb[i] = bg;
}
// Draw a filled box with a color that drifts over time (5-bit quantized —
// the banding is what the real panel shows)
uint16_t color = rgb565((int)(16 + 15 * sinf(nowMs / 900.0f)) & 31,
24, 12);
uint16_t wcolor = wire565(color);
for (int y = (int)boxY; y < (int)(boxY + BOX); y++) {
if (y < 0 || y >= H) continue;
for (int x = (int)boxX; x < (int)(boxX + BOX); x++) {
if (x < 0 || x >= W) continue;
g_fb[y * W + x] = wcolor;
}
}
}
} // namespace demo
+117
View File
@@ -0,0 +1,117 @@
/**
* DemoHW — the template's bundled demo on the real T-Deck
* (ESP32-S3 + ST7789), with frame-time instrumentation.
*
* Firmware twin of the emulator sketch (../examples/Demo/Demo.cpp).
* Both drive the same device-agnostic DemoCore.h, which renders the
* whole scene in RGB565 (panel wire order) into a single 320x240
* buffer. Here that buffer IS a TFT_eSprite's frameBuffer() — the core
* writes straight into the sprite, and the sprite is pushed with the
* proven NetDeck M1 anti-flicker pattern.
*
* Build & flash (from the repo root):
* pio run -d emulator-template/fw -t upload
* pio device monitor # 115200 baud
*
* The loop is deliberately free-running: the serial report every 2 s is
* the true throughput of the core + SPI push on this hardware.
*/
#include <Arduino.h>
#include <SPI.h>
#include <TFT_eSPI.h>
#include "utilities.h"
#include "DemoCore.h"
TFT_eSPI tft;
static TFT_eSprite fb(&tft); // full-frame 320x240x16 buffer (PSRAM)
// --- frame-time accounting ---------------------------------------------------
static uint32_t accRenderUs = 0;
static uint32_t accPushUs = 0;
static uint32_t accFrames = 0;
static uint32_t reportT0 = 0;
void setup()
{
Serial.begin(115200);
Serial.println();
Serial.println("DemoHW — emulator-template demo on real T-Deck (RGB565)");
Serial.println("Free-running benchmark: report every 2 s over USB serial.");
// Proven T-Deck bring-up (same sequence as NetDeck.ino hardwareInit)
pinMode(BOARD_POWERON, OUTPUT);
digitalWrite(BOARD_POWERON, HIGH);
pinMode(BOARD_SDCARD_CS, OUTPUT);
pinMode(RADIO_CS_PIN, OUTPUT);
pinMode(BOARD_TFT_CS, OUTPUT);
digitalWrite(BOARD_SDCARD_CS, HIGH);
digitalWrite(RADIO_CS_PIN, HIGH);
digitalWrite(BOARD_TFT_CS, HIGH);
pinMode(BOARD_SPI_MISO, INPUT_PULLUP);
SPI.begin(BOARD_SPI_SCK, BOARD_SPI_MISO, BOARD_SPI_MOSI);
tft.begin();
tft.setRotation(1); // 320x240 landscape
tft.fillScreen(TFT_BLACK);
pinMode(BOARD_BL_PIN, OUTPUT);
digitalWrite(BOARD_BL_PIN, HIGH);
// Full-frame 16-bit sprite; the core draws directly into its buffer.
fb.setColorDepth(16);
if (!fb.createSprite(320, 240)) {
Serial.println("DemoHW: framebuffer alloc failed (stopping)");
while (true) delay(1000);
}
uint16_t *buf = (uint16_t *)fb.frameBuffer(0);
if (!buf) {
Serial.println("DemoHW: frameBuffer() unavailable (stopping)");
while (true) delay(1000);
}
demo::demoInit(buf);
reportT0 = millis();
}
void loop()
{
static uint32_t lastUs = 0;
uint32_t t0 = micros();
// Delta time from real elapsed time — motion speed stays correct no
// matter the achieved fps.
float dt = lastUs ? (t0 - lastUs) / 1e6f : 1.0f / 60.0f;
lastUs = t0;
if (dt > 0.1f) dt = 0.1f;
demo::demoFrame(dt, millis());
uint32_t renderUs = micros() - t0;
// Panel push: the M1 anti-flicker pattern (NetDeck.ino present()).
uint32_t p0 = micros();
tft.startWrite();
fb.pushSprite(0, 0);
tft.endWrite();
uint32_t pushUs = micros() - p0;
// --- accounting ---
accRenderUs += renderUs;
accPushUs += pushUs;
accFrames++;
uint32_t elapsed = millis() - reportT0;
if (elapsed >= 2000) {
float fps = accFrames * 1000.0f / elapsed;
float avgRender = accFrames ? accRenderUs / (float)accFrames / 1000.0f : 0.0f;
float avgPush = accFrames ? accPushUs / (float)accFrames / 1000.0f : 0.0f;
Serial.printf("DemoHW: %lu frames in %lu ms = %.1f fps | "
"render %.1f ms, push %.1f ms\n",
(unsigned long)accFrames, (unsigned long)elapsed, fps,
avgRender, avgPush);
reportT0 = millis();
accRenderUs = accPushUs = accFrames = 0;
}
}
+37
View File
@@ -0,0 +1,37 @@
; PlatformIO project for running the template demo on the real T-Deck
; (ESP32-S3 + ST7789) as a free-running benchmark.
;
; Standalone on purpose (the repo's top-level platformio.ini keeps
; src_dir = src/netdeck for NetDeck): this points back at the shared
; boards/ and lib/ directories.
;
; pio run -d emulator-template/fw -t upload # flash the T-Deck
; pio device monitor # fps report every 2 s
;
; The loop free-runs (no pacing); the serial report's render/push split
; is the true throughput of the sketch core + SPI push on the hardware.
[platformio]
default_envs = DemoHW
src_dir = .
boards_dir = ../../boards
lib_dir = ../../lib
[env:DemoHW]
platform = espressif32@6.3.0
board = T-Deck
framework = arduino
upload_speed = 921600
monitor_speed = 115200
build_flags =
-DBOARD_HAS_PSRAM=1
-DCORE_DEBUG_LEVEL=1
-DARDUINO_USB_CDC_ON_BOOT=1
-DDISABLE_ALL_LIBRARY_WARNINGS
-DSPI_FREQUENCY=80000000
; -O2: PlatformIO's default -Os optimizes for size and can cost a
; large fraction of frame time — benchmarks deserve the honest number.
-O2
-I../examples/Demo
; T-Deck pin map (BOARD_POWERON, TFT pins...) from the firmware tree
-I../../src/netdeck
+16
View File
@@ -77,6 +77,22 @@ inline uint32_t esp_random()
return ((uint32_t)std::rand() << 17) ^ (uint32_t)std::rand() ^ millis(); return ((uint32_t)std::rand() << 17) ^ (uint32_t)std::rand() ^ millis();
} }
// ---------------------------------------------------------------------------
// RGB565 helpers — the panel-facing color format of the T-Deck's ST7789.
// The emulator framebuffer contract is RGB565 in PANEL WIRE ORDER
// (big-endian): see README "The color contract". Use rgb565() to build
// colors and wire565() before storing a pixel into the framebuffer.
// ---------------------------------------------------------------------------
inline uint16_t rgb565(uint32_t r, uint32_t g, uint32_t b)
{
return (uint16_t)(((r & 31) << 11) | ((g & 63) << 5) | (b & 31));
}
inline uint16_t wire565(uint16_t c)
{
return (uint16_t)((c << 8) | (c >> 8));
}
// --------------------------------------------------------------------------- // ---------------------------------------------------------------------------
// Minimal String class (Arduino-style) // Minimal String class (Arduino-style)
// --------------------------------------------------------------------------- // ---------------------------------------------------------------------------
+51 -41
View File
@@ -5,7 +5,18 @@
* and calls the user's sketch setup() / loop() each frame. * and calls the user's sketch setup() / loop() each frame.
* *
* This file is deliberately hardware-free: no TFT_eSPI, no SPI, * This file is deliberately hardware-free: no TFT_eSPI, no SPI,
* no I2S, no GPIO matrix. It only depends on SDL3 and the shim. * no I2S, no GPIO. It only depends on SDL3 and the shim.
*
* COLOR CONTRACT (matches the real T-Deck panel pipeline): the sketch
* renders into emuGfx::fb565 — a 320x240 buffer of 16-bit RGB565 pixels
* held in PANEL WIRE ORDER (big-endian: each pixel's high byte is what
* the ST7789 receives first over SPI; the same convention TFT_eSprite's
* own primitives use on hardware). The host expands 565 -> 8888 for the
* desktop window only. On the device the 565 buffer is pushed as-is, so
* anything you see here is exactly what the panel would show — including
* 5-bit color banding. Sketches that ignore this and write native
* little-endian values will render byte-swapped on hardware even though
* they look right in the emulator.
*/ */
#include <SDL3/SDL.h> #include <SDL3/SDL.h>
@@ -24,7 +35,7 @@
#include "shim.h" #include "shim.h"
// --- Emulator shared state (defined in main.cpp below) --- // --- Emulator shared state (defined in main.cpp below) ---
// The sketch writes to emuGfx::fb; this file presents it each frame. // The sketch writes to emuGfx::fb565; this file presents it each frame.
// --------------------------------------------------------------------------- // ---------------------------------------------------------------------------
namespace emu { namespace emu {
uint8_t pinLevels[64]; uint8_t pinLevels[64];
@@ -37,11 +48,26 @@ namespace emu {
} // namespace emu } // namespace emu
namespace emuGfx { namespace emuGfx {
uint32_t fb[320 * 240]; // ABGR8888 pixels, 320x240 uint16_t fb565[320 * 240]; // RGB565, panel wire order — THE sketch target
uint32_t fb[320 * 240]; // ABGR8888 staging for SDL (host-internal)
SDL_Texture *tex = nullptr; SDL_Texture *tex = nullptr;
bool dirty = true; bool dirty = true;
} // namespace emuGfx } // namespace emuGfx
// Expand the 565 wire-order buffer into the 8888 staging buffer.
// Wire order = big-endian 565: unswap, then replicate 5/6/5 -> 8/8/8 bits.
static void expand565()
{
for (int i = 0; i < 320 * 240; i++) {
uint16_t c = (uint16_t)((emuGfx::fb565[i] << 8) | (emuGfx::fb565[i] >> 8));
uint32_t r5 = (c >> 11) & 31, g6 = (c >> 5) & 63, b5 = c & 31;
uint32_t r = (r5 << 3) | (r5 >> 2);
uint32_t g = (g6 << 2) | (g6 >> 4);
uint32_t b = (b5 << 3) | (b5 >> 2);
emuGfx::fb[i] = 0xFF000000u | (b << 16) | (g << 8) | r;
}
}
// --- Forward declarations of the user's sketch functions --- // --- Forward declarations of the user's sketch functions ---
// These will be defined in the sketch .cpp file included below. // These will be defined in the sketch .cpp file included below.
extern "C" void setup(); extern "C" void setup();
@@ -56,6 +82,22 @@ extern "C" void loop();
#include APP_SRC #include APP_SRC
// --------------------------------------------------------------------------- // ---------------------------------------------------------------------------
// Save the current frame (after 565 expansion) as a BMP.
static void dumpFrame(const char *path)
{
if (!path) return;
expand565();
SDL_Surface *s = SDL_CreateSurface(320, 240, SDL_PIXELFORMAT_ABGR8888);
if (!s) return;
Uint32 *sp = (Uint32 *)s->pixels;
for (int y = 0; y < 240; y++) {
memcpy(sp + y * s->w, emuGfx::fb + y * 320, 320 * sizeof(Uint32));
}
SDL_SaveBMP(s, path);
SDL_DestroySurface(s);
std::printf("[emu] frame dumped to %s\n", path);
}
// --- Main entry point --- // --- Main entry point ---
int main(int argc, char **argv) int main(int argc, char **argv)
{ {
@@ -155,6 +197,7 @@ int main(int argc, char **argv)
if (!userRun && timeoutMs > 0 && millis() >= (unsigned long)timeoutMs) { if (!userRun && timeoutMs > 0 && millis() >= (unsigned long)timeoutMs) {
std::printf("[emu] safety hatch: exiting after %ld ms " std::printf("[emu] safety hatch: exiting after %ld ms "
"(pass --user-run to run indefinitely)\n", timeoutMs); "(pass --user-run to run indefinitely)\n", timeoutMs);
dumpFrame(dumpPath);
running = false; running = false;
break; break;
} }
@@ -164,8 +207,9 @@ int main(int argc, char **argv)
// --- Present frame if dirty --- // --- Present frame if dirty ---
if (emuGfx::dirty) { if (emuGfx::dirty) {
expand565();
SDL_UpdateTexture(emuGfx::tex, nullptr, emuGfx::fb, SDL_UpdateTexture(emuGfx::tex, nullptr, emuGfx::fb,
320 * sizeof(uint32_t)); 320 * sizeof(uint32_t));
emuGfx::dirty = false; emuGfx::dirty = false;
} }
@@ -177,26 +221,7 @@ int main(int argc, char **argv)
// --- Frame counting / dump --- // --- Frame counting / dump ---
if (maxFrames > 0 && --maxFrames == 0) { if (maxFrames > 0 && --maxFrames == 0) {
running = false; running = false;
if (dumpPath) { dumpFrame(dumpPath);
// Create a surface from the texture and save as BMP
SDL_Surface *s = SDL_CreateSurface(320, 240, SDL_PIXELFORMAT_ABGR8888);
if (s) {
// Read pixels from the texture
void *pixels;
int pitch;
SDL_LockTexture(emuGfx::tex, nullptr, &pixels, &pitch);
// Copy the framebuffer directly to the surface
Uint32 *sp = (Uint32 *)s->pixels;
for (int y = 0; y < 240; y++) {
memcpy(sp + y * s->w, emuGfx::fb + y * 320, 320 * sizeof(Uint32));
}
SDL_UnlockTexture(emuGfx::tex);
SDL_SaveBMP(s, dumpPath);
SDL_DestroySurface(s);
std::printf("[emu] frame dumped to %s\n", dumpPath);
}
}
} }
// --- Frame pacing: sleep until the next 60 Hz tick --- // --- Frame pacing: sleep until the next 60 Hz tick ---
@@ -213,22 +238,7 @@ int main(int argc, char **argv)
} }
// --- Save last frame as BMP for AI inspection --- // --- Save last frame as BMP for AI inspection ---
{ dumpFrame("frame.bmp");
SDL_Surface *s = SDL_CreateSurface(320, 240, SDL_PIXELFORMAT_ABGR8888);
if (s) {
void *pixels;
int pitch;
SDL_LockTexture(emuGfx::tex, nullptr, &pixels, &pitch);
Uint32 *sp = (Uint32 *)s->pixels;
for (int y = 0; y < 240; y++) {
memcpy(sp + y * s->w, emuGfx::fb + y * 320, 320 * sizeof(Uint32));
}
SDL_UnlockTexture(emuGfx::tex);
SDL_SaveBMP(s, "frame.bmp");
SDL_DestroySurface(s);
std::printf("[emu] last frame saved to frame.bmp\n");
}
}
// --- Cleanup --- // --- Cleanup ---
TTF_Quit(); TTF_Quit();
@@ -237,4 +247,4 @@ int main(int argc, char **argv)
SDL_DestroyWindow(win); SDL_DestroyWindow(win);
SDL_Quit(); SDL_Quit();
return 0; return 0;
} }