DevIL Logo
      A full featured cross-platform image library.




SourceForge Home





Contact Us

Tutorial 4: Image Names ExplainedLast Revised: 8:50 PM 12/09/2000
Generating Images
DevIL operates on the basis of generated image names. An image name is simply a 32-bit unsigned integer (ILuint) with a unique value. Every image uploaded to DevIL has an image name, so image names are DevIL's way of keeping track of images. Image names must first be generated before DevIL can load an image, or you can call ilBindImage (described later) directly with an image name. The former is accomplished through the use of the ilGenImages function, which accepts two arguments:

ILvoid ilGenImages(ILsizei Num, ILuint *Images);

The Num parameter specifies how many images you will load with DevIL. The Images parameter is set to the image names. Image names are usually contiguous, but they are not required to be, so do not rely on this incorrect assumption. All image names can be used for images with any dimensions (even 3d images). A simple use of ilGenImages could be:

ILuint GenerateSingleImage(void)
    ILuint ImageName; // The image name to return.
    ilGenImages(1, &ImageName); // Grab a new image name.
    return ImageName; // Go wild with the return value.

Binding Images
Generating image names is not enough to load an image, though. You must bind an image name to actually load an image. Binding is the process of setting one image name as the current image and performing all succeeding operations on that image. If no image is bound, DevIL will complain and refuse to do much of anything. You can even bind an image name, load an image, bind another image name, load another image, bind the first image name and save that image, or any combination needed. DevIL keeps all image data in its internal image stack. To actually bind an image in DevIL, call ilBindImage, which accepts one argument:

ILvoid ilBindImage(ILuint Image);

The only argument ilBindImage accepts is Image, which is the image name to bind. Any subsequent operations after calling ilBindImage will operate on the image with the image name bound, such as ilLoadImage(). As a special note: If you pass 0 to ilBindImage, DevIL will use its default image (ugly checkerboard image generated by ilDefaultImage(), which you can modify (though it is not recommended), but DevIL will never let you delete it. Deletion is explained in the next section.

If you pass an image name to ilBindImage that has not yet been generated, ilBindImage will generate that image name internally and bind it. This reduces loading by a function call and could even help correspond OpenGL's textures and DevIL's images if need be.

Deleting Images
When you are done with an image, simply delete its image name. This is accomplished through the ilDeleteImages function, which accepts two parameters:

ILvoid ilDeleteImages(ILsizei Num, const ILuint *Images);

The Num parameter specifies how many image names to delete, and the Images parameter is the list of image names to delete. A very simple usage of ilDeleteImages is:

void DeleteSingleImage(ILuint ImageName)
    ilDeleteImages(1, &ImageName); // Delete the image name.