JPEGView/Independent JPEG Group/libjpeg.doc

USING THE IJG JPEG LIBRARY

Copyright (C) 1994, Thomas G. Lane.
This file is part of the Independent JPEG Group's software.
For conditions of distribution and use, see the accompanying README file.


This file describes how to use the IJG JPEG library within an application
program.  Read it if you want to write a program that uses the library.

The file example.c provides heavily commented skeleton code for calling the
JPEG library.  Also see jpeglib.h (the include file to be used by application
programs) for full details about data structures and function parameter lists.
The library source code, of course, is the ultimate reference.

Note that there have been *major* changes from the application interface
presented by IJG version 4 and earlier versions.  The old design had several
inherent limitations, and it had accumulated a lot of cruft as we added
features while trying to minimize application-interface changes.  We have
sacrificed backward compatibility in the version 5 rewrite, but we think the
improvements justify this.


TABLE OF CONTENTS
-----------------

Overview:
	Functions provided by the library
	Outline of typical usage
Basic library usage:
	Data formats
	Compression details
	Decompression details
	Mechanics of usage: include files, linking, etc
Advanced features:
	Compression parameter selection
	Decompression parameter selection
	Special color spaces
	Error handling
	Compressed data handling (source and destination managers)
	I/O suspension
	Abbreviated datastreams and multiple images
	Special markers
	Downsampled image data
	Progress monitoring
	Memory management
	Library compile-time options
	Portability considerations
	Notes for MS-DOS implementors

You should read at least the overview and basic usage sections before trying
to program with the library.  The sections on advanced features can be read
if and when you need them.


OVERVIEW
========

Functions provided by the library
---------------------------------

The IJG JPEG library provides C code to read and write JPEG-compressed image
files.  The surrounding application program receives or supplies image data a
scanline at a time, using a straightforward uncompressed image format.  All
details of color conversion and other preprocessing/postprocessing can be
handled by the library.

The library includes a substantial amount of code that is not covered by the
JPEG standard but is necessary for typical applications of JPEG.  These
functions preprocess the image before JPEG compression or postprocess it after
decompression.  They include colorspace conversion, downsampling/upsampling,
and color quantization.  The application indirectly selects use of this code
by specifying the format in which it wishes to supply or receive image data.
For example, if colormapped output is requested, then the decompression
library automatically invokes color quantization.

A wide range of quality vs. speed tradeoffs are possible in JPEG processing,
and even more so in decompression postprocessing.  The decompression library
provides multiple implementations that cover most of the useful tradeoffs,
ranging from very-high-quality down to fast-preview operation.  On the
compression side we have generally not provided low-quality choices, since
compression is normally less time-critical.  It should be understood that the
low-quality modes may not meet the JPEG standard's accuracy requirements;
nonetheless, they are useful for viewers.

A word about functions *not* provided by the library.  We handle a subset of
the ISO JPEG standard; most baseline and extended-sequential JPEG processes
are supported.  (Our subset includes all features now in common use.)
Unsupported ISO options include:
	* Progressive storage (may be supported in future versions)
	* Hierarchical storage
	* Lossless JPEG
	* Arithmetic entropy coding (unsupported for legal reasons)
	* DNL marker
	* Nonintegral subsampling ratios
We support both 8- and 12-bit data precision, but this is a compile-time
choice rather than a run-time choice; hence it is difficult to use both
precisions in a single applicati