Check these out if your questions aren't directly about using the library as a developer.
| General | General questions about SDL |
| Using SDL | Questions for people using SDL applications |
| Licensing | Questions about licensing SDL with products |
#include <SDL.h> or #include <SDL3/SDL.h>?If something isn't covered here, it doesn't mean we don't know about it! It's difficult to collate everything between bugs, intended but perhaps unexpected behavior, and even many Frequently Asked Questions.
When looking to do something, generally the first place to look is the Category the API you're looking for is likely in. If it has to do with a specific function, check the documentation for that, specifically the remarks section, there's fantastic information in those sections. If you still can't figure it out, SDL has several communities you can connect with to get help!
Regarding something seeming to be broken, you can first search on the bug tracker. If you don't find anything but would like to check with other folks before reporting, you can drop by one of the SDL related Communities
#include <SDL.h> or #include <SDL3/SDL.h>? The most portable way to include SDL headers is to use angular quotes around the full header name:
#include <SDL3/SDL.h>This is new in SDL3! Previously, in SDL2, we recommended #include "SDL.h", but this proved to be unfriendly to macOS frameworks and having the API version in the include line is useful for making dependency requirements clear.
SDL provides the lower level of functionality that a cross-platform game engine needs, leaving higher level tasks to other libraries. The libraries page has a non-exhaustive list of libraries that are known to work well with SDL.
No, most graphics back ends are not thread-safe, so you should only call SDL video functions from the main thread of your application. SDL_RunOnMainThread() can be used to dispatch code that needs to run on the main thread.
The main event handling should be done on the main thread, though you can use SDL_PushEvent() and SDL_PeepEvents() to interact with the event queue on other threads. Most SDL functions have their thread-safety noted in their documentation.
Take a look at these blogs for an in-depth understanding of the problems of timing:
In SDL3 you should be using SDL_DelayPrecise (which uses an algorithm similar to above) or SDL_DelayNS (More precise than SDL_Delay, but doesn't busy-wait)
On a similar note, when doing timing, prefer using SDL_GetPerformanceCounter and SDL_GetPerformanceFrequency , or SDL_GetTicksNS , over using SDL_GetTicks, which has only has millisecond precision. SDL_GetTicksNS uses SDL_GetPerformanceCounter under the hood, but converted to nanoseconds for convenience.
NOTE: This answer is written for brevity, but this is a complex topic! For a full understanding of what's happening, please look over our main functions README.
It's most likely you have #include <SDL3/SDL_main.h> included in the file with your main function, but your main function doesn't have the expected signature: int main(int argc, char *argv[])
If you see an error about "a previous definition of SDL_main", there's pretty much two possibilities:
main twice in one file yourself. Pretty unlikely, but it can happen!#define SDL_MAIN_USE_CALLBACKS somewhere, or have SDL_MAIN_USE_CALLBACKS defined through your build system as a switch to the compiler, but you're implementing main instead of or in addition to the callbacks.The last common issue here is you've placed #include <SDL3/SDL_main.h> in two Translation Units (c/cpp files).
Please read AppFreezeDuringDrag for a technical explanation and solutions.
Once SDL 3.4.0 is available, you can get fragment shaders, take a look at SDL_CreateGPURenderer and SDL_CreateGPURenderState. Until then you can try out this function using the main branch on GitHub
That said, there are many different ways to use shaders, and if you need more than the subset of shader functionality we expose there, we recommend using a full 3D API like SDL GPU. You can look at how SDL uses the GPU API for 2D rendering if you'd like to expand on that: SDL_render_gpu.c
This is a very difficult question to give a good answer to. We'll try to give some soft recommendations here, along with information on the other native APIs so that you can decide for yourself what feels right for you.
We're quite proud of the new GPU API that was added in SDL3, and are confident it can handle the majority of use cases you'll run into. FNA has already shipped games on console using SDL3 and the GPU API for rendering. That said, since the API is relatively new, if you're intending to learn graphics, you may want to start with tutorials using OpenGL or another graphics API. In addition, while it has fairly wide platform support, including the big 3 console platforms, it currently does not support the web and has limited support on Android, which doesn't have the necessary driver support across many devices. On desktop, the GPU API supports Vulkan 1.0 capable hardware, which includes graphics cards made in the last 10-15 years. If you want features that are newer and have less wide-spread support, like mesh shaders and bindless textures, then you'll want to use Vulkan directly.
In addition to the GPU API, here are some other alternatives that may work for you, depending on your needs.
No, the backends are DX12, Metal, Vulkan. Although it should be noted that it's also supported on the NDA only console forks of SDL. (More information on how to get access on the respective platform pages.)
Yes, but to get wide support, you'll need to give up on some features. Each Vulkan feature from the properties you disable when creating your SDL_GPUDevice will get you wider Android support. In general if you're interested in Android you should just turn all of the Vulkan features here off. Hopefully in a year or two, things will improve as Google has announced somewhat agressive goals for upcoming Android versions.
We recommend using SDL_shadercross, a shader compiler that tries to make it easy to go from HLSL to all the shader formats SDL_GPU needs for each backend. That said, we recommend not building it yourself, as the build process is complex and has large dependencies. You can find builds on the actions page, just be signed into GitHub, and select the latest build from main.
It's likely that you're running Wayland. RenderDoc doesn't support Wayland, please force XWayland and give that a try!
You can set this before calling SDL_Init to get that behavior if your system is set up as expected: SDL_SetHint(SDL_HINT_VIDEO_DRIVER, "x11");