By Tony and Paige at www.tonyandpaige.com

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 Project for API documentation.

To get started using SDL, you'll first need to download it 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.5a-VC6.zip. Download this file and unzip it to a folder, I like to use "C:\Program Files\SDL-1.2.5". Now that you have installed the development package, the documentation is available at "C:\Program Files\SDL-1.2.5\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. Click the directories tab.
3. Choose "Include files" and add a new path "C:\Program Files\SDL-1.2.5\include".
4. Now choose "Library files" and add "C:\Program Files\SDL-1.2.5\lib".

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

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("hello.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;
}
      

g++ sdltest.cpp `sdl-config --cflags --libs` -o sdltest

./sdltest