DevIL Logo
      A full featured cross-platform image library.




SourceForge Home





Contact Us

Tutorial 9: Registering FunctionsLast Revised: 10:20 PM 12/09/2000
The DevIL creators realized the need for some kind of extension system, but the OpenGL extension mechanism did not fit well with DevIL, as DevIL has only one vendor. DevIL needed some kind of extension system though, because some people use home-brewed image formats, and some need to use obscure formats for backwards compatibility, along with others who need it just because. Users can actually also use this registration system to override DevIL's default loading and saving functions.

The Registration System
The DevIL registration system was developed to meet these needs. The registration system allows third party applications to utilize DevIL's power while using their own loading and saving routines. This is accomplished through function pointers and a set of registration functions in DevIL. DevIL calls these functions when a file needs to be opened that has an extension matching a registered function's registered extension. ilLoadImage and ilSaveImage both will use registered functions if any are registered. To register a loading function, use ilRegisterLoad. To register a saving function, use ilRegisterSave.

ILboolean ilRegisterLoad(char *Ext, IL_LOADPROC Load);
ILboolean ilRegisterSave(char *Ext, IL_SAVEPROC Save);

Ext is the file extension that the function callback operates on (e.g. "tga"). Load and Save are pointers to functions that DevIL can call.

Simple example of registering a loading function

ILboolean LoadFunction(char *FileName)
    return IL_FALSE;
void RegisterLoadFunction(void)
    ilRegisterLoad("xxx", LoadFunction);

Any load or save function to be registered must be in the same format as LoadFunction is. The function must return IL_FALSE if the image was not loaded properly, else it should return IL_TRUE to signify the image was loaded correctly. There is no need to check the extension of FileName in a registered function, as DevIL only calls the function if FileName's extension matches the extension the function was registered with.

Registration Functions for Loading
The loading registration system would not be complete at all if there was no way to tell DevIL the characteristics of the image (width, height, format, etc.) and set the image data. A general-purpose function that doesn't necessarily have to be used in registration functions but sets the current bound image to the correct states is ilTexImage. ilTexImage takes a whopping six parameters:

ILboolean ilTexImage(ILuint Width, ILuint Height, ILuint Depth, ILubyte Bpp, ILenum Format, ILvoid *Data);

If the image already has the appropriate dimensions but needs a data update, just use ilSetData to let DevIL copy your copy of the image data. Another function you can use to set the image data is ilSetPixels.

ilRegisterFormat, ilRegisterOrigin, ilRegisterPal and ilRegisterType are the actual functions used specifically for registration of the image's characteristics in DevIL.

Saving Images
DevIL gives all the information needed to access image characteristics and data for saving through its generalized querying system. ilGetInteger and ilGetData are the only two functions needed to obtain info about the current bound image to be saved.

Simple example of a registered saving function

ILboolean SaveFunction(char *FileName)
    // Open file here

    fwrite(ilGetData(), 1, ilGetInteger(IL_IMAGE_SIZE_OF_DATA), File);

    // Close file here

    return IL_TRUE;
void RegisterSaveFunction(void)
    ilRegisterSave("xxx", SaveFunction);