
         __   _____    ______   ______   ___    ___
        /\ \ /\  _ `\ /\  ___\ /\  _  \ /\_ \  /\_ \
        \ \ \\ \ \L\ \\ \ \__/ \ \ \L\ \\//\ \ \//\ \      __     __
      __ \ \ \\ \  __| \ \ \  __\ \  __ \ \ \ \  \ \ \   /'__`\ /'_ `\
     /\ \_\/ / \ \ \/   \ \ \L\ \\ \ \/\ \ \_\ \_ \_\ \_/\  __//\ \L\ \
     \ \____//  \ \_\    \ \____/ \ \_\ \_\/\____\/\____\ \____\ \____ \
      \/____/    \/_/     \/___/   \/_/\/_/\/____/\/____/\/____/\/___L\ \
                                                                  /\____/
                                                                  \_/__/

                  Version 2.5, by Angelo Mottola, 2000-2004



Thanks for downloading JPGalleg! This add-on for Allegro will allow you to
load/save JPG images using standard Allegro image handling functions.
Its main advantages are:


* Supports baseline and progressive JPG decoding, and baseline JPG encoding.
  This should ensure it'll load almost any JPG image you'll throw at it

* Full Allegro integration: use load_bitmap() to load JPGs as if they were
  BMPs or other Allegro supported image formats

* Fast encoding/decoding

* Allegro datafile support: store JPGs in datafiles using the Grabber (plugin
  included), then load your datafiles from your programs and use JPG objects
  as if they were normal BITMAPs

* Encoding/decoding work on both files and memory data

* Small footprint: compiled library weights only 40K and is self-contained,
  in that it doesn't depend on external libraries other than Allegro


It does not support arithmetic coding, but this shouldn't be a problem at all
as most JPG don't use it as it's a patented type of encoding. Standard
baseline and progressive formats are fully supported; if you fail to load a
particular JPG image, please let me know!

JPGalleg needs Allegro 4.0 or newer to run, and should work on any platform
supported by Allegro, even if it has only been successfully tested under
Windows (MinGW32), Linux and MacOS X.



Install instructions
--------------------

JPGalleg is shipped in source code form, so you need to compile it first in
order to use it. Supported compilers are DJGPP (DOS), MinGW32 (Windows), MS
Visual C++ (6.0 or newer) and gcc (Linux, BeOS, MacOS X).
If you're willing to use Visual C++, you need GNU make in order to install;
you can grab a working copy of it from the MinGW32 Sourceforge project:

   http://prdownloads.sf.net/mingw/make-3.79.1-20010722.tar.gz?download

Place the make.exe program in a directory pointed by your $PATH environmental
variable and you're done.
To install, the steps to follow are almost the same under all platforms:


If you're under DOS/Windows:
   fix.bat <platform>

If you're under an Unix variant:
   ./fix.sh <platform>


Where <platform> must be one of "djgpp", "mingw32", "msvc", "unix", "beos"
or "macosx".
This will configure JPGalleg to be compiled for the selected environment.
Next you just have to start the build process:


   make


Under platforms that supports it, this will assume a dynamic version of Allegro
to be installed on the system; if you have a static Allegro, you need to use:


   make STATICLINK=1


You can also build a special debugging version of the library instead, by
issueing:


   make DEBUG=1


The debugging version will output lots of messages to stderr, and it could
be useful when dealing with a JPG image JPGalleg fails to load.
In any case, at the end of the build process you should get the compiled
library (in lib/libjpgal.a or lib/libjpgal.lib); you need to install it into
your system so that your compiler will know where to look for it when you
link against it (warning: this step requires root permissions under Unix and
MacOS X):


   make install


Congratulations! You have now successfully installed JPGalleg, and you are
ready to use it in your own programs. See the next section "Using JPGalleg"
for details.
You may also want to install the JPGalleg Grabber plugin; this will let you
manage JPG images easily from the Allegro Grabber utility, so you can store
and use JPGs in datafiles. You need to have set the ALLEGRO environmental
variable before being able to install the plugin; this variable must contain
the full path to your local Allegro directory. If you don't have it set yet,
proceed this way:


