Loading Resources (Troubleshooting)

From Allegro Wiki

Jump to: navigation, search


Common Problems

The following are common problems people report with Allegro 5:

  • I load an image (font, etc) but Allegro crashes when I use it.
  • I load an image (etc) but it is just NULL.
  • My program is very slow when I use fonts or bitmaps.

If one of the above applies, then the solution is most likely below.


Initialize the Library

In addition to calling al_init() you must also initialize the appropriate add-ons before using any of the related functions. If you are using C++, be very cautious with constructors, particularly with global objects. Make sure that you never have a situation where you are calling a function before the add-on has been initialized.


While al_load_bitmap() is part of the core Allegro library, no bitmap loading code is available. You must initialize the Allegro image add-on via al_init_image_addon(). Don't forget to link to the image add-on library, and include the allegro5/allegro_image.h header.


You must call al_init_font_addon() and then al_init_ttf_addon(). You must link with both the font and ttf addons and include allegro5/allegro_font.h and allegro5/allegro_ttf.h.


The audio subsystem is part of the audio add-on and is initialized via al_init_audio(). You must include allegro5/allegro_audio.h. To be able to load audio files (e.g., Ogg Vorbis), you must also use the audio codec add-on. Use al_init_acodec_addon() to initialize it and include allegro5/allegro_acodec.h.

Check Return Values

If it "isn't working", check your return codes. For example:

bmp = al_load_bitmap("foo.png");
if (bmp == NULL) {

Do not blindly assume that the resource was loaded. If Allegro could not load the file for any reason whatsoever, it will return NULL. If you use that NULL resource, you will end up crashing your program.

If you are using the debug version of Allegro (which you should do while developing) check out the allegro.log file next to your executable to see if it says anything helpful.

Fix the Path

You are probably using (and should be using) a relative path when loading your resources. However, your program may not be starting up in the location you think it is. Every program has a "current working directory" that is set when it starts up.

Your IDE may be starting the program from another location, such as a debugging folder. The relative path will then be pointing to the wrong location. To quickly check if this is a problem, temporarily use an absolute path:

bmp = al_load_bitmap("c:/bitmaps/foo.png");

Note that you should always use forward slashes. Back slashes cause problems because they are treated as escape sequences and they are only native to Windows operating systems. Using forward slashes will work everywhere.

Of course you cannot use absolute paths when you want to distribute your program. The proper solution is as follows:

ALLEGRO_PATH *path = al_get_standard_path(ALLEGRO_RESOURCES_PATH);
al_append_path_component(path, "resources");
al_set_path_filename(path, "foo.png");
bmp1 = al_load_bitmap(al_path_cstr(path, '/'));
al_set_path_filename(path, "bar.png");
bmp2 = al_load_bitmap(al_path_cstr(path, '/'));

The ALLEGRO_RESOURCES_PATH represents the folder that contains the executable. (Within an OS X application bundle, it represents the resource folder.) In this example, the bitmaps are located in a sub folder called resources:

  • c:/game/game.exe
  • c:/game/resources/foo.png
  • c:/game/resources/bar.png

Check out the manual to see how you can manipulate the path to suit your needs.

There is a shorter method you can use:

ALLEGRO_PATH *path = al_get_standard_path(ALLEGRO_RESOURCES_PATH);
al_append_path_component(path, "resources");
al_change_directory(al_path_cstr(path, '/'));  // change the working directory
bmp1 = al_load_bitmap("foo.png");
bmp2 = al_load_bitmap("bar.png");

Notice how we've changed the working directory via al_change_directory. Now all of the future paths will be relative to that location. Generally this is less of a hassle than adjusting the path for every resources.

Load the Image or Font after Creating the Display

Allegro images are only fast if accelerated via your graphics card. Since fonts are actually just rendered to a bitmap, the same thing applies to them. In Allegro terms, the bitmap must be an ALLEGRO_VIDEO_BITMAP. By default, Allegro tries to load a video bitmap.

However, if you have not created a display yet, no video bitmap can be created!

In that case, a (very slow) memory bitmap will be used. The easiest thing to do is to simply create the display first. Then load the fonts and images. You'll now be using hardware accelerated video bitmaps.

To check if a bitmap is hardware accelerated:

if (al_get_bitmap_flags(bmp) & ALLEGRO_VIDEO_BITMAP) {
  // this is a video bitmap

Also note that a bitmap is attached to a single display. If you use multiple displays, you need to create a bitmap that is compatible with each one. To do so:

bmp2 = al_clone_bitmap(bmp);

You can use al_is_compatible_bitmap() to check if a given bitmap will be accelerated for the active display.

If you load a bitmap or font from a thread that is separate from your drawing thread, the above also applies. Again, simply clone the bitmap for the display. (In this case, it's likely that you can discard the original memory bitmap after cloning it.)

Use a Smaller Bitmap (or use a Memory Bitmap)

Bitmaps are stored as textures, and as such, cannot be larger than what your video card supports. This will vary by each card, but anything less than 1024 pixels wide or tall will probably work. But you definitely will run into problems with images exceeding 2048 or 4096 pixels.

First, to check to see if this is the problem, you can force Allegro to load a memory bitmap.

bmp = al_load_bitmap("huge_bitmap.png");

If that fixes the problem, then the bitmap was too big. You can check to see what the maximum size is:

int max_size = al_get_display_option(display, ALLEGRO_MAX_BITMAP_SIZE);

Keep in mind that this limitation is per side. So while 1024x1024 may work, the smaller bitmap (but with a longer side) of 1200x32 may not work. If you are using a tile map, you will get more space if you use a square bitmap, as opposed to a long rectangular one.

Use a Different Format

It's possible that your file isn't supported. First check to make sure Allegro (or the appropriate add-ons) was compiled with support for the file you are using. e.g., Allegro does not support MP3 files.

If it should be supported, try a different file of the same type. If that works, then you may have stumbled across a particular variation of the file type that is not supported. That could be a bug, so it's worth telling somebody.

Personal tools