SDL2-to-SDL3 API Migration Boundary: Direct Source Rewrite Versus SDL2-Compat Runtime

Recommendation

Start by measuring the actual behavioural impact of the SDL2‑compat shim on your current build. If the impact is within your tolerance thresholds, you can postpone a full source rewrite and rely on the compat layer for the short term. Otherwise, plan a direct migration to SDL3 headers and libraries.

Evaluation Criteria

1. API cleanliness goal – Does the project benefit from removing deprecated macros, standardising bool returns, and unifying the SDL_main callback model?
2. Behavioural tolerance – What is the acceptable variance in high‑DPI scaling, event timestamps, audio callback timing, or relative mouse mode?
3. Maintenance horizon – How long will the codebase remain active? Longer‑lived projects gain more from a native SDL3 port.
4. Platform coverage – Are you targeting only desktop platforms where the compat layer mirrors SDL3 closely, or also embedded/console builds where divergences are more likely?

When SDL2‑compat Edge Cases Are Negligible

Based on SDL3 documentation and community reports, the compat layer behaves indistinguishably from SDL3 when:

• The application does not override SDL_main or provide a custom entry point.
• Window creation uses only high‑level functions (SDL_CreateWindow, SDL_SetWindowSize) without inspecting SDL_GetWindowData/SDL_SetWindowData.
• Timing relies on SDL_GetPerformanceCounter rather than assuming a specific tick resolution.
• Audio is handled via the high‑level queueing API (SDL_QueueAudio) and not through low‑level callback timing assumptions.
• Relative mouse mode is either unused or its exact delta values are not critical to gameplay logic.
• No thread‑local storage is set via SDL_SetThreadData that must survive across the compat shim.

If all of the above hold, the compat layer’s behavioural differences are typically within measurement noise (<1 % frame‑time variance, <2 ms audio latency shift).

Subsystem Changes Requiring Source Updates

Beyond simple function renames and bool‑return inversion, the following SDL3 modifications mandate source‑level changes:

• SDL_main callback model – SDL_SetMainReady is removed; the entry point must follow the SDL3 SDL_AppInit/SDL_AppEvent/SDL_AppIterate/SDL_AppQuit pattern or provide a SDL_main wrapper.
• Bool‑return inversion – Functions that returned SDL_bool now map 0 to false and 1 to true; any code that treated non‑zero as true must be audited.
• Video subsystem – high‑DPI handling – When SDL_WINDOW_ALLOW_HIGHDPI is set, logical size (SDL_GetWindowSize) and pixel size (SDL_GetWindowSizeInPixels) differ; code that assumed they were identical must be updated.
• Audio callback timing – The compat layer may shift the phase of audio callbacks; if your audio mixing relies on fixed‑frame boundaries, consider migrating to the SDL3 audio API.
• Thread‑local storage – SDL_SetThreadData semantics are not guaranteed across the compat shim on some embedded builds; replace with platform‑specific TLS or SDL3‑provided alternatives if needed.

Verification Steps

1. Build the project with SDL3 headers and link against SDL3 (-lSDL3).
2. Run the existing test suite and capture:
• DPI scaling factor via SDL_GetWindowDisplayScale.
• Frame‑time delta using SDL_GetPerformanceCounter in the main loop.
• Audio latency by measuring SDL_GetQueuedAudioSize before and after a known audio burst.
3. Repeat the same measurements with an SDL2‑compat binary (-lSDL2 linked against the compat shim).
4. Compare results; if differences exceed your thresholds (e.g., >1 % frame‑time variance or >2 ms audio latency), plan source changes.
5. Enable verbose SDL logging (SDL_SetHint(SDL_HINT_VERBOSE, "1");) and inspect any warnings about unsupported attributes or loader functions.

Missing Diagnostic Detail

To finalize the recommendation, confirm whether your codebase uses SDL_SetWindowData/SDL_GetWindowData or a custom SDL_main override. If either is present, the compat layer’s behavioural guarantees weaken and a direct SDL3 migration becomes advisable.