SDL Quickstart for Linux: Empty Window

This short tutorial explains how to get started with SDL on Linux, by showing an empty Window. Once this is set up, you can go on to create 2D games or use SDL as a basis for OpenGL.

This tutorial is loosely based on Lazy Foo's "Getting an Image on the Screen" tutorial, but is intended to be more concise, link to reference material, apply directly to Linux, and teach additional items learned through experience.

Setting up

First of all you need to have the SDL development and runtime libraries installed on your system. You can find the SDL-related libraries using the command

apt-cache search sdl

This will give you a whole list of libraries. At the time of writing of this tutorial, the one you need is libsdl1.2-dev. Therefore, on Ubuntu or similar Debian-based Linux distributions, you would install SDL using the command:

sudo apt-get install libsdl1.2-dev

This will install the header files in /usr/include/SDL/ and also the shared libraries you need to run SDL applications (similar to the SDL.dll you need on Windows).

First SDL Application: Empty Window

Like with any C program, you start with a main() function and any necessary header inclusions. For SDL applications you need to include the SDL.h file, which contains all the functionality you will need:

#include <SDL/SDL.h>

int main(int argc, char * argv[])
{

    return 0;
}

In SDL programs, it is necessary to declare the main() function with arguments, as above. I have experienced errors in the past when compiling SDL programs with a main() function that did not account for command line parameter arguments (argc and argv).

The next step is to initialise the SDL library, and also prepare the cleanup function while you're at it. Other program code will go in between.

    SDL_Init(SDL_INIT_VIDEO);

    // other program code goes here

    SDL_Quit();

SDL_Init is the function that initialises SDL. As a parameter, it takes a number of flags which tell it what to initialise. Multiple flags may be used at once by using the bitwise OR operator (e.g. SDL_INIT_VIDEO | SDL_INIT_AUDIO). Although Lazy Foo's tutorial simply initialises everything, all you need for this simple tutorial is video display functionality.

SDL_Quit is a cleanup routine that you should use at the end of your SDL code, to free resources allocated by SDL_Init.

Between SDL_Init and SDL_Quit, you can now show your window. First declare relevant variables:

    int width = 640;
    int height = 480;
    int bpp = 32;
    Uint32 flags = SDL_SWSURFACE;

    SDL_Surface * screen = NULL;

Then actually show the screen, and clean up after. Program code will go in between.

    screen = SDL_SetVideoMode(width, height, bpp, flags);

    // program code goes here

    SDL_FreeSurface(screen);

SDL_SetVideoMode displays a window with the given parameters. SDL has the limitation that only one window can be displayed at any given time, so calling this function again will result in a new window drawn instead of the first one. As parameters, SDL_SetVideoMode takes the width and height of the window (in pixels), the bits per pixel (32 on modern systems - this is a measure of the graphical quality used) and a set of flags (refer to the function's documentation via the link). For the purpose of displaying something simple, you can use the SDL_SWSURFACE flag; however for complex applications such as OpenGL you will need to use more advanced options to optimise your program.

Handling the "X" to close the window

If you run your program now, a window will flash briefly on the screen and then disappear. This is because you are showing the window but have no code in place to keep it there. Lazy Foo's tutorial uses SDL_Delay to delay the disappearance of the window.

A better way is to handle events - something you will need to do anyway in your program. Games and other graphical applications generally run a game loop, i.e. they will keep running until something happens (e.g. you quit the game). In this case we want to handle the "X" at the top of the window, so that when a user clicks on it, the window closes - but otherwise the window remains. The following code will do the trick::

    int quit = 0;

    SDL_Event event;

    while (quit == 0)
    {
        SDL_WaitEvent(&event);

        switch(event.type)
        {
            case SDL_QUIT:
                quit = 1;
        }
    }

The code above runs the game loop, i.e. the window will remain visible as long as quit is zero. Using SDL_WaitEvent, the program sits idle until something happens. In this case we are taking action when the event is SDL_QUIT, i.e. the close-window "X" button has been clicked. At that point we set quit to one and let the program exit.

Interactive applications such as games normally use SDL_PollEvent to constantly check for events and update the game state. However, this is very CPU intensive, and for something as simple as this, SDL_WaitEvent is a better alternative. Note:  SDL_PollEvent can be combined with a small SDL_Delay to reduce the burden on CPU.

Compile and run

Save the code in a file called main.c. From your terminal, use the following command to compile your SDL application:

gcc main.c -lSDLmain -lSDL -o app

Run ./app to launch the application.

Full code (main.c)

#include <SDL/SDL.h>

int main(int argc, char * argv[])
{
    int width = 640;
    int height = 480;
    int bpp = 32;
    Uint32 flags = SDL_SWSURFACE;
    SDL_Event event;
    int quit = 0;

    SDL_Surface * screen = NULL;
    
    SDL_Init(SDL_INIT_VIDEO);
    
    screen = SDL_SetVideoMode(width, height, bpp, flags);
    
    while (quit == 0)
    {
        SDL_WaitEvent(&event);

        switch(event.type)
        {
            case SDL_QUIT:
                quit = 1;
        }
    }
    
    SDL_FreeSurface(screen);
    
    SDL_Quit();
    
    return 0;
}