If you're under DOS/Windows:
   set ALLEGRO=C:\ALLEGRO
If you're under an Unix variant:
   export ALLEGRO=~/allegro


supposing you previously installed Allegro C:\ALLEGRO (for DOS/Windows) or
into ~/allegro (for Unix-like systems).
Once you have the ALLEGRO environmental variable set, just type


   make plugin


to install the plugin. This will rebuild the Grabber that will now support
JPG images natively.
For more info on the plugin, see section "Grabber plugin" below.



Using JPGalleg
--------------

JPGalleg is a library, and as such you need to link against it every time you
want to use its functionalities. If you have successfully installed the
package, the library libjpgal.a is already available for your compiler to use;
you just have to specify the "-ljpgal" command line link option when linking
your programs (on gcc based platforms); for example:


   gcc myprog.c -o myprog.exe -lalleg -ljpgal


On MSVC, you need to add libjpgal.lib to the list of libraries linked to
your project.
You also need to include "jpgalleg.h" at the beginning of your source files,
in order to use the library functions:


   #include <jpgalleg.h>


See next section for a reference of the JPGalleg functions.



Functions reference
-------------------

int jpgalleg_init()

   Parameters:
      none

   Returns 0 on success, -1 on error.
   
   
   This function initializes the JPGalleg library, by registering the JPG file
   format with the Allegro image loading and datafile subsystems. You don't
   really need to call this before calling any other library functions, but
   if you do, load_bitmap() will recognize files with the JPG extension, and
   datafiles holding JPEG objects will automatically decode them on datafile
   load, meaning you'll be able to work with them as if they were normal
   Allegro BITMAPs.
   Currently this function always returns 0.

______________________________________________________________________________

BITMAP *load_jpg(AL_CONST char *filename,
                 RGB *palette)

   Parameters:
      filename          Name of the JPG file to be loaded
      palette           PALETTE structure that will hold the JPG palette
   
   Returns the loaded image into a BITMAP structure, or NULL on error.
   
   
   Similar to the other Allegro image loading functions, this is a shortcut
   version of load_jpg_ex(), specifying no progress callback.

______________________________________________________________________________

