Menu
▾
▴
Tree [656fb3] master / History
Björn Ganster
unknown
Read Me
Resilient Image Library (ResIL) version 1.7.9 Readme, Notes and Quick Use
-------------------------------------------------------------------------
<DZA[afk]> ResIL 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?
-----------
ResIL 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.
It was created as an updated fork of DevIL. Like DevIL, ResIL offers you a
simple way to implement loading, manipulating, filtering, converting,
displaying, saving from/to several different image formats in your own project.
ResIL source code uses code from the following projects:
ILMBase
Jasper
The Independent JPEG Group's JPEG software
Little CMS
libMNG
libPNG
OpenEXR
Tiff
zlib
Please refer to the idividual license files contained in the full source of ResIL
for the respective licenses of the projects.
Where can I find it?
--------------------
ResIL can be found at http://sourceforge.net/projects/resil
How do I build and install the 3 libraries ?
--------------------------------------------
The easiest way to build ResIL is to use cmake. It supports a wide range of platforms and compilers.
For building under Windows with MSVC 2010 or later, use the project files provided in <ResIL>\projects\MSVC10.
In case you ship builds, ResIL can be built with libinstrumentation to obtain stacktraces consisting of pairs of <File Number>:<Line Number>. This is useful because often you can't run debuggers on other people's computers. Either download libinstrumentation from
https://sourceforge.net/projects/libinstrumentation/
or make sure that HAVE_LIBINSTRUMENTATION is undefined - this will disable this feature.
There are files to support the "./configure; make" workflow preferred by Linuxers. Unfortunately, I do not have the time to maintain those files. If you're interested in fixing yourself, please send me a patch.
More Extensive Documentation
----------------------------
This file is only a quick guide to point you to more detailed information on
how to use ResIL. If you want to know how more about the functions provided
by ResIL, look at src-SDLTest. There is a folder containing example code
in <ResIL>/examples, but I do not currently have the time to maintain it.
Sorry for that ...
Why the hell another image library?
-----------------------------------
I have never seen an image library that can do everything ResIL does. Sure,
various different libraries can do part of what ResIL 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 ResIL as well as ResILU and
ResILUT, unless otherwise stated. (This file is best viewed with word wrap on.)
Errors:
-------
All errors generated inside ResIL, along with illegal parameters passed to
ResIL 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 ResIL 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 ResILError;
ilInit();
ResILError = ilGetError();
if (ResILError != IL_NO_ERROR) {
printf ("ResIL Error (ilInit: %s\n", iluGetErrorString (ResILError));
exit (2);
}
....
ILuint ResILID;
ilGenImages(1, &ResILID);
ilBindImage(ResILID);
ilLoadImage("default1.tga"); // Loads into the current bound image
ResILError = ilGetError();
if (ResILError != IL_NO_ERROR) {
printf ("ResIL Error (ilLoadImage: %s\n", iluGetErrorString (ResILError));
exit (2);
}
....
ilutRenderer(IL_OPENGL); // Switch the renderer
....
GLuint openglID, openglError;
openglID = ilutGLBindTexImage(); // This generates the texture for you
ResILError = ilGetError();
if (ResILError != IL_NO_ERROR) {
printf ("Error: %s\n", iluGetErrorString (ResILError));
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 ResIL
// automatically deletes them when the program exits):
glDeleteTextures(1, &openglID);
ilDeleteImages (1, &ResILID);
The example above demonstrates the use of the API version 1. There is a seperate API version 2, where all functions are start of il2, ilu2 or ilut2. These functions do not rely on a currently bound image, so the image to process has to be passed in as a first parameter. API version 2 can work in a multithreaded environment as long as there is only one thread operating on each image. This has been tested and it works. If you still run into issues, please let us know.
More Examples:
---------
The TestIL project is included to test features of ResIL.
ResIL includes a project called GLTest. This is a simple test of ResIL'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 ResIL'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 ResIL 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. Last edited by Björn Ganster.