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.

To get started using SDL, you'll first need to download some files from http://www.libsdl.org/download-1.2.php. If you're using Windows, all you need is the development package. As of writing this tutorial, that file was named SDL-devel-1.2.9-VC6.zip. Download this file and unzip it to a folder, I like to use "C:\Program Files\SDL-1.2.9". Now that you have installed the development package, the documentation is available at "C:\Program Files\SDL-1.2.9\docs\index.html".

If you're using 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.

Once you've downloaded and installed the development files on Linux, you're ready to start compiling programs. On Windows, there are a few more steps to perform:

  1. Open Visual C++ then go to Tools, Options.
  2. Double-click "Projects and Solutions".
  3. Click "VC++ Directories".
  4. Under "Show directories for:" choose "Include files".
  5. Add a new path "C:\Program Files\SDL-1.2.9\include".
  6. Under "Show directories for:" choose "Lib files".
  7. Add "C:\Program Files\SDL-1.2.9\lib".

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.cpp, or sdltest.c if you'd like to use straight C instead of 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;

  /* message pump */
  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;
          }
          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:

g++ sdltest.cpp `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.

In Visual C++ you'll need to follow these steps:

  1. Create a new empty Windows Application Project.
  2. Add the "sdltest.cpp" file to your project.
  3. On the menu click Project, then Properties.
  4. Double-click "Configuration Properties".
  5. Double-click "C/C++".
  6. Click "Code Generation".
  7. Change "Runtime Library" to "Multi-threaded DLL".
  8. Double-click "Linker".
  9. Click "Input".
  10. Beside "Additional Dependencies", type "sdl.lib sdlmain.lib".

At this point, you should be able to press F7 to Build the program.

Before we can run the program, you'll need to put the "SDL.dll" file where Windows can find it. Copy the file from "C:\Program Files\SDL-1.2.9" to your new Visual C++ project's folder. If your program compiled without errors, you can now press F5 to execute the program.

Downloads

  • sdltest.zip - Tutorial Source, Graphic, and Project files for Visual C++ 2005.
  • sdltest.tar.gz - Tutorial Source, Graphic, and Makefile for Linux.

Resources

Game Programming in C++ is a fairly new book that's getting good reviews. The examples in this book use SDL and OpenGL. There's only one book that I know of that just talks about SDL, Focus on SDL. The book that taught me the most about SDL is actually Programming Linux Games. This book is not just for Linux geeks, most of the information here can be applied to other platforms as well.

Hopefully this tutorial gave you enough information to start learning SDL on your own. My more advanced graphics tutorials and projects will all use SDL for its cross-platform capabilities.