Request for Comments: Portability & Rendering Architecture Roadmap

[noctonca]

This RFC proposes a phased roadmap toward hardware rendering and broader platform portability. Each phase is independently mergeable and has a payoff on its own — this is not a big-bang rewrite.

The immediate motivation is hardware rendering. Getting there cleanly requires two abstraction layers and a directory structure that don't exist yet. This RFC is about agreeing on the shape of those layers and the order of work before anyone moves files around.

Note on preservation: This roadmap applies only to lba2-classic-community. The original 1997 source is preserved without modification at 2point21/lba2-classic. Original file authorship, French comments, and developer artifacts are preserved in git history — renames are tracked, and the staged move SHAs are added to .git-blame-ignore-revs so git blame skips through them to the original author. The software renderer is a permanent backend, not a stepping stone to be removed.

Roadmap at a glance

Phase	What	Independently shippable?
0	Restructure directories + normalise case	Yes
1	Platform abstraction layer (PAL) — decouple engine from direct SDL calls	Yes
2	Render interface — engine stops touching pixels directly	Yes
3	SDL_GPU hardware backend + equivalence CI	Yes

Testing is a first-class concern from Phase 0, not a separate phase.

---

Phase 0 — Restructure

Move from the historical Adeline layout (SOURCES/ + LIB386/) to a modern tree, and normalise filename case while we're touching everything.

Target tree

lba2-classic-community/
  src/
    engine/             game logic (was SOURCES/)
      3dext/            terrain, sky, rain, decor
      config/
      console/          in-game dev console
    platform/
      sdl/              SDL3 backend
      headless/         CI / equivalence backend
    render/
      software/         paletted software path
        pol_work/       polygon fillers — flat, gouraud, textured, fog, z-buffer
        svga/           raster blits, palette upload, dirty rect, present
      sdlgpu/           Phase 3 placeholder (empty until then)
    lib/                engine libraries — candidates for cross-repo share
      math/             3D math, projection, rotation
      anim/             animation frames, interpolation
      audio/            AIL interface; backends under audio/{null,sdl,…}/
      audio_resample/   sample-rate conversion helper
      fileio/           PCX, PNG, save loaders
      object/           3D object display
      system/           file I/O, timer, keyboard, mouse, window facade
      snapshot/         polygon-recording replay infra
      menu/             unbuilt today — preserved
      video/            SMACKER wrapper — unbuilt today — preserved
      include/          all public headers (was LIB386/H/)
                        subsystem subdirs: 3d ail anim fileio menu object
                                           polygon smacker snapshot svga system
      third_party/      vendored libraries
        libsmacker/     LGPL-2.1 — Smacker (.smk) FMV decoder
        stb_vorbis/     public domain — Ogg Vorbis audio decoder
  packaging/            existing — icons, .rc/.desktop/Info.plist templates
                        absorbs SOURCES/WIN/ (LBA2.ICO, LBA2.RC, RESOURCE.H)
  tests/                CTest tree, subdirs mirror src/ (3d/, 3dext/, anim/, …)
    cmake/              test helpers (asm_test_helpers.cmake, …)

Host-only vs ASM-/render-equivalence tests are distinguished by CTest labels (host_quick vs equiv), not directory layout — LBA2_BUILD_ASM_EQUIV_TESTS=OFF runs the host suite without Docker.

Mapping table

