Cause 1: PNG Files Not Found

The most common cause of trouble of PNG file loading is the operating system being unable to find the file. Suppose you have the following SDL_image function call in your code to load an image:

SDL_Surface* image;
image = IMG_Load_RW("background.png", 1);

That code works only if the file background.png is in the current working directory. If the file isn’t in the current working directory, SDL_image won’t load it, and you have problems.

On Linux and Windows, the current working directory is the directory where the executable file is. Make sure your image files are in the same directory as the executable file.

On Mac OS X, SDL sets the working directory to the directory containing the application bundle. But your image files are in the Resources folder inside the application bundle. This means the code example to load background.png will not work on Mac OS X. The best solution is to change the working directory. My SDL Tips for Mac OS X post has instructions on changing the working directory.

Cause 2: DLLs Not Found

The second common cause of PNG loading problems affects only Windows programmers. For SDL code to run on Windows, Windows must be able to find the SDL DLLs. To find the DLLs, they must reside either in the same directory as the executable file or in the windows\system32 directory.

To use SDL_image on Windows, you must add the SDL_image DLL to the same location as the SDL DLL. Most people remember to add the SDL_image DLL, but they discover PNG files will not load.

The reason the PNG files will not load is that loading PNG files with SDL_image on Windows requires the zlib and libpng DLLs as well as the SDL_image DLL. It’s an easy mistake to make, and the error message SDL_image returns isn’t very clear. The solution is to move the zlib and libpng DLLs to the same location as the SDL and SDL_image DLLs.

Use the Xcode Project Templates

If you haven’t done so already, go to the SDL website and download it. At the SDL download site, you will see both runtime and development libraries for Mac OS X. Download both libraries. The runtime libraries contain the SDL framework. The development libraries contain documentation and Xcode project templates.

The Xcode project templates do two nice things for you when you build the project. First, the templates create a proper Mac application bundle for you. Second, the templates copy the SDL framework to the application bundle. Including the SDL framework with your game lets people play your game without having to install SDL.

Adding Files to the Game

Games contain many external files, such as graphics, sound, and data files. Mac games store these files in the Resources folder inside the game’s application bundle. If you add graphics, sound, and data files to your project’s Resources folder, they will be copied to the application bundle’s Resources folder when you build your project.

Go to the Groups and Files list on the left side of Xcode’s project window. The top entry should be the name of your project. Click the disclosure triangle next to the project name to see a series of folders. Right-click the Resources folder and choose Add > Existing Files. Select the files you want to add and click the Add button.

A second sheet will open. If you are adding individual files, click the Add button. If you’re adding a folder of files, click the Create Folder References for any added folders radio button before clicking the Add button. Creating a folder reference copies the folder to the Resources folder inside the application bundle when Xcode builds your project.

Changing the Working Directory

The Mac OS X version of SDL sets the working directory to the directory containing the application bundle. This default behavior makes loading images and sounds more difficult because the images and sounds usually reside in the application bundle’s Resources folder. You can make file loading simpler by changing the working directory to the Resources folder.

Open the file SDLMain.m and modify the setupWorkingDirectory: method. The following code changes the working directory to the application bundle’s Resources folder:

NSString *resourcePath = [[NSBundle mainBundle] resourcePath];
[[NSFileManager defaultManager] changeCurrentDirectoryPath:resourcePath];

By changing the working directory to the application’s Resources folder, you should be able to use the same code to load files on Linux, Mac OS X, and Windows.

The reason was that Visual C++’s debugger uses a different working directory. Windows normally sets the working directory to the same directory as the executable file, which is where I had my image file. But Visual C++’s debugger sets the working directory to the directory containing the project file. Where is the project file? When you create a Visual C++ project, Visual C++ creates a folder that has the same name as the project name. Inside this folder is a second folder that has the same name as the project name. The project file resides in the second folder. The second folder is where the image file needed to be to debug my program. Moving my image file to the second folder fixed the crashing problem inside the Visual C++ debugger.

If you’re using Visual C++ to write a game and you want to run the game inside the debugger, make sure your game’s files are in the same directory as the project file.

You change the working directory by modifying the method -setupWorkingDirectory: in the file SDLMain.m. You’ll want to change the code in SDLMain.m in SDL’s Xcode templates so your changes take effect for any new SDL projects you create. Just to be safe, you should comment out the original code or save a copy of it so you can go back to the original if things go wrong. Enter the following code in the -setupWorkingDirectory: method:

NSString *resourcePath = [[NSBundle mainBundle] resourcePath];[[NSFileManager defaultManager] changeCurrentDirectoryPath:resourcePath];

Thanks to Keith Bauer, aka OneSadCookie, for the source code to change the working directory.

There are two service packs you must install for Visual C++ to work with Vista. The first is Visual C++ 2005 Express Service Pack 1. The second is Visual Studio 2005 Service Pack 1 Update for Windows Vista. Both of these service packs can be downloaded at Microsoft’s developer site.

There are four things you have to do to get SDL working with Eclipse on Mac OS X in addition to what I outlined in my SDL tutorial. First, you must copy the files SDLMain.h and SDLMain.m to the same directory as your SDL program. My interpretation of this statement is if you create an Eclipse project and add your source code files to the project folder, you must also add SDLMain.h and SDLMain.m to the project folder.

Second, you must add the directory where your SDL headers reside to the Directories setting for the GCC C++ compiler. Your headers most likely reside in the following directory:

/Library/Frameworks/SDL.framework/Headers

Third, you must add linker flags for the Cocoa and SDL frameworks as well as the path to the SDLMain.m file.

-framework Cocoa
-framework SDL
/Path/To/YourProject/SDLMain.m

Fourth, you must change the following line of code in SDLMain.m:

#import “SDL.h”

to the following:

#include SDL/SDL.h

Put less than and greater than signs around the SDL/SDL.h. For some reason I can’t get those characters to show up in the blog.