Developer's Image Library version 1.7.8 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 whose distribution is done under the
terms of the GNU LGPL license. See the COPYING file for more details.
DevIL offers you a simple way to implement loading, manipulating, filtering,
converting, displaying, saving from/to several different image formats in your
own project.


Where can I find it?
--------------------

DevIL can be found at http://openil.sourceforge.net


How do I build and install the 3 libraries ?
-----------------------------------------

*nix    users should read README.unix
VisualC users should read README.win
Cygwin  users should read README.cygwin
MacOSX  users should read README.macosx

PS: *nix stands for GNU/Linux, *BSD, SunOS/Solaris and perhaps some more.


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://openil.sf.net 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. (This file is best viewed with word wrap on.)


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.


Basic Usage:
------

This demonstrates loading an image through DevIL for OpenGL. Don't forget to
call ilInit before you before you do anything:

#include <IL/il.h>
#include <IL/ilu.h>
#include <IL/ilut.h>

...

ILuint devilError;


ilInit();

devilError = ilGetError();

if (devilError != IL_NO_ERROR) {
  printf ("Devil Error (ilInit: %s\n", iluGetErrorString (devilError));
  exit (2);
}

....

ILuint devilID;


ilGenImages(1, &devilID);
ilBindImage(devilID);
ilLoadImage("default1.tga");  // Loads into the current bound image
devilError = ilGetError();

if (devilError != IL_NO_ERROR) {
  printf ("Devil Error (ilLoadImage: %s\n", iluGetErrorString (devilError));
  exit (2);
}

....

ilutRenderer(IL_OPENGL);  // Switch the renderer

....

GLuint openglID, openglError;


openglID   = ilutGLBindTexImage(); // This generates the texture for you
devilError = ilGetError();

if (devilError != IL_NO_ERROR) {
  printf ("Error: %s\n", iluGetErrorString (devilError));
  exit (2);
}

if (openglError != GL_NO_ERROR) {
  printf ("Opengl Error (ilutGLBindTexImage): %s\n", gluGetErrorString (openglError));
  exit (2);
}



// Make sure to close the image when you are done with it (though DevIL
// automatically deletes them when the program exits):

glDeleteTextures(1, &openglID);
ilDeleteImages  (1, &devilID);


More Examples:
---------

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://openil.sf.net, 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-2008.

How do I compile the library ?
----------------------------------

Download and install. In the Unix way it will produce a shared library.
Using the project file for the Apple Developer Tools you can get a framework.
However they are without the external libraries which are needed to be installed.
However the packages are somehow out of date. but anyone can setup a new project easily.
DevIL was packaging them along with the distribution but that's was to hard to mantain
for each update of these libraries.


Libraries needed to compile DevIL* :
-----------------------------------

Needs the same libraries as the *nix version.

Installation:
-------------
All the libraries can be easiliy installed from source, manually or using
some tools like the fink project or the darwinports project.

to use fink you must set the environment variables. for some libraries you must have
the PATH correctly set up to execute programs installed with the tools.

tcsh:
setenv LDFLAGS -L/sw/lib
setenv CFLAGS -I/sw/include -L/sw/lib

sh:
export LDFLAGS=-L/sw/lib
export CFLAGS=-I/sw/includee -L/sw/lib

same thing with darwinports
tcsh:
setenv LDFLAGS -L/opt/local/lib
setenv CFLAGS -I/opt/local/include -L/opt/local/lib

sh:
export LDFLAGS=-L/opt/local/lib
export CFLAGS=-I/opt/local/include -L/opt/local/lib

How do I compile the 3 libraries?
--------------------------------

You will need autoconf, automake and libtool.

Just type:
autoreconf -i
./configure <your options here>
make
sudo make install

If you want to use the ILU and ILUT parts of DevIL, you will want to run
./configure --enable-ILU --enable-ILUT

If you want configure to install in /usr instead of /usr/local, append
--prefix=/usr to the ./configure line.

It should find automatically what can (or cannot) be built on your system.  Libtool, autoconf and
automake will need to be installed.  You may need to copy files from your libtool
into the libtools directory and overwrite ltmain.sh if it will not compile with the
included files.

NB : ./configure --help gives you all compiling options available for the three
      libs. This includes enabling/disabling picture formats, ilut apis.

Enable/Disable:
All features are basically enabled, and a test will be performed
to verify if is possible to compile them in. If they are explicitly enabled
or disabled no test will occour.

Compiling under Cygwin or MingW in Windows:
------------------------------------------

Run the same commands as above.  You will need to have the following packages installed: gcc-core, gcc-mingw-core, gcc-g++, autoconf, automake, libtool.

Config.h and JasPer:
-------------------

If compiling with JasPer, you may need to modify config.h so that it does not
redefine things that are defined in JasPer's jas_config.h.  PACKAGE, PACKAGE_NAME,
etc. are generated for both projects, since they use a similar configuration
program.  If there are conflicts, just comment out the ones in DevIL's config.h.


Libraries needed to compile DevIL* :
-----------------------------------

They are all autodetected by the ./configure script. But if you want to include
one of those formats, you have just to install the corresponding lib :

(libs listed in libraries.txt)

or in your distro/port ftp/site/whatever_you_want :-)


Installation:
-------------

If #make succeeded, just type #make install, followed by #ldconfig
(as su, of course)

Where do I find the project files ?
-----------------------------------------

MSVC++ projects are in DevIL\projects\vc8 and DevIL\projects\vc9.
If compiling with Cygwin or MinGW, use the instructions in README.unix.


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.


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++.