Interaction Between SDL_SetError() and Internal SDL Errors

SDL_SetError() and the error-setting mechanisms within SDL functions operate on the same thread-local error state. This means they will overwrite each other.

1. SDL_SetError() Overwrites SDL Errors: If an SDL function fails and sets an error message (e.g., "Invalid window"), and you subsequently call SDL_SetError("My custom error") on the same thread before calling SDL_GetError(), your custom message will replace the one set by SDL. SDL_GetError() will then return "My custom error".
2. SDL Errors Overwrite SDL_SetError()__: Conversely, if you call SDL_SetError("My custom error") and then call an SDL function that fails on the same thread, that function will typically overwrite your custom message with its own specific error description. SDL_GetError() will then return the error message from the failed SDL function.

SDL_GetError() always returns the most recently set error message for the current thread, regardless of whether it was set via SDL_SetError() or internally by another SDL function.

1#include <SDL.h>
2#include <iostream>
3#include <string>
4
5int main(int argc, char* argv[]) {
6  SDL_Init(SDL_INIT_VIDEO);
7
8  // 1. SDL Error occurs
9  SDL_SetRenderDrawColor(nullptr, 255, 0, 0, 255); 
10  std::cout << "After SDL Error: "
11            << SDL_GetError() << '\n';
12
13  // 2. SDL_SetError overwrites the SDL Error
14  SDL_SetError("This is my custom error message.");
15  std::cout << "After SetError: "
16            << SDL_GetError() << '\n';
17
18  // 3. Another SDL Error overwrites the custom error
19  SDL_RenderFillRect(nullptr, nullptr); 
20  std::cout << "After 2nd SDL Error: "
21            << SDL_GetError() << '\n';
22
23  SDL_Quit();
24  return 0;
25}

1After SDL Error: Invalid renderer
2After SetError: This is my custom error message.
3After 2nd SDL Error: Invalid renderer

This behavior means SDL_SetError() is primarily useful for:

• Integrating your own non-SDL library errors into the SDL error reporting mechanism for consistency.
• Providing more context-specific error messages within your wrapper functions around SDL calls, potentially after checking an SDL error but before returning control.

Be mindful that any subsequent SDL call on the same thread that fails might erase the custom error you just set. If you need to preserve your custom error message alongside potential subsequent SDL errors, you'd need to store it separately (e.g., in your own variable or logging system) immediately after calling SDL_SetError().