Monday, February 4, 2008


SDL (Simple Direct Media Layer) is a very powerful, low-level, cross-platform, high-performance multimedia library. If you are unfamiliar with this library I recommend going to the SDL website and having a look around for an hour or nine. Browse the documentation and the header files, and be sure to read the license so you know what you have the rights to use and how you may use it.

Now, assuming you intend to compile SDL apps using the free MinGW compiler (MinGW?), get the latest version of the SDL from the download section on the SDL website. Get the Development Runtime for Win32, the MinGW version. SDL users tend to favour MSVC when on Windows, so some of the MinGW-specific information is a bit sparse. As-is, the development runtime package needs to be configured and installed before you can compile with it. This requires the help of a more unix-like command line shell, either Cygwin (configured to use MinGW) or MSYS from (as described in the first section).

Instead of doing this, which will install the libraries and headers into your MinGW system, I prefer to keep SDL separate so I can easily switch between versions of SDL and MinGW just by re-naming the folder.

Furthermore, on Windows, you will most likely ship your app with the SDL DLLs, as opposed to compiling them statically to your app. In which case, you should take advantage of the MSVC-compiled DLL available from, which will in all likelyhood be better optimized than what MinGW will produce. Dynamically linking also gives the user the opportunity to upgrade the SDL DLLs themselves later if need be (or if they choose to share a single SDL.dll with all their apps by placing it in the Windows System folder). Statically linking will also tie your app to the LGPL which SDL was released under.

So, to create a quick-and-dirty standalone SDL SDK which you can use with MinGW, follow these steps:

  • Begin by unpacking the SDL development runtime archive to a temporary directory. You need to find the header files, the static-link libraries, and the SDL.dll file. These should be found (assuming the packaging hasn't changed since this writing) within another archive called i386-mingw32msvc.tar.gz that should have been created while extracting the first archive. Extract this into another temporary directory. From that you need the headers (.h) and libs (.a), including the dll. For development purposes, you might put those into a directory structure as follows:


  • Then put a copy of the SDL.dll into the directory your final executable target will reside so that Windows can do the run-time linking when you start up your app. Or, you can place this dll into your Windows directory if you want share that same dll with multiple SDL apps.

  • The only trick in getting this to compile now is to add the include path (eg: -I../SDL/include), the linker path (eg: -L../SDL/lib) and then finally adding the libraries themselves in the right order. Use:

    -lmingw32 -lSDLmain -lSDL

    Also, don't forget to add the -mwindows flag, if your IDE doesn't add it automatically (in addition to whatever other libraries you want to link). If you don't put them in the right order, you'll get a linker error complaining about the missing symbol WinMain@16.

What is this libSDLmain.a file? It is built from the source file SDL_main.c, in the sdl/src/main/win32 directory (when on Win32 platform). It contains the bare framework for a Windows app, including the essential WinMain function which is a Windowed application's entry-point. If for whatever reason you are having insurmountable problems linking to libSDLmain.a, or if you have a specific need to alter the 'WinMain' or add other platform-specific calls, you can simply add this source file to your project in its place to resolve the link errors and then modify it to your heart's content. I am not recommending this approach, it is only here for your information and to give some insight into how SDL works on Windows.

MinGW and SDL_image

SDL_image is an invaluable add-on library that allows you to use a wide variety of image formats with SDL, including BMP, JPG, GIF, PNG, TGA, PCX and many more (as opposed to just BMPs with SDL alone).

If you want to get up and running quickly without re-compiling from source, simply grab the runtime development package. This time however, you can use the MSVC package. You can link directly to the SDL_image.lib file as it only requires plain vanilla C linkage (no C++ or other MinGW-specific WinMain). Just extract the archive to a location and remember to set the include and lib paths when you compile.

The documentation site for SDL_image is clear and straightforward. It also has an excellent example source to try which serves as a great little intro to both SDL and SDL_Image at the same time. Assuming your SDL/ and SDL_image/ directories are at the same level, create another folder at that same level, called viewimage. Grab the viewimage.c source from the demos directory, as well as a few image files to test. Put the files you download in the viewimage folder. Then you can use this makefile to build the test app:

make -f viewimage.makefile

Finally, copy all the .dll files (zlib.dll, jpeg.dll, libpng1.dll, SDL_image.dll and SDL.dll) to the viewimage directory so the app can find them when you run it. The app is a command-line app, so pull up a command prompt and cd to that directory. Test it by running it with the name of one of the demo images:

viewimage lena.jpg

originally posted on 2001-06-06
edited: 2001-06-10
(thanks to Matt Jones for the linker tip ;) edited: 2001-08-08
edited: 2001-09-05
edited: 2002-12-31


Greg said...

Thank you so much for this. Got me going with SDL after hours of trying to figure out what to do!

Anonymous said...

Just big thank you! You helped me getting things work, though I don't understand much of it ^^