Today	Target
SOURCES/*.cpp, *.h, *.asm (flat)	src/engine/ (still flat — subdivide later once coupling is mapped)
SOURCES/3DEXT/	src/engine/3dext/
SOURCES/CONFIG/	src/engine/config/
SOURCES/CONSOLE/	src/engine/console/
SOURCES/WIN/	packaging/ (existing dir — Windows resources join the macOS/Linux packaging artefacts)
LIB386/3D/	src/lib/math/
LIB386/AIL/	src/lib/audio/
LIB386/ANIM/	src/lib/anim/
LIB386/FILEIO/	src/lib/fileio/
LIB386/OBJECT/	src/lib/object/
LIB386/SYSTEM/	src/lib/system/
LIB386/MENU/	src/lib/menu/ (currently unbuilt — see note)
LIB386/SMACKER/	src/lib/video/ (currently unbuilt — see note)
LIB386/SNAPSHOT/	src/lib/snapshot/
LIB386/VIDEO_AUDIO_RESAMPLE/	src/lib/audio_resample/
LIB386/SVGA/	src/render/software/svga/
LIB386/pol_work/	src/render/software/pol_work/
LIB386/H/	src/lib/include/ (subdirs match code dir names)
LIB386/libsmacker/	src/lib/third_party/libsmacker/
LIB386/AIL/SDL/stb_vorbis.{c,h}	src/lib/third_party/stb_vorbis/ (lifted out of the SDL backend — it's third-party, not SDL-specific)

Dead-code discovery during dry run: LIB386/MENU/ and LIB386/SMACKER/ aren't currently wired into the main build (no parent add_subdirectory). MENU has tests, SMACKER doesn't. Decision needed: preserve, delete, or revive. Conservative default = preserve.

SVGA + pol_work is a merge, not a move. Both have separate CMake targets (libsvg.a, libpoly.a). Proposing to keep as two subdirs under src/render/software/{svga,pol_work}/ rather than flatten into one — the concerns are distinct (raster blits vs polygon fillers).

Case rule

Everything lowercase, with three carve-outs:

1. SDL3/ system headers stay uppercase (<SDL3/SDL.h>). Upstream's install path.
2. Retail data filenames preserved (LBA2.CFG, LBA2.RC, LBA2.ICO, PALETTE.PAL, CLAVIER.TXT). Referenced by exact name in shipped game data + packaging.
3. INITADEL.C → initadel.cpp (semantic upgrade). Unix convention says uppercase .C is C++; the engine was already C++ by content. Becoming .cpp is the right modernisation.

Why lowercase: modern C++ convention (Boost, fmt, abseil, spdlog, Godot, bgfx — all lowercase). Uppercase is Adeline's 1996 MS-DOS / Watcom convention; we keep it in git history but move the live tree forward.

After 0c, CONTRIBUTING.md states the rule for new files: lowercase basename, lowercase extensions, except for retail data filenames and external library paths (e.g. SDL3/).

Staging — 3 commits

Commit	What	Scope
0a — directory restructure	git mv directories only. Code dirs, header dirs, test dirs all lowercase. Update CMakeLists add_subdirectory() paths.	~70 ops
0b — case normalisation	Lowercase all source filenames. Rewrite #include directives to match. Pure mechanical churn.	~600 file renames + ~440 include edits
0c — semantic edge cases	INITADEL.C → .cpp. Lowercase generated-header templates (build_info.h.in, version_generated.h). Update cmake/embed_lba2_cfg.cmake include line. SDL3/ carve-out exceptions documented in CONTRIBUTING.	~6 surgical changes

All three SHAs added to .git-blame-ignore-revs so git blame skips through the move and surfaces the original Adeline / community authorship.

Dry-run status — verified

The dry run is on a public branch for inspection:

noctonca/lba2-classic-community @ dryrun/phase0-restructure (commit 7e19e73, not for merge)

End-to-end verification on that branch:

cmake -B build -G Ninja -DSOUND_BACKEND=null -DMVIDEO_BACKEND=null
cmake --build build              # 208/208, 967 KB lba2cc binary
make test                        # 7/7 host_quick tests pass

The commit is the all-three-stages end state — when actually staged as three commits in the implementation PR, all three SHAs go into .git-blame-ignore-revs.

Testing infrastructure

The existing tests/ tree gets renamed alongside src/ in 0a. New unit tests for lib/math/ and lib/fileio/ are easy first additions — they have no platform or render dependencies. Render-equivalence scaffolding gets populated in Phase 2.

CMake dependency rule (established here)

engine    → render.h, platform.h, lib/
render    → platform.h, lib/
platform  → (nothing internal)
lib/      → (nothing internal)

CMake enforces this at link time. Accidental upward dependencies fail in CI.

---

Phase 1 — Platform abstraction layer

Decouple the engine from direct SDL calls behind a thin interface. Builds directly on the scancode abstraction from #58 (virtual scancode mapping is essentially a micro-PAL for input).

Evidence the PAL boundary is real

lba2-dreamcast is a KallistiOS port at V0.9 alpha — boots, plays intro FMV, full first-island gameplay on Flycast. Files they had to replace to make a non-SDL port work:

• LIB386/SVGA/SDL.CPP → LIB386/SVGA/KOS.CPP
• Eight SDL-using LIB386/SYSTEM/* files → one LIB386/SYSTEM/KOS_BACKEND.CPP
• LIB386/AIL/SDL/* → LIB386/AIL/KOS/*
• Plus an 83-line dc_sdl_compat.h shim faking SDL_GetTicks, SDL_Delay, SDL_GetBasePath etc. so engine call sites in PERSO.CPP / PLAYACF.CPP / RES_DISCOVERY.CPP / DIRECTORIES.CPP could keep their syntax.

That shim is the Phase 1 PAL-shaped hole, made literal. A clean PAL reduces it to zero lines.

Proposed interface

typedef struct PlatformCallbacks {
    /* lifecycle */
    bool     (*init)(void);
    void     (*shutdown)(void);

    /* event loop */
    void     (*poll_events)(void);
    bool     (*should_quit)(void);

    /* time */
    uint64_t (*ticks_ms)(void);
    void     (*delay_ms)(uint32_t ms);
    void     (*delay_events_ms)(uint32_t ms);   /* sleep, break on input */

    /* display — paletted is the engine's native output */
    void     (*get_window_size)(int *w, int *h);
    void     (*set_fullscreen)(bool fs);
    void     (*set_vsync)(bool on);
    void     (*set_palette)(const uint8_t *rgb_256);
    void     (*present_frame)(const uint8_t *indexed, int w, int h, const Rect *dirty);

    /* input — pull model */
    bool     (*key_down)(int scancode);
    int      (*key_modifiers)(void);
    void     (*get_mouse)(int *x, int *y, uint32_t *buttons);
    int      (*gamepad_count)(void);
    float    (*axis_value)(int gamepad_id, int axis);
    bool     (*button_down)(int gamepad_id, int button);

    /* host services — currently in RES_DISCOVERY / RES_PICKER / DIRECTORIES */
    const char *(*pref_path)(void);
    const char *(*base_path)(void);
    int          (*pick_folder)(char *out, int outsz);
    void         (*message_box)(const char *title, const char *body);
} PlatformCallbacks;

