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

The SDL2-to-SDL3 API migration boundary encompasses function renames, bool-return convention shifts, and the SDL_main callback model change, which affect all subsystems that rely on windowing, input, and timer semantics.

SDL3 explicitly defines behaviors that SDL2 implicitly handled, such as high-DPI scaling and event timestamping, so compiled code may exhibit different runtime behavior even when it links successfully.

The SDL2-compat compatibility layer functions as a runtime bridge for SDL2-linked binaries on SDL3, but it is not a source-level compatibility guarantee, and edge cases can surface depending on platform and subsystem usage.

Given that documentation does not settle the tradeoff between long-term API cleanliness and short-term migration risk, project maintainers face an unresolved decision point.

How should project maintainers evaluate the long-term API cleanliness benefits of direct SDL3 migration against the short-term behavioral uncertainty of compat-layer usage? What criteria distinguish cases where SDL2-compat edge cases are negligible from those where they require source adaptation? Which SDL3 subsystem modifications, if any, mandate source-level changes beyond function renames and bool-return inversion?