As with any code, interacting with SDL can sometimes result in errors. For example, let's imagine we're trying to create a window that uses Metal, which is Apple's API for creating high-performance graphics.

To do this, we can pass the SDL_WINDOW_METAL flag to SDL_CreateWindow():

1#include <SDL3/SDL.h>
2#include <SDL3/SDL_main.h>
3
4int main(int, char**) {
5  SDL_Init(SDL_INIT_VIDEO);
6  SDL_Window* Window{SDL_CreateWindow(
7    "Hello World",
8    1024, 768,
9    SDL_WINDOW_METAL
10  )};
11
12  if (Window) {
13    SDL_DestroyWindow(Window);
14  }
15  SDL_Quit();
16  return 0;
17}

If this program is run on a platform that doesn't support Metal (such as a Windows machine), window creation will fail, and it might not be obvious why that is.

In this lesson, we'll introduce the ways we can detect and recover from errors coming from SDL.

Retrieving Error Messages

The SDL_GetError() function is the main way we retrieve information about errors coming from SDL. It returns a string, representing the most recent error that occurred.

If we call this function after attempting to create our window, we'll get more information about what's going wrong:

src/main.cpp

1#include <SDL3/SDL.h>
2#include <SDL3/SDL_main.h>
3#include <iostream>
4
5int main(int, char**) {
6  SDL_Init(SDL_INIT_VIDEO);
7  SDL_Window* Window{SDL_CreateWindow(
8    "Hello World",
9    1024, 768,
10    SDL_WINDOW_METAL
11  )};
12
13  std::cout << SDL_GetError();
14
15  if (Window) {
16    SDL_DestroyWindow(Window);
17  }
18  SDL_Quit();
19  return 0;
20}

1Metal support is either not configured in SDL or not available in current SDL video driver (windows) or platform

SDL_GetError() can only return the most recent error message. In the following example, we have two errors - one when we create the window, as before, and a second error when we then try to get the surface associated with that (non-existent) window:

src/main.cpp

1#include <SDL3/SDL.h>
2#include <SDL3/SDL_main.h>
3#include <iostream>
4
5int main(int, char**) {
6  SDL_Init(SDL_INIT_VIDEO);
7  SDL_Window* Window{SDL_CreateWindow(
8    "Hello World",
9    1024, 768,
10    SDL_WINDOW_METAL 
11  )};
12
13  SDL_GetWindowSurface(Window);
14
15  std::cout << SDL_GetError();
16
17  if (Window) {
18    SDL_DestroyWindow(Window);
19  }
20  SDL_Quit();
21  return 0;
22}

When we called SDL_GetError(), the most recent error was from the SDL_GetWindowSurface() call. SDL_CreateWindow() failed, but information about that error was overwritten by the error from SDL_GetWindowSurface():

1Invalid window

Additionally, SDL_GetError() does not clear the error state. Subsequent calls to SDL_GetError() will return the same message until a new error occurs:

src/main.cpp

1#include <SDL3/SDL.h>
2#include <SDL3/SDL_main.h>
3#include <iostream>
4
5int main(int, char**) {
6  SDL_Init(SDL_INIT_VIDEO);
7  SDL_GetWindowSurface(nullptr);
8
9  std::cout << SDL_GetError() << '\n';
10  std::cout << SDL_GetError() << '\n';
11  std::cout << SDL_GetError() << '\n';
12
13  SDL_Quit();
14  return 0;
15}

1Invalid window
2Invalid window
3Invalid window

The `char*` Data Type

In previous lessons, we've been using std::string when working with strings of text. SDL uses a more primitive type, sometimes called a C-style string.

Its specific type is a const char* - that is, a pointer to an individual character (char) that we cannot modify:

1const char* Error = SDL_GetError();

Like any pointer, a char* represents a location in memory. In this case, it represents the first character in the string.

