Tutorial 4: Image Names Explained
Last Revised: 8:50 PM 12/09/2000
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
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 ImageName; // The image name to return.
ilGenImages(1, &ImageName); // Grab a new image name.
return ImageName; // Go wild with the return value.
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.
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.