SDL (Simple DirectMedia Layer) - Basics

Getting started

In this section, we will show you how to initialise and shutdown SDL subsystems.

#include <stdio.h> /* printf and fprintf */

#ifdef _WIN32
#include <SDL/SDL.h> /* Windows-specific SDL2 library */
#else
#include <SDL2/SDL.h> /* macOS- and GNU/Linux-specific */
#endif
 
int main (int argc, char **argv)
{
  /*
  * Initialises the SDL video subsystem (as well as the events subsystem).
  * Returns 0 on success or a negative error code on failure using SDL_GetError().
  */
  if (SDL_Init(SDL_INIT_VIDEO) != 0)
  {
    fprintf(stderr, "SDL failed to initialise: %s\n", SDL_GetError());
    return 1;
  }
 	
  printf("SDL initialised!");

  /* Shuts down all SDL subsystems */
  SDL_Quit(); 
  
  return 0;
}

^{You can download the source code of this section in this GitLab repository. All source code is stored in this group.}

Linking SDL2 libraries

The basic functions required for SDL2 is either in the <SDL/SDL.h> library or <SDL2/SDL.h> library depending on the operating system, hence the above source code uses

#ifdef _WIN32
#include <SDL/SDL.h> /* Windows-specific SDL2 library */
#else
#include <SDL2/SDL.h> /* macOS- and GNU/Linux-specific */
#endif

main macro in Windows

When writing code for Windows machines, it is necessary to include

int main (int argc, char **argv)

since SDL overwrites the main macro. According to SDL's FAQWindows:

You should be using main() instead of WinMain() even though you are creating a Windows application, because SDL provides a version of WinMain() which performs some SDL initialization before calling your main code. If for some reason you need to use WinMain(), take a look at the SDL source code in src/main/win32/SDL_main.c to see what kind of initialization you need to do in your WinMain() function so that SDL works properly.

Initialising SDL subsystems

When using a SDL subsystem, you must always initialise it first. In the following if-statement, we initialise the SDL video subsystem with the flag SDL_INIT_VIDEO. If it succeeds, it returns 0, otherwise it returns a negative error code and will print information about the error using SDL_GetError through the stderr stream.

/*
* Initialises the SDL video subsystem (as well as the events subsystem).
* Returns 0 on success or a negative error code on failure using SDL_GetError().
*/
if (SDL_Init(SDL_INIT_VIDEO) != 0)
{
  fprintf(stderr, "SDL failed to initialise: %s\n", SDL_GetError());
  return 1;
}

You can initialise multiple subsystems using the | operator:

if (SDL_Init(SDL_INIT_VIDEO | SDL_INIT_AUDIO) != 0)
{
  fprintf(stderr, "SDL failed to initialise: %s\n", SDL_GetError());
  return 1;
}

All information about the SDL_Init function subsystems, and their flags can be found in the SDL Wiki's SDL_Init page.

Shutting down SDL subsystems

To shut down the SDL subsystems, you must execute

SDL_Quit();

However, this will only shut down the main subsystems; shutting down the TTF subsystem requires a different function

TTF_Quit();

Setting up on various operating systems

Getting started in Windows

SDL (Simple DirectMedia Layer)/Basics/Getting started in Windows

Getting started in macOS

SDL (Simple DirectMedia Layer)/Basics/Getting started in macOS

Getting started in Linux

Install the development libraries of SDL from the official repositories of your Linux distribution.

Terminal

$ gcc sdl.c -o sdl -lSDL2

The argument -lSDL2 means after compiling sdl.c with gcc, the binary sdl, named using the -o argument, is linked to the SDL 2 runtime libraries.

NOTE: Linking the binary to SDL 1.2 libraries requires the -lSDL argument.

To continue using the terminal to build your source, you can use GNU Make, CMake or a plain Makefile.

Creating a window

In this section, we will demonstrate how to create and destroy basic SDL windows. The following code will create a window called "SDL Example", 800 by 600 pixels in width and height respectively, and print it on the screen for 3000 miliseconds.

#include <stdio.h> /* printf and fprintf */

#ifdef _WIN32
#include <SDL/SDL.h> /* Windows-specific SDL2 library */
#else
#include <SDL2/SDL.h> /* macOS- and GNU/Linux-specific */
#endif

/* Sets constants */
#define WIDTH 800
#define HEIGHT 600
#define DELAY 3000

int main (int argc, char **argv)
{
  /* Initialises data */
  SDL_Window *window = NULL;
  
  /*
  * Initialises the SDL video subsystem (as well as the events subsystem).
  * Returns 0 on success or a negative error code on failure using SDL_GetError().
  */
  if (SDL_Init(SDL_INIT_VIDEO) != 0) {
    fprintf(stderr, "SDL failed to initialise: %s\n", SDL_GetError());
    return 1;
  }

  /* Creates a SDL window */
  window = SDL_CreateWindow("SDL Example", /* Title of the SDL window */
			    SDL_WINDOWPOS_UNDEFINED, /* Position x of the window */
			    SDL_WINDOWPOS_UNDEFINED, /* Position y of the window */
			    WIDTH, /* Width of the window in pixels */
			    HEIGHT, /* Height of the window in pixels */
			    0); /* Additional flag(s) */

  /* Checks if window has been created; if not, exits program */
  if (window == NULL) {
    fprintf(stderr, "SDL window failed to initialise: %s\n", SDL_GetError());
    return 1;
  }

  /* Pauses all SDL subsystems for a variable amount of milliseconds */
  SDL_Delay(DELAY);

  /* Frees memory */
  SDL_DestroyWindow(window);
  
  /* Shuts down all SDL subsystems */
  SDL_Quit(); 
  
  return 0;
}

^{You can download the source code of this section in this GitLab repository. All source code is stored in this group.}

Setting up data

In order to create the window, we need to specify its height and width. In this case we define the global constants using a macro. We'll make the width 800 pixels long and the height 600 pixels high.

#define WIDTH 800
#define HEIGHT 600

In this program, we will have to pause the SDL subsystems to let the window stay open. We'll define the delay to be 3000 milliseconds.

#define DELAY 3000

In C, it's a good idea to initialise your variables first in order to understand when and how they are being used. In this case, we initialise a SDL_Window pointer called window. In SDL, almost all objects are initialised as pointers.

SDL_Window *window = NULL;

Creating the window

In order to create the window, we need to use the SDL_CreateWindow function and set some parameters too.

window = SDL_CreateWindow("SDL Example", /* Title of the SDL window */
			  SDL_WINDOWPOS_UNDEFINED, /* Position x of the window */
			  SDL_WINDOWPOS_UNDEFINED, /* Position y of the window */
			  WIDTH, /* Width of the window in pixels */
			  HEIGHT, /* Height of the window in pixels */
			  0); /* Additional flag(s) */

You can learn more about SDL_CreateWindow in the SDL Wiki.

Using SDL_Delay

In the example code, we used the function SDL_Delay in order to pause the SDL subsystems for a variable amount of time in milliseconds and allow the window to be shown on the screen whilst it is open. In this case, the pause is defined with the DELAY macro as being 3000 milliseconds.

SDL_Delay(DELAY);

You can learn more about SDL_Delay in the SDL Wiki.

Destroying the window

In order to close the window and free memory, we must destroy the window. Destroying window is much simpler than creating it.

SDL_DestroyWindow(window);

You can learn more about SDL_DestroyWindow in the SDL Wiki.