Subsequent characters are then stored in subsequent memory addresses, until we encounter a special character that is designed to represent the end of the string. That special character is called the null terminator and is typically represented as a backslash followed by 0: \0:

Diagram showing a character pointer pointing at a c-string in memory

Through this simple convention, a single memory address can represent strings of any length. If the first character in a string is the null terminator \0, that is equivalent to the string being empty:

src/main.cpp

1#include <SDL3/SDL.h>
2#include <SDL3/SDL_main.h>
3#include <iostream>
4
5int main(int, char**){
6  SDL_Init(SDL_INIT_VIDEO);
7
8  const char* Error{SDL_GetError()};
9  if (*Error == '\0') {
10    std::cout << "There is no error";
11  } else {
12    std::cout << "Error: " << Error;
13  }
14
15  SDL_Quit();
16  return 0;
17}

1There is no error

C-Style Strings and `std::string`

C-Style strings are primitive, and working with raw memory addresses is error-prone. Often, we'll want to use a more powerful and modern string representation, such as std::string, in our projects. This means we need to deal with conversions between std::string and char* when interacting with the SDL API.

std::string has a constructor that accepts a char*, so converting a string returned from SDL to a std::string is easy:

1const char* Error{SDL_GetError()};
2std::string Error{SDL_GetError()};

The std::string type also has a much friendlier API:

1const char* Error{SDL_GetError()};
2bool isEmpty{*Error == '\0'};
3
4std::string Error{SDL_GetError()};
5bool isEmpty{Error.empty()};

Updating our earlier code to use a std::string might look like this:

src/main.cpp

1#include <SDL3/SDL.h>
2#include <SDL3/SDL_main.h>
3#include <iostream>
4#include <string>
5
6int main(int, char**) {
7  SDL_Init(SDL_INIT_VIDEO);
8
9  std::string Error{SDL_GetError()};
10  if (Error.empty()) {
11    std::cout << "There is no error";
12  } else {
13    std::cout << "Error: " << Error;
14  }
15
16  SDL_Quit();
17  return 0;
18}

1There is no error

When we have a std::string and need an equivalent char* to pass to some SDL function, the c_str() method can help us:

1std::string SomeString{"Hello"};
2const char* SomeCString{SomeString.c_str()};

SDL_CreateWindow() is an example of where this might be needed, as the window title needs to be provided as a const char*:

src/main.cpp

1#include <SDL3/SDL.h>
2#include <SDL3/SDL_main.h>
3#include <string>
4
5int main(int, char**) {
6  SDL_Init(SDL_INIT_VIDEO);
7
8  std::string GameName{"My Game"}; 
9  SDL_Window* Window{SDL_CreateWindow(
10    GameName.c_str(), 
11    1024, 768, 0
12  )};
13
14  if (Window) {
15    SDL_DestroyWindow(Window);
16  }
17  SDL_Quit();
18  return 0;
19}

We cover C-style strings and std::string in much more detail in our lesson on .

Clearing Errors

Once we've processed and acknowledged an error, we can call SDL_ClearError().

This will cause SDL_GetError() to return an empty string, unless another error has occurred between the SDL_ClearError() call and the next SDL_GetError() call:

src/main.cpp

1#include <SDL3/SDL.h>
2#include <SDL3/SDL_main.h>
3#include <iostream>
4
5int main(int, char**) {
6  SDL_Init(SDL_INIT_VIDEO);
7  SDL_GetWindowSurface(nullptr);
8  std::cout << "Error: " << SDL_GetError();
9  SDL_ClearError();
10  std::cout << "\nError: " << SDL_GetError();
11
12  SDL_Quit();
13  return 0;
14}

1Error: Invalid window
2Error:

Creating an Error Handler

If we're going to be doing a lot of error checking, it can be helpful to create a simple function that makes this easier. The following function:

Accepts a string, letting the caller explain what action is associated with the error check
If SDL_GetError() returns a non-empty string, it logs that error, as well as the action that caused it for context
Clears SDL's error string using SDL_ClearError()

