Getting Started with SDL in Visual Studio 2010

The first step is to install the SDL 1.3 libraries. The source code for the libraries is available for download from http://www.libsdl.org/tmp/SDL-1.3.zip . To use this you will first need to compile the libraries instructions for this can be found in the file VisualC.html but is fairly straightforward. If you are on Windows, then you could more simply download a pre-built version of the library that I have posted online here: http://bit.ly/sdl1-3 . Note that at time of writing, SDL 1.3 is still under development, so this download may not include the latest features or bug-fixes. This zip file contains three folders: include the SDL header files. You need to #include the appropriate headers to access SDL functions lib This folder contains the two library files SDL.lib and SDLmain.lib. These need to be linked during compilation. See below for notes on adding these to your project or development environment. dll contains SDL.dll. This dynamic link library is required to actually run your programs. Again see below for notes on adding SDL.dll to your project or development environment.

Installing SDL (Windows/Visual Studio)

There are a couple of different ways you can install SDL you could add the lib and include files to the existing Visual Studio lib and include folders, which will make the libraries visible to all development projects. Installing the dll file in the Windows/System32 folder should also mean that any project that uses SDL has access to the dll at runtime. There are some issues with this approach though: It is difficult to use different versions of SDL. This can become an issue if SDL is updated and you need to maintain projects that use incompatible versions of the SDL library. Adding the dll to your system folder means that your Windows environment will be different from end users Windows environment. You might miss problems in creating a redistributable version of your project that would otherwise be caught. You may have issues in trying to work with your project using computers that have a different Windows environment or which have installed the libraries in different locations.

For these reasons, I would recommend the alternative of installing SDL into a separate development folder and manually changing project settings to include the include, lib and dll files as required. Save and unzip the SDL-1.3 folder onto your computer. On my laptop, the path to this is C:\Development\SDL-1.3\ . For use in the university you could use your home drive or the temp folder on the local C drive ( C:\temp\SDL-1.3 ). In the examples that follow I will use the path C:\Development\SDL-1.3\ , change this as appropriate for your settings.

Your First SDL project

Unzip and install the SDL files as described above Open a new Win32 Project in Visual Studio call it SDL test:

In application settings, check the Empty Project option, and then click finish to create the project:

Add a new source file (main.cpp) to the project, and type in the following lines of code. Note that at this point the SDL types and functions will not be recognised by Visual Studio as you have not yet added the SDL include folder to the include file path.

#include <SDL.h> // Program entry point - SDL manages the actual WinMain entry point for us int main(int argc, char *argv[]) { SDL_WindowID hWindow; // window handle SDL_Init(SDL_INIT_VIDEO); // initialize SDL // Create 800x600 window hWindow = SDL_CreateWindow("SDL Test", 100, 100, 480, 320, SDL_WINDOW_SHOWN | SDL_WINDOW_RESIZABLE ); SDL_Delay(5000); SDL_DestroyWindow(hWindow); SDL_Quit(); return 0; }

Project Configuration
Open the Project Properties dialog, select the All Configurations option, and add the SDL-1.3\include folder to the Additional Include Diectories path. In my case, C:\Development\SDL-1.3\include :

If you try building the project now, it will complete the first stage of compilation but fail at the linking stage (with numerous LNK - unresolved external symbol errors). We also need to add the lib files to the project. Use the project properties dialog to add the lib folder to the Additional Library Directories:

Almost there! While the library path has been updated, you still need to tell VS to use the lib files add SDL.lib and SDL.lib to the Linker -> Input -> Additional Dependencies option.

Now you can compile and link your program but if you try to run it, you might get the following error:

Copy SDL.dll from the dll folder into the debug folder:

Now when you run your project, the SDL Test window should appear. Currently your application does not do anything it will simply show a blank window which disappears after a five second display. Note that you cannot actually interact with the window it will be unable to respond to events. The SDL_Delay call causes SDL to pause, and as soon as the delay is over, our program closes.

A Simple Game Loop

A very basic game (or windows application event loop) might look like this: while (running) { processEvents update render } Events in SDL use the SDL_Event type, so we can create a simple event loop using the following code to replace the call to SDL_Delay: SDL_Event sdlEvent; // variable to detect SDL events

while (running) // the event loop { while (SDL_PollEvent(&sdlEvent)) { if (sdlEvent.type == SDL_QUIT) running = false; } //update(); // not used yet! //draw(hWindow); // not used yet! } Finally, a window that can be resized and which stays open until you click on the close button. SDL handles the mouse input allowing the window to be resized, moved, minimized, etc.

Debug Output and Detecting Errors

You may have noticed that there was no console window when your SDL application opened. Modify your to output a Hello World message using std::cout.

The message does not appear anywhere. Text output messages can be useful as a simple means of displaying error or other debug information during program development. On Windows it is possible to create a console window simply, adding the following code to the top of your program. (The #if

_DEBUG directive will remove the code creating the console when the program is compiled in a release configuration)
#if _DEBUG #pragma comment(linker, "/subsystem:\"console\" /entry:\"WinMainCRTStartup\"") #endif

You can now add appropriate error messages to the code to catch conditions where SDL fails to initialize. First add a function to display error messages and to close the program when there is a fatal error starting SDL. We'll keep this quite general so that it can also be used to print other error messages in later programs: // Something went wrong - print error message and quit void exitFatalError(char *message) { cout << message << " " << endl; cout << SDL_GetError(); SDL_Quit(); exit(1); } The existing call to SDL_Init can be embedded in code to detect whether or not the call succeeds, e.g.: if (SDL_Init(SDL_INIT_VIDEO) < 0) // Initialize video exitFatalError("Unable to initialize SDL"); And after the call to SDL_CreateWindow, a test can be made to check for success: if (!hWindow) // Check window was created OK exitFatalError("Unable to create window");

Keyboard Input
Run and test your program before proceeding further it should still work as before. Time to add a simple event handler to detect and respond to keyboard input. Inside the program loop, modify the contents of the while loop so that it now reads:

while (running) // the event loop { SDL_PollEvent(&sdlEvent); running = handleSDLEvent(sdlEvent); //update(); // not used yet! //draw(hWindow); // not used yet! }
And add the event handler function:

bool handleSDLEvent(SDL_Event const &sdlEvent) {

if (sdlEvent.type == SDL_QUIT) return false; if (sdlEvent.type == SDL_KEYDOWN) { // Can extend this to handle a wider range of keys switch( sdlEvent.key.keysym.sym ) { case SDLK_ESCAPE: return false; default: break; } } return true; }
Now test your program again this time you should be able to quit the program by pressing the escape key as well as by clicking on the close window icon. Over time you will be able to extend the range of events that your program can handle but the next exercise will be to actually render some 3D graphics with OpenGL!

More Information on SDL

http://www.libsdl.org/ http://www.libsdl.org/tmp/SDL-1.3-docs/ http://www.libsdl.org/

This work by Daniel Livingstone, University of the West of Scotland, is licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported License. To view a copy of this license, visit http://creativecommons.org/licenses/by-sa/3.0/ or send a letter to Creative Commons, 444 Castro Street, Suite 900, Mountain View, California, 94041, USA.