Emulator: migrate SDL2 -> SDL3

Port the shared emulator harness (all apps) to SDL 3.4 + SDL3_ttf 3.2:
- window creation without position args; renderer logical size via
  SDL_SetRenderLogicalPresentation(LETTERBOX); SDL_RenderTexture;
  SDL_SaveBMP_IO frame dumps
- SDL_EVENT_* event scheme, flattened SDL_KeyboardEvent, float mouse
  coords; clicks mapped with SDL_ConvertEventToRenderCoordinates, keeping
  the Xwayland global-state cross-check from 260a2b3
- audio shim on the stream API (SDL_OpenAudioDeviceStream +
  SDL_PutAudioStreamData) since SDL_QueueAudio is gone
- TTF_RenderText_Blended (explicit length); SDL3_ttf header layout
  handled via __has_include (Ubuntu installs under SDL3_ttf/)
- e2e freeze-tint pixel assertions updated to the committed
  diagonal-stripe pattern (stale since the freeze rework; pre-existing
  failures at HEAD under SDL2), sampled away from the freeze text

Full suite green: 14 unit + 7 integration + 3 E2E journeys, 0 failures.
MissileCommand, MiataDrive, NetDeck build; CrtTerminal (missing sndBlip
declaration) and Lotus3 (sketch not in repo) fail identically at HEAD -
pre-existing, out of scope.
This commit is contained in:
Dejvino
2026-11-14 17:03:30 +01:00
parent 260a2b3d0d
commit 21d37486cf
8 changed files with 129 additions and 97 deletions
+3 -3
View File
@@ -1,4 +1,4 @@
# SDL2 emulator for T-Deck example sketches (run the app on your PC)
# SDL3 emulator for T-Deck example sketches (run the app on your PC)
#
# make build the MissileCommand emulator (default)
# make APP=CrtTerminal build the CRT terminal emulator
@@ -38,9 +38,9 @@ APP_TITLE ?= $(APP)
CXX ?= g++
CXXFLAGS ?= -std=gnu++17 -O2 -Wall -Wextra
SDLFLAGS := -I/usr/include/SDL2
SDLFLAGS := $(shell pkg-config --cflags sdl3 sdl3-ttf)
INC := -Isrc/shim -I$(APP_DIR) $(if $(APP_EXTRA_INC),-I$(APP_EXTRA_INC))
LIBS := -lSDL2 -lSDL2_ttf
LIBS := $(shell pkg-config --libs sdl3 sdl3-ttf)
DEFS += -DAPP_INO='"$(APP).ino"' -DAPP_NAME='"$(APP_TITLE)"'
+56 -59
View File
@@ -1,5 +1,5 @@
/**
* SDL2 host for T-Deck example sketches — run the app on your PC.
* SDL3 host for T-Deck example sketches — run the app on your PC.
* The sketch is selected with -DAPP_INO (see the Makefile, APP=...).
*
* Input mapping:
@@ -11,8 +11,12 @@
* Backspace/Delete keyboard device (0x08 / 0x7F)
* --type "text" queue keys programmatically (for smoke tests)
*/
#include <SDL.h>
#include <SDL_ttf.h>
#include <SDL3/SDL.h>
#if __has_include(<SDL3/SDL_ttf.h>) // upstream install layout
#include <SDL3/SDL_ttf.h>
#else // Debian/Ubuntu package layout
#include <SDL3_ttf/SDL_ttf.h>
#endif
#include <cstdio>
#include <cctype>
#include <cstring>
@@ -60,12 +64,16 @@ const FreeFontStub FreeSans12pt7b {0};
static void saveBmp(const char *path)
{
SDL_Surface *s = SDL_CreateRGBSurfaceWithFormatFrom(
emuGfx::fb, emuGfx::W, emuGfx::H, 32, emuGfx::W * 4, SDL_PIXELFORMAT_ABGR8888);
SDL_Surface *s = SDL_CreateSurfaceFrom(
emuGfx::W, emuGfx::H, SDL_PIXELFORMAT_ABGR8888,
emuGfx::fb, emuGfx::W * 4);
if (s) {
SDL_SaveBMP(s, path);
SDL_FreeSurface(s);
std::printf("[emu] frame dumped to %s\n", path);
SDL_IOStream *dst = SDL_IOFromFile(path, "wb");
if (dst) {
SDL_SaveBMP_IO(s, dst, true); // true = close the stream for us
std::printf("[emu] frame dumped to %s\n", path);
}
SDL_DestroySurface(s);
}
}
@@ -119,18 +127,18 @@ int main(int argc, char **argv)
#endif
}
if (SDL_Init(SDL_INIT_VIDEO | SDL_INIT_AUDIO) != 0) {
if (!SDL_Init(SDL_INIT_VIDEO | SDL_INIT_AUDIO)) {
std::printf("SDL_Init failed: %s\n", SDL_GetError());
return 1;
}
TTF_Init();
SDL_Window *win = SDL_CreateWindow("T-Deck emulator — " APP_NAME,
SDL_WINDOWPOS_CENTERED, SDL_WINDOWPOS_CENTERED,
640, 480, SDL_WINDOW_RESIZABLE);
SDL_Renderer *ren = SDL_CreateRenderer(win, -1, SDL_RENDERER_ACCELERATED);
if (!ren) ren = SDL_CreateRenderer(win, -1, 0); // software fallback (headless)
SDL_RenderSetLogicalSize(ren, emuGfx::W, emuGfx::H);
SDL_Renderer *ren = SDL_CreateRenderer(win, NULL);
if (!ren) ren = SDL_CreateRenderer(win, "software"); // fallback (headless)
SDL_SetRenderLogicalPresentation(ren, emuGfx::W, emuGfx::H,
SDL_LOGICAL_PRESENTATION_LETTERBOX);
emuGfx::tex = SDL_CreateTexture(ren, SDL_PIXELFORMAT_ABGR8888,
SDL_TEXTUREACCESS_STREAMING, emuGfx::W, emuGfx::H);
@@ -149,13 +157,13 @@ int main(int argc, char **argv)
SDL_Event e;
while (SDL_PollEvent(&e)) {
switch (e.type) {
case SDL_QUIT:
case SDL_EVENT_QUIT:
running = false;
break;
case SDL_KEYDOWN: {
case SDL_EVENT_KEY_DOWN: {
if (e.key.repeat) break;
SDL_Keycode k = e.key.keysym.sym;
SDL_Keycode k = e.key.key;
switch (k) {
case SDLK_RIGHT: held[0] = true; emu::pinLevels[dirPin[0]] = 0; break;
case SDLK_UP: held[1] = true; emu::pinLevels[dirPin[1]] = 0; break;
@@ -191,8 +199,8 @@ int main(int argc, char **argv)
break;
}
case SDL_KEYUP: {
SDL_Keycode k = e.key.keysym.sym;
case SDL_EVENT_KEY_UP: {
SDL_Keycode k = e.key.key;
switch (k) {
case SDLK_RIGHT: held[0] = false; emu::pinLevels[dirPin[0]] = 1; break;
case SDLK_UP: held[1] = false; emu::pinLevels[dirPin[1]] = 1; break;
@@ -207,71 +215,60 @@ int main(int argc, char **argv)
break;
}
case SDL_MOUSEWHEEL: {
case SDL_EVENT_MOUSE_WHEEL: {
// Each wheel notch = a burst of ball edges on the matching
// direction pin (emitted over the next few iterations).
const int perNotch = 6;
if (e.wheel.y > 0) wheelPulse[1] += perNotch * e.wheel.y; // up
if (e.wheel.y < 0) wheelPulse[3] += perNotch * -e.wheel.y; // down
if (e.wheel.x > 0) wheelPulse[0] += perNotch * e.wheel.x; // right
if (e.wheel.x < 0) wheelPulse[2] += perNotch * -e.wheel.x; // left
if (e.wheel.y > 0) wheelPulse[1] += perNotch * (int)e.wheel.y; // up
if (e.wheel.y < 0) wheelPulse[3] += perNotch * (int)-e.wheel.y; // down
if (e.wheel.x > 0) wheelPulse[0] += perNotch * (int)e.wheel.x; // right
if (e.wheel.x < 0) wheelPulse[2] += perNotch * (int)-e.wheel.x; // left
break;
}
case SDL_MOUSEBUTTONDOWN:
case SDL_MOUSEBUTTONUP: {
// Work out the true window-relative cursor position. Two
// pitfalls to sidestep here:
// 1. SDL_RenderSetLogicalSize letterboxes the 320x240
// surface inside the (resizable) window when it is not
// exactly 4:3, so event coords must be mapped through
// that centered viewport, not scaled against the whole
// window.
// 2. Under Xwayland the X server may deliver pointer event
// coords in a scaled space (observed: exactly half the
// window size on a scaled desktop), so e.button.x/y
// cannot be trusted blindly. Reconstruct the position
// from the global cursor minus the window position
// (raw root coords on X11, unaffected by event scaling)
// and use it when it lands inside the window.
case SDL_EVENT_MOUSE_BUTTON_DOWN:
case SDL_EVENT_MOUSE_BUTTON_UP: {
// SDL3 converts window-relative event coords into the
// renderer's logical (320x240) space, handling HiDPI and
// the letterboxed viewport officially.
SDL_ConvertEventToRenderCoordinates(ren, &e);
// Caveat kept from the SDL2 era (commit 260a2b3): under
// Xwayland the X server may deliver pointer event coords in
// a scaled space (observed: exactly half the true position),
// so cross-check against the cursor position reconstructed
// from the global state minus the window position (raw root
// coords on X11, unaffected by event scaling) and prefer it
// when it lands inside the window.
int ww, wh;
SDL_GetWindowSize(win, &ww, &wh);
int srcX = e.button.x, srcY = e.button.y;
if (ww > 0 && wh > 0) {
int gx, gy, wpx, wpy;
float gx, gy;
int wpx, wpy;
Uint32 gbtn = SDL_GetGlobalMouseState(&gx, &gy);
SDL_GetWindowPosition(win, &wpx, &wpy);
int relX = gx - wpx, relY = gy - wpy;
int relX = (int)(gx - wpx), relY = (int)(gy - wpy);
if (gbtn && relX >= 0 && relX < ww && relY >= 0 && relY < wh) {
srcX = relX;
srcY = relY;
float lx, ly;
if (SDL_RenderCoordinatesFromWindow(ren, (float)relX, (float)relY, &lx, &ly)) {
e.button.x = lx;
e.button.y = ly;
}
}
}
int ow, oh;
SDL_GetRendererOutputSize(ren, &ow, &oh);
int wx = 0, wy = 0;
if (ww > 0 && wh > 0) {
float scale = (ww * emuGfx::H <= wh * emuGfx::W)
? (float)ww / emuGfx::W
: (float)wh / emuGfx::H;
float vw = emuGfx::W * scale, vh = emuGfx::H * scale;
float vx = (ww - vw) / 2.0f, vy = (wh - vh) / 2.0f;
wx = (int)((srcX - vx) / scale);
wy = (int)((srcY - vy) / scale);
}
int wx = (int)e.button.x, wy = (int)e.button.y;
if (wx < 0) wx = 0;
if (wx > emuGfx::W - 1) wx = emuGfx::W - 1;
if (wy < 0) wy = 0;
if (wy > emuGfx::H - 1) wy = emuGfx::H - 1;
if (e.button.button == SDL_BUTTON_LEFT) {
bool down = (e.type == SDL_MOUSEBUTTONDOWN);
bool down = (e.type == SDL_EVENT_MOUSE_BUTTON_DOWN);
emu::touchDown = down;
emu::touchX = wx;
emu::touchY = wy;
} else if (e.button.button == SDL_BUTTON_RIGHT) {
emu::pinLevels[BOARD_BOOT_PIN] =
(e.type == SDL_MOUSEBUTTONDOWN) ? 0 : 1;
(e.type == SDL_EVENT_MOUSE_BUTTON_DOWN) ? 0 : 1;
}
break;
}
@@ -368,7 +365,7 @@ int main(int argc, char **argv)
emuGfx::dirty = false;
}
SDL_RenderClear(ren);
SDL_RenderCopy(ren, emuGfx::tex, nullptr, nullptr);
SDL_RenderTexture(ren, emuGfx::tex, nullptr, nullptr);
SDL_RenderPresent(ren);
if (maxFrames > 0 && --maxFrames == 0) {
+12 -8
View File
@@ -1,13 +1,17 @@
/**
* TFT_eSPI shim: renders the same drawing calls into a 320x240 ABGR8888
* framebuffer that the SDL2 host pushes to a window. Text uses SDL_ttf with
* framebuffer that the SDL3 host pushes to a window. Text uses SDL3_ttf with
* DejaVu fonts as stand-ins for the TFT_eSPI font set.
*/
#pragma once
#include <Arduino.h>
#include <SDL.h>
#include <SDL_ttf.h>
#include <SDL3/SDL.h>
#if __has_include(<SDL3/SDL_ttf.h>) // upstream install layout
#include <SDL3/SDL_ttf.h>
#else // Debian/Ubuntu package layout
#include <SDL3_ttf/SDL_ttf.h>
#endif
#include "emu_gfx.h"
#include <map>
@@ -179,10 +183,10 @@ public:
if (!f) return;
SDL_Color col = sdlColor(fg);
SDL_Surface *surf = TTF_RenderUTF8_Blended(f, s.s.c_str(), col);
SDL_Surface *surf = TTF_RenderText_Blended(f, s.s.c_str(), s.s.size(), col);
if (!surf) return;
SDL_Surface *conv = SDL_ConvertSurfaceFormat(surf, SDL_PIXELFORMAT_ABGR8888, 0);
SDL_FreeSurface(surf);
SDL_Surface *conv = SDL_ConvertSurface(surf, SDL_PIXELFORMAT_ABGR8888);
SDL_DestroySurface(surf);
if (!conv) return;
int w = conv->w, h = conv->h;
@@ -214,7 +218,7 @@ public:
if ((p >> 24) > 0) emuGfx::fb[ty * emuGfx::W + tx] = p;
}
}
SDL_FreeSurface(conv);
SDL_DestroySurface(conv);
emuGfx::dirty = true;
}
@@ -252,7 +256,7 @@ private:
"/usr/share/fonts/dejavu/DejaVuSans-Bold.ttf",
};
const char *path = bold ? paths[1] : paths[0];
TTF_Font *f = TTF_OpenFont(path, size);
TTF_Font *f = TTF_OpenFont(path, (float)size);
if (!f) {
f = TTF_OpenFont(paths[2], size);
if (!f) f = TTF_OpenFont(paths[3], size);
+15 -13
View File
@@ -5,7 +5,7 @@
#pragma once
#include <cstdint>
#include <cstddef>
#include <SDL.h>
#include <SDL3/SDL.h>
#define ESP_OK 0
#define ESP_FAIL -1
@@ -39,28 +39,30 @@ struct i2s_pin_config_t {
int data_in_num;
};
inline SDL_AudioDeviceID &emuAudioDev()
inline SDL_AudioStream *&emuAudioStream()
{
static SDL_AudioDeviceID d = 0;
return d;
static SDL_AudioStream *s = nullptr;
return s;
}
inline int i2s_driver_install(i2s_port_t, const i2s_config_t *cfg, int, void *)
{
SDL_AudioSpec want {}, have {};
// SDL3 audio: open a stream on the default playback device with our
// spec (conversion to the device format is automatic) and feed it from
// i2s_write() via SDL_PutAudioStreamData().
SDL_AudioSpec want {};
want.freq = (int)cfg->sample_rate;
want.format = AUDIO_S16SYS;
want.format = SDL_AUDIO_S16;
want.channels = 1;
want.samples = 512;
want.callback = nullptr; // SDL_QueueAudio mode
emuAudioDev() = SDL_OpenAudioDevice(nullptr, 0, &want, &have, 0);
if (emuAudioDev() == 0) {
emuAudioStream() = SDL_OpenAudioDeviceStream(SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK,
&want, nullptr, nullptr);
if (!emuAudioStream()) {
std::printf("[emu] no audio device: %s (running silent)\n", SDL_GetError());
return ESP_FAIL;
}
SDL_PauseAudioDevice(emuAudioDev(), 0);
std::printf("[emu] audio open: %d Hz (requested %u)\n", have.freq, cfg->sample_rate);
SDL_ResumeAudioStreamDevice(emuAudioStream());
std::printf("[emu] audio open: %d Hz\n", want.freq);
return ESP_OK;
}
@@ -68,7 +70,7 @@ inline int i2s_set_pin(i2s_port_t, const i2s_pin_config_t *) { return ESP_OK; }
inline int i2s_write(i2s_port_t, const void *src, size_t size, size_t *written, unsigned)
{
if (emuAudioDev()) SDL_QueueAudio(emuAudioDev(), src, (uint32_t)size);
if (emuAudioStream()) SDL_PutAudioStreamData(emuAudioStream(), src, (int)size);
if (written) *written = size;
return ESP_OK;
}
+1 -1
View File
@@ -1,5 +1,5 @@
/**
* Framebuffer shared between the TFT_eSPI shim and the SDL2 host.
* Framebuffer shared between the TFT_eSPI shim and the SDL3 host.
*/
#pragma once
#include <cstdint>
+1 -1
View File
@@ -1,6 +1,6 @@
/**
* Emulator <-> shim shared state. Included by both the Arduino shim headers
* and the SDL2 host (main.cpp).
* and the SDL3 host (main.cpp).
*/
#pragma once
#include <cstdint>
+19 -12
View File
@@ -11,10 +11,10 @@
* Slower by nature (~1-2 min: the scenario runs at 20 Hz real time), which
* is why it gets its own build and its own make target.
*/
#include "harness.h"
#include <SDL3/SDL.h>
#include <SDL3_ttf/SDL_ttf.h> // Debian/Ubuntu layout (upstream: SDL3/SDL_ttf.h)
#include <SDL.h>
#include <SDL_ttf.h>
#include "harness.h"
// pull in the whole sketch as a single translation unit (-DAPP_INO)
#include APP_INO
@@ -115,13 +115,20 @@ TEST(e2e/boot_and_controls)
// HUD separator rendered across the top of the HUD bar
EXPECT(test::pixelIs565(160, nd::HUD_Y, nd::C_BORDER));
// paused -> dithered freeze tint with color-key transparency:
// black dots where ((x>>1)+(y>>1)) is even, map shows through elsewhere
EXPECT(test::pixelIs565(50, 2, 0x0000)); // dither dot drawn
EXPECT(test::pixelIs565(52, 0, 0x0000)); // dither dot drawn
EXPECT(test::pixelIs565(50, 0, nd::C_WALL)); // transparent: wall pixel
EXPECT(test::pixelIs565(50, 4, nd::C_WALL)); // survives untouched
EXPECT(!test::pixelIs565(50, 0, 0x1F1F)); // key color never rendered
// paused -> diagonal-stripe freeze tint with color-key transparency:
// within each 8x8 cell the anti-diagonal stripe ((x%8)+(y%8))%8 == 2
// stamps black, every other pixel keeps the frozen view, and the key
// color 0x1F1F is never rendered (transparency held). Sampled on the
// left side of the top wall row, away from the top-right anchored
// "* TACTICAL FREEZE *" text, so font metric drift can't leak in.
EXPECT(test::pixelIs565(10, 0, 0x0000)); // stripe dot (2,0)
EXPECT(test::pixelIs565(9, 1, 0x0000)); // stripe dot (1,1)
EXPECT(test::pixelIs565(8, 2, 0x0000)); // stripe dot (0,2)
EXPECT(!test::pixelIs565(12, 0, 0x0000)); // off-stripe: frozen view
EXPECT(!test::pixelIs565(12, 0, 0x1F1F)); // key color never rendered
for (int yy = 0; yy < 8; yy++)
for (int xx = 8; xx < 16; xx++)
EXPECT(!test::pixelIs565(xx, yy, 0x1F1F));
}
TEST(e2e/network_journey)
@@ -154,8 +161,8 @@ TEST(e2e/corridor_assault)
int main(int argc, char **argv)
{
// headless: no window needed — rendering goes into the shim framebuffer
SDL_setenv("SDL_VIDEODRIVER", "dummy", 1);
if (SDL_Init(SDL_INIT_VIDEO) != 0) {
::setenv("SDL_VIDEODRIVER", "dummy", 1);
if (!SDL_Init(SDL_INIT_VIDEO)) {
std::printf("SDL_Init failed: %s\n", SDL_GetError());
return 2;
}
+22
View File
@@ -153,3 +153,25 @@ became a plain `#include "nd_layout.h"`). Build configs stay put:
(plus `-I .` for `utilities.h`), and the emulator Makefile points NetDeck's
`APP_DIR` at `../src/netdeck`. `pio run -d examples/NetDeck` and
`make APP=NetDeck` are both verified green from the new location.
### Emulator host: migrated SDL2 → SDL3
The shared emulator harness (`emulator/src/main.cpp`, all apps) now builds
against SDL 3 (3.4.x) + SDL3_ttf. Notable API moves encountered: window
creation lost the position args; renderer logical size is now
`SDL_SetRenderLogicalPresentation(..., SDL_LOGICAL_PRESENTATION_LETTERBOX)`;
`SDL_RenderCopy` → `SDL_RenderTexture`; event types renamed to the
`SDL_EVENT_*` scheme with float mouse coords; `SDL_KeyboardEvent.keysym.sym`
→ `e.key.key`; the audio queue model became an audio stream
(`SDL_OpenAudioDeviceStream` + `SDL_PutAudioStreamData`); frame dumps use
`SDL_SaveBMP_IO`; `TTF_RenderUTF8_Blended` → `TTF_RenderText_Blended` (with
explicit length) and Ubuntu installs SDL3_ttf headers under
`/usr/include/SDL3_ttf` (handled via `__has_include`). The Xwayland
pointer-coords workaround (global-state reconstruction, commit 260a2b3) is
kept alongside the official `SDL_ConvertEventToRenderCoordinates()` until
verified on this desktop. Ubuntu 24.04 → 26.04 note: SDL2 dev is now 2.24
(the floor for `SDL_GetWindowSizeInPixels`); SDL3 arrives from the repos.
E2E freeze-tint pixel assertions were stale since the diagonal-stripe
rework (pre-existing failures at HEAD under SDL2 too) — updated to the
committed pattern, sampled away from the freeze text. Full suite green:
14 unit + 7 integration + 3 E2E journeys, 0 failures.