Contents  Introduction  Setting Up  A Simple SDL  Application  Printable version  Discuss this article The Series  Setting Up Your  System for SDL  SDL Video

A Simple SDL Application (TGO-01-E)

Delete everything in main.cpp, and replace it with the following code:

#include "SDL.h"
int main( int argc, char* argv[] )
{
  //initialize systems
  SDL_Init ( SDL_INIT_VIDEO ) ;
  //set our at exit function
  atexit ( SDL_Quit ) ;
  //create a window
  SDL_Surface* pSurface = SDL_SetVideoMode ( 512 , 384 , 0, SDL_ANYFORMAT ) ;
  //declare event variable
  SDL_Event event ;
  //message pump
  for ( ; ; )
  {
    //look for an event
    if ( SDL_PollEvent ( &event ) )
    {
      //an event was found
      if ( event.type == SDL_QUIT ) break ;
    }
  }//end of message pump
  //done
  return ( 0 ) ;
}

Compile this and run it (we'll go though each of the lines in a moment). If you've done everything correctly, you will be met with a blank, black window with "SDL_App" in the title bar. You can move this window around, and hit the X button in the corner to close it. It is a pretty minimal application, but it's a lot easier than the equivalent WIN32 application that uses DirectX, I guarantee.

Now for a bit of explanation. We'll start with the first line of the program.

SDL_Init ( SDL_INIT_VIDEO ) ;

As you might imagine, SDL_Init is used to initialize the various subsystems of SDL. In this case, we are only initializing the video subsystem. Calling SDL_Init is akin to making use of an IDirectDraw or IDirectSound object, all rolled into one.

atexit ( SDL_Quit ) ;

If you've never used the atexit function before, it sets up another function to be called when the program terminates. This is an old C function that was used before C++ came around and made garbage collection a bit easier with the use of destructors. This line sets up SDL_Quit to be called after the program has terminated. SDL_Quit uninitializes all of SDL for you, so you don't have to. Alternately, you could call SDL_Quit at the end of your program, and you would accomplish the same thing. SDL_Quit is akin to calling IDirectDraw::Release and IDirectSound::Release all in one.

SDL_Surface* pSurface = SDL_SetVideoMode ( 512 , 384 , 0, SDL_ANYFORMAT ) ;

It's only the third line of the program, and already we are setting up the video mode. In a normal WIN32 program, we wouldn't even be half way through setting up our WNDCLASSEX structure. Without over explaining, SDL_Surface is a structure that abstracts a rectangular set of pixels on which you can draw. It is roughly akin to an HDC or an IDirectDrawSurface. The SDL_SetVideoMode function sets up your display. Despite the functions name, it doesn't always set a different display mode, and it certainly doesn't in this case. The parameters are width, height, bits per pixel, and flags. In this case, I am creating a 512x384 surface, but I have a 0 for the bits per pixel. This is because I am using the SDL_ANYFORMAT flag. With this flag, the current format of the display is taken as the format for the surface, so it doesn't really matter what is placed into the third parameter. I could indeed specify a number for this parameter and leave off the SDL_ANYFORMAT flag, and SDL would accommodate me by giving me a surface in the format I requested, regardless of the screen's format. This isn't a good idea, because it requires SDL to "fake" the format if it doesn't match the screen's format. So, if you are making a windowed application, use the SDL_ANYFORMAT flag.

SDL_Event event ;
//message pump
for ( ; ; )
{
  //look for an event
  if ( SDL_PollEvent ( &event ) )
  {
    //an event was found
    if ( event.type == SDL_QUIT ) break ;
  }
}//end of message pump

We will take a look at the rest of the code (minus the line with return on it... I assume you know what THAT does) all at once. SDL_Event is another SDL structure. This time, it abstracts events, something you are likely more than used to in WIN32 programming. Like WIN32, SDL is event driven, and so we have a message pump. The SDL message pump is a lot simpler than the equivalent WIN32 message pump, of course.

Some folks prefer while(1) for their message pump, but I'm one of those who prefer for(;;). I feel it more accurately describes what I'm doing. Both statements are equivalent, of course, so it doesn't really matter which way you do it.

The SDL_PollEvent function checks for a event in the queue. If there is no message waiting, it returns 0. If a message is waiting, it returns 1, and copies the event into the parameter passed to it, in this case the variable I have so aptly named "event".

Only if SDL_PollEvent returns non-zero (i.e. an event has occurred) does the next line get called. In this case, the type member of SDL_Event is checked to see if it is SDL_QUIT, which is the event for exiting the application. If this has happened, we break out of the message pump loop and proceed to exit the application.

Summary

So, is everything about SDL this easy? Yes, pretty much. As I said earlier, the hardest part is setting up the environment. After that, everything is mostly the same as a regular WIN32 application, just with different functions. The key is that this API is called the SIMPLE DirectMedia Layer. From here, I suggest taking a look at some of the SDL docs and playing around with the API, at least until someone convinces me to get off my duff and write another tutorial.