SDL is the Simple DirectMedia Layer. From the SDL homepage - "Simple DirectMedia Layer is a cross-platform multimedia library designed to provide level access to audio, keyboard, mouse, joystick, 3D hardware via OpenGL, and 2D video framebuffer." In addition to the SDL Homepage, you can also see the SDL Documentation Wiki for API documentation.

Under Linux, you can either install the appropriate libraries and development packages using RPMs or DEBs, or you can make your own by downloading the source from here and building the package according to their instructions.

With Debian or Ubuntu, the following packages should be enough for a start: libsdl1.2debian libsdl1.2-dev libsdl-ttf2.0-dev. This should trigger the installation of other dependencies and give something functional.

You're now ready to compile your first SDL program.

Your first program with SDL

Here's a breakdown of what's happening in the sample program.

  1. First, we initialize the SDL video system with SDL_Init().
  2. Next, we set the title for our application window.
  3. Then we create the window and get a pointer to the surface with SDL_SetVideoMode().
  4. The background image is loaded on to a temporary surface.
  5. SDL_DisplayFormat() creates a copy of the temporary surface using the same bit-depth as the screen surface. This will speed up rendering.
  6. The memory for the temporary surface is freed with a call to SDL_FreeSurface().
  7. Now we enter the "main loop" of the program. Here we check for events and then update the screen.
  8. When the user presses ESC or 'q', we end the "main loop"
  9. Before the program ends we free the memory for the background surface with SDL_FreeSurface, and cleanup SDL with SDL_Quit().

Save this file as sdltest.c. You'll also need the bitmap file that goes with this program. It's available for download with the source code at the bottom of this page.

#include <SDL.h>

int main( int argc, char* argv[] )
{
    /* initialize SDL */
    SDL_Init(SDL_INIT_VIDEO);

    /* set the title bar */
    SDL_WM_SetCaption("SDL Test", "SDL Test");

    /* create window */
    SDL_Surface* screen = SDL_SetVideoMode(640, 480, 0, 0);

    /* load bitmap to temp surface */
    SDL_Surface* temp = SDL_LoadBMP("sdl_logo.bmp");

    /* convert bitmap to display format */
    SDL_Surface* bg = SDL_DisplayFormat(temp);

    /* free the temp surface */
    SDL_FreeSurface(temp);

    SDL_Event event;
    int gameover = 0;

    /* main loop: check events and re-draw the window until the end */
    while (!gameover)
    {
        /* look for an event */
        if (SDL_PollEvent(&event)) {
            /* an event was found */
            switch (event.type) {
                /* close button clicked */
                case SDL_QUIT:
                    gameover = 1;
                    break;

                /* handle the keyboard */
                case SDL_KEYDOWN:
                    switch (event.key.keysym.sym) {
                        case SDLK_ESCAPE:
                        case SDLK_q:
                            gameover = 1;
                            break;
                        /* do nothing for other keys */
                        default:
                            break;
                    }
                    break;
            }
        }

        /* draw the background */
        SDL_BlitSurface(bg, NULL, screen, NULL);

        /* update the screen */
        SDL_UpdateRect(screen, 0, 0, 0, 0);
    }

    /* free the background surface */
    SDL_FreeSurface(bg);

    /* cleanup SDL */
    SDL_Quit();

    return 0;
}

Note, there is no error checking in this program. If something fails, it will be hard to track down. I left out the error checking just to make the program shorter and easier to follow. In a real program you should check the return values of all the SDL function calls.

Compiling

On Linux you can compile this program by typing this command:

gcc -Wall -g -std=c99 sdltest.c `sdl-config --cflags --libs` -o sdltest

Then run the program by typing:

./sdltest

If everything worked correctly, a 640x480 window should open and display the SDL logo.

Downloads