About News Download SourceForge Home Documentation Tutorials Logos Links Projects Contact Us

Tutorial 5: Loading ImagesLast Revised: 6:50 PM 11/26/2000 Loading Images 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: ilLoad, ilLoadF, ilLoadL and ilLoadImage(). 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 ilLoad(IL_TGA, "monkey.tga"); 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 image handler, 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 ILubyte *Lump; ILuint Size; FILE *File; 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); fclose(File); ilLoadL(IL_TGA, Lump, Size); free(Lump); Miscellaneous 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 Registering. Palette Loading 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.