BITMAP *load_jpg_ex(AL_CONST char *filename,
                    RGB palette,
		    void (*callback)(int progress))

   Parameters:
      filename          Name of the JPG file to be loaded
      palette           PALETTE structure that will hold the JPG palette
      callback          Progress callback (see below)
   
   Returns the loaded image into a BITMAP structure, or NULL on error.
   
   
   load_jpg() loads a JPG image from a file and returns it in a BITMAP; it is
   similar to the other Allegro image loading functions. The returned bitmap
   will be 24 or 8 bit, depending on if the loaded JPG stores a truecolor or a
   greyscale image. Allegro color conversion rules apply here, so pay attention
   as if the COLORCONV_TOTAL flag is set (as is by default), the image will
   be automatically converted to the current color depth before being given
   to the user (see Allegro documentation of function set_color_conversion()
   for details).
   If image is in greyscale, `palette' will be filled with a greyscale palette,
   otherwise the generate_optimized_palette() or generate_332_palette() Allegro
   functions will be used to build it depending on if the current gfx mode is 8
   bit or not. You can also specify NULL in this parameter, in which case no
   palette is returned.
   The callback parameter can be used to specify a callback function to be used
   as progress indicator. The function must return void and accept only one
   parameter, an integer, that will range 0-100 specifying the percentage of
   progress achieved at call time. Pay attention since the number of times this
   callback gets called varies; it can be called up to several hundreds times,
   and thus receive the same percentage value for more than one call.
   On error, this function returns NULL and sets the jpgalleg_error global
   variable to the proper error code (see the "Error codes" section).

______________________________________________________________________________

BITMAP *load_memory_jpg(void *buffer,
                        int size,
                        RGB *palette)

   Parameters:
      buffer            Pointer to a block of memory that holds the JPG data
      size              Size of the memory block
      palette           PALETTE structure that will hold the JPG palette
   
   Returns the loaded image into a BITMAP structure, or NULL on error.
   
   
   This function is a shortcut version of load_memory_jpg_ex(), specifying no
   progress callback.

______________________________________________________________________________

BITMAP *load_memory_jpg_ex(void *buffer,
                           int size,
                           RGB *palette,
			   void (*callback)(int progress))

   Parameters:
      buffer            Pointer to a block of memory that holds the JPG data
      size              Size of the memory block
      palette           PALETTE structure that will hold the JPG palette
      callback          Progress callback (see load_jpg_ex())
   
   Returns the loaded image into a BITMAP structure, or NULL on error.
   
   
   This function behaves exactly as load_jpg(), but tries to decode a JPG
   image held into a memory block. The memory block size is needed to ensure
   the JPG data integrity.

______________________________________________________________________________

int save_jpg(AL_CONST char *filename,
             BITMAP *image,
             AL_CONST RGB *palette)

   Parameters:
      filename          Name of the file that will hold the JPG image
      image             The BITMAP structure holding the image data to save
      palette           PALETTE structure holding the image palette
   
   Returns 0 on success, -1 on error.
   
   
   Similar to the other Allegro image saving functions, this is a shortcut
   version of save_jpg_ex(), saving the image with a default quality of 75,
   no subsampling, no optimization and no progress callback.

______________________________________________________________________________

int save_jpg_ex(AL_CONST char *filename,
                BITMAP *image,
                AL_CONST RGB *palette,
                int quality,
                int flags,
		void (*callback)(int progress))

   Parameters:
      filename          Name of the file that will hold the JPG image
      image             The BITMAP structure holding the image data to save
      palette           PALETTE structure holding the image palette
      quality           JPG encoding quality, in the range 1-100
      flags             Miscellaneous encoding flags (see below)
      callback		Progress callback (see load_jpg_ex())
   
   Returns 0 on success, -1 on error.
   
   
   Saves an image held in an Allegro BITMAP structure into a JPG file, using
   baseline encoding. The image can be any color depth, but the saved JPG will
   always be a 24 bit truecolor image (or 8 bit if saving in greyscale).
   Quality ranges from 1 (very low) to 100 (very high) (other values are
   clamped in this range); a value of 90 already gives an image that is hardly
   distinguishable from the original one. Obviously higher quality means bigger
   file size.
   JPGalleg supports chrominance subsampling; that is, while luminance (which
   specify the brightness of each pixel) is always sampled once for every
   image pixel, chrominance (which is used to specify the chromatic components
   of each pixel) can be sampled from every image pixel (no subsampling, also
   named mode 444), only on even pixels horizontally (mode 422), or only on
   even pixels both horizontally and vertically (mode 411). The mode name
   already tells you the subsampling type: for example 422 means that for
   4 luminance samples, only 2 chrominance samples are taken.
   Subsampling helps reducing the final JPG file size and is hardly noticeable
   by the human eye, expecially if you use high qualities. A good compromise
   in quality/size settings is for example a quality of 90 and a subsampling
   mode 411.
   You specify the subsampling mode in the `flags' parameter to this function,
   by setting one of the following constants (defined in jpgalleg.h):
   
      JPG_SAMPLING_444      For mode 444 (no subsampling)
      JPG_SAMPLING_422      For mode 422 (horizontal subsampling)
      JPG_SAMPLING_411      For mode 411 (horizontal and vertical subsampling)
   
   The flags parameter can accept more options, chained together by a bitwise
   OR. If you pass the JPG_GREYSCALE constant, the image will be saved in
   greyscale mode; only the luminance component of the image will be saved,
   therefore any specified subsampling of the chrominance is ignored.
   Passing JPG_OPTIMIZE to the flags parameter will activate optimized
   encoding; the routine will take twice the time to complete, but the saved
   file size will be reduced by an average 10% compared to unoptimized mode.
   The final function parameter can be used to specify a callback for progress
   indication, and works the same as seen in load_jpg_ex().
   This function returns 0 on success, or -1 on error. If an error occured,
   you can get more details on it by checking the jpgalleg_error global
   variable. See the "Error codes" section for more details.

