At the top of the source file we include the SDL header file so we can use the SDL functions and data types.

Remember that some of you (like Visual Studio users) are going to include SDL like this:

#include "SDL.h"

So if the compiler is complaining that it can't find "SDL/SDL.h", then it's either because you're including the wrong path or you forgot to put SDL.h in the right place.

At the top of the main() function, two SDL_Surface pointers are declared. An SDL_Surface is an image, and in this application we're going to be dealing with two images. The surface "hello" is the image we're going to be loading and showing. The "screen" is what is visible on the screen.

Whenever you're dealing with pointers, you should always remember to initialize them.

Also, when using SDL, you must have your main() function declared like it is above. You can't use void main() or anything like that.

The first function we call in the main() function is SDL_Init(). This call of SDL_Init() initializes all the SDL subsystems so we can start using SDL's graphics functions.

Next SDL_SetVideoMode() is called to set up a 640 pixel wide, 480 pixel high window that has 32 bits per pixel. The last argument (SDL_SWSURFACE) sets up the surface in software memory. After SDL_SetVideoMode() executes, it returns a pointer to the window surface so we can use it.

After the window is set up, we load our image using SDL_LoadBMP(). SDL_LoadBMP() takes in a path to a bitmap file as an argument and returns a pointer to the loaded SDL_Surface. This function returns NULL if there was an error in loading the image.

Now that we have our window set up and our image loaded, we want to apply the loaded image onto the screen. We do this using SDL_BlitSurface(). The first of SDL_BlitSurface() argument is the source surface. The third argument is the destination surface. SDL_BlitSurface() sticks the source surface onto the destination surface. In this case, it's going to apply our loaded image onto the screen. You'll find out what the other arguments do in later tutorials.

Now that our image is applied to screen, we need to update the screen so we can see it. We do this using SDL_Flip(). If you don't call SDL_Flip(), you'll only see an unupdated blank screen.

Now that the image is applied to the screen and it's made visible, we have to make the window stay visible so it doesn't just flash for a split second and disappear. We'll make the window stay by calling SDL_Delay(). Here we delay the window for 2000 milliseconds (2 seconds). You'll learn a better way to make the window stay in place in tutorial 4.

Now that we're not going to use the loaded image anymore in our program, we need to remove it from memory. You can't just use delete, you have to use SDL_FreeSurface() to remove the image from memory. At the end of our program, we call SDL_Quit() to shut down SDL.

You may be wondering why we never deleted the screen surface. Don't worry, SDL_Quit() cleans it up for you.

Congratulations, you've just made your first graphics application.

Troubleshooting your SDL application

If the compiler complains that it can't find 'SDL/SDL.h', it means you forgot to set up your header files. Your compiler/IDE should be looking for the SDL header files, so make sure that it's configured to look in the SDL include folder.

If you're using Visual Studio and the compiler complains 'SDL/SDL.h': No such file or directory, go to the top of the source code and make sure it says #include "SDL.h".

If your program compiles, but linker complains it can't find some lib files, make sure your compiler/IDE is looking in the SDL lib folder. If your linker complains about an undefined references to a bunch of SDL functions, make sure you linked against SDL in the linker.

If your linker complains about entry points, make sure that you have the main function declared the right way and that you only have one main function combined in your source code.

If the program compiles, links, and builds, but when you try to run it it complains that it can't find SDL.dll, make sure you put SDL.dll in the same directory as the compiled executable. Visual Studio users will need to put the dll file in the same directory as your vcproj file. Windows users can also put the dll inside of the system32 directory.

If you run the program and the images don't show up or the window flashes for a second and you find in stderr.txt:
Fatal signal: Segmentation Fault (SDL Parachute Deployed)
It's because the program tried to access memory it wasn't supposed to. Odds are its because it tried to access NULL when SDL_BlitSurface() was called. This means you need to make sure the bitmap files are in the same directory as the program. Visual Studio users will need to put the bitmap file in the same directory as your vcproj file.

Also if you're using Visual Studio and you get the error "The application failed to start because the application configuration is incorrect. Reinstalling the application may fix this problem.", it's because you don't have the service pack update installed. Do not forget to have the latest version of your compiler/IDE with the service pack update for your compiler/IDE or SDL will not work with Visual Studio.

Some Linux users will run and get a blank screen. Try running the program from the command line.

If you had to create a project to compile an SDL program, remember that you will need to create a project for every SDL program you create. Or, better yet, you can reuse the SDL project you made the first time.