Detecting and Managing Errors

Discover techniques for detecting and responding to SDL runtime errors

Ryan McCombe
Updated

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 pass the SDL_WINDOW_METAL flag to SDL_CreateWindow():

#include <SDL.h>

int main(int argc, char** argv) {
  SDL_Init(SDL_INIT_VIDEO);
  SDL_Window* Window{SDL_CreateWindow(
    "Hello World",
    SDL_WINDOWPOS_UNDEFINED,
    SDL_WINDOWPOS_UNDEFINED,
    1024, 768,
    SDL_WINDOW_METAL
  )};
  
  SDL_DestroyWindow(Window);
  SDL_Quit();
  return 0;
}

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 cover 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:

#include <SDL.h>
#include <iostream>

int main(int argc, char** argv) {
  SDL_Init(SDL_INIT_VIDEO);
  SDL_Window* Window{SDL_CreateWindow(
    "Hello World",
    SDL_WINDOWPOS_UNDEFINED,
    SDL_WINDOWPOS_UNDEFINED,
    1024, 768,
    SDL_WINDOW_METAL
  )};

  std::cout << SDL_GetError();
  
  SDL_DestroyWindow(Window);
  SDL_Quit();
  return 0;
}
Metal 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 window:

#include <SDL.h>
#include <iostream>

int main(int argc, char** argv) {
  SDL_Init(SDL_INIT_VIDEO);
  SDL_Window* Window{SDL_CreateWindow(
    "Hello World",
    SDL_WINDOWPOS_UNDEFINED,
    SDL_WINDOWPOS_UNDEFINED,
    1024, 768,
    SDL_WINDOW_METAL 
  )};

  SDL_GetWindowSurface(Window);

  std::cout << SDL_GetError();
  
  SDL_DestroyWindow(Window);
  SDL_Quit();
  return 0;
}

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

Invalid 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:

#include <SDL.h>
#include <iostream>

int main(int argc, char** argv) {
  SDL_Init(SDL_INIT_VIDEO);
  SDL_GetWindowSurface(nullptr);

  std::cout << SDL_GetError() << '\n';
  std::cout << SDL_GetError() << '\n';
  std::cout << SDL_GetError() << '\n';

  SDL_Quit();
  return 0;
}
Invalid window
Invalid window
Invalid 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 char* - that is, a pointer to an individual character (char):

const 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:

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:

#include <SDL.h>
#include <iostream>

int main(int argc, char** argv){
  SDL_Init(SDL_INIT_VIDEO);

  const char* Error{SDL_GetError()};
  if (*Error == '\0') {
    std::cout << "There is no error";
  } else {
    std::cout << "Error: " << Error;
  }

  SDL_Quit();
  return 0;
}
There 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:

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

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

const char* Error{SDL_GetError()};
bool isEmpty{*Error == '\0'};

std::string Error{SDL_GetError()};
bool isEmpty{Error.empty()};

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

#include <SDL.h>
#include <iostream>

int main(int argc, char** argv) {
  SDL_Init(SDL_INIT_VIDEO);

  std::string Error{SDL_GetError()};
  if (Error.empty()) {
    std::cout << "There is no error";
  } else {
    std::cout << "Error: " << Error;
  }
  
  SDL_Quit();
  return 0;
}
There 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:

std::string SomeString{"Hello"};
const 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 char*:

#include <SDL.h>
#include <string>

int main(int argc, char** argv) {
  SDL_Init(SDL_INIT_VIDEO);

  std::string GameName{"My Game"}; 
  SDL_Window* Window{SDL_CreateWindow(
    GameName.c_str(), 
    SDL_WINDOWPOS_UNDEFINED,
    SDL_WINDOWPOS_UNDEFINED,
    1024, 768, 0
  )};

  SDL_DestroyWindow(Window);
  SDL_Quit();
  return 0;
}

Our advanced course has a dedicated chapter that goes much deeper on C-style strings and std::string. That chapter starts here:

Characters, Unicode and Encoding

An introduction to C++ character types, the Unicode standard, character encoding, and C-style strings

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 occured between the SDL_ClearError() call and the next SDL_GetError() call:

#include <SDL.h>
#include <iostream>

int main(int argc, char** argv) {
  SDL_Init(SDL_INIT_VIDEO);
  SDL_GetWindowSurface(nullptr);
  std::cout << "Error: " << SDL_GetError();
  SDL_ClearError();
  std::cout << "\nError: " << SDL_GetError();

  SDL_Quit();
  return 0;
}
Error: Invalid window
Error:

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_Error() 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()
// ErrorHandling.h
#pragma once
#include <SDL.h>
#include <iostream>

void CheckSDLError(const std::string& Action) {
  const char* Error{SDL_GetError()};
  if (*Error != '\0') {
    std::cout << Action << " Error: "
      << Error << '\n';
    SDL_ClearError();
  }
}

We can use it like this:

#include <SDL.h>
#include <iostream>
#include "ErrorHandling.h"

