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
+20 -34
View File
@@ -1,10 +1,15 @@
/**
* 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):
* - implement setup() — called once at launch
* - 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
* - read keys from emu::keyboard (ASCII queue, filled from SDL events)
*
@@ -18,56 +23,37 @@
*/
#include "shim.h"
#include "DemoCore.h"
// 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 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()
{
randomSeed(millis());
velX = 60.0f + random(100) * 1.2f; // 60..180 px/s
velY = 60.0f + random(100) * 1.2f;
demo::demoInit(emuGfx::fb565);
}
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.
static unsigned long lastMs = 0;
unsigned long now = millis();
float dt = lastMs ? (now - lastMs) / 1000.0f : 1.0f / 60.0f;
lastMs = now;
if (dt > 0.1f) dt = 0.1f; // clamp after stalls (drag, breakpoint)
// 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; }
// Render one frame into the 565 buffer
demo::demoFrame(dt, now);
// Clear the framebuffer (opaque black, alpha = 0xFF)
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
// Present: the host expands 565 -> 8888 for the desktop window
emuGfx::dirty = true;
}