______________________________________________________________________________

int save_memory_jpg(void *buffer,
                    int *size,
                    BITMAP *image,
                    AL_CONST RGB *palette)
   
   Parameters:
      buffer            Pointer to a memory buffer that will hold the JPG data
      size              Size of the memory buffer (see save_memory_jpg_ex())
      image             The BITMAP structure holding the image data to save
      palette           PALETTE structure holding the image palette
   
   Returns 0 on success, -1 on error.
   
   
   This is a shortcut version of save_memory_jpg_ex(), saving the image with a
   default quality of 75, no subsampling, no optimization and no progress
   callback.

______________________________________________________________________________

int save_memory_jpg_ex(void *buffer,
                       int *size,
                       BITMAP *image,
                       AL_CONST RGB *palette,
                       int quality,
                       int flags,
		       void (*callback)(int progress))
   
   Parameters:
      buffer            Pointer to a memory buffer that will hold the JPG data
      size              Size of the memory buffer (see below)
      image             The BITMAP structure holding the image data to save
      palette           PALETTE structure holding the image palette
      quality           JPG encoding quality, in the range 1-100
      flags             Miscellaneous encoding flags (see save_jpg_ex())
      callback          Progress callback (see load_jpg_ex())
   
   Returns 0 on success, -1 on error.
   
   
   This is the same as save_jpg_ex(), but encodes the image in a memory block
   rather than into a file. The `size' parameter has a double function: on
   input, you must set it to the size of the memory buffer that will hold the
   encoded JPG data (this ensures the function will fail if the buffer is too
   small to hold the encoded JPG), on output it'll hold the final size of the
   encoded JPG data in bytes.

______________________________________________________________________________



Error codes
-----------

All the JPGalleg functions set the jpgalleg_error global variable to a proper
error code on error, so if a function fails, you can check this variable for
more details on what went wrong. Here's the list of possible error codes
(defined in jpgalleg.h):

   JPG_ERROR_NONE
      No error occured during last operation.
   
   JPG_ERROR_READING_FILE
      There was an I/O error reading from a file.
   
   JPG_ERROR_WRITING_FILE
      There was an I/O error writing to a file.
   
   JPG_ERROR_INPUT_BUFFER_TOO_SMALL
      The memory buffer holding the encoded JPG data is too small for the JPG
      itself. The JPG is truncated and can't be loaded.
   
   JPG_ERROR_OUTPUT_BUFFER_TOO_SMALL
      The buffer specified when saving a JPG image is too small to hold the
      encoded JPG data.
   
   JPG_ERROR_HUFFMAN
      An huffman encoding error has occured while saving a JPG. This should
      never happen and is considered an internal error, so if you ever get
      this error, please report it to me!
   
   JPG_ERROR_NOT_JPEG
      The file/data being loaded isn't recognized as a valid JPG image.
   
   JPG_ERROR_UNSUPPORTED_ENCODING
      The JPG file/data being loaded is encoded in a format not supported by
      JPGalleg. Currently the library can only load baseline and progressive
      encoded JPG images.
   
   JPG_ERROR_UNSUPPORTED_COLOR_SPACE
      JPGalleg supports only greyscale and luminance/chrominance JPG images.
      If the JPG being loaded isn't encoded in one of these color spaces, this
      error occurs.
   
   JPG_ERROR_UNSUPPORTED_DATA_PRECISION
      JPGalleg only supports 8 bit data precision. If the JPG being loaded is
      not encoded using this precision, this error occurs.
   
   JPG_ERROR_BAD_IMAGE
      The JPG file/data being loaded is corrupted.
   
   JPG_ERROR_OUT_OF_MEMORY
      JPGalleg ran out of memory while decoding a JPG image.



Grabber plugin
--------------

JPGalleg ships with a plugin for the Allegro Grabber utility. This allows the
Grabber to easily handle JPG images into datafiles, so you can store your JPGs
and later load the datafile and see them as normal Allegro BITMAPs.
For informations on how to install the Grabber plugin, see section "Install
instructions". Alternatively, you can copy the whole contents of the
jpgalleg/plugin directory into your allegro/tools/plugins directory, and then
recompile the grabber by calling

   make tools/grabber

from your root Allegro directory. Be sure you already successfully installed
JPGalleg before installing the plugin, otherwise the plugin will not compile!
Once you have a JPG-enabled Grabber, you can create and grab new data objects
of type "JPEG"; these will hold the compressed JPG data of your images.
To create a new JPEG object, use New -> JPG image. A new temp 32x32 JPG image
will be created and assigned to the new object, as if you created a normal
bitmap object. You can now use the grab command on that object to load any
Allegro supported image into it; obviously you can now grab JPG images, but
you can also grab the other Allegro supported image formats, which will be
converted to JPG before being assigned to the JPEG object. Conversion to JPG
only occurs if the selected image isn't already in JPG format, and by default
the conversion will use a quality of 75 and no subsampling.
You can alter these settings at any time by using the dialog which appears
when you select the menu item File -> JPG import settings. Beware though that
the new settings will only apply on the next image conversions, not to images
already imported.

When you load a datafile holding JPEG type objects, these will automatically
be decoded into normal BITMAP objects at datafile load time. This means that
if you have stored a JPEG object named "MY_JPG_IMAGE" into a datafile, after
you've loaded the datafile into `data', you'll be able to call:

   BITMAP *bmp = data[MY_JPG_IMAGE].dat;
   blit(bmp, screen, 0, 0, 0, 0, bmp->w, bmp->h);

