Files
lilygo-t-deck/emulator-template/shim.h
T
Dejvino c58f31d02c 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).
2026-11-16 22:51:44 +01:00

169 lines
6.2 KiB
C++

/**
* Minimal emulator shim — provides only the subset of Arduino API needed
* for graphics/engine prototypes running on the SDL3 emulator.
*
* Include this single header in your sketch:
* #include "shim.h"
*
* The template's main.cpp includes this file and sets up the emulated state.
* This header defines: millis(), random(), randomSeed(), String, and basic
* type definitions. No GPIO, no interrupts, no peripheral dependencies.
*/
#pragma once
#include <cstdint>
#include <cstddef>
#include <cstdio>
#include <cstdlib>
#include <cstring>
#include <cmath>
#include <cctype>
#include <string>
#include <deque>
#include <thread> // for std::this_thread::sleep_for
#include <chrono> // for std::chrono::milliseconds, microseconds
// ---------------------------------------------------------------------------
// Platform marker: the sketch can #ifdef EMULATOR for emulator-only code
// ---------------------------------------------------------------------------
#define EMULATOR 1
// ---------------------------------------------------------------------------
// Flash-resident data macros (no-op on emulator; flash-mapped memory)
// ---------------------------------------------------------------------------
#define PROGMEM
#define pgm_read_byte(addr) (*(const unsigned char *)(addr))
#define pgm_read_word(addr) (*(const unsigned short *)(addr))
#define pgm_read_dword(addr) (*(const unsigned long *)(addr))
// ---------------------------------------------------------------------------
// Time
// ---------------------------------------------------------------------------
inline unsigned long millis()
{
using namespace std::chrono;
static const auto start = steady_clock::now();
return (unsigned long)duration_cast<milliseconds>(steady_clock::now() - start).count();
}
inline unsigned long micros()
{
using namespace std::chrono;
static const auto start = steady_clock::now();
return (unsigned long)duration_cast<microseconds>(steady_clock::now() - start).count();
}
inline void delay(unsigned long ms)
{
std::this_thread::sleep_for(std::chrono::milliseconds(ms));
}
inline void delayMicroseconds(unsigned int us)
{
std::this_thread::sleep_for(std::chrono::microseconds(us));
}
// ---------------------------------------------------------------------------
// Random (Arduino-style)
// ---------------------------------------------------------------------------
inline long random(long maxv) { return maxv > 0 ? std::rand() % maxv : 0; }
inline long random(long lo, long hi) { return hi > lo ? lo + std::rand() % (hi - lo) : lo; }
inline void randomSeed(unsigned long seed) { std::srand((unsigned)seed); }
// Emulated esp_random (used by some sketches)
inline uint32_t esp_random()
{
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)
// ---------------------------------------------------------------------------
class String {
public:
std::string s;
String() {}
String(const char *c) : s(c) {}
String(const std::string &x) : s(x) {}
String(char c) : s(1, c) {}
String(int v) : s(std::to_string(v)) {}
String(long v) : s(std::to_string(v)) {}
String(unsigned v) : s(std::to_string(v)) {}
String(unsigned long v) : s(std::to_string(v)) {}
String(float v) : s(std::to_string(v)) {}
const char *c_str() const { return s.c_str(); }
unsigned length() const { return (unsigned)s.length(); }
};
inline String operator+(const String &a, const String &b) { return String(a.s + b.s); }
inline String operator+(const String &a, const char *b) { return String(a.s + b); }
inline String operator+(const char *a, const String &b) { return String(std::string(a) + b.s); }
// -------------------------------------------------------------------------//
// Minimal GPIO — emulated pin levels (idle HIGH). Access via
// emu::pinLevels in the main.cpp; this shim provides a safe read API.
// For the template's purposes, users should use the emu::keyboard queue
// for input instead of raw GPIO reads.
// -------------------------------------------------------------------------//
#define INPUT 0
#define OUTPUT 1
#define INPUT_PULLUP 2
#define HIGH 1
#define LOW 0
inline void pinMode(int, int) {} // no-op in emulator
inline int digitalRead(int pin)
{
(void)pin;
return 1; // idle HIGH
}
inline void digitalWrite(int, int) {}
// Pin edge structure — used by the emulator's ISR dispatch logic.
struct PinEdge { int pin, from, to; };
// -------------------------------------------------------------------------//
// Serial simulation (minimal)
// -------------------------------------------------------------------------//
struct SerialSim {
std::deque<std::string> *sink = nullptr;
void capture(const char *s)
{
if (!sink) return;
sink->push_back(s);
while (sink->size() > 512) sink->pop_front();
}
template <typename... A> void printf(const char *fmt, A... a)
{
char buf[512];
std::snprintf(buf, sizeof(buf), fmt, a...);
std::fputs(buf, stdout);
capture(buf);
}
void println() { std::printf("\n"); capture("\n"); }
void println(const char *s) { std::printf("%s\n", s); capture(s); capture("\n"); }
void println(const String &s) { std::printf("%s\n", s.c_str()); capture(s.c_str()); capture("\n"); }
void println(int v) { std::printf("%d\n", v); capture(std::to_string(v).c_str()); capture("\n"); }
};
// External instance — the emulator main.cpp defines this.
extern SerialSim Serial;