SDL 3.0 migration guide

SDL 3.0 development is well underway, and we have lots of changes in the works.

You can check out the major API changes in our migration guide here:
SDL/ at main · libsdl-org/SDL (

We’re still iterating and refining things, so please feel free to give feedback on things as you start to migrate your code to the new API. Things are very much in flux at the moment, so APIs will come and go and we have more changes to make, and feedback is welcome!



I’m glad to see the more consistent function naming conventions.

I was hoping it’d be 100% SDL_{namespace}{action} (like SDL_RenderSetState(), SDL_RenderGetState(), SDL_RenderDoAction(), etc.) but at least having all setters/getters start with SDL_Set/Get is better than SDL 2.0’s mix of SDL_{namespace}SetThing() and others SDL_Set{namespace}Thing()

Really looking forward to SDL_GPU

For people who plan to be on SDL2 a little longer, for stability reasons, and plan to migrate to SDL3 later (once things are more settled and battle tested), would be nice to have some recommendations, like, APIs to avoid, or how to use or how to not use something, just how to adapt your SDL2 code now, in a way that the migration when it comes is a bit smoother.

It’s hard to say what to avoid because a lot has changed, even mundane things, and even for things we’re removing we’re trying to make sure there’s a reasonable migration path…so far the only thing we outright removed was the gesture API, and that’s now available as a header-only library that can be dropped into an SDL3 app.

1 Like

Also, sdl2-compat is a thing right from the start, so in the worst case you can live on SDL2 and have it powered by SDL3 behind the scenes.

1 Like

Most things feel like they were renamed, and renaming is fine, there’s even a script there to ease this.

The gesture is a good thing to mention - I haven’t implemented using it and don’t plan to, but it’s good to be aware I will keep not using it. :smile:

Having a migration path is good, that would be more about it, like, things where the migration path is harder or even unsure at the moment. I will consider those to be lava and avoid.

I haven’t dived down in the new code, so I won’t attempt imaginary examples to avoid confusion. But I am anxious. :grimacing:

Ah, right, but the point, the migration manual is good, but just as a perspective, I imagine a lot of people reading it are not going to migrate right away, but they need to grasp, ok, giving my codebase now, what I should not do to ensure things are smooth when the time comes.

… and support for the OpenGLES 1 backend, for which a “reasonable migration path” is sadly absent. :frowning:

(I’m working on it.)

1 Like