As if MY_JPG_IMAGE was a normal BITMAP (and infact it is, after you've loaded
the datafile).
A final hint: when storing JPGs into your datafiles, do not use compression,
otherwise it is likely your datafile will be even bigger than the uncompressed
version...



Frequently Asked Questions
--------------------------

Q) I get a "undefined reference to: 'register_datafile_object'" message when
   linking my program, while the examples shipped with the library compiled
   nicely. What's wrong?

A) Try swapping the order with which you link Allegro and JPGalleg to your
   program. This should solve the problem.


Q) My JPG image won't load! What can I do?

A) That JPG is probably not a standard baseline or progressive encoded JPG.
   JPGalleg can't load arithmetic encoded JPGs; these are rare, but it could
   be your case. In order to load it, you first need to convert it to baseline
   or progressive format; most paint programs will support at least one of
   them. The encoding format is usually selected in the same dialog in which
   you set the JPG quality when saving.
   If your image is already a baseline or progressive JPG and it won't still
   load, please contact me and send me the image; I'll try to spot the bug and
   maybe fix it in the next JPGalleg release.


Q) Why isn't arithmetic encoding supported?

A) Arithmetic encoding uses a patented algorithm, so it is unlikely it'll ever
   be supported in a free library like JPGalleg.
   

Q) Why JPGs saved by JPGalleg are bigger than (my paint program) generated
   JPGs?

A) Saving a JPG is a complex task, and the compression relies on several
   factors. The quality factor as an example, is implementation dependent, and
   is therefore different from the one used by other programs; a JPGalleg
   quality of 90 may correspond to a completely different quality elsewhere.
   You should also check subsampling: activating it will help reducing final
   file size a lot. And you can also use the JPG_OPTIMIZE flag to generate
   optimized huffman encoding tables that will help reducing size by another
   average 10%.


