Tutorial 5: Loading Images
Last Revised: 6:50 PM 11/26/2000
DevIL's main purpose is to load images, and it does this quite well.
DevIL can load Bitmap (.bmp), Cut (.cut), Doom flats and textures,
Icon (.ico), Jpeg (.jpg, .jpe, .jpeg), Lbm (.lbm), Pcd (.pcd), ZSoft Pcx (.pcx),
Pic (.pic), Portable Anymap (.pbm, .pgm, .ppm), Portable Network Graphics (.png),
Sgi (.sgi, .bw, .rgb, .rgba), Truevision Targa (.tga) and
Tiff (.tif, .tiff) images.
There are four image loading functions in DevIL:
In addition, there is one palette loading function -- ilLoadPal.
ILboolean ilLoadImage(char *FileName);
ILboolean ilLoad(ILenum Type, char *FileName);
ILboolean ilLoadF(ILenum Type, ILHANDLE File);
ILboolean ilLoadL(ILenum Type, ILvoid *Lump, ILuint Size);
ILboolean ilLoadPal(char *FileName);
Loading Methods Explained
To load an image, there must first be a current image bound.
Read the tutorial on Binding Images to learn how to
accomplish this. DevIL supports loading from multiple data inputs, to make it
quite full-featured. The first, common method, is loading a file on the user's computer.
The programmer needs to only pass the correct filename of the image file, and that
file is loaded with no additional hassle. The two functions that can load from just
an image's filename are ilLoad and ilLoadImage. These two functions are similar but are not
exactly alike in design and use. The first thing you might notice is that ilLoad
accepts an extra parameter. This parameter is an enum that will force DevIL to
recognize the file as a specific type of image. Even if a file has a .bmp extension,
you can force DevIL to load it as a .tga or anything else. This can also be used on
files without any file extension whatsoever. To find the accepted values for
Type, read the ilLoad docs.
If IL_TYPE_UNKNOWN is passed as the Type parameter, ilLoad behaves exactly
like ilLoadImage. In fact, ilLoad calls ilLoadImage.
Example of ilLoad
ilLoadImage is very simple to use -- just pass the filename of the file in the FileName parameter.
ilLoadImage does the rest. First, it checks the filename's extension and tries to find a matching image handler.
This includes registered image handlers. If ilLoadImage cannot find a matching
it attempts to identify the image by matching the first few bytes of a file with known image format headers.
Of course, not all images can be identified this way, because not all images have extensive headers.
Some start immediately with the width and height, then the image data follows. DevIL cannot determine
the type of these files and returns with IL_FALSE. IL_TRUE is returned if the image was loaded successfully.
ilLoadF is quite like ilLoad, but it operates on file handles, not filenames. To learn more
about how DevIL uses file handles, look at this tutorial. After DevIL is
done loading the image, the file stream is reset to the state it was in when ilLoadF was called.
ilLoadL is exactly like ilLoadF, but it operates on what I call "lumps". Memory "lumps" are just
pointers you pass to DevIL. ilLoadL also requires a third parameter -- the lump's size. If you
want no bounds-checking to be done on the lump, specify a size of 0.
When DevIL is done loading an image from the lump, you can be assured that the data in the
lump is left unharmed, as DevIL only reads from it. ilLoadL (and ilLoadF) can be useful when you are
loading from a package file, such as the .pak format. It would be quite inconvenient if you had to write
each image entry from the package file to the harddrive, and then load them with DevIL.
A Dirty C Example using ilLoadL
File = fopen("monkey.tga", "rb");
fseek(File, 0, SEEK_END);
Size = ftell(File);
Lump = (ILubyte*)malloc(Size);
fseek(File, 0, SEEK_SET);
fread(Lump, 1, Size, File);
ilLoadL(IL_TGA, Lump, Size);
If an image is in a format that is non-native to DevIL, it is automatically converted to a useable format.
All 16-bit images are handled this way, being converted to 24-bit images on load. To use your own functions
to load unsupported image formats or to override DevIL's loading functions, read the tutorial on
Loading palette data to the current bound image is simple. It is not near as full-featured as
full image loading yet, though. If the current bound image is not palettized, ilLoadPal still
loads the palette into the image, though it will never be used for anything. Just call ilLoadPal
with the name of the file you wish to load. ilLoadPal automatically determines the type of palette
present in the file and loads it.