# LIBRARY:   ImageIO Library v0.13
# 
# FILE:      README
#
# COPYRIGHT: Copyright (c) 2003-2004 Adrien Treuille
# 
# AUTHORS:   Adrien Treuille (treuille [AT] cs [DOT] washington [DOT] edu)
#
# LICENSE:   The ImageIO Library is supplied "AS IS".  The Authors
#            disclaim all warranties, expressed or implied,
#            including, without limitation, the warranties of
#            merchantability and of fitness for any purpose. 
#            The Authors assume no liability for direct, indirect,
#            incidental, special, exemplary, or consequential
#            damages, which may result from the use of the ImageIO
#            Library, even if advised of the possibility of such
#            damage.
#
#            Permission is hereby granted to use, copy, modify,
#            and distribute this source code, or portions hereof,
#            for any purpose, without fee, for non-commercial
#            purposes. All rights reserved for commercial uses of
#            this source code.
#


I. Introduction


Currently it is quite difficult to open and save images in different
file formats on Linux. This library addresses this by providing an
extremely simple wrapper around farrago of libraries that currently
provide image I/O on Linux. You get no say in how the image is stored
and retrieved, but, in exchange, you can load an image and touch it's
pixels in one line of code.


II. Documentation


To load an image call:

int width, height;
char *imgName = "myImageName.png";
unsigned char *myImgBuffer = loadImageRGBA(imgName, &width, &height);

This will allocate a unsigned char array of size width * heigth * 4
containg the image. The width and height variables will be set to the
appropriate values. The library will automatically save the image to
the appropriate format based on its extension (currently, only .png
and .tiff are supported). The image is stored in big-endian RGBA
format, one byte per channel in rows-major form starting from the
lower left-hand corner. Alpha means opacity, not transparency. If the
image does not have transparency then the alpha channel will always be
255 for every pixel. If the image only has binary transparency, then
the alpha channel will be set to 255 for opaque pixels and 0 for
transparent pixels. The returned buffer has been dynamically
allocated, and can be deallocated with a call to
free(myImageBuffer). If this function fails for whatever reason, then
0 will be returned and width and height both will be set to -1.

To get all four channels of the (xth, yth) pixel of an image:

int r = myImageBuffer[imgIndx(x, y, width) + 0];
int g = myImageBuffer[imgIndx(x, y, width) + 1];
int b = myImageBuffer[imgIndx(x, y, width) + 2];
int a = myImageBuffer[imgIndx(x, y, width) + 3];

The imgIndx function simply converts (x, y) coordinates (measured from
the lower left-hand corner of the image) into an index into the
unsigned char array. The width variable is the width of the image in
pixels (of course).

To save an image:

saveImageRGBA(imgName, myImageBuffer, width, height);

This function returns true if the image was successfully save, false
otherwise.

The byte order of images created with this library is compatible with
that used by OpenGL. To write an image to the screen, simply use:

glDrawPixels(width, height, GL_RGBA, GL_UNSIGNED_BYTE, myImageBuffer);


IV. Compilation


This library has been tested with RedHat Linux 8.0. The requirement is
that you have libpng and libtiff installed. If you know of other
platforms on which this code compiles, please write me at
treuille@cs.washington.edu.

To link this code, create imageio.a by typing "make" in the imageio
directory. Then link with -ltiff -lpng and -limageio, for example:

g++ myAwesomeProgram.cpp imageio.o -o myAwesomeProgram -ltiff -lpng


V. Supported File Formats


* png
* tiff
* Would like to add more. You could help! (See section VI.)


VI. Things to do


* Fix bugs. If you find any, tell me, or better yet fix it and then
  send me the patched version. 
* Add more file formats. I would like to add at least gif and
  jpg. That would cover the big four (in my opinion). Again, I would
  love code contributions to this end.
* Create a configure script to compile in support for different
  formats based on library availability. Do you know how to do this?
  (I have no idea.)