Developer's Image Library version 1.6.7 Readme, Notes and Quick Use

-------------------------------------------------------------------



<DZA[afk]> DevIL song: "la la la, a cross-platform image library utilizing a

           simple syntax to load, save, convert, manipulate, filter and

           display a variety of images with ease, la la la"





What is it?

-----------



DevIL is an Open Source image library based on the LGPL license.  DevIL* is

capable of loading/manipulating/filtering/converting/displaying/saving from/to

several different image formats.





Where can I find it?

--------------------



DevIL can be found at http://www.imagelib.org and http://openil.sourceforge.net





Where do I find the projects files ?

-----------------------------------------



MSVC++ projects are in \DevIL\projects\MSVC.





More Extensive Documentation

----------------------------



This file is only a quick guide to point you to more detailed information on

how to use DevIL.  More extensive documentation can currently be found on the

DevIL site at http://www.imagelib.org and in the /Docs directory in a normal

install.





Why the hell another image library?

-----------------------------------



I have never seen an image library that can do everything DevIL does.  Sure,

various different libraries can do part of what DevIL can do as well or even

better, but I wanted a simple to use library that encompassed all of these

features.  I also wanted an extremely portable image library that could be used

from a variety of languages and utilized the OpenGL syntax.





Basic Readme

------------



Most anything stated in this document applies to DevIL as well as DevILU and

DevILUT, unless otherwise stated.





The IL_NO_XXX #define's:

------------------------



A user can recompile this library without complete image support in it.  For

example, if your project does not use .jpg files, you can uncomment

#define IL_NO_JPG at the top of il/il.h, recompile the library, and no .jpg

support will be added, meaning quicker compiles and a smaller library.





The ILUT_USE_XXX #define's:

---------------------------



To disable support for a specific API, edit IL/ilut.h and comment the

corresponding #define.  Per example, to disable OpenGL functions support,

 add // in front of the line that reads:



#define ILUT_USE_OPENGL





Libraries needed to compile DevIL* :

-----------------------------------



Libraries.txt (included with the DevIL distribution) lists all libraries needed

to properly compile DevIL.



Precompiled versions and sources of all libraries needed to compile DevIL are

available at http://openil.sourceforge.net/libs/LibCompiled.zip and

http://openil.sourceforge.net/libs/LibSrc.zip , respectively.





Errors:

-------



All errors generated inside DevIL, along with illegal parameters passed to

DevIL functions are caught and passed to ilSetError(), an internal library

function.  The calling program can call ilGetError() to get the value of the

error generated.  Error types are defined in il.h, using the 0x501 - 0x5FF

range.  ilGetError() will return 0 (IL_NO_ERROR) if no error has occurred.





Installation:

-------------



Just unzip and compile other libs included if needed.



Please also refer to MSVC++.txt for further instructions if you are using

Microsoft Visual C++.





Usage:

------



Before you do anything, call ilInit().  To load an image, simply:



#include <IL/il.h>

#include <IL/ilu.h>

#include <IL/ilut.h>





ILuint id, Error;



ilInit();



ilGenImages(1, &id);

ilBindImage(id);

ilLoadImage("default1.tga");  // Loads into the current bound image

Error = ilGetError();





Then you can do something with the image, such as sending it to OpenGL as a

texture:



ilutRenderer(IL_OPENGL);  // Switch the renderer

TexID = ilutGLBindTexImage();

Error = ilGetError();





Make sure to close the image when you are done with it (though DevIL

automatically deletes them when the program exits):



glDeleteTextures(1, &TexID);

ilDeleteImages(1, &id);





The TestIL project is included to test features of DevIL.



DevIL includes a project called GLTest.  This is a simple test of DevIL's

capabilities.  All it does it load any image and displays it in a window

created by FreeGlut, which is available on http://freeglut.sourceforge.net.

It is also included to let the user have an idea of what the library can

really be used for.



Several other test projects are included to test support with various display

APIs.  The WindowsTest project is a basic image program that only runs in

Windows right now but showcases several of DevIL's features through various

menus.



If you want more in-depth tutorials, you can find them on

http://www.imagelib.org, or they may be in your installation under the

/examples directory.  Documents are also available in the /docs directory.





Additional Reading

------------------



All image formats used in DevIL have corresponding documents on

http://www.wotsit.org, under the Graphics Files section.  These documents

proved invaluable for the creation of this library when there was no library

already available for that image format.





Legalese

--------



All contents of this file are intellectual property of Denton Woods

copyright 2001-2002.

