Open Image Library version 1.5.8a Readme, Notes and Quick Use
-------------------------------------------------------------
<fiend-> LSD enhances your CGA to 32bit color


What is it?
-----------

OpenIL is an OpenSource image library based on the lgpl license.  OpenIL* is capable of loading/manipulating/converting/displaying/saving from/to several different image formats.


Why the hell another image library?
-----------------------------------

I have never seen an image library that can do everything OpenIL does.  Sure, various different libraries can do part of what OpenIL can do as well or even better, but I wanted a simple to use library that encompassed all of these features.


Basic Readme
------------

Most anything stated in this document applies to OpenIL as well as OpenILU and OpenILUT, unless otherwise stated.
(This file is best viewed with word wrap on.)


All basic types used in this library are taken from OpenGL, defined in gl/gl.h.  We thought it best to not define our own cross-platform types, which could cause some confusion and was deemed unnecessary.


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.

If you enable any of the IL_NO_XXX #define's, you will need to manually edit the .def file for OpenIL, found in /def, if you are compiling with MSVC++.  Just place a semicolon in front of the functions that are being rid of by you uncommenting the #define.


Libraries needed to compile OpenIL* :
-----------------------------------

ZLib / Libpng for .png support available at http://www.libpng.org/pub/png/
Libjpeg for .jpg support from http://www.ijg.org/
Libtiff for .tif support from http://www.libtiff.org
glext.h from http://oss.sgi.com/projects/ogl-sample/ABI/glext.h (as <gl/glext.h>)

As of this writing, these libraries haven't been uploaded to the OpenIL site, but we may put some precompiled versions plus the sources up there soon.


Errors:
-------

All errors generated inside OpenIL, along with illegal parameters passed to OpenIL 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...  You should be able to just go to tools - options - directories and add in the include and lib directories for OpenIL instead of editing the cumbersome batch files.  You will need to edit the post-build tabs for each OpenIL* project (Project - Settings - Post-Build) if your Windows System directory isn't c:\windows\system.


Usage:
------

As of right now, no function needs to be called to setup the library, as it is all setup in DllMain() in Windows.  To load an image, simply:

#include <il/ilut.h>


GLuint id;

ilGenImages(1, &id);
ilBindImage(id);
ilLoadImage("default1.tga");  // Loads into the current binded image
GLint 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 = ilutBindImage();


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

ilDeleteImages(1, &id);


The TestIL project is included to test features of OpenIL.

OpenIL now includes a new project called WindowTest.  This is a simple test of OpenIL's capabilities.  All it does it load background.tga and display it in a window created by FreeGlut, which is available on http://freeglut.sourceforge.net (I think...).  It is also included to let the user have an idea of what the library can really be used for.


Function Descriptions:
----------------------

These will be included later, when I have much more free time.  A little bit of digging through the sources should give you any answers you want.  The code is normally not hard to understand at all...it's just that there's a lot of it.  Too bad I comment like crap...



Possible Future Additions:
--------------------------

Use pngcrush (http://pmt.sourceforge.net)
Incorporate .jif support (http://jeff.cafe.net/jif)
Jpeg2000 support?


Additional Reading
------------------

All image formats used in OpenIL 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
--------

Open Image Library (OpenIL) is in no way associated with the Open Graphics Library (OpenGL) provided by Silicon Graphics Incorporated and several other vendors.  OpenGL is a trademark of Silicon Graphics Incorporated.

All contents of this file are intellectual property of Denton Woods, copyright 2000.