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).
On some operating systems (notably Windows, but others as well), your call into SDL_PollEvent, SDL_WaitEvent, SDL_WaitEventTimeout, or SDL_PumpEvents may block during resizing or dragging. This means these function will not return and yield control to your code, until the OS is done with this operation. That said, the OS's do provide ways for a user application to still do work during these operations, but they do so through callbacks, which is to say a function the user provides and the OS will call at appropriate times.
SDL provides two ways to get called during these blocking operations.
SDL_main.h
SDL_AppIterate should be called for you, even when being resized or moved.SDL_EVENT_WINDOW_EXPOSED event. That event will tell you you're blocked and to do whatever you need to do to keep your process healthy, including re-rendering the Window so it doesn't stretch or look overly unnatural.For further context, even when blocked the OS gives your application time slices during these operations, but they do so through callbacks themselves, not by returning back to user code. So the only solution is for SDL or similar to give you a callback as well.
This doesn't guarantee perfectly smooth resizing but greatly improves the situation.
Here's a program that demonstrates the callbacks still allowing user code to run during Window resize and move operations:
#include <SDL3/SDL.h>
#define SDL_MAIN_USE_CALLBACKS
#include <SDL3/SDL_main.h>
SDL_Window* g_window;
SDL_Renderer* g_renderer;
SDL_FRect g_rect = {
100.f, 100.f, 100.f, 100.f
};
SDL_AppResult SDL_AppInit(void** appstate, int argc, char** argv) {
SDL_CreateWindowAndRenderer("Test", 300, 300, SDL_WINDOW_RESIZABLE, &g_window, &g_renderer);
return SDL_APP_CONTINUE;
}
SDL_AppResult SDL_AppIterate(void* appstate) {
SDL_SetRenderDrawColor(g_renderer, 0, 0, 0, 255);
SDL_RenderClear(g_renderer);
SDL_FRect rect = g_rect;
rect.x += 50 * SDL_sinf(SDL_GetTicksNS() / 1000000000.f);
SDL_SetRenderDrawColor(g_renderer, 255, 255, 255, 255);
SDL_RenderFillRect(g_renderer, &rect);
SDL_RenderPresent(g_renderer);
return SDL_APP_CONTINUE;
}
SDL_AppResult SDL_AppEvent(void* appstate, SDL_Event* event) {
if (event->common.type == SDL_EVENT_QUIT) {
return SDL_APP_SUCCESS;
}
return SDL_APP_CONTINUE;
}
void SDL_AppQuit(void* appstate, SDL_AppResult result) { }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");