Files

src

Select a file to view its content

We can use it like this:

src/main.cpp

1#include <SDL3/SDL.h>
2#include <SDL3/SDL_main.h>
3#include <iostream>
4#include "ErrorHandling.h"
5
6int main(int, char**) {
7  SDL_Init(SDL_INIT_VIDEO);
8  SDL_Window* Window{SDL_CreateWindow(
9    "Hello World",
10    1024, 768,
11    SDL_WINDOW_METAL 
12  )};
13  CheckSDLError("Creating Window");
14
15  SDL_GetWindowSurface(Window);
16  CheckSDLError("Getting Surface");
17
18  std::cout << "Hello World\n";
19  // No error has occurred since the last call
20  // to CheckSDLError, so this won't log anything
21  CheckSDLError("Saying Hello");
22
23  if (Window) {
24    SDL_DestroyWindow(Window);
25  }
26  SDL_Quit();
27  return 0;
28}

1Creating Window Error: Metal support is either not configured in SDL or not available in current SDL video driver (windows) or platform
2Getting Surface Error: Invalid window
3Hello World

Toggling Error Logs at Build Time

We may want to disable calls to this function in our final released games. We can have the preprocessor include them only if some macro, such as ERROR_LOGGING, is defined.

This definition would typically be set through our build management tools but, for this example, we'll just define it in our code file:

src/ErrorHandling.h

1#pragma once
2#include <SDL3/SDL.h>
3#include <iostream>
4#include <string>
5
6// Define me to enable error logging:
7#define ERROR_LOGGING
8
9void CheckSDLError(const std::string& Action) {
10#ifdef ERROR_LOGGING
11  const char* Error{SDL_GetError()};
12  if (*Error != '\0') {
13    std::cout << Action << " Error: "
14      << Error << '\n';
15    SDL_ClearError();
16  }
17#endif
18}

Invoking Empty Functions

Our previous example removes the entire body of our function if ERROR_LOGGING is not defined. This means that any calls to that function would be invoking an empty function.

You may also wish to remove those calls using a similar #ifdef check:

src/main.cpp

1#include <SDL3/SDL.h>
2#include <SDL3/SDL_main.h>
3#include "ErrorHandling.h"
4
5int main(int, char**) {
6  SDL_Init(SDL_INIT_VIDEO);
7  SDL_Window* Window{SDL_CreateWindow(
8    "Hello World",
9    1024, 768,
10    SDL_WINDOW_METAL 
11  )};
12
13#ifdef ERROR_LOGGING 
14  CheckSDLError("Creating Window");
15#endif 
16
17  if (Window) {
18    SDL_DestroyWindow(Window);
19  }
20  SDL_Quit();
21  return 0;
22}

Naturally, whether we do this or not doesn't affect the behavior, as invoking a function that does nothing is equivalent to not invoking a function.

However, it may be worth adding these #ifdef checks anyway, as it makes it clearer to anyone reading the code that this behavior is only applied in a specific situation.

Our decision here is unlikely to change the performance characteristics, as compilers and linkers will typically detect and remove calls to empty functions when we build our final, performance-optimized game.

This process is called whole program optimization (WPO) and link-time optimization (LTO). More details can be found on Wikipedia.

Detecting Specific Errors

In most advanced programs, our error handling will often want to go beyond simply logging out what went wrong. We'll often want to implement logic that reacts and potentially recovers from certain types of errors.

In addition to updating the string returned by SDL_GetError(), SDL functions will often use their return values to indicate something went wrong.

We need to refer to the official documentation for information on any specific function. However, as a general pattern, functions that return a pointer, such as SDL_CreateWindow(), will return a nullptr if something went wrong:

src/main.cpp