extern PlatformCallbacks g_platform;

The interface lives in src/platform/platform.h. Each backend implements it in its own subdir (sdl/, headless/, …).

Audio is not in the PAL. AIL owns the audio device directly (validated by the DC port replacing the AIL backend cleanly without engine changes). Keeping AIL as src/lib/audio/ and a separate audio interface is the right factoring.

Backends

• src/platform/sdl/ — the existing SDL3 implementation, reorganised.
• src/platform/headless/ — all stubs, monotonic clock. Enables headless CI and integration tests.
• src/platform/console/switch/ — natural second target via devkitPro's SDL3 port.

Runtime backend switching is supported by the struct pointer pattern. Useful for debug toggling and silent SDL_GPU → software fallback.

Testing — integration tier lands here

Headless boot + N ticks + assert-no-crash. Surfaces any engine code that bypasses the PAL. Scriptable input injection for deterministic replays:

typedef struct { int scancode; uint64_t at_ms; } InputEvent;
void headless_inject_input(InputEvent *events, int count);

---

Phase 2 — Render interface

The engine stops touching pixels or draw calls directly. The interface between engine and renderer needs to be picked, not just sketched.

The decision

The current engine isn't triangle submission. Exterior is a sort tree driving per-poly filler dispatch with material flags; interior is iso + z-buffer; output is paletted pixels. So "engine stops touching pixels" has three plausible boundaries:

