How to report SDL bugs

Where to report bugs in SDL

Bug reports for SDL can be posted at the bug tracker.

The bug tracker is our TODO list and our institutional memory; it's totally cool to ask about and discuss bugs on the forums, Discord, or by email, but we will almost certainly forget to deal with the problem if it's not open in the bug tracker.

Don't use the bug tracker for questions

We have various places for discussion. Questions about SDL can be asked there, including "how do I use this?" and "am I using this correctly?"

These questions are better posted to those places, so they don't clog up the bug tracker and so others can benefit from them later.

Tell us what platform you're using

SDL runs on a lot of platforms, and people often forget to mention which one they're using when they hit a bug. It's extremely useful to say "I'm on Windows 10" or "I'm seeing this on macOS 15.4."

If you're dealing with a rendering bug, it's useful to report that you're using a specific 2D render backend (OpenGL, Direct3D 9, etc) or GPU API target (Vulkan, Metal, etc).

Try the example programs

If you're using a programming language other than C/C++/ObjC, using SDL through a language-specific binding, please try one of our test programs before reporting a bug. Often the problem is not SDL, but the binding!

The "test" directory has lots of programs to exercise various parts of SDL. If you build SDL with CMake, the SDL_TESTS=On option will build all of these tests alongside SDL itself.

Even smaller test code is in the "examples" directory, and each can be built as a single C file that just needs to link against SDL (CMake option: SDL_EXAMPLES=On). If you don't want to get into CMake, a simple compiler command line similar to this might work:

cd SDL
cc -o clear examples/renderer/01-clear/clear.c -Iinclude -lSDL3

Reporting memory leaks

Memory leaks happen, and we are happy to fix leaks in SDL. However, almost all leaks reported to our bug tracker are either leaks in other libraries that SDL uses, or intentional one-time allocations made by GPU drivers.

If you're using a memory leak tool, like AddressSanitizer or Valgrind, before reporting:

• Are you sure this is an SDL leak? If the last thing in the callstack is not SDL, it's very likely it's a leak in a system library or graphics driver that SDL doesn't control. It's possible SDL is misusing a library, but almost always this is either a bug or an intentional one-time allocation by that library. In particular D-Bus, Mesa, and NVIDIA drivers are known to have these. Please report these leaks to that library's maintainer instead of SDL, since we do not have the power to fix their leaks.
• If the leak is in SDL, it's often easy to identify where it's leaking and where it should be cleaned up. Please submit a PR with a fix if possible. Not only will this make it easy for us to confirm and accept your change, often in the process you may discover you're just not calling the code that cleans up the memory.
• If you're not able to tell where the leak should be cleaned up, please include symbols in your leak stack traces so we can see clearly what is happening.

Requesting new GPU API features

Before raising an issue to request a feature, please make sure it hasn't been requested already.

Here are some commonly requested features that we have chosen not to support at this time.

• Bindless:

  Supporting bindless rendering would require large modifications to all GPU backends and shader tooling, and supporting bindless in a way that wouldn't cause a confusing mess across the rest of the GPU API would be a significant challenge and time investment. The only technique that absolutely requires bindless is hardware raytracing, which is also unlikely to be supported by the GPU API any time soon. Furthermore, the tooling for debugging bindless renderers is quite immature at this time.

  Binding resources to make them available to the shader was the only way to write renderers for 20+ years and even today only a minority of shipped games use this feature.

  It is far more likely that we will just design SDL4 around bindless rather than graft it onto the SDL3 version of the API.

• Tessellation Shaders:

  Tessellation shaders are currently being made obsolete by mesh shaders. They are known to cause performance issues on specific platforms. Once a large majority of hardware supports mesh shaders, we will just add support for those instead.

All wiki content is licensed under Creative Commons Attribution 4.0 International (CC BY 4.0).
Wiki powered by ghwikipp.