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 application.

By itself, the library handles only interchange JPEG datastreams --- in
particular the widely used JFIF file format.  The library can be used by
surrounding code to process interchange or abbreviated JPEG datastreams that
are embedded in more complex file formats.  (For example, we anticipate that
Sam Leffler's LIBTIFF library will use this code to support the revised TIFF
JPEG format.)


Outline of typical usage
------------------------

The rough outline of a JPEG compression operation is:

	Allocate and initialize a JPEG compression object
	Specify the destination for the compressed data (eg, a file)
	Set parameters for compression, including image size & colorspace
	jpeg_start_compress(...);
	while (scan lines remain to be written)
		jpeg_write_scanlines(...);
	jpeg_finish_compress(...);
	Release the JPEG compression object

A JPEG compression object holds parameters and working state for the JPEG
library.  We make creation/destruction of the object separate from starting
or finishing compression of an image; the same object can be re-used for a
series of image compression operations.  This makes it easy to re-use the
same parameter settings for a sequence of images.  Re-use of a JPEG object
also has important implications for processing abbreviated JPEG datastreams,
as discussed later.

The image data to be compressed is supplied to jpeg_write_scanlines() from
in-memory buffers.  If the application is doing file-to-file compression,
reading image data from the source file is the application's responsibility.
The library emits compressed data by calling a "data destination manager",
which typically will write the data into a file; but the application can
provide its own destination manager to do something else.

Similarly, the rough outline of a JPEG decompression operation is:

	Allocate and initialize a JPEG decompression object
	Specify the source of the compressed data (eg, a file)
	Call jpeg_read_header() to obtain image info
	Set parameters for decompression
	jpeg_start_decompress(...);
	while (scan lines remain to be read)
		jpeg_read_scanlines(...);
	jpeg_finish_decompress(...);
	Release the JPEG decompression object

This is comparable to the compression outline except that reading the
datastream header is a separate step.  By doing this, information about the
image's size, colorspace, etc is available when the application selects
decompression parameters.  For example, the application can choose an output
scaling ratio that will fit the image into the available screen size.

The decompression library obtains compressed data by calling a data source
manager, which typically will read the data from a file; but other behaviors
can be obtained with a custom source manager.  Decompressed data is delivered
into in-memory buffers passed to jpeg_read_scanlines().

It is possible to abort an incomplete compression or decompression operation
by calling jpeg_abort(); or, if you do not need to retain the JPEG object,
simply release it by calling jpeg_destroy().

JPEG compression and decompression objects are two separate struct types.
However, they share some common fields, and certain routines such as
jpeg_destroy() can work on either type of object.

The JPEG library has no static variables: all state is in the compression
or decompression object.  Therefore it is possible to process multiple
compression and decompression operations concurrently, using multiple JPEG
objects.

Both compression and decompression can be done in an incremental memory-to-
memory fashion, if suitable source/destination managers are used.  However,
there are some restrictions on the processing that can be done in this mode.
See the section on "I/O suspension" for more details.


BASIC LIBRARY USAGE
===================

Data formats
------------

Before diving into procedural details, it is helpful to understand the
image data format that the JPEG library expects or returns.

The standard input image format is a rectangular array of pixels, with each
pixel having the same number of "component" values (color channels).  You
must specify how many components there are and the colorspace interpretation
of the components.  Most applications will use RGB data (three components
per pixel) or grayscale data (one component per pixel).

Note that there is no provision for colormapped input.  You can feed in a
colormapped image by expanding it to full-color format.  However JPEG often
doesn't work very well with colormapped source data, because of dithering
noise.  This is discussed in more detail in the JPEG FAQ and the other
references mentioned in the README file.

Pixels are stored by scanlines, with each scanline running from left to
right.  If you are working with color data, then the component values for each
pixel are adjacent in the row; for example, R,G,B,R,G,B,R,G,B,... for 24-bit
RGB color.  Each scanline is an array of data type JSAMPLE --- which is
generally "unsigned char", unless you've changed jmorecfg.h.

A 2-D array of pixels is formed by making a list of pointers to the starts of
scanlines; the scanlines need not be adjacent in memory.  Even if you process
just one scanline at a time, you must make a one-element pointer array to
serve this purpose.  Pointers to JSAMPLE rows are of type JSAMPROW, and the
pointer to the pointer array is of type JSAMPARRAY.

The library accepts or supplies one or more complete scanlines per call;
it is not possible to process part of a row at a time.  Scanlines are always
processed top-to-bottom.  You can process an entire image in one call if
you have it all in memory, but usually it's more convenient to process one
scanline at a time.

For best results, source data values should have the precision specified by
BITS_IN_JSAMPLE (normally 8 bits).  For instance, if you choose to compress
data that's only 6 bits/channel, you should left-justify each value in a
byte before passing it to the compressor.  If you need to compress data
that has more than 8 bits/channel, compile with BITS_IN_JSAMPLE = 12.
(See "Library compile-time options", later.)

The data format returned by the decompressor is the same in all details,
except that colormapped data is supported.  If you request colormapped
output then the returned data array contains a single JSAMPLE per pixel;
its value is an index into a color map.  The color map is represented as
a 2-D JSAMPARRAY in which each row holds the values of one color component,
that is, colormap[i][j] is the value of the i'th color component for pixel
value (map index) j.  Note that since the colormap indexes are stored in
JSAMPLEs, the maximum number of colors is limited by the size of JSAMPLE
(ie, at most 256 colors for an 8-bit JPEG library).


Compression details
-------------------

Here we revisit the JPEG compression outline given in the overview.

1. Allocate and initialize a JPEG compression object.