1#include <SDL3/SDL.h>
2#include <SDL3/SDL_main.h>
3#include <iostream>
4
5int main(int, char**) {
6  SDL_Init(SDL_INIT_VIDEO);
7  SDL_Window* Window{SDL_CreateWindow(
8    "Hello World",
9    1024, 768,
10    SDL_WINDOW_METAL 
11  )};
12
13  if (!Window) {
14    std::cout << "Couldn't create window -"
15                 " trying without Metal\n";
16
17    Window = SDL_CreateWindow(
18      "Hello World",
19      1024, 768,
20      0
21    );
22  }
23
24  if (Window) {
25    std::cout << "Window created successfully\n";
26    SDL_ClearError();
27    SDL_DestroyWindow(Window);
28  }
29
30  SDL_Quit();
31  return 0;
32}

1Couldn't create window - trying without Metal
2Window created successfully

Other functions that can fail will typically return a boolean value. For example, SDL_Init() will return true if it was successful, and false otherwise:

src/main.cpp

1#include <SDL3/SDL.h>
2#include <SDL3/SDL_main.h>
3#include <iostream>
4
5int main(int, char**) {
6  if (!SDL_Init(SDL_INIT_VIDEO)) {
7    std::cout << "Init failed: "
8              << SDL_GetError();
9  }
10
11  SDL_Quit();
12  return 0;
13}

Setting Custom Errors

While SDL_SetError() is primarily used internally by SDL functions, we can also use it in our own code if we want to use SDL's error reporting system.

This can be useful when we want to use a consistent error-handling mechanism throughout our project, even for non-SDL related errors:

src/main.cpp

1#include <SDL3/SDL.h>
2#include <SDL3/SDL_main.h>
3#include <iostream>
4
5int Divide(int a, int b) {
6  if (b == 0) {
7    SDL_SetError("Cannot divide by 0");
8    return 0;
9  }
10  return a / b;
11}
12
13int main(int, char**) {
14  SDL_Init(SDL_INIT_VIDEO);
15  Divide(2, 0);
16  std::cout << SDL_GetError();
17  // Alternatively, using the function
18  // we created earlier:
19  // CheckSDLError("Dividing");
20
21  SDL_Quit();
22  return 0;
23}

1Cannot divide by 0

Summary

In this lesson, we've explored techniques for handling errors when working with SDL3. We learned:

How to use SDL_GetError() to retrieve human-readable error messages.
An introduction to working with C-style strings (char*) and how they interact with std::string.
The use of SDL_ClearError() to reset the internal error state.
How to implement a custom error handling function to streamline error checking.
How to detect specific errors by examining the return values from SDL functions, such as nullptr for pointers and false for functions that return a bool.
How SDL_SetError() can be used to integrate our custom errors into SDL's system.

Detecting and Managing Errors in SDL3

Retrieving Error Messages

src/main.cpp

src/main.cpp

src/main.cpp

The `char*` Data Type

src/main.cpp

C-Style Strings and `std::string`

src/main.cpp

src/main.cpp

Clearing Errors

src/main.cpp

Creating an Error Handler

Files

src/main.cpp

Toggling Error Logs at Build Time

src/ErrorHandling.h

Detecting Specific Errors

src/main.cpp

src/main.cpp

Setting Custom Errors

src/main.cpp

Summary

Implementing an Application Loop

Game Development with SDL3

Detecting and Managing Errors in SDL3

Retrieving Error Messages

src/main.cpp

src/main.cpp

src/main.cpp

The char* Data Type

src/main.cpp

C-Style Strings and std::string

src/main.cpp

src/main.cpp

Clearing Errors

src/main.cpp

Creating an Error Handler

Files

src/main.cpp

Toggling Error Logs at Build Time

src/ErrorHandling.h

Detecting Specific Errors

src/main.cpp

src/main.cpp

Setting Custom Errors

src/main.cpp

Summary

Implementing an Application Loop

The `char*` Data Type

C-Style Strings and `std::string`