Ninadvisor

Checking Versions
This is a critical first step for any well-written application that utilizes DevIL. With almost all compilers supported, DevIL is generated as a shared library. Even though the function names may all be the same, earlier versions of DevIL may have inconsistencies that render your application unuseable. Bugfixes are constantly introduced to try to make DevIL the best image library ever. The drawback to shared libraries is that a user may inadvertently (or purposefully) replace a newer version of DevIL with an older version than your application was designed for. Luckily, DevIL provides version mechanisms to check versions -- ilGetInteger, iluGetInteger and ilutGetInteger. There are #defines in all three libraries that provide the version number your application was compiled with to check against the version number returned by their respective GetInteger functions: IL_VERSION, ILU_VERSION and ILUT_VERSION.

Example of version checking.
if (ilGetInteger(IL_VERSION_NUM) < IL_VERSION ||
iluGetInteger(ILU_VERSION_NUM) < ILU_VERSION)
ilutGetInteger(ILUT_VERSION_NUM) < ILUT_VERSION) {
printf('DevIL version is different...exiting!n');
return 1;
}

Initializing the Library
With compilers that support shared libraries, no initialization is required, as DevIL is automatically intialized when it is loaded by an application. Initialization is recommended, though, to ease any porting troubles. Plus, it is only one additional line of source. All that is needed to initialize DevIL is to call ilInit. No parameters are even needed.

Image Names
DevIL's image name system is virtually identical to OpenGL's texture name system. First, you need an image name variable:

ILuint ImageName;

Next, generate an image name to be put in this variable:

ilGenImages(1, &ImageName);

Now bind this image name so that DevIL performs all subsequent operations on this image:

ilBindImage(ImageName);

Creating images is as simple as that. No messy pointers or anything else to mess with. To get an in-depth explanation of image names, read the tutorial on them.

Loading an Image
Loading an image is as simple as it can be with DevIL. For most programs, a simple call to ilLoadImage will suffice. IF the image was not loaded due to any of various reasons, ilLoadImage returns false, else it returns true if the image was successfully loaded.

Code for loading an image.
ilLoadImage('monkey.tga');

Saving an Image
Saving an image is just as easy as loading an image via DevIL. Just call ilSaveImage with the desired filename as the only parameter. If DevIL could not save the image, ilSaveImage returns false, else it returns true. By default, DevIL will refuse to overwrite any images that already exist on the harddrive to prevent from overwriting important data. To change this behaviour to allow overwriting of files, use ilEnable with the IL_FILE_OVERWRITE parameter.

Code for saving an image.
ilEnable(IL_FILE_OVERWRITE);
ilSaveImage('llama.jpg');

Checking for Errors
Occassionally, errors may occur in DevIL, such as an image not being loaded. If an DevIL function returns indicating an error (e.g. returns false from a function that returns an ILboolean), an error code is set internally in DevIL and may be retrieved via ilGetError. Usually, the code is quite specific about what kind of error occurred. DevIL maintains an error stack (usually 32 errors deep) so that if more than one error is set, an error doesn't get 'lost'. When you call ilGetError, the last error set is popped off of the stack. If no error has occurred, or all the errors have been popped off of the stack, ilGetError returns IL_NO_ERROR.

For a more in-depth discussion of errors, read the tutorial on them.

Code for detecting an error.
ILenum Error;
Error = ilGetError();

Image Information
Of course DevIL would be pretty useless if you could not retrieve information about the image somehow. ilGetInteger serves this purpose very well, allowing you to know pretty much everything about an image. Some useful values to pass as parameters to ilGetInteger are IL_IMAGE_WIDTH, IL_IMAGE_HEIGHT and IL_IMAGE_BPP. All of these and more are defined in DevIL's il.h header.

Code for getting an image's width and height.
ILuint Width, Height;
Width = ilGetInteger(IL_IMAGE_WIDTH);
Height = ilGetInteger(IL_IMAGE_HEIGHT);

Image Data
To get a pointer to the image data for your own use, make a call to ilGetData. ilGetData returns a direct pointer to the image data. Do not try to free this pointer when you are done with it, as it does not point to a copy of the image data but to the actual image data. The image data is freed when you delete the image.

Code for getting the image data.
ILubyte *Data = ilGetData();

Display the Image
DevIL supports several different APIs for displaying an image through ilut. Since ilut is separate from il, you could manually send data to the API just as ilut does, though it would require more code and time from you (same as writing your own image routines =). Right now, we will only focus on OpenGL though, as DevIL is OpenGL's bastard sibling.

For a much more in-depth discussion of using DevIL with OpenGL, read this tutorial.

Before you call any ilut functions dealing with OpenGL and after you have initialized OpenGL, you *must* call ilutRenderer with the ILUT_OPENGL parameter to initialize ilut correctly.

Most applications will then only need to call ilutGLBindTexImage to get a corresponding OpenGL texture from the DevIL image. If you only need to use the OpenGL texture and not the DevIL image after this, it is safe to delete the image.

Example of getting an OpenGL texture.
GLuint Texture;
Texture = ilutGLBindTexImage().

Deleting an Image
To delete an image when you are through with it, call ilDeleteImages. ilDeleteImages frees all data and makes that image name available for use in the future. ilDeleteImages has a syntax exactly like ilGenImages, and the functions are each other's complement.

Example of deleting an image.
ilDeleteImages(1, &ImageName);