A JPEG compression object is a "struct jpeg_compress_struct" (plus a bunch of
subsidiary structures which are allocated via malloc(), but the application
doesn't control those directly).  This struct can be just a local variable in
the calling routine, if a single routine is going to execute the whole JPEG
compression sequence.  Otherwise it can be static or allocated from malloc().

You will also need a structure representing a JPEG error handler.  The part of
this that the library cares about is a "struct jpeg_error_mgr".  If you are
providing your own error handler, you'll typically want to embed the
jpeg_error_mgr struct in a larger structure; this is discussed later under
"Error handling".  For now we'll assume you are just using the default error
handler.  The default error handler will print JPEG error/warning messages on
stderr, and it will call exit() if a fatal error occurs.

You must initialize the error handler structure, store a pointer to it into
the JPEG object's "err" field, and then call jpeg_create_compress() to
initialize the rest of the JPEG object.

Typical code for this step, if you are using the default error handler, is

	struct jpeg_compress_struct cinfo;
	struct jpeg_error_mgr jerr;
	...
	cinfo.err = jpeg_std_error(&jerr);
	jpeg_create_compress(&cinfo);

jpeg_create_compress allocates a small amount of memory, so it could fail
if you are out of memory.  In that case it will exit via the error handler.


2. Specify the destination for the compressed data (eg, a file).

As previously mentioned, the JPEG library delivers compressed data to a
"data destination" module.  The library includes one data destination
module which knows how to write to a stdio stream.  You can use your own
destination module if you want to do something else, as discussed later.

If you use the standard destination module, you must open the target stdio
stream beforehand.  Typical code for this step looks like:

	FILE * outfile;
	...
	if ((outfile = fopen(filename, "wb")) == NULL) {
	    fprintf(stderr, "can't open %s\n", filename);
	    exit(1);
	}
	jpeg_stdio_dest(&cinfo, outfile);

where the last line invokes the standard destination module.

WARNING: it is critical that the binary compressed data be delivered to the
output file unchanged.  On non-Unix systems the stdio library may perform
newline translation or otherwise corrupt binary data.  To suppress this
behavior, you may need to use a "b" option to fopen (as shown above), or use
setmode() or another routine to put the stdio stream in binary mode.  See
cjpeg.c and djpeg.c for code that has been found to work on many systems.

You can select the data destination after setting other parameters (step 3),
if that's more convenient.  You may not change the destination between
calling jpeg_start_compress() and jpeg_finish_compress().


3. Set parameters for compression, including image size & colorspace.

You must supply information about the source image by setting the following
fields in the JPEG object (cinfo structure):

	image_width		Width of image, in pixels
	image_height		Height of image, in pixels
	input_components	Number of color channels (samples per pixel)
	in_color_space		Color space of source image

The image dimensions are, hopefully, obvious.  JPEG supports image dimensions
of 1 to 64K pixels in either direction.  The input color space is typically
RGB or grayscale, and input_components is 3 or 1 accordingly.  (See "Special
color spaces", later, for more info.)  The in_color_space field should be
assigned one of the enum constants JCS_RGB or JCS_GRAYSCALE.

JPEG has a large number of compression parameters that determine how the image
is encoded.  Most applications don't need or want to know about all these
parameters.  You can set all the parameters to reasonable defaults by calling
jpeg_set_defaults(); then, if there are particular values you want to change,
you can do so after that.  The "Compression parameter selection" section tells
about all the parameters.

You must set in_color_space correctly before calling jpeg_set_defaults(),
because the defaults depend on the source image colorspace.  However the
other three source image parameters need not be valid until you call
jpeg_start_compress().  There's no harm in calling jpeg_set_defaults() more
than once, if that happens to be convenient.

Typical code for a 24-bit RGB source image is

	cinfo.image_width = Width; 	/* image width and height, in pixels */
	cinfo.image_height = Height;
	cinfo.input_components = 3;	/* # of color components per pixel */
	cinfo.in_color_space = JCS_RGB; /* colorspace of input image */

	jpeg_set_defaults(&cinfo);
	/* Make optional parameter settings here */


4. jpeg_start_compress(...);

After you have established the data destination and set all the necessary
source image info and other parameters, call jpeg_start_compress() to begin
a compression cycle.  This will initialize internal state, allocate working
storage, and emit the first few bytes of the JPEG datastream header.

Typical code:

	jpeg_start_compress(&cinfo, TRUE);

The "TRUE" parameter ensures that a complete JPEG interchange datastream
will be written.  This is appropriate in most cases.  If you think you might
want to use an abbreviated datastream, read the section on abbreviated
datastreams, later.

Once you have called jpeg_start_compress(), you may not alter any JPEG
parameters or other fields of the JPEG object until you have completed
the compression cycle.


5. while (scan lines remain to be written)
	jpeg_write_scanlines(...);

Now write all the required image data by calling jpeg_write_scanlines()
one or more times.  You can pass one or more scanlines in each call, up
to the total image height.  In most applications it is convenient to pass
just one or a few scanlines at a time.  The expected format for the passed
data is discussed under "Data formats", above.

Image data should be written in top-to-bottom scanline order.  The JPEG spec
contains some weasel wording about how top and bottom are application-defined
terms (a curious interpretation of the English language...) but if you want
your files to be compatible with everyone else's, you WILL use top-to-bottom
order.  If the source data must be read in bottom-to-top order, you can use
the JPEG library's virtual array mechanism to invert the data efficiently.
Examples of this can be found in the sample application cjpeg.

The library maintains a count of the number of scanlines written so far
in the next_scanline field of the JPEG object.  Usually you can just use
this variable as the loop counter, so that the loop test looks like
"while (cinfo.next_scanline < cinfo.image_height)".

Code for this step depends heavily on the way that you store the source data.
example.c shows the following code for the case of a full-size 2-D source
array containing 3-byte RGB pixels:

	JSAMPROW row_pointer[1];	/* pointer to a single row */
	int row_stride;			/* physical row width in buffer */

	row_stride = image_width * 3;	/* JSAMPLEs per row in image_buffer */

	while (cinfo.next_scanline < cinfo.image_height) {
	    row_pointer[0] = & image_buffer[cinfo.next_scanline * row_stride];
	    jpeg_write_scanlines(&cinfo, row_pointer, 1);
	}

jpeg_write_scanlines() returns the number of scanlines actually written.
This will normally be equal to the number passed in, so you can usually
ignore the return value.  It is different in just two cases:
  * If you try to write more scanlines than the declared image height,
    the additional scanlines are ignored.
  * If you use a suspending data destination manager, output buffer overrun
    will cause the compressor to return before accepting all the passed lines.
    This feature is discussed under "I/O suspension", below.  The normal
    stdio destination manager will NOT cause this to happen.
In any case, the return value is the same as the change in the value of
next_scanline.


6. jpeg_finish_compress(...);

After all the image data has been written, call jpeg_finish_compress() to
complete the compression cycle.  This step is ESSENTIAL to ensure that the
last bufferload of data is written to the data destination.
jpeg_finish_compress() also releases working memory associated with the JPEG
object.

Typical code:

	jpeg_finish_compress(&cinfo);

If using the stdio destination manager, don't forget to close the output
stdio stream if necessary.

If you have requested a multi-pass operating mode, such as Huffman code
optimization, jpeg_finish_compress() will perform the additional passes using
data buffered by the first pass.  In this case jpeg_finish_compress() may take
quite a while to complete.  With the default compression parameters, this will
not happen.

It is an error to call jpeg_finish_compress() before writing the necessary
total number of scanlines.  If you wish to abort compression, call
jpeg_abort() as discussed below.

After completing a compression cycle, you may dispose of the JPEG object
as discussed next, or you may use it to compress another image.  In that case
return to step 2, 3, or 4 as appropriate.  If you do not change the
destination manager, the new datastream will be written to the same target.
If you do not change any JPEG parameters, the new datastream will be written
with the same parameters as before.  Note that you can change the input image
dimensions freely between cycles, but if you change the input colorspace, you
should call jpeg_set_defaults() to adjust for the new colorspace; and then
you'll need to repeat all of step 3.


7. Release the JPEG compression object.

When you are done with a JPEG compression object, destroy it by calling
jpeg_destroy_compress().  This will free all subsidiary memory.  Or you can
call jpeg_destroy() which works for either compression or decompression
objects --- this may be more convenient if you are sharing code between
compression and decompression cases.  (Actually, these routines are equivalent
except for the declared type of the passed pointer.  To avoid gripes from
ANSI C compilers, pass a j_common_ptr to jpeg_destroy().)

If you allocated the jpeg_compress_struct structure from malloc(), freeing
it is your responsibility --- jpeg_destroy() won't.  Ditto for the error
handler structure.

Typical code:

	jpeg_destroy_compress(&cinfo);


8. Aborting.

If you decide to abort a compression cycle before finishing, you can clean up
in either of two ways:

* If you don't need the JPEG object any more, just call
  jpeg_destroy_compress() or jpeg_destroy() to release memory.  This is
  legitimate at any point after calling jpeg_create_compress() --- in fact,
  it's safe even if jpeg_create_compress() fails.

* If you want to re-use the JPEG object, call jpeg_abort_compress(), or
  jpeg_abort() which works on both compression and decompression objects.
  This will return the object to an idle state, releasing any working memory.
  jpeg_abort() is allowed at any time after successful object creation.

Note that cleaning up the data destination, if required, is your
responsibility.


Decompression details
---------------------

Here we revisit the JPEG decompression outline given in the overview.

1. Allocate and initialize a JPEG decompression object.

This is just like initialization for compression, as discussed above,
except that the object is a "struct jpeg_decompress_struct" and you
call jpeg_create_decompress().  Error handling is exactly the same.

Typical code:

	struct jpeg_decompress_struct cinfo;
	struct jpeg_error_mgr jerr;
	...
	cinfo.err = jpeg_std_error(&jerr);
	jpeg_create_decompress(&cinfo);

(Both here and in the IJG code, we usually use variable name "cinfo" for
both compression and decompression objects.)


2. Specify the source of the compressed data (eg, a file).

As previously mentioned, the JPEG library reads compressed data from a "data
source" module.  The library includes one data source module which knows how
to read from a stdio stream.  You can use your own source module if you want
to do something else, as discussed later.

If you use the standard source module, you must open the source stdio stream
beforehand.  Typical code for this step looks like:

	FILE * infile;
	...
	if ((infile = fopen(filename, "rb")) == NULL) {
	    fprintf(stderr, "can't open %s\n", filename);
	    exit(1);
	}
	jpeg_stdio_src(&cinfo, infile);

where the last line invokes the standard source module.

WARNING: it is critical that the binary compressed data be read unchanged.
On non-Unix systems the stdio library may perform newline translation or
otherwise corrupt binary data.  To suppress this behavior, you may need to use
a "b" option to fopen (as shown above), or use setmode() or another routine to
put the stdio stream in binary mode.  See cjpeg.c and djpeg.c for code that
has been found to work on many systems.

You may not change the data source between calling jpeg_read_header() and
jpeg_finish_decompress().  If you wish to read a series of JPEG images from
a single source file, you should repeat the jpeg_read_header() to
jpeg_finish_decompress() sequence without reinitializing either the JPEG
object or the data source module; this prevents buffered input data from
being discarded.


3. Call jpeg_read_header() to obtain image info.

Typical code for this step is just

	jpeg_read_header(&cinfo, TRUE);

This will read the source datastream header markers, up to the beginning
of the compressed data proper.  On return, the image dimensions and other
info have been stored in the JPEG object.  The application may wish to
consult this information before selecting decompression parameters.

More complex code is necessary if
  * A suspending data source is used --- in that case jpeg_read_header()
    may return before it has read all the header data.  See "I/O suspension",
    below.  The normal stdio source manager will NOT cause this to happen.
  * Abbreviated JPEG files are to be processed.  See the section on
    abbreviated datastreams.  Standard applications that deal only in
    interchange JPEG files need not be concerned with this case either.

It is permissible to stop at this point if you just wanted to find out the
image dimensions and other header info for a JPEG file.  In that case,
call jpeg_destroy() when you are done with the JPEG object, or call
jpeg_abort() to return it to an idle state before selecting a new data
source and reading another header.


4. Set parameters for decompression.

jpeg_read_header() sets appropriate default decompression parameters based on
the properties of the image (in particular, its colorspace).  However, you
may well want to alter these defaults before beginning the decompression.
For example, the default is to produce full color output from a color file.
If you want colormapped output you must ask for it.  Other options allow the
returned image to be scaled and allow various speed/quality tradeoffs to be
selected.  "Decompression parameter selection", below, gives details.

If the defaults are appropriate, nothing need be done at this step.

Note that all default values are set by each call to jpeg_read_header().
If you reuse a decompression object, you cannot expect your parameter
settings to be preserved across cycles, as you can for compression.
You must adjust parameter values each time.


5. jpeg_start_decompress(...);

Once the parameter values are satisfactory, call jpeg_start_decompress() to
begin decompression.  This will initialize internal state, allocate working
memory, and prepare for returning data.

Typical code is just

	jpeg_start_decompress(&cinfo);

If you have requested a multi-pass operating mode, such as 2-pass color
quantization, jpeg_start_decompress() will do everything needed before data
output can begin.  In this case jpeg_start_decompress() may take quite a while
to complete.  With a single-scan (fully interleaved) JPEG file and default
decompression parameters, this will not happen; jpeg_start_decompress() will
return quickly.

After this call, the final output image dimensions, including any requested
scaling, are available in the JPEG object; so is the selected colormap, if
colormapped output has been requested.  Useful fields include

	output_width		image width and height, as scaled
	output_height
	out_color_components	# of color components in out_color_space
	output_components	# of color components returned per pixel
	colormap		the selected colormap, if any
	actual_number_of_colors		number of entries in colormap

output_components is 1 (a colormap index) when quantizing colors; otherwise it
equals out_color_components.  It is the number of JSAMPLE values that will be
emitted per pixel in the output arrays.

Typically you will need to allocate data buffers to hold the incoming image.
You will need output_width * output_components JSAMPLEs per scanline in your
output buffer, and a total of output_height scanlines will be returned.

Note: if you are using the JPEG library's internal memory manager to allocate
data buffers (as djpeg does), then the manager's protocol requires that you
request large buffers *before* calling jpeg_start_decompress().  This is a
little tricky since the output_XXX fields are not normally valid then.  You
can make them valid by calling jpeg_calc_output_dimensions() after setting the
relevant parameters (scaling, output color space, and quantization flag).


6. while (scan lines remain to be read)
	jpeg_read_scanlines(...);

Now you can read the decompressed image data by calling jpeg_read_scanlines()
one or more times.  At each call, you pass in the maximum number of scanlines
to be read (ie, the height of your working buffer); jpeg_read_scanlines()
will return up to that many lines.  The return value is the number of lines
actually read.  The format of the returned data is discussed under "Data
formats", above.

Image data is returned in top-to-bottom scanline order.  If you must write
out the image in bottom-to-top order, you can use the JPEG library's virtual
array mechanism to invert the data efficiently.  Examples of this can be
found in the sample application djpeg.

The library maintains a count of the number of scanlines returned so far
in the output_scanline field of the JPEG object.  Usually you can just use
this variable as the loop counter, so that the loop test looks like
"while (cinfo.output_scanline < cinfo.output_height)".  (Note that the test
should NOT be against image_height, unless you never use scaling.  The
image_height field is the height of the original unscaled image.)

If you don't use a suspending data source, it is safe to assume that
jpeg_read_scanlines() reads at least one scanline per call, until the
bottom of the image has been reached.  If you use a buffer larger than one
scanline, it is NOT safe to assume that jpeg_read_scanlines() fills it.
In any case, the return value is the same as the change in the value of
output_scanline.


7. jpeg_finish_decompress(...);

After all the image data has been read, call jpeg_finish_decompress() to
complete the decompression cycle.  This causes working memory associated
with the JPEG object to be released.

Typical code:

	jpeg_finish_decompress(&cinfo);

If using the stdio source manager, don't forget to close the source stdio
stream if necessary.

It is an error to call jpeg_finish_decompress() before reading the correct
total number of scanlines.  If you wish to abort compression, call
jpeg_abort() as discussed below.

After completing a decompression cycle, you may dispose of the JPEG object as
discussed next, or you may use it to decompress another image.  In that case
return to step 2 or 3 as appropriate.  If you do not change the source
manager, the next image will be read from the same source.


8. Release the JPEG decompression object.

When you are done with a JPEG decompression object, destroy it by calling
jpeg_destroy_decompress() or jpeg_destroy().  The previous discussion of
destroying compression objects applies here too.

Typical code:

	jpeg_destroy_decompress(&cinfo);


9. Aborting.

You can abort a decompression cycle by calling jpeg_destroy_decompress() or
jpeg_destroy() if you don't need the JPEG object any more, or
jpeg_abort_decompress() or jpeg_abort() if you want to reuse the object.
The previous discussion of aborting compression cycles applies here too.


Mechanics of usage: include files, linking, etc
-----------------------------------------------

Applications using the JPEG library should include the header file jpeglib.h
to obtain declarations of data types and routines.  Before including
jpeglib.h, include system headers that define at least the typedefs FILE and
size_t.  On ANSI-conforming systems, including <stdio.h> is sufficient; on
older Unix systems, you may need <sys/types.h> to define size_t.

If the application needs to refer to individual JPEG library error codes, also
include jerror.h to define those symbols.

jpeglib.h indirectly includes the files jconfig.h and jmorecfg.h.  If you are
installing the JPEG header files in a system directory, you will want to
install all four files: jpeglib.h, jerror.h, jconfig.h, jmorecfg.h.

(It may be worth pointing out that the core JPEG library does not actually
require the stdio library: only the default source/destination managers and
error handler need it.  You can use the library in a stdio-less environment
if you replace those modules.  More info about the minimum system library
requirements may be found in jinclude.h.)

The most convenient way to include the JPEG code into your executable program
is to prepare a library file ("libjpeg.a", or a corresponding name on non-Unix
machines) and reference it at your link step.  If you use only half of the
library (only compression or only decompression), only that much code will be
included from the library, unless your linker is hopelessly brain-damaged.
Most of the supplied makefiles build libjpeg.a automatically (see install.doc).

On some systems your application may need to set up a signal handler to ensure
that temporary files are deleted if the program is interrupted.  This is most
critical if you are on MS-DOS and use the jmemdos.c memory manager back end;
it will try to grab extended memory for temp files, and that space will NOT be
freed automatically.  See cjpeg.c or djpeg.c for an example signal handler.


ADVANCED FEATURES
=================

Compression parameter selection
-------------------------------

This section describes all the optional parameters you can set for JPEG
compression, as well as the "helper" routines provided to assist in this
task.  Proper setting of some parameters requires detailed understanding
of the JPEG standard; if you don't know what a parameter is for, it's best
not to mess with it!  See REFERENCES in the README file for pointers to
more info about JPEG.

It's a good idea to call jpeg_set_defaults() first, even if you plan to set
all the parameters; that way your code is more likely to work with future JPEG
libraries that have additional parameters.  For the same reason, we recommend
you use a helper routine where one is provided, in preference to twiddling
cinfo fields directly.

The helper routines are:

jpeg_set_defaults (j_compress_ptr cinfo)
	This routine sets all JPEG parameters to reasonable defaults, using
	only the input image's color space (field in_color_space, which must
	already be set in cinfo).  Many applications will only need to use
	this routine and perhaps jpeg_set_quality().

jpeg_set_colorspace (j_compress_ptr cinfo, J_COLOR_SPACE colorspace)
	Sets the JPEG file's colorspace (field jpeg_color_space) as specified,
	and sets other color-space-dependent parameters appropriately.  See
	"Special color spaces", below, before using this.  A large number of
	parameters, including all per-component parameters, are set by this
	routine; if you want to twiddle individual parameters you should call
	jpeg_set_colorspace() before rather than after.

jpeg_set_quality (j_compress_ptr cinfo, int quality, boolean force_baseline)
	Constructs JPEG quantization tables appropriate for the indicated
	quality setting.  The quality value is expressed on the 0..100 scale
	recommended by IJG (cjpeg's "-quality" switch uses this routine).
	Note that the exact mapping from quality values to tables may change
	in future IJG releases as more is learned about DCT quantization.
	If the force_baseline parameter is TRUE, then the quantization table
	entries are constrained to the range 1..255 for full JPEG baseline
	compatibility.  In the current implementation, this only makes a
	difference for quality settings below 25, and it effectively prevents
	very small/low quality files from being generated.  The IJG decoder
	is capable of reading the non-baseline files generated at low quality
	settings when force_baseline is FALSE, but other decoders may not be.

jpeg_set_linear_quality (j_compress_ptr cinfo, int scale_factor,
			 boolean force_baseline)
	Same as jpeg_set_quality() except that the generated tables are the
	sample tables given in the JPEC spec section K.1, multiplied by the
	specified scale factor (which is expressed as a percentage; thus
	scale_factor = 100 reproduces the spec's tables).  Note that larger
	scale factors give lower quality.  This entry point is useful for
	conforming to the Adobe PostScript DCT conventions, but we do not
	recommend linear scaling as a user-visible quality scale otherwise.
	force_baseline again constrains the computed table entries to 1..255.

int jpeg_quality_scaling (int quality)
	Converts a value on the IJG-recommended quality scale to a linear
	scaling percentage.  Note that this routine may change or go away
	in future releases --- IJG may choose to adopt a nonlinear scaling,
	in which case the premise of this routine collapses.

jpeg_add_quant_table (j_compress_ptr cinfo, int which_tbl,
		      const unsigned int *basic_table,
		      int scale_factor, boolean force_baseline));
	Allows an arbitrary quantization table to be created.  which_tbl
	indicates which table slot to fill.  basic_table points to an array
	of 64 unsigned ints given in JPEG zigzag order.  These values are
	multiplied by scale_factor/100 and then clamped to the range 1..65535
	(or to 1..255 if force_baseline is TRUE).


Compression parameters (cinfo fields) include:

boolean optimize_coding
	TRUE causes the compressor to compute optimal Huffman coding tables
	for the image.  This requires an extra pass over the data and
	therefore costs a good deal of space and time.  The default is
	FALSE, which tells the compressor to use the supplied or default
	Huffman tables.  In most cases optimal tables save only a few percent
	of file size compared to the default tables.  Note that when this is
	TRUE, you need not supply Huffman tables at all, and any you do
	supply will be overwritten.

int smoothing_factor
	If non-zero, the input image is smoothed; the value should be 1 for
	minimal smoothing to 100 for maximum smoothing.  Consult jcsample.c
	for details of the smoothing algorithm.  [Ignored in version
	5alpha2, but should be implemented before v5 release.]

unsigned int restart_interval
int restart_in_rows
	To emit restart markers in the JPEG file, set one of these nonzero.
	Set restart_interval to specify the exact interval in MCU blocks.
	Set restart_in_rows to specify the interval in MCU rows.  (If
	restart_in_rows is not 0, then restart_interval is set after the
	image width in MCUs is computed.)

J_COLOR_SPACE jpeg_color_space
int num_components
	The JPEG color space and corresponding number of components; see
	"Special color spaces", below, for more info.  We recommend using
	jpeg_set_color_space() if you want to change these.

boolean write_JFIF_header
	If TRUE, a JFIF APP0 marker is emitted.  jpeg_set_defaults() and
	jpeg_set_colorspace() set this TRUE if a JFIF-legal JPEG color space
	(ie, YCbCr or grayscale) is selected, otherwise FALSE.

UINT8 density_unit
UINT16 X_density
UINT16 Y_density
	The resolution information to be written into the JFIF marker;
	not used otherwise.  density_unit may be 0 for unknown,
	1 for dots/inch, or 2 for dots/cm.  The default values are 0,1,1
	indicating square pixels of unknown size.

boolean write_Adobe_marker
	If TRUE, an Adobe APP14 marker is emitted.  jpeg_set_defaults() and
	jpeg_set_colorspace() set this TRUE if JPEG color space RGB, CMYK,
	or YCCK is selected, otherwise FALSE.  It is generally a bad idea
	to set both write_JFIF_header and write_Adobe_marker.  In fact,
	you probably shouldn't change the default settings at all --- the
	default behavior ensures that the JPEG file's color space can be
	recognized by the decoder.

JQUANT_TBL * quant_tbl_ptrs[NUM_QUANT_TBLS]
	Pointers to coefficient quantization tables, one per table slot,
	or NULL if no table is defined for a slot.  Usually these should
	be set via one of the above helper routines; jpeg_add_quant_table()
	is general enough to define any quantization table.  The other
	routines will set up table slot 0 for luminance quality and table
	slot 1 for chrominance.  If you insist on creating tables directly,
	use jpeg_alloc_quant_table(); the struct JQUANT_TBL is *not* large
	enough, because there are additional hidden fields.

JHUFF_TBL * dc_huff_tbl_ptrs[NUM_HUFF_TBLS]
JHUFF_TBL * ac_huff_tbl_ptrs[NUM_HUFF_TBLS]
	Pointers to Huffman coding tables, one per table slot, or NULL if
	no table is defined for a slot.  Slots 0 and 1 are filled with the
	JPEG sample tables by jpeg_set_defaults().  If you want to
	experiment with your own Huffman tables, allocate a table with
	jpeg_alloc_huff_table() unless the table slot pointer is already
	non-NULL.  (The struct JHUFF_TBL is *not* large enough.)  Then
	fill the bits[] and huffval[] arrays in the structure.
	Note that optimal Huffman tables can be computed for an image
	by setting optimize_coding, as discussed above; there's seldom
	any need to mess with providing your own Huffman tables.

There are some additional cinfo fields which are not documented here
because you currently can't change them; for example, you can't set
arith_code TRUE because arithmetic coding is unsupported.


Per-component parameters are stored in the struct cinfo.comp_info[i] for
component number i.  Note that components here refer to components of the
JPEG color space, *not* the source image color space.  A suitably large
comp_info[] array is allocated by jpeg_set_defaults(); if you choose not
to use that routine, it's up to you to allocate the array.

int component_id
	The one-byte identifier code to be recorded in the JPEG file for
	this component.  For the standard color spaces, we recommend you
	leave the default values alone.

int h_samp_factor
int v_samp_factor
	Horizontal and vertical sampling factors for the component; must
	be 1..4 according to the JPEG standard.  Note that larger sampling
	factors indicate a higher-resolution component; many people find
	this behavior quite unintuitive.  The default values are 2,2 for
	luminance components and 1,1 for chrominance components, except
	for grayscale where 1,1 is used.

int quant_tbl_no
	Quantization table number for component.  The default value is
	0 for luminance components and 1 for chrominance components.

int dc_tbl_no
int ac_tbl_no
	DC and AC entropy coding table numbers.  The default values are
	0 for luminance components and 1 for chrominance components.

int component_index
	Must equal the component's index in comp_info[].  Don't mess
	with this.


Decompression parameter selection
---------------------------------

Decompression parameter selection is somewhat simpler than compression
parameter selection, since all of the JPEG internal parameters are
recorded in the source file and need not be supplied by the application.
(Unless you are working with abbreviated files, in which case see
"Abbreviated datastreams", below.)  Decompression parameters control
the postprocessing done on the image to deliver it in a format suitable
for the application's use.  Many of the parameters control speed/quality
tradeoffs, in which faster decompression may be obtained at the price of
a poorer-quality image.  The defaults select the highest quality (slowest)
processing.

The following fields in the JPEG object are set by jpeg_read_header() and
may be useful to the application in choosing decompression parameters:

JDIMENSION image_width			Width and height of image
JDIMENSION image_height
int num_components			Number of color components
J_COLOR_SPACE jpeg_color_space		Colorspace of image
boolean saw_JFIF_marker			TRUE if a JFIF APP0 marker was seen
  UINT8 density_unit			Resolution data from JFIF marker
  UINT16 X_density
  UINT16 Y_density
boolean saw_Adobe_marker		TRUE if an Adobe APP14 marker was seen
  UINT8 Adobe_transform			Color transform code from Adobe marker

The JPEG color space, unfortunately, is something of a guess since the JPEG
standard proper does not provide a way to record it.  In practice most files
adhere to the JFIF or Adobe conventions, and the decoder will recognize these
correctly.  See "Special color spaces", below, for more info.


The decompression parameters that the application may set are:

J_COLOR_SPACE out_color_space
	Output color space.  jpeg_read_header() sets an appropriate default
	based on jpeg_color_space; typically it will be RGB or grayscale.
	The application can force this to grayscale to get grayscale output
	from a color file.  Grayscale output is faster than full color since
	the color components need not be processed.  (Note that not all
	possible color space transforms are currently implemented; you may
	need to extend jdcolor.c if you want an unusual conversion.)

unsigned int scale_num, scale_denom
	Scale the image by the fraction scale_num/scale_denom.  Default is
	1/1, or no scaling.  Currently, the only supported scaling ratios
	are 1/1, 1/2, 1/4, and 1/8.  (The library design allows for arbitrary
	scaling ratios but this is not likely to be implemented any time soon.)
	Smaller scaling ratios permit significantly faster decoding since
	fewer pixels need be processed and a simpler IDCT method can be used.

boolean do_block_smoothing
	If TRUE, apply cross-block smoothing.  Default is FALSE.  Smoothing
	sometimes improves the appearance of very-low-quality-setting files.
	(Not currently implemented in v5, and may not be any time soon.)

boolean do_fancy_upsampling
	If TRUE, do careful upsampling of chroma components.  If FALSE,
	a faster but sloppier method is used.  Default is TRUE.  The visual
	impact of the sloppier method is often very small.

boolean quantize_colors
	If set TRUE, colormapped output will be delivered.  Default is FALSE,
	meaning that full-color output will be delivered.

The next three parameters are relevant only if quantize_colors is TRUE.

int desired_number_of_colors
	Maximum number of colors to use in generating a library-supplied color
	map (the actual number of colors is returned in a different field).
	Default 256.  Ignored when the application supplies its own color map.

boolean two_pass_quantize
	If TRUE, an extra pass over the image is made to select a custom color
	map for the image.  This usually looks a lot better than the one-size-
	fits-all colormap that is used otherwise.  Default is TRUE.  Ignored
	when the application supplies its own color map.

boolean use_dithering
	If TRUE, Floyd-Steinberg dithering is applied.  F-S dithering is
	fairly slow but usually improves the perceived quality significantly.
	Default is TRUE.

When quantize_colors is TRUE, the target color map is described by the next
two fields.  colormap is set to NULL by jpeg_read_header().  The application
can supply a color map by setting colormap non-NULL and setting
actual_number_of_colors to the map size.  Otherwise, jpeg_start_decompress()
selects a color map and sets these fields.

JSAMPARRAY colormap
	The color map represented as a 2-D pixel array of out_color_components
	rows and actual_number_of_colors columns.  Ignored if not quantizing.
int actual_number_of_colors
	The number of colors in the color map.


The output image dimensions are given by the following fields.  These are
computed from the source image dimensions and the decompression parameters
by jpeg_start_decompress().  You can also call jpeg_calc_output_dimensions()
to obtain the values that will result from the current parameter settings.
This can be useful if you are trying to pick a scaling ratio that will get
close to a desired target size.  It's also important if you are using the
JPEG library's memory manager to allocate output buffer space, because you
are supposed to request such buffers *before* jpeg_start_decompress().

JDIMENSION output_width		Actual dimensions of output image.
JDIMENSION output_height
int out_color_components	Number of color components in out_color_space.
int output_components		Number of color components returned.
int rec_outbuf_height		Recommended height of scanline buffer.

When quantizing colors, output_components is 1, indicating a single color map
index per pixel.  Otherwise it equals out_color_components.  The output arrays
are required to be output_width * output_components JSAMPLEs wide.

rec_outbuf_height is the recommended minimum height (in scanlines) of the
buffer passed to jpeg_read_scanlines().  If the buffer is smaller, the library
will still work, but space and time will be wasted due to unnecessary data
copying.  As of version 5alpha1, rec_outbuf_height is always 1, but future
high-speed processing modes may set it to larger values (2 to 4 would be
typical).  If you are going to ask for a high-speed processing mode, you
may as well go to the extra work of avoiding data copying...


Special color spaces
--------------------

The JPEG standard itself is "color blind" and doesn't specify any particular
color space.  It is customary to convert color data to a luminance/chrominance
color space before compressing, since this permits greater compression.  The
existing de-facto JPEG file format standards specify YCbCr or grayscale data
(JFIF), or grayscale, RGB, YCbCr, CMYK, or YCCK (Adobe).  For special
applications such as multispectral images, other color spaces can be used,
but it must be understood that such files will be unportable.

The JPEG library can handle the most common colorspace conversions (namely
RGB <=> YCbCr and CMYK <=> YCCK).  It can also deal with data of an unknown
color space, passing it through without conversion.  If you deal extensively
with an unusual color space, you can easily extend the library to understand
additional color spaces and perform appropriate conversions.

For compression, the source data's color space is specified by field
in_color_space.  This is transformed to the JPEG file's color space given
by jpeg_color_space.  jpeg_set_defaults() chooses a reasonable JPEG color
space depending on in_color_space, but you can override this by calling
jpeg_set_colorspace().  Of course you must select a supported transformation.
jccolor.c currently supports the following transformations:
	RGB => YCbCr
	RGB => GRAYSCALE
	YCbCr => GRAYSCALE
	CMYK => YCCK
plus the null transforms: GRAYSCALE => GRAYSCALE, RGB => RGB,
YCbCr => YCbCr, CMYK => CMYK, YCCK => YCCK, and UNKNOWN => UNKNOWN.

The de-facto file format standards (JFIF and Adobe) specify APPn markers that
indicate the color space of the JPEG file.  It is important to ensure that
these are written correctly, or omitted if the JPEG file's color space is not
one of the ones supported by the de-facto standards.  jpeg_set_colorspace()
will set the compression parameters to include or omit the APPn markers
properly, so long as it is told the truth about the JPEG color space.
For example, if you are writing some random 3-component color space without
conversion, don't try to fake out the library by setting in_color_space and
jpeg_color_space to JCS_YCbCr; use JCS_UNKNOWN.  You may want to write an
APPn marker of your own devising to identify the colorspace --- see "Special
markers", below.

When told that the color space is UNKNOWN, the library will default to using
luminance-quality compression parameters for all color components.  You may
well want to change these parameters.  See the source code for
jpeg_set_colorspace(), in jcparam.c, for details.

For decompression, the JPEG file's color space is given in jpeg_color_space,
and this is transformed to the output color space out_color_space.
jpeg_read_header's setting of jpeg_color_space can be relied on if the file
conforms to JFIF or Adobe conventions, but otherwise it is no better than a
guess.  If you know the JPEG file's color space for certain, you can override
jpeg_read_header's guess by setting jpeg_color_space.  jpeg_read_header also
selects a default output color space based on (its guess of) jpeg_color_space;
set out_color_space to override this.  Again you must select a supported
transformation.  jdcolor.c currently supports
	YCbCr => GRAYSCALE
	YCbCr => RGB
	YCCK => CMYK
as well as the null transforms.


Error handling
--------------

When the default error handler is used, any error detected inside the JPEG
routines will cause a message to be printed on stderr, followed by exit().
You can supply your own error handling routines to override this behavior
and to control the treatment of nonfatal warnings and trace/debug messages.
The file example.c illustrates the most common case, which is to have the
application regain control after an error rather than exiting.

The JPEG library never writes any message directly; it always goes through
the error handling routines.  Three classes of messages are recognized:
  * Fatal errors: the library cannot continue.
  * Warnings: the library can continue, but the data is corrupt, and a
    damaged output image is likely to result.
  * Trace/informational messages.  These come with a trace level indicating
    the importance of the message; you can control the verbosity of the
    program by adjusting the maximum trace level that will be displayed.

You may, if you wish, simply replace the entire JPEG error handling module
(jerror.c) with your own code.  However, you can avoid code duplication by
only replacing some of the routines depending on the behavior you need.
This is accomplished by calling jpeg_std_error() as usual, but then overriding
some of the method pointers in the jpeg_error_mgr struct, as illustrated by
example.c.

All of the error handling routines will receive a pointer to the JPEG object
(a j_common_ptr which points to either a jpeg_compress_struct or a
jpeg_decompress_struct; if you need to tell which, test the is_decompressor
field).  This struct includes a pointer to the error manager struct in its
"err" field.  Frequently, custom error handler routines will need to access
additional data which is not known to the JPEG library or the standard error
handler.  The most convenient way to do this is to embed either the JPEG
object or the jpeg_error_mgr struct in a larger structure that contains
additional fields; then casting the passed pointer provides access to the
additional fields.  Again, see example.c for one way to do it.

The individual methods that you might wish to override are:

error_exit (j_common_ptr cinfo)
	Receives control for a fatal error.  Information sufficient to
	generate the error message has been stored in cinfo->err; call
	output_message to display it.  Control must NOT return to the caller;
	generally this routine will exit() or longjmp() somewhere.
	Typically you would override this routine to get rid of the exit()
	default behavior.  Note that if you continue processing, you should
	clean up the JPEG object with jpeg_abort() or jpeg_destroy().

output_message (j_common_ptr cinfo)
	Actual output of any JPEG message.  Override this to send messages
	somewhere other than stderr.  Note that this method does not know
	how to generate a message, only where to send it.

format_message (j_common_ptr cinfo, char * buffer)
	Constructs a readable error message string based on the error info
	stored in cinfo->err.  This method is called by output_message.  Few
	applications should need to override this method.  One possible
	reason for doing so is to implement dynamic switching of error message
	language.

emit_message (j_common_ptr cinfo, int msg_level)
	Decide whether or not to emit a warning or trace message; if so,
	calls output_message.  The main reason for overriding this method
	would be to abort on warnings.  msg_level is -1 for warnings,
	0 and up for trace messages.

Only error_exit() and emit_message() are called from the rest of the JPEG
library; the other two are internal to the error handler.

The actual message texts are stored in an array of strings which is pointed to
by the field err->jpeg_message_table.  The messages are numbered from 0 to
err->last_jpeg_message, and it is these code numbers that are used in the
JPEG library code.  You could replace the message texts (for instance, with
messages in French or German) by changing the message table pointer.  See
jerror.h for the default texts.  CAUTION: this table will almost certainly
change or grow from one library version to the next.

It may be useful for an application to add its own message texts that are
handled by the same mechanism.  The error handler supports a second "add-on"
message table for this purpose.  To define an addon table, set the pointer
err->addon_message_table and the message numbers err->first_addon_message and
err->last_addon_message.  If you number the addon messages beginning at 1000
or so, you won't have to worry about conflicts with the library's built-in
messages.  See the sample applications cjpeg/djpeg for an example of using
addon messages (the addon messages are defined in cderror.h).

Actual invocation of the error handler is done via macros defined in jerror.h:
	ERREXITn(...)	for fatal errors
	WARNMSn(...)	for corrupt-data warnings
	TRACEMSn(...)	for trace and informational messages.
These macros store the message code and any additional parameters into the
error handler struct, then invoke the error_exit() or emit_message() method.
The variants of each macro are for varying numbers of additional parameters.
The additional parameters are inserted into the generated message using
standard printf() format codes.

See jerror.h and jerror.c for further details.


Compressed data handling (source and destination managers)
----------------------------------------------------------

The JPEG compression library sends its compressed data to a "destination
manager" module.  The default destination manager just writes the data to a
stdio stream, but you can provide your own manager to do something else.
Similarly, the decompression library calls a "source manager" to obtain the
compressed data; you can provide your own source manager if you want the data
to come from somewhere other than a stdio stream.

In both cases, compressed data is processed a bufferload at a time: the
destination or source manager provides a work buffer, and the library invokes
the manager only when the buffer is filled or emptied.  (You could define a
one-character buffer to force the manager to be invoked for each byte, but
that would be rather inefficient.)  The buffer's size and location are
controlled by the manager, not by the library.  For example, if you desired to
decompress a JPEG datastream that was all in memory, you could just make the
buffer pointer and length point to the original data in memory.  Then the
buffer-reload procedure would be invoked only if the decompressor ran off the
end of the datastream, which would indicate an erroneous datastream.

The work buffer is defined as an array of datatype JOCTET, which is generally
"char" or "unsigned char".  On a machine where char is not exactly 8 bits
wide, you must define JOCTET as a wider data type and then modify the data
source and destination modules to transcribe the work arrays into 8-bit units
on external storage.

A data destination manager struct contains a pointer and count defining the
next byte to write in the work buffer and the remaining free space:

	JOCTET * next_output_byte;  /* => next byte to write in buffer */
	size_t free_in_buffer;      /* # of byte spaces remaining in buffer */

The library increments the pointer and decrements the count until the buffer
is filled.  The manager's empty_output_buffer method must reset the pointer
and count.  The manager is expected to remember the buffer's starting address
and total size in private fields not visible to the library.

A data destination manager provides three methods:

init_destination (j_compress_ptr cinfo)
	Initialize destination.  This is called by jpeg_start_compress()
	before any data is actually written.  It must initialize
	next_output_byte and free_in_buffer.  free_in_buffer must be
	initialized to a positive value.

empty_output_buffer (j_compress_ptr cinfo)
	This is called whenever the buffer has filled (free_in_buffer
	reaches zero).  In typical applications, it should write out the
	*entire* buffer (use the saved start address and buffer length;
	ignore the current state of next_output_byte and free_in_buffer).
	Then reset the pointer & count to the start of the buffer, and
	return TRUE indicating that the buffer has been dumped.
	free_in_buffer must be set to a positive value when TRUE is
	returned.  A FALSE return should only be used when I/O suspension is
	desired (this operating mode is discussed in the next section).

term_destination (j_compress_ptr cinfo)
	Terminate destination --- called by jpeg_finish_compress() after all
	data has been written.  In most applications, this must flush any
	data remaining in the buffer.  Use either next_output_byte or
	free_in_buffer to determine how much data is in the buffer.

term_destination() is NOT called by jpeg_abort() or jpeg_destroy().  If you
want the destination manager to be cleaned up during an abort, you must do it
yourself.

You will also need code to create a jpeg_destination_mgr struct, fill in its
method pointers, and insert a pointer to the struct into the "dest" field of
the JPEG compression object.  This can be done in-line in your setup code if
you like, but it's probably cleaner to provide a separate routine similar to
the jpeg_stdio_dest() routine of the supplied destination manager.

Decompression source managers follow a parallel design, but with some
additional frammishes.  The source manager struct contains a pointer and count
defining the next byte to read from the work buffer and the number of bytes
remaining:

	const JOCTET * next_input_byte; /* => next byte to read from buffer */
	size_t bytes_in_buffer;         /* # of bytes remaining in buffer */

The library increments the pointer and decrements the count until the buffer
is emptied.  The manager's fill_input_buffer method must reset the pointer and
count.  In most applications, the manager must remember the buffer's starting
address and total size in private fields not visible to the library.

A data source manager provides five methods:

init_source (j_decompress_ptr cinfo)
	Initialize source.  This is called by jpeg_read_header() before any
	data is actually read.  Unlike init_destination(), it may leave
	bytes_in_buffer set to 0 (in which case a fill_input_buffer() call
	will occur immediately).

fill_input_buffer (j_decompress_ptr cinfo)
	This is called whenever bytes_in_buffer has reached zero and more
	data is wanted.  In typical applications, it should read fresh data
	into the buffer (ignoring the current state of next_input_byte and
	bytes_in_buffer), reset the pointer & count to the start of the
	buffer, and return TRUE indicating that the buffer has been reloaded.
	It is not necessary to fill the buffer entirely, only to obtain at
	least one more byte.  bytes_in_buffer MUST be set to a positive value
	if TRUE is returned.  A FALSE return should only be used when I/O
	suspension is desired (this mode is discussed in the next section).

skip_input_data (j_decompress_ptr cinfo, long num_bytes)
	Skip num_bytes worth of data.  The buffer pointer and count should
	be advanced over num_bytes input bytes, refilling the buffer as
	needed.  This is used to skip over a potentially large amount of
	uninteresting data (such as an APPn marker).  In some applications
	it may be possible to optimize away the reading of the skipped data,
	but it's not clear that being smart is worth much trouble; large
	skips are uncommon.  bytes_in_buffer may be zero on return.
	A zero or negative skip count should be treated as a no-op.

resync_to_restart (j_decompress_ptr cinfo)
	This routine is called only when the decompressor has failed to find
	a restart (RSTn) marker where one is expected.  Its mission is to
	find a suitable point for resuming decompression.  For most
	applications, we recommend that you just use the default resync
	procedure, jpeg_resync_to_restart().  However, if you are able to back
	up in the input data stream, or if you have a-priori knowledge about
	the likely location of restart markers, you may be able to do better.
	Read the read_restart_marker() and jpeg_resync_to_restart() routines
	in jdmarker.c if you think you'd like to implement your own resync
	procedure.

term_source (j_decompress_ptr cinfo)
	Terminate source --- called by jpeg_finish_decompress() after all
	data has been read.  Often a no-op.

For both fill_input_buffer() and skip_input_data(), there is no such thing
as an EOF return.  If the end of the file has been reached, the routine has
a choice of exiting via ERREXIT() or inserting fake data into the buffer.
In most cases, generating a warning message and inserting a fake EOI marker
is the best course of action --- this will allow the decompressor to output
however much of the image is there.  In pathological cases, the decompressor
may swallow the EOI and again demand data ... just keep feeding it fake EOIs.
jdatasrc.c illustrates the recommended error recovery behavior.

term_source() is NOT called by jpeg_abort() or jpeg_destroy().  If you want
the source manager to be cleaned up during an abort, you must do it yourself.

You will also need code to create a jpeg_source_mgr struct, fill in its method
pointers, and insert a pointer to the struct into the "src" field of the JPEG
decompression object.  This can be done in-line in your setup code if you
like, but it's probably cleaner to provide a separate routine similar to the
jpeg_stdio_src() routine of the supplied source manager.

For more information, consult the stdio source and destination managers
in jdatasrc.c and jdatadst.c.


I/O suspension
--------------

Some applications need to use the JPEG library as an incremental memory-to-
memory filter: when the compressed data buffer is filled or emptied, they want
control to return to the outer loop, rather than expecting that the buffer can
be flushed or reloaded within the data source/destination manager subroutine.
The library supports this need by providing an "I/O suspension" mode, which we
describe in this section.

The I/O suspension mode is a limited solution: it works only in the simplest
operating modes (namely single-pass processing of single-scan JPEG files), and
it has several other restrictions which are documented below.  Furthermore,
nothing is guaranteed about the maximum amount of time spent in any one call
to the library, so a single-threaded application may still have response-time
problems.  If you need multi-pass processing or guaranteed response time, we
suggest you "bite the bullet" and implement a real multi-tasking capability.

To use I/O suspension, cooperation is needed between the calling application
and the data source or destination manager; you will always need a custom
source/destination manager.  (Please read the above section if you haven't
already.)  The basic idea is that the empty_output_buffer() or
fill_input_buffer() routine is a no-op, merely returning FALSE to indicate
that it has done nothing.  Upon seeing this, the JPEG library suspends
operation and returns to its caller.  The surrounding application is
responsible for emptying or refilling the work buffer before calling the JPEG
library again.

Compression suspension:

For compression suspension, use an empty_output_buffer() routine that returns
FALSE; typically it will not do anything else.  This will cause the compressor
to return to the caller of jpeg_write_scanlines(), with the return value
indicating that not all the supplied scanlines have been accepted.  The
application must make more room in the output buffer, adjust the pointer/count
appropriately, and then call jpeg_write_scanlines() again, pointing to the
first unconsumed scanline.

When forced to suspend, the compressor will backtrack to a convenient stopping
point (usually the start of the current MCU); it will regenerate some output
data when restarted.  Therefore, although empty_output_buffer() is only called
when the buffer is filled, you should NOT dump out the entire buffer, only the
data up to the current position of next_output_byte/free_in_buffer.  The data
beyond that point will be regenerated after resumption.

Because of the backtracking behavior, a good-size output buffer is essential
for efficiency; you don't want the compressor to suspend often.  (In fact, an
overly small buffer could lead to infinite looping, if a single MCU required
more data than would fit in the buffer.)  We recommend a buffer of at least
several Kbytes.  You may want to insert explicit code to ensure that you don't
call jpeg_write_scanlines() unless there is a reasonable amount of space in
the output buffer; in other words, flush the buffer before trying to compress
more data.

The JPEG compressor does not support suspension while it is trying to write
JPEG markers at the beginning and end of the file.  This means that
  * At the beginning of a compression operation, there must be enough free
    space in the output buffer to hold the header markers (typically 600 or
    so bytes).  The recommended buffer size is bigger than this anyway, so
    this is not a problem as long as you start with an empty buffer.  However,
    this restriction might catch you if you insert large special markers, such
    as a JFIF thumbnail image.
  * When you call jpeg_finish_compress(), there must be enough space in the
    output buffer to emit any buffered data and the final EOI marker.  In the
    current implementation, half a dozen bytes should suffice for this, but
    for safety's sake we recommend ensuring that at least 100 bytes are free
    before calling jpeg_finish_compress().
Furthermore, since jpeg_finish_compress() cannot suspend, you cannot request
multi-pass operating modes such as Huffman code optimization or multiple-scan
output.  That would imply that a large amount of data would be written inside
jpeg_finish_compress(), which would certainly trigger a buffer overrun.

Decompression suspension:

For decompression suspension, use a fill_input_buffer() routine that returns
FALSE (except perhaps during error recovery, as discussed below).  This will
cause the decompressor to return to its caller with an indication that
suspension has occurred.  This can happen at three places:
  * jpeg_read_header(): will return JPEG_SUSPENDED.
  * jpeg_read_scanlines(): will return the number of scanlines already
	completed (possibly 0).
  * jpeg_finish_decompress(): will return FALSE, rather than its usual TRUE.
The surrounding application must recognize these cases, load more data into
the input buffer, and repeat the call.  In the case of jpeg_read_scanlines(),
adjust the passed pointers to reflect any scanlines successfully read.

Just as with compression, the decompressor will typically backtrack to a
convenient restart point before suspending.  The data beyond the current
position of next_input_byte/bytes_in_buffer must NOT be discarded; it will
be re-read upon resumption.  In most implementations, you'll need to shift
this data down to the start of your work buffer and then load more data
after it.  Again, this behavior means that a several-Kbyte work buffer is
essential for decent performance; furthermore, you should load a reasonable
amount of new data before resuming decompression.  (If you loaded, say,
only one new byte each time around, you could waste a LOT of cycles.)

The skip_input_data() source manager routine requires special care in a
suspension scenario.  This routine is NOT granted the ability to suspend the
decompressor; it can decrement bytes_in_buffer to zero, but no more.  If the
requested skip distance exceeds the amount of data currently in the input
buffer, then skip_input_data() must set bytes_in_buffer to zero and record the
additional skip distance somewhere else.  The decompressor will immediately
call fill_input_buffer(), which will return FALSE, which will cause a
suspension return.  The surrounding application must then arrange to discard
the right number of bytes before it resumes loading the input buffer.  (Yes,
this design is rather baroque, but it avoids complexity in the far more common
case where a non-suspending source manager is used.)

If the input data has been exhausted, we recommend that you emit a warning
and insert dummy EOI markers just as a non-suspending data source manager
would do.  This can be handled either in the surrounding application logic or
within fill_input_buffer(); the latter is probably more efficient.  If
fill_input_buffer() knows that no more data is available, it can set the
pointer/count to point to a dummy EOI marker and then return TRUE just as if
it had read more data in a non-suspending situation.

The decompressor does not support suspension within jpeg_start_decompress().
This means that you cannot use suspension with any multi-pass processing mode
(eg, two-pass color quantization or multiple-scan JPEG files).  In single-pass
modes, jpeg_start_decompress() reads no data and thus need never suspend.

The decompressor does not attempt to suspend within any JPEG marker; it will
backtrack to the start of the marker.  Hence the input buffer must be large
enough to hold the longest marker in the file.  We recommend at least a 2K
buffer.  The buffer would need to be 64K to allow for arbitrary COM or APPn
markers, but the decompressor does not actually try to read these; it just
skips them by calling skip_input_data().  If you provide a special marker
handling routine that does look at these markers, coping with buffer overflow
is your problem.  Ordinary JPEG markers should normally not exceed a few
hundred bytes each (DHT tables are typically the longest).  For robustness
against damaged marker length counts, you may wish to insert a test in your
application for the case that the input buffer is completely full and yet the
decoder has suspended without consuming any data --- otherwise, if this
situation did occur, it would lead to an endless loop.


Abbreviated datastreams and multiple images
-------------------------------------------

A JPEG compression or decompression object can be reused to process multiple
images.  This saves a small amount of time per image by eliminating the
"create" and "destroy" operations, but that isn't the real purpose of the
feature.  Rather, reuse of an object provides support for abbreviated JPEG
datastreams.  Object reuse can also simplify processing a series of images in
a single input or output file.  This section explains these features.

A JPEG file normally contains several hundred bytes worth of quantization
and Huffman tables.  In a situation where many images will be stored or
transmitted with identical tables, this may represent an annoying overhead.
The JPEG standard therefore permits tables to be omitted.  The standard
defines three classes of JPEG datastreams:
  * "Interchange" datastreams contain an image and all tables needed to decode
     the image.  These are the usual kind of JPEG file.
  * "Abbreviated image" datastreams contain an image, but are missing some or
    all of the tables needed to decode that image.
  * "Abbreviated table specification" (henceforth "tables-only") datastreams
    contain only table specifications.
To decode an abbreviated image, it is necessary to load the missing table(s)
into the decoder beforehand.  This can be accomplished by reading a separate
tables-only file.  A variant scheme uses a series of images in which the first
image is an interchange (complete) datastream, while subsequent ones are
abbreviated and rely on the tables loaded by the first image.  It is assumed
that once the decoder has read a table, it will remember that table until a
new definition for the same table number is encountered.

It is the application designer's responsibility to figure out how to associate
the correct tables with an abbreviated image.  While abbreviated datastreams
can be useful in a closed environment, their use is strongly discouraged in
any situation where data exchange with other applications might be needed.
Caveat designer.

The JPEG library provides support for reading and writing any combination of
tables-only datastreams and abbreviated images.  In both compression and
decompression objects, a quantization or Huffman table will be retained for
the lifetime of the object, unless it is overwritten by a new table definition.


To create abbreviated image datastreams, it is only necessary to tell the
compressor not to emit some or all of the tables it is using.  Each
quantization and Huffman table struct contains a boolean field "sent_table",
which normally is initialized to FALSE.  For each table used by the image, the
header-writing process emits the table and sets sent_table = TRUE unless it is
already TRUE.  (In normal usage, this prevents outputting the same table
definition multiple times, as would otherwise occur because the chroma
components typically share tables.)  Thus, setting this field to TRUE before
calling jpeg_start_compress() will prevent the table from being written at
all.

If you want to create a "pure" abbreviated image file containing no tables,
just call "jpeg_suppress_tables(&cinfo, TRUE)" after constructing all the
tables.  If you want to emit some but not all tables, you'll need to set the
individual sent_table fields directly.

To create an abbreviated image, you must also call jpeg_start_compress()
with a second parameter of FALSE, not TRUE.  Otherwise jpeg_start_compress()
will force all the sent_table fields to FALSE.  (This is a safety feature to
prevent abbreviated images from being created accidentally.)

To create a tables-only file, perform the same parameter setup that you
normally would, but instead of calling jpeg_start_compress() and so on, call
jpeg_write_tables(&cinfo).  This will write an abbreviated datastream
containing only SOI, DQT and/or DHT markers, and EOI.  All the quantization
and Huffman tables that are currently defined in the compression object will
be emitted unless their sent_tables flag is already TRUE, and all the
sent_tables flags will be set TRUE.

A sure-fire way to create matching tables-only and abbreviated image files
is to proceed as follows:

	create JPEG compression object
	set JPEG parameters
	set destination to tables-only file
	jpeg_write_tables(&cinfo);
	set destination to image file
	jpeg_start_compress(&cinfo, FALSE);
	write data...
	jpeg_finish_compress(&cinfo);

Since the JPEG parameters are not altered between writing the table file and
the abbreviated image file, the same tables are sure to be used.  Of course,
you can repeat the jpeg_start_compress() ... jpeg_finish_compress() sequence
many times to produce many abbreviated image files matching the table file.

You cannot suppress output of the computed Huffman tables if Huffman
optimization is selected.  (If you could, there'd be no way to decode the
image...)  Generally, you don't want to set optimize_coding = TRUE when
you are trying to produce abbreviated files.

In some cases you might want to compress an image using tables which are
not stored in the application, but are defined in an interchange or
tables-only file readable by the application.  This can be done by setting up
a JPEG decompression object to read the specification file, then copying the
tables into your compression object.


To read abbreviated image files, you simply need to load the proper tables
into the decompression object before trying to read the abbreviated image.
If the proper tables are stored in the application program, you can just
allocate the table structs and fill in their contents directly.  More commonly
you'd want to read the tables from a tables-only file.  The jpeg_read_header()
call is sufficient to read a tables-only file.  You must pass a second
parameter of FALSE to indicate that you do not require an image to be present.
Thus, the typical scenario is

	create JPEG decompression object
	set source to tables-only file
	jpeg_read_header(&cinfo, FALSE);
	set source to abbreviated image file
	jpeg_read_header(&cinfo, TRUE);
	set decompression parameters
	jpeg_start_decompress(&cinfo);
	read data...
	jpeg_finish_decompress(&cinfo);

In some cases, you may want to read a file without knowing whether it contains
an image or just tables.  In that case, pass FALSE and check the return value
from jpeg_read_header(): it will be JPEG_HEADER_OK if an image was found,
JPEG_HEADER_TABLES_ONLY if only tables were found.  (A third return value,
JPEG_SUSPENDED, is possible when using a suspending data source manager.)
Note that jpeg_read_header() will not complain if you read an abbreviated
image for which you haven't loaded the missing tables; the missing-table check
occurs in jpeg_start_decompress().


It is possible to read a series of images from a single source file by
repeating the jpeg_read_header() ... jpeg_finish_decompress() sequence,
without releasing/recreating the JPEG object or the data source module.
(If you did reinitialize, any partial bufferload left in the data source
buffer at the end of one image would be discarded, causing you to lose the
start of the next image.)  When you use this method, stored tables are
automatically carried forward, so some of the images can be abbreviated images
that depend on tables from earlier images.

If you intend to write a series of images into a single destination file,
you might want to make a specialized data destination module that doesn't
flush the output buffer at term_destination() time.  This would speed things
up by some trifling amount.  Of course, you'd need to remember to flush the
buffer after the last image.  You can make the later images be abbreviated
ones by passing FALSE to jpeg_start_compress().


Special markers
---------------

[to be written ... API needs thought]


Downsampled image data
----------------------

[to be written --- not yet implemented anyway]


Progress monitoring
-------------------

[to be written --- not yet implemented in v5 anyway]


Memory management
-----------------

This section covers some key facts about the JPEG library's built-in memory
manager.  For more info, please read structure.doc's section about the memory
manager, and consult the source code if necessary.

All memory and temporary file allocation within the library is done via the
memory manager.  If necessary, you can replace the "back end" of the memory
manager to control allocation yourself (for example, if you don't want the
library to use malloc() and free() for some reason).

Some data is allocated "permanently" and will not be freed until the JPEG
object is destroyed.  Most data is allocated "per image" and is freed by
jpeg_finish_compress, jpeg_finish_decompress, or jpeg_abort.  You can call the
memory manager yourself to allocate structures that will automatically be
freed at these times.  Typical code for this is
  ptr = (*cinfo->mem->alloc_small) ((j_common_ptr) cinfo, JPOOL_IMAGE, size);
Use JPOOL_PERMANENT to get storage that lasts as long as the JPEG object.
Use alloc_large instead of alloc_small for anything bigger than a few Kbytes.
There are also alloc_sarray and alloc_barray routines that automatically
build 2-D sample or block arrays.

The library's minimum space requirements to process an image depend on the
image's width, but not on its height, because the library ordinarily works
with "strip" buffers that are as wide as the image but just a few rows high.
Some operating modes (eg, two-pass color quantization) require full-image
buffers.  Such buffers are treated as "virtual arrays": only the current strip
need be in memory, and the rest can be swapped out to a temporary file.

If you use the simplest memory manager back end (jmemnobs.c), then no
temporary files are used; virtual arrays are simply malloc()'d.  Images bigger
than memory can be processed only if your system supports virtual memory.
The other memory manager back ends support temporary files of various flavors
and thus work in machines without virtual memory.  They may also be useful on
Unix machines if you need to process images that exceed available swap space.

When using temporary files, the library will make the in-memory buffers for
its virtual arrays just big enough to stay within a "maximum memory" setting.
Your application can set this limit by setting cinfo->mem->max_memory_to_use
after creating the JPEG object.  (Of course, there is still a minimum size for
the buffers, so the max-memory setting is effective only if it is bigger than
the minimum space needed.)  If you allocate any large structures yourself, you
must allocate them before jpeg_start_compress() or jpeg_start_decompress() in
order to have them counted against the max memory limit.  Also keep in mind
that space allocated with alloc_small() is ignored, on the assumption that
it's too small to be worth worrying about.

If you use the jmemname.c or jmemdos.c memory manager back end, it is
important to clean up the JPEG object properly to ensure that the temporary
files get deleted.  (This is especially crucial with jmemdos.c, where the
"temporary files" may be extended-memory segments; if they are not freed,
DOS will require a reboot to recover the memory.)  Thus, with these memory
managers, it's a good idea to provide a signal handler that will trap any
early exit from your program.  The handler should call either jpeg_abort()
or jpeg_destroy() for any active JPEG objects.  A handler is not needed with
jmemnobs.c, and shouldn't be necessary with jmemansi.c either, since the C
library is supposed to take care of deleting files made with tmpfile().


Library compile-time options
----------------------------

A number of compile-time options are available by modifying jmorecfg.h.

The JPEG standard provides for both the baseline 8-bit DCT process and
a 12-bit DCT process.  12-bit lossy JPEG is supported if you define
BITS_IN_JSAMPLE as 12 rather than 8.  Note that this causes JSAMPLE to be
larger than a char, so it affects the surrounding application's image data.
At present, a 12-bit library can handle *only* 12-bit images, not both
precisions.

The maximum number of components (color channels) in the image is determined
by MAX_COMPONENTS.  The JPEG standard allows up to 255 components, but we
expect that few applications will need more than four or so.

On machines with unusual data type sizes, you may be able to improve
performance or reduce memory space by tweaking the various typedefs in
jmorecfg.h.  In particular, on some RISC CPUs, access to arrays of "short"s
is quite slow; consider trading memory for speed by making JCOEF, INT16, and
UINT16 be "int" or "unsigned int".  UINT8 is also a candidate to become int.
You probably don't want to make JSAMPLE be int unless you have lots of memory
to burn.

You can reduce the size of the library by compiling out various optional
functions.  To do this, undefine xxx_SUPPORTED symbols as necessary.


Portability considerations
--------------------------

The JPEG library has been written to be extremely portable; the sample
applications cjpeg and djpeg are slightly less so.  This section summarizes
the design goals in this area.  (If you encounter any bugs that cause the
library to be less portable than is claimed here, we'd appreciate hearing
about them.)

The code works fine on both ANSI and pre-ANSI C compilers, using any of the
popular system include file setups, and some not-so-popular ones too.  See
install.doc for configuration procedures.

The code is not dependent on the exact sizes of the C data types.  As
distributed, we make the assumptions that
	char	is at least 8 bits wide
	short	is at least 16 bits wide
	int	is at least 16 bits wide
	long	is at least 32 bits wide
(These are the minimum requirements of the ANSI C standard.)  Wider types will
work fine, although memory may be used inefficiently if char is much larger
than 8 bits or short is much bigger than 16 bits.  The code should work
equally well with 16- or 32-bit ints.

In a system where these assumptions are not met, you may be able to make the
code work by modifying the typedefs in jmorecfg.h.  However, you will probably
have difficulty if int is less than 16 bits wide, since references to plain
int abound in the code.

char can be either signed or unsigned, although the code runs faster if an
unsigned char type is available.  If char is wider than 8 bits, you will need
to redefine JOCTET and/or provide custom data source/destination managers so
that JOCTET represents exactly 8 bits of data on external storage.

The JPEG library proper does not assume ASCII representation of characters.
But some of the image file I/O modules in cjpeg/djpeg do have ASCII
dependencies in file-header manipulation; so does cjpeg's select_file_type()
routine.

The JPEG library does not rely heavily on the C library.  In particular, C
stdio is used only by the data source/destination modules and the error
handler, all of which are application-replaceable.  (cjpeg/djpeg are more
heavily dependent on stdio.)  malloc and free are called only from the memory
manager "back end" module, so you can use a different memory allocator by
replacing that one file.

The code generally assumes that C names must be unique in the first 15
characters.  However, global function names can be made unique in the
first 6 characters by defining NEED_SHORT_EXTERNAL_NAMES.

More info about porting the code may be gleaned by reading jconfig.doc,
jmorecfg.h, and jinclude.h.


Notes for MS-DOS implementors
-----------------------------

The JPEG code is designed to be compiled with 80x86 "small" or "medium"
memory models (i.e., data pointers are 16 bits unless explicitly declared
"far"; code pointers can be either size).  You should be able to use small
model to compile cjpeg or djpeg by itself, but you will probably have to go
to medium model if you include the JPEG code in a larger application.  This
shouldn't hurt performance much.  You *will* take a noticeable performance
hit if you compile in a large-data memory model, and you should avoid "huge"
model if at all possible.  Be sure that NEED_FAR_POINTERS is defined in
jconfig.h if you use a small-data model; be sure it is NOT defined if you use
a large-data or flat memory model.

[The following space estimates are out of date and need to be recalculated.]

An 8K stack is much more than sufficient for the JPEG code.  When executed, it
will typically malloc about 10K-20K worth of near heap space (and lots of far
heap, but that doesn't count in this calculation).  This figure will vary
depending on image size and other factors, but figuring 30K should be more
than sufficient.  Thus you have about 25K available for static data and other
modules' near heap requirements before you need to go to a larger memory
model.  The C library's static data will account for several K of this, but
that still leaves a good deal for your needs.  (If you are tight on space,
you could reduce the sizes of the I/O buffers allocated by jdatasrc.c and
jdatadst.c, say from 4K to 1K.)

Far data space may also be a tight resource when you are dealing with large
images.  The most memory-intensive case is decompression with two-pass color
quantization, or single-pass quantization to an externally supplied color map.
This requires a 128Kb color lookup table plus strip buffers amounting to about
150 bytes per column for typical sampling ratios (eg, about 96000 bytes for a
640-pixel-wide image).  You may not be able to process wide images if you have
large data structures of your own.

Of course, all of these concerns vanish if you use a flat-memory-model 386
compiler such as DJGPP or Watcom C.  We highly recommend flat model if you
can use it; the JPEG library is significantly faster in flat model.