Q) Why can't I save JPGs using progressive encoding?

A) In order to be compact, JPGalleg only supports saving in baseline encoding.
   Adding support for saving in progressive mode too would add weight to the
   lib, and IMHO it's not really worth it, and behind the scope of this
   library.



Versions history
----------------

Version 2.5 (July 2004)
    * Now directly works on and returns a 24 bit image when dealing with
      truecolor JPGs, instead of using an intermediate 32 bpp buffer
    * New faster YCbCr <--> RGB MMX routines
    * Refactored I/O subsystem, now always works in memory internally
    * Optimized bit stream fetching resulting in big performance bump
    * Reduced memory footprint
    * Fixed a possible memory leak in the decoder

Version 2.4 (June 2004)
    * Changed the decoder IDCT algorithm to AAN, ensuring faster decoding
    * Added an experimental MMX IDCT routine
    * Small optimizations on other parts of the decoder
    * Fixed a bug in the decoder not recognizing some EXIF images
    * Tightened a bit the encoder code
    * Reworked build system to use different target directories on different
      platforms
    * Added a small benchmark utility
    
Version 2.3 (March 2004)
    * Fixed output colors bug when decoding JPGs while in 32 bits mode
    * Small optimization to the decoder
    * Refactored encoder code, enhanced compactness
    * Added progress callback functionality to both decoder and encoder
    * Enhanced errors reporting
    * Reworked encoder quantization resulting in big output size reduction at
      the same quality; also changed the quality curve formula
    * Made ex5 to report expected size of file when saving JPGs and to show
      progress when loading/saving
    * Added a license

Version 2.2 (February 2004)
    * Updated codebase to be compatible with latest Allegro WIPs
    * Added debug capabilities to the lib
    * Added optimized huffman tables generation to encoder
    * Added support for loading JPGs with a 422 subsampling mode with an 8x16
      MCU (previously supported only 16x8)
    * Can now load EXIF JPG images
    * Now loaded images are either 8 (greyscale) or 24 (truecolor) bit, rather
      than always 32 bit
    * Fixed loading of JPGs with a restart interval of 0
    * Fixed little endianess related issues
    * Reworked make system, added MS Visual C++ and MacOS X support, added a
      "plugin" target
    * Replaced example images with smaller ones
    * Fixed some small bugs in the grabber plugin

Version 2.1 (May 2003)
    * Small bugfixes to the library and the Grabber plugin
    * Optimized the decoder
    * Now supports progressive JPG decoding
    * The encoder has a new better quality curve formula
    * Updated the docs and added a FAQ

Version 2.0 (April 2003)
    * Complete rewrite of the library
    * Faster, more baseline JPG compliant decoder
    * Added a baseline JPG encoder
    * Uses dedicated MMX routines for YCbCr <--> RGB color space conversion
      when available
    * Proper Allegro datafile support: decodes JPG objects on datafile load
    * Added a Grabber plugin
    * New examples
    * Uses a dedicated makefile for each supported platform
    * Now compiles as a standalone library

Version 1.2 (March 2002)
    * Faster decoding by using fixed point math in the YCbCR -> RGB color
      space conversion.
    * Fixed compatibility with C++
    * Modified makefile to support multiple platforms.

Version 1.1 (June 2000)
    * Added support for loading JPGs from memory
    * New examples with better test images.

Version 1.0 (May 2000)
    * First public release, supports baseline decoding from JPG files.



Thanks
------

* Shawn Hargreaves and the many others who contributed to the excellent
  Allegro library; keep on rockin'!
* The Independent JPEG Group: the fast DCT algorithm used here comes from
  their great jpeg codec package.
* Cristi Cuturicu for his JPEG compression and file format FAQ. Without your
  document, my work would have never been possible.