Option	What engine submits	Sort tree	RI complexity
(a)	Transformed screen-space polygons with material IDs	Stays in engine	Lower
(b)	World-space meshes with materials	Moves to RI	Higher — bigger rewrite
(c)	Engine drives sort tree, calls RI per polygon	Stays in engine	Lowest

Proposed: (a). Concrete evidence: the DC port runs the existing software renderer producing paletted output, then does a 565 blit at present time. They never touched pol_work or the sort tree. The boundary that already works in shipping code is (a).

The interface must remain bimodal

There is no GL on SH4, PSP, or most retro targets. The software renderer is a permanent backend, not a stepping stone. The RI accommodates two valid output modes:

• Paletted software — the renderer produces an indexed framebuffer; the PAL presents it (DC, headless, fallback). First-class forever.
• GPU geometry — engine submits transformed polygons + materials, backend rasterises with shaders (SDL_GPU/Vulkan/Metal). Phase 3+.

A backend implements one or the other, not both.

Testing

First render-equivalence scenes captured here against the software backend. These become the golden reference all future hardware backends are validated against.

---

Phase 3 — SDL_GPU + Equivalence CI

Implement the RI's GPU mode against SDL3's SDL_GPU API. SDL_GPU translates to Vulkan on Linux, D3D12 on Windows, Metal on macOS — no per-platform graphics code required.

Equivalence CI

Lavapipe (software Vulkan, CPU) renders the GPU output in CI. Software renderer renders the reference. Perceptual-diff with tolerance:

- name: Run equivalence tests
  env:
    SDL_VIDEODRIVER: offscreen
    VK_ICD_FILENAMES: /usr/share/vulkan/icd.d/lvp_icd.x86_64.json
  run: ./lba2cc --backend=sdlgpu --run-equiv-suite

Prerequisite — software-renderer determinism

The software renderer is not deterministic across platforms today. LPROJ3DF.CPP / LROT3DF.CPP use long double + lrintl to match x87 fistp rounding. long double is 80-bit on Linux x86_64, 64-bit on Windows MSYS2, 64-bit on macOS ARM64. There are platform-specific differences in screen coords and Z values today, and an open exterior draw-order bug on Linux tied to this.

"Software goldens" begs the question: captured on which platform? Perceptual-diff tolerance won't paper over a polygon drawn in the wrong place.

Decision needed before Phase 3 starts:

• One canonical platform (Linux x86_64) + accept per-platform divergence elsewhere, OR
• Per-platform goldens, OR
• Fix the precision issue first (probably the right answer; deferred only if blocking).

---

Testing pyramid

Unit          lib/ in isolation — math, fileio, anim
              No platform, no render, no SDL

Integration   engine/ with headless PAL + software render
              Full game loop, deterministic input injection

Equivalence   software vs SDL_GPU render output
              Perceptual diff, lavapipe in CI, goldens in repo

---

Forward-looking — shared library across LBA engines

The PAL contract proposed in Phase 1 is shape-compatible with twin-e's platform.h and timeco's system.h. With small choices early — a C header (extern "C" linkage), stdint types, audio as a sibling contract, lowercase convention — the same interface could later live in a shared adeline-common consumed by all three engines.

This RFC does not commit to that extraction. It does suggest designing Phase 1 as if extraction were possible — the cost is near-zero and the option is valuable. A separate cross-repo discussion will work out scope and governance.

---

Open questions

1. Phase 0 — Are the case-rule carve-outs (SDL3, retail data, .C→.cpp) acceptable?
2. Phase 0 — Anything missing from the mapping table?
3. Phase 0 — Dead code in LIB386/MENU/ and LIB386/SMACKER/: preserve, delete, or revive?
4. Phase 1 — Audio out of the PAL (AIL owns the device): agree?
5. Phase 2 — Pick option (a)?
6. Phase 2 — Bimodal RI (paletted-software + GPU as alternative outputs) — any objections?
7. Phase 3 — Software-renderer determinism: which option for goldens?
8. Bandwidth — who has interest in which phases?

[sergiou87]

Platform Abstracting Layer: sounds like a great idea to me. I personally prefer using SDL as PAL in my projects (SDL2 covers most platforms, even Dreamcast AFAIK), but I understand (and have experienced it) that some platforms might need even lower level access to hardware/OS stuff.

