SDL Tutorial Series - Part 3 - Your First Application

This tutorial will help you create your first SDL application using Microsoft Visual C++ Express 2008. You are going to learn how to initialize and shutdown the SDL and how to create a window. Also, you will see how the SDL handles events that are sent from the system. If you have not done so already, open up Microsoft Visual C++ Express so we may begin.

Once you have opened Visual C++, click on File and select New, then Project...


In the 'New Project' dialog box, select Win32 Console Application. At the bottom of the dialog box enter a name for the project, 'SDLTutorial' should be fine. Also, select a location for the project. Important! Remember where you saved the project because this will be important later on.


After you click 'OK', you will see a new dialog box labeled 'Win32 Application Wizard'. Click on the 'Next >' button and you should see this dialog box.


Make sure that you select the 'Empty Project' check box. This should be the only change you need to make. Click on the 'Finish' button.

Now, click on 'Project' from the menu bar and select 'Add New Item...'. You should see a dialog box like this.


Be sure to select C++ File (.cpp) and enter a name for the file. 'Main' will suffice for our purposes, so click on the 'Add' button to add it to your project.

Paste the following code into the source code file you just created:
#include <iostream>
#include "SDL.h"

using std::cerr;
using std::endl;

int main(int argc, char* args[])
    // Initialize the SDL
    if (SDL_Init(SDL_INIT_VIDEO) != 0)
  cerr << "SDL_Init() Failed: " << SDL_GetError() << endl;

 // Set the video mode
 SDL_Surface* display;
 display = SDL_SetVideoMode(640, 480, 32, SDL_HWSURFACE | SDL_DOUBLEBUF);
 if (display == NULL)
  cerr << "SDL_SetVideoMode() Failed: " << SDL_GetError() << endl;

 // Set the title bar
 SDL_WM_SetCaption("SDL Tutorial", "SDL Tutorial");

 // Main loop
 SDL_Event event;
  // Check for messages
  if (SDL_PollEvent(&event))
   // Check for the quit message
   if (event.type == SDL_QUIT)
    // Quit the program
  // Game loop will go here...

    // Tell the SDL to clean up and shut down
    return 0;    

In the menu bar, select 'Project' and then 'Properties' at the bottom of the menu.


We need to modify some settings in order for the SDL program to run. Expand the 'C/C++' list and select 'Code Generation'. On the right, select 'Runtime Library' and set it to 'Multi-threaded DLL (/MD)'.

Go back to the list box on the left and expand the 'Linker' category. Select the 'Input' field and on the right select 'Additional Dependencies'. Type in the following:

SDL.lib SDLmain.lib

Note: This is case sensitive so be sure to type this exactly as shown.

Click on the 'OK' button. You should now be able to compile and run the program. Select 'Build' from the menu bar and click on 'Build Solution'. If everything worked as it should there should be no errors and no warnings. You need to copy SDL.dll to the same folder as the .exe file you just created. It should be in the 'Debug' sub-folder inside where you saved your project. Now, select 'Debug' from the menu bar and click on 'Start Without Debugging'. You should get a black window to popup and the title should be 'SDL Tutorial'.

Congratulations! You have just built and run your first SDL application. It does not do much of anything interesting but in future tutorials we will be adding elements to it. Let me explain some of the SDL functions to you.

The first function of interest is:
int SDL_Init(Uint32 flags)
This function initializes and loads the SDL library. All you need to know is if it was successful in loading the SDL library. If it was successful it will return 0. If there was an error, it will return -1. Information about the error can be obtained by the next function.

char* SDL_GetError(void)
This function will return a null terminated string that has information about the last internal error generated by the SDL library. This can be very useful in discovering errors in our program code.

The next function allows us to set our video mode.
SDL_Surface* SDL_SetVideoMode(int width, int height, int bitsperpixel, Uint32 flags)
With this function we can set the width and height of our window and the bits per pixel (16 or 32 are the most common). The flags parameter is of special note here. In this tutorial we set the flags to SDL_HWSURFACE and SDL_DOUBLEBUF by ORing them together. These will be most useful to us in future tutorials since we are interested in making games. We could have selected a software surface by specifying SDL_SWSURFACE instead of SDL_HWSURFACE but the hardware surface should be faster. Also, we selected double buffering for our application because this allows us to display one buffer to the user while we perform all drawing operations on the back buffer. Once we are finished drawing the current frame on the back buffer, we swap the buffers and display the one we just finished to the user. This allows us to provide the user with smooth animation and prevents him or her from seeing the frame being drawn which will break the immersion. Note: if you want a full screen window, you can pass SDL_FULLSCREEN to attempt full screen at the specified resolution.

void SDL_WM_SetCaption(const char *title, const char *icon);
This function sets the caption for our window. The first parameter is the string to display in the title bar of our window and the second parameter will be displayed when the window is minimized.

int SDL_PollEvent(SDL_Event *event)

This function will check to see if any events have been posted to the event queue. If there are events in the queue, the function pops the event off the queue and stores it in the SDL_Event data structure pointed to by event. It returns 1 if there is an event or 0 if there are none in the queue. The only event we care about for now is if the quit message has been posted. This will occur when the user clicks the 'x' button on the title bar. We will learn more about events that can occur in our SDL applications in a future tutorial. If you are not familiar with event driven programming I suggest you check out the tutorial on this site here.

void SDL_Quit(void);
This function should always be called if you are using the SDL before exiting your program. It shuts down all the subsystems, unloads all the dynamically linked libraries, and frees any allocated resources.

You have now successfully completed your first SDL application. You should have gained an understanding of the basic functions of the SDL and how they work together to create a functional application. The next tutorial will cover displaying graphics on the screen which will be fundamental in creating video games using the SDL.

Back to SDL Tutorial Index

Back to Main Page.