int main(int argc, char** argv) {
  SDL_Init(SDL_INIT_VIDEO);
  SDL_Window* Window{SDL_CreateWindow(
    "Hello World",
    SDL_WINDOWPOS_UNDEFINED,
    SDL_WINDOWPOS_UNDEFINED,
    1024, 768,
    SDL_WINDOW_METAL 
  )};
  CheckSDLError("Creating Window");

  SDL_GetWindowSurface(Window);
  CheckSDLError("Getting Surface");

  std::cout << "Hello World\n";
  // No error has occurred since the last call
  // to CheckSDLError, so this won't log anything
  CheckSDLError("Saying Hello");

  SDL_DestroyWindow(Window);
  SDL_Quit();
  return 0;
}
Creating Window Error: Metal support is either not configured in SDL or not available in current SDL video driver (windows) or platform
Getting Surface Error: Invalid window
Hello World

Toggling Error Logs at Build Time

We may want to disable calls to this function in our final released games, so 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:

// ErrorHandling.h
#pragma once
#include <SDL.h>
#include <iostream>

// Define me to enable error logging:
#define ERROR_LOGGING

void CheckSDLError(const std::string& Action) {
#ifdef ERROR_LOGGING
  const char* Error{SDL_GetError()};
  if (*Error != '\0') {
    std::cout << Action << " Error: "
      << Error << '\n';
    SDL_ClearError();
  }
#endif
}

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:

#include <SDL.h>
#include <iostream>

int main(int argc, char** argv) {
  SDL_Init(SDL_INIT_VIDEO);
  SDL_Window* Window{SDL_CreateWindow(
    "Hello World",
    SDL_WINDOWPOS_UNDEFINED,
    SDL_WINDOWPOS_UNDEFINED,
    1024, 768,
    SDL_WINDOW_METAL 
  )};

  if (!Window) {
    std::cout << "Couldn't create window -"
                 "trying without Metal\n";

    Window = SDL_CreateWindow(
      "Hello World",
      SDL_WINDOWPOS_UNDEFINED,
      SDL_WINDOWPOS_UNDEFINED,
      1024, 768,
      0 
    );
  }

  if (Window) {
    std::cout << "Window created successfully";
    SDL_ClearError();
  }

  SDL_DestroyWindow(Window);
  SDL_Quit();
  return 0;
}
Couldn't create window - trying without Metal
Window created successfully

Other functions that report errors will typically do so through an integer they return, with negative values indicating an error. For example, SDL_Init() returns 0 if it was successful, or a negative value if it failed:

#include <SDL.h>
#include <iostream>

int main(int argc, char** argv) {
  if (SDL_Init(SDL_INIT_VIDEO) < 0) {
    std::cout << "Init failed: "
              << SDL_GetError();
  }

  SDL_Quit();
  return 0;
}

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:

#include <SDL.h>
#include <iostream>

int Divide(int a, int b) {
  if (b == 0) {
    SDL_SetError("Cannot divide by 0");
    return 0;
  }
  return a / b;
}

int main(int argc, char** argv) {
  SDL_Init(SDL_INIT_VIDEO);
  Divide(2, 0);
  std::cout << SDL_GetError();
  // Alternatively, using the function
  // we created earlier:
  // CheckSDLError("Dividing");

  SDL_Quit();
  return 0;
}
Cannot divide by 0

Summary

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

  • How to use SDL_GetError() to retrieve error messages
  • An introduction to working with C-style strings, and how they interact with std::string
  • The use of SDL_ClearError() to manage the error state
  • How to implement custom error handling functions
  • How to check for specific errors by examining the return values from SDL functions
  • Calling SDL_SetError() to use SDL to handle our own custom error states
Next Lesson
Lesson 20 of 129

Implementing an Application Loop

Step-by-step guide on creating the SDL2 application and event loops for interactive games

Questions & Answers

Answers are generated by AI models and may not have been reviewed. Be mindful when running any code on your device.

SDL_GetError() Behavior in Multi-threaded Applications
Does SDL_GetError() work correctly if multiple SDL errors happen in different threads?
Safely Converting SDL char* Errors to std::string
How can I convert an SDL error char* to a std::string safely?
Interaction Between SDL_SetError() and Internal SDL Errors
How does SDL_SetError() interact with errors generated by SDL itself?
Effect of SDL_ClearError() on SDL Function Return Values
Does calling SDL_ClearError() affect the return values of SDL functions?
Obtaining Detailed Error Information (e.g., Stack Traces) with SDL
How can I get more detailed error information, like a stack trace?
Common Reasons for SDL_Init() Failure
What are common reasons for SDL_Init() to fail?
Implementing Custom SDL Error Logging
How can I implement a custom error logging system that writes SDL errors to a file instead of the console?
SDL Error Handling in Multi-threaded Apps
What's the best way to handle SDL errors in a multi-threaded application?
Global Error Handling in SDL Applications
Is it possible to set up a global try-catch block to handle SDL errors throughout my entire application?
Efficient Error Handling in SDL Game Loops
What's the most efficient way to handle errors in a game loop without significantly impacting performance?
Categorizing SDL Errors
Is there a way to categorize SDL errors and handle them differently based on their severity?
Or Ask your Own Question
Get an immediate answer to your specific question using our AI assistant