About renaming and restructuring files: I think I prefer keeping the original structure so it's easier to look back at the original code at any time, or older commits. But not sure how useful is that at this point 🤔 In summary… no strong opinion about this, but those are my 2c 😅

[noctonca]

Thanks for weighing in! And I appreciate the endorsement on the PAL.

On SDL: you're right that SDL3 covers most of what we care about and it will remain the default backend. The PAL isn't replacing SDL, it's just letting us also target what SDL doesn't reach. The Dreamcast port already proves this matters: they're on KallistiOS natively (no SDL3 path on DC), and they had to write a small shim faking SDL calls just to make the engine compile. With a PAL above SDL that shim wouldn't exist; the KOS backend would just be another implementation alongside the SDL one. Same story for PSP, Vita, and similar retro or exotic targets where there's no SDL3 support at all.

So the framing is: SDL3 stays the default, the PAL just keeps the engine from being coupled to it. AIL already does this for audio in the codebase (SDL, Miles, Null backends, with the DC port adding a KOS one cleanly), and the PAL extends the same pattern from audio to the rest.

On keeping the original structure: that's a genuine tradeoff and I get the instinct. The mitigation is that 2point21/lba2-classic is the frozen preservation copy, untouched, one clone away whenever you want to look back at the original layout. Plus the move SHAs go into .git-blame-ignore-revs so git blame still skips through them to the original Adeline / community authors. Where the case for restructure lands strongest is forward-looking: every new contributor in 2026 has to learn the 1996 LIB386 / SOURCES split otherwise.

That said, "no strong opinion" works for me as a position too. Happy to treat the restructure as lower-priority than the PAL discussion if that's where the substance is.

[noctonca]

Update: the architecture docs from #293 feed directly into this roadmap.

A batch of engine-axis docs just merged (#293) that overlap a few of the open questions here:

• Open question 3 (dead code in LIB386/MENU / LIB386/SMACKER): docs/ENGINE_GAME_SEAM.md now pins every module engine/game/platform + live/dormant, with a dormant register that catalogues the full unbuilt surface: not just MENU/SMACKER but DEC/DEC_XCF, HERCULE, KEYB, CRITICAL, COPY, AIL/MILES, and the standalone CONFIG/ tool. Its default is preserve, with a reason: most of it is the engine's other-era / other-game surface, not cruft. Clearest case: DEC_XCF is dead in LBA2 but decodes Time Commando's .ACF cinematics (see docs/TIME_COMMANDO.md). Cross-checking the register against this RFC's Phase-0 dry run also caught a labelling slip (MENU was marked live); fixed in docs(architecture): fix MENU/SMACKER dormant status in the per-module map #294.

• Phase 0 mapping table: the per-module labels are a ready cross-check for the LIB386/* → src/lib|render|platform mapping. Two spots worth a look. SVGA is split (raster goes to render, but mode-setup / palette-upload / present is a platform tail, relevant to where present_frame lands). And the dormant DEC/DEC_XCF codec lives in SOURCES/, so it falls outside the LIB386/* mapping; as a reusable cinematic codec it likely belongs near src/lib/video/ rather than flat src/engine/.

• The shared-adeline-common forward-look: docs/ENGINE_FILE_FORMATS.md specs the on-disk formats (HQR, LZ, body, anim, sprite, samples, XMIDI, XCF) and verifies they're byte-identical across LBA1/TC/LBA2: the same reader code reads all three games' data. So the format / lib/ layer is already a shared surface, arguably more share-ready than the PAL (no design step needed). Worth folding into the cross-repo discussion when it happens.

• One coupling to flag: Phase 0's lowercase rename + dir moves will invalidate the path references in these docs (LIB386/SYSTEM/HQFILE.CPP, SOURCES/DEC_XCF.CPP, scripts/dev/iso_bin.py, ...). The "~440 include edits" sweep should include docs/.

None of this changes the roadmap; just connective tissue for whoever picks up Phase 0.