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);
return;
}
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);
return;
}
