1 files changed, 3085 insertions, 3085 deletions

diff --git a/libraries/irrlicht-1.8/source/Irrlicht/jpeglib/libjpeg.txt b/libraries/irrlicht-1.8/source/Irrlicht/jpeglib/libjpeg.txt
index 98394c8..9702669 100644
--- a/libraries/irrlicht-1.8/source/Irrlicht/jpeglib/libjpeg.txt
+++ b/libraries/irrlicht-1.8/source/Irrlicht/jpeglib/libjpeg.txt
@@ -1,3085 +1,3085 @@
-USING THE IJG JPEG LIBRARY

-

-Copyright (C) 1994-2011, Thomas G. Lane, Guido Vollbeding.

-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

-        Progressive JPEG support

-        Buffered-image mode

-        Abbreviated datastreams and multiple images

-        Special markers

-        Raw (downsampled) image data

-        Really raw data: DCT coefficients

-        Progress monitoring

-        Memory management

-        Memory usage

-        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, extended-sequential, and progressive

-JPEG processes are supported.  (Our subset includes all features now in common

-use.)  Unsupported ISO options include:

-        * Hierarchical storage

-        * Lossless JPEG

-        * 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, this library is

-used by the free LIBTIFF library to support JPEG compression in TIFF.)

-

-

-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.  This is helpful because 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.  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" or "sample" 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).

-PLEASE NOTE THAT RGB DATA IS THREE SAMPLES PER PIXEL, GRAYSCALE ONLY ONE.

-A remarkable number of people manage to miss this, only to find that their

-programs don't work with grayscale JPEG files.

-

-There is no provision for colormapped input.  JPEG files are always full-color

-or full grayscale (or sometimes another colorspace such as CMYK).  You can

-feed in a colormapped image by expanding it to full-color format.  However

-JPEG often doesn't work very well with source data that has been colormapped,

-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.  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 typically "unsigned char", unless

-you've changed jmorecfg.h.  (You can also change the RGB pixel layout, say

-to B,G,R order, by modifying jmorecfg.h.  But see the restrictions listed in

-that file before doing so.)

-

-A 2-D array of pixels is formed by making a list of pointers to the starts of

-scanlines; so the scanlines need not be physically adjacent in memory.  Even

-if you process just one scanline at a time, you must make a one-element

-pointer array to conform to this structure.  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 simplest 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 output is supported.  (Again, a JPEG file is never

-colormapped.  But you can ask the decompressor to perform on-the-fly color

-quantization to deliver colormapped output.)  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".  (It also has

-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;

-that's why the error handler must be initialized first.

-

-

-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 must be

-assigned one of the J_COLOR_SPACE enum constants, typically 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, below.

-

-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) afterwards.

-

-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 (regardless of

-the previous state of the object).  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, jpeg_destroy()

-should be passed a j_common_ptr.)

-

-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 call

-  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; neither of these routines will call term_destination().

-(See "Compressed data handling", below, for more about that.)

-

-jpeg_destroy() and jpeg_abort() are the only safe calls to make on a JPEG

-object that has reported an error by calling error_exit (see "Error handling"

-for more info).  The internal state of such an object is likely to be out of

-whack.  Either of these two routines will return the object to a known state.

-

-

-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 set desired 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 (non progressive) 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.  Don't forget that grayscale and color JPEGs will return

-different data formats!

-

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

-The return value always equals the change in the value of output_scanline.

-

-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.  (The current implementation returns only a

-few scanlines per call, no matter how large a buffer you pass.)  So you must

-always provide a loop that calls jpeg_read_scanlines() repeatedly until the

-whole image has been read.

-

-

-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 decompression, 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.

-

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

-The supplied makefiles build libjpeg.a automatically (see install.txt).

-

-While you can build the JPEG library as a shared library if the whim strikes

-you, we don't really recommend it.  The trouble with shared libraries is that

-at some point you'll probably try to substitute a new version of the library

-without recompiling the calling applications.  That generally doesn't work

-because the parameter struct declarations usually change with each new

-version.  In other words, the library's API is *not* guaranteed binary

-compatible across versions; we only try to ensure source-code compatibility.

-(In hindsight, it might have been smarter to hide the parameter structs from

-applications and introduce a ton of access functions instead.  Too late now,

-however.)

-

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

-

-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 and use jmemnobs.c (or another memory manager of

-your own devising).  More info about the minimum system library requirements

-may be found in jinclude.h.

-

-

-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_default_colorspace (j_compress_ptr cinfo)

-        Selects an appropriate JPEG colorspace based on cinfo->in_color_space,

-        and calls jpeg_set_colorspace().  This is actually a subroutine of

-        jpeg_set_defaults().  It's broken out in case you want to change

-        just the colorspace-dependent JPEG parameters.

-

-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 scaling method that

-        can't be expressed as a simple scalar multiplier, in which case the

-        premise of this routine collapses.  Caveat user.

-

-jpeg_default_qtables (j_compress_ptr cinfo, boolean force_baseline)

-        Set default quantization tables with linear q_scale_factor[] values

-        (see below).

-

-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 normal array 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).

-        CAUTION: prior to library version 6a, jpeg_add_quant_table expected

-        the basic table to be given in JPEG zigzag order.  If you need to

-        write code that works with either older or newer versions of this

-        routine, you must check the library version number.  Something like

-        "#if JPEG_LIB_VERSION >= 61" is the right test.

-

-jpeg_simple_progression (j_compress_ptr cinfo)

-        Generates a default scan script for writing a progressive-JPEG file.

-        This is the recommended method of creating a progressive file,

-        unless you want to make a custom scan sequence.  You must ensure that

-        the JPEG color space is set correctly before calling this routine.

-

-

-Compression parameters (cinfo fields) include:

-

-int block_size

-        Set DCT block size.  All N from 1 to 16 are possible.

-        Default is 8 (baseline format).

-        Larger values produce higher compression,

-        smaller values produce higher quality.

-        An exact DCT stage is possible with 1 or 2.

-        With the default quality of 75 and default Luminance qtable

-        the DCT+Quantization stage is lossless for value 1.

-        Note that values other than 8 require a SmartScale capable decoder,

-        introduced with IJG JPEG 8.  Setting the block_size parameter for

-        compression works with version 8c and later.

-

-J_DCT_METHOD dct_method

-        Selects the algorithm used for the DCT step.  Choices are:

-                JDCT_ISLOW: slow but accurate integer algorithm

-                JDCT_IFAST: faster, less accurate integer method

-                JDCT_FLOAT: floating-point method

-                JDCT_DEFAULT: default method (normally JDCT_ISLOW)

-                JDCT_FASTEST: fastest method (normally JDCT_IFAST)

-        The FLOAT method is very slightly more accurate than the ISLOW method,

-        but may give different results on different machines due to varying

-        roundoff behavior.  The integer methods should give the same results

-        on all machines.  On machines with sufficiently fast FP hardware, the

-        floating-point method may also be the fastest.  The IFAST method is

-        considerably less accurate than the other two; its use is not

-        recommended if high quality is a concern.  JDCT_DEFAULT and

-        JDCT_FASTEST are macros configurable by each installation.

-

-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 supported scaling ratios are

-        M/N with all N from 1 to 16, where M is the destination DCT size,

-        which is 8 by default (see block_size parameter above).

-        (The library design allows for arbitrary scaling ratios but this

-        is not likely to be implemented any time soon.)

-

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

-

-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.)  Defaults are zero (no restarts).

-        One restart marker per MCU row is often a good choice.

-        NOTE: the overhead of restart markers is higher in grayscale JPEG

-        files than in color files, and MUCH higher in progressive JPEGs.

-        If you use restarts, you may want to use larger intervals in those

-        cases.

-

-const jpeg_scan_info * scan_info

-int num_scans

-        By default, scan_info is NULL; this causes the compressor to write a

-        single-scan sequential JPEG file.  If not NULL, scan_info points to

-        an array of scan definition records of length num_scans.  The

-        compressor will then write a JPEG file having one scan for each scan

-        definition record.  This is used to generate noninterleaved or

-        progressive JPEG files.  The library checks that the scan array

-        defines a valid JPEG scan sequence.  (jpeg_simple_progression creates

-        a suitable scan definition array for progressive JPEG.)  This is

-        discussed further under "Progressive JPEG support".

-

-boolean do_fancy_downsampling

-        If TRUE, use direct DCT scaling with DCT size > 8 for downsampling

-        of chroma components.

-        If FALSE, use only DCT size <= 8 and simple separate downsampling.

-        Default is TRUE.

-        For better image stability in multiple generation compression cycles

-        it is preferable that this value matches the corresponding

-        do_fancy_upsampling value in decompression.

-

-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.  The default is zero.

-

-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 JFIF_major_version

-UINT8 JFIF_minor_version

-        The version number to be written into the JFIF marker.

-        jpeg_set_defaults() initializes the version to 1.01 (major=minor=1).

-        You should set it to 1.02 (major=1, minor=2) if you plan to write

-        any JFIF 1.02 extension markers.

-

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

-

-int q_scale_factor[NUM_QUANT_TBLS]

-        Linear quantization scaling factors (percentage, initialized 100)

-        for use with jpeg_default_qtables().

-        See rdswitch.c and cjpeg.c for an example of usage.

-        Note that the q_scale_factor[] fields are the "linear" scales, so you

-        have to convert from user-defined ratings via jpeg_quality_scaling().

-        Here is an example code which corresponds to cjpeg -quality 90,70:

-

-                jpeg_set_defaults(cinfo);

-

-                /* Set luminance quality 90. */

-                cinfo->q_scale_factor[0] = jpeg_quality_scaling(90);

-                /* Set chrominance quality 70. */

-                cinfo->q_scale_factor[1] = jpeg_quality_scaling(70);

-

-                jpeg_default_qtables(cinfo, force_baseline);

-

-        CAUTION: You must also set 1x1 subsampling for efficient separate

-        color quality selection, since the default value used by library

-        is 2x2:

-

-                cinfo->comp_info[0].v_samp_factor = 1;

-                cinfo->comp_info[0].h_samp_factor = 1;

-

-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 need to allocate

-        more table structures, jpeg_alloc_huff_table() may be used.

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

-

-

-The actual dimensions of the JPEG image that will be written to the file are

-given by the following fields.  These are computed from the input image

-dimensions and the compression parameters by jpeg_start_compress().  You can

-also call jpeg_calc_jpeg_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.

-

-JDIMENSION jpeg_width           Actual dimensions of output image.

-JDIMENSION jpeg_height

-

-

-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[].  (Beginning in

-        release v6, the compressor library will fill this in automatically;

-        you don't have to.)

-

-

-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 JFIF_major_version              Version information from JFIF marker

-  UINT8 JFIF_minor_version

-  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 determine the basic properties of the

-returned image 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 change this field to request output in a different

-        colorspace.  For example, set it to JCS_GRAYSCALE to get grayscale

-        output from a color file.  (This is useful for previewing: 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.  Currently,

-        the supported scaling ratios are M/N with all M from 1 to 16, where

-        N is the source DCT size, which is 8 for baseline JPEG.  (The library

-        design allows for arbitrary scaling ratios but this is not likely

-        to be implemented any time soon.)  The values are initialized by

-        jpeg_read_header() with the source DCT size.  For baseline JPEG

-        this is 8/8.  If you change only the scale_num value while leaving

-        the other unchanged, then this specifies the DCT scaled size to be

-        applied on the given input.  For baseline JPEG this is equivalent

-        to M/8 scaling, since the source DCT size for baseline JPEG is 8.

-        Smaller scaling ratios permit significantly faster decoding since

-        fewer pixels need be processed and a simpler IDCT method can be used.

-

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

-

-J_DITHER_MODE dither_mode

-        Selects color dithering method.  Supported values are:

-                JDITHER_NONE    no dithering: fast, very low quality

-                JDITHER_ORDERED ordered dither: moderate speed and quality

-                JDITHER_FS      Floyd-Steinberg dither: slow, high quality

-        Default is JDITHER_FS.  (At present, ordered dither is implemented

-        only in the single-pass, standard-colormap case.  If you ask for

-        ordered dither when two_pass_quantize is TRUE or when you supply

-        an external color map, you'll get F-S dithering.)

-

-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 suitable color map and sets these two fields itself.

-[Implementation restriction: at present, an externally supplied colormap is

-only accepted for 3-component output color spaces.]

-

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

-        CAUTION: if the JPEG library creates its own colormap, the storage

-        pointed to by this field is released by jpeg_finish_decompress().

-        Copy the colormap somewhere else first, if you want to save it.

-

-int actual_number_of_colors

-        The number of colors in the color map.

-

-Additional decompression parameters that the application may set include:

-

-J_DCT_METHOD dct_method

-        Selects the algorithm used for the DCT step.  Choices are the same

-        as described above for compression.

-

-boolean do_fancy_upsampling

-        If TRUE, use direct DCT scaling with DCT size > 8 for upsampling

-        of chroma components.

-        If FALSE, use only DCT size <= 8 and simple separate upsampling.

-        Default is TRUE.

-        For better image stability in multiple generation compression cycles

-        it is preferable that this value matches the corresponding

-        do_fancy_downsampling value in compression.

-

-boolean do_block_smoothing

-        If TRUE, interblock smoothing is applied in early stages of decoding

-        progressive JPEG files; if FALSE, not.  Default is TRUE.  Early

-        progression stages look "fuzzy" with smoothing, "blocky" without.

-        In any case, block smoothing ceases to be applied after the first few

-        AC coefficients are known to full accuracy, so it is relevant only

-        when using buffered-image mode for progressive images.

-

-boolean enable_1pass_quant

-boolean enable_external_quant

-boolean enable_2pass_quant

-        These are significant only in buffered-image mode, which is

-        described in its own section below.

-

-

-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 time will be wasted due to unnecessary data

-copying.  In high-quality modes, rec_outbuf_height is always 1, but some

-faster, lower-quality modes set it to larger values (typically 2 to 4).

-If you are going to ask for a high-speed processing mode, you may as well

-go to the trouble of honoring rec_outbuf_height so as to avoid data copying.

-(An output buffer larger than rec_outbuf_height lines is OK, but won't

-provide any material speed improvement over that height.)

-

-

-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 => RGB

-        YCbCr => GRAYSCALE

-        RGB => GRAYSCALE

-        GRAYSCALE => RGB

-        YCCK => CMYK

-as well as the null transforms.  (Since GRAYSCALE=>RGB is provided, an

-application can force grayscale JPEGs to look like color JPEGs if it only

-wants to handle one case.)

-

-The two-pass color quantizer, jquant2.c, is specialized to handle RGB data

-(it weights distances appropriately for RGB colors).  You'll need to modify

-the code if you want to use it for non-RGB output color spaces.  Note that

-jquant2.c is used to map to an application-supplied colormap as well as for

-the normal two-pass colormap selection process.

-

-CAUTION: it appears that Adobe Photoshop writes inverted data in CMYK JPEG

-files: 0 represents 100% ink coverage, rather than 0% ink as you'd expect.

-This is arguably a bug in Photoshop, but if you need to work with Photoshop

-CMYK files, you will have to deal with it in your application.  We cannot

-"fix" this in the library by inverting the data during the CMYK<=>YCCK

-transform, because that would break other applications, notably Ghostscript.

-Photoshop versions prior to 3.0 write EPS files containing JPEG-encoded CMYK

-data in the same inverted-YCCK representation used in bare JPEG files, but

-the surrounding PostScript code performs an inversion using the PS image

-operator.  I am told that Photoshop 3.0 will write uninverted YCCK in

-EPS/JPEG files, and will omit the PS-level inversion.  (But the data

-polarity used in bare JPEG files will not change in 3.0.)  In either case,

-the JPEG library must not invert the data itself, or else Ghostscript would

-read these EPS files incorrectly.

-

-

-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.  (Beginning

-with IJG version 6b, there is also a void pointer "client_data" in each

-JPEG object, which the application can also use to find related data.

-The library does not touch client_data at all.)

-

-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

-memory buffer or 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 memory

-buffer or 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, the memory

-source manager just makes the buffer pointer and length point to the original

-data in memory.  In this case the buffer-reload procedure will 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() or jpeg_mem_dest() routines of the supplied destination

-managers.

-

-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, int desired)

-        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() or jpeg_mem_src() routines of the supplied source managers.

-

-For more information, consult the memory and 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 emptied 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 not a panacea: nothing is guaranteed about the

-maximum amount of time spent in any one call to the library, so it will not

-eliminate response-time problems in single-threaded applications.  If you

-need 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 previous 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 output

-buffer 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 write out the entire buffer

-after a suspension.  Write 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 compressor does not allow 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, without flushing the buffer afterwards.

-  * 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().

-

-A more significant restriction is that jpeg_finish_compress() cannot suspend.

-This means you cannot use suspension with multi-pass operating modes, namely

-Huffman code optimization and multiple-scan output.  Those modes write the

-whole file during jpeg_finish_compress(), which will certainly result in

-buffer overrun.  (Note that this restriction applies only to compression,

-not decompression.  The decompressor supports input suspension in all of its

-operating modes.)

-

-Decompression suspension:

-

-For decompression suspension, use a fill_input_buffer() routine that simply

-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 four places:

-  * jpeg_read_header(): will return JPEG_SUSPENDED.

-  * jpeg_start_decompress(): will return FALSE, rather than its usual TRUE.

-  * 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(),

-increment the passed pointers past any scanlines successfully read.

-

-Just as with compression, the decompressor will typically backtrack to a

-convenient restart point before suspending.  When fill_input_buffer() is

-called, next_input_byte/bytes_in_buffer point to the current restart point,

-which is where the decompressor will backtrack to if FALSE is returned.

-The data beyond that position must NOT be discarded if you suspend; it needs

-to 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 should return FALSE, which will cause a

-suspension return.  The surrounding application must then arrange to discard

-the recorded 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

-though it had read more data in a non-suspending situation.

-

-The decompressor does not attempt to suspend within standard JPEG markers;

-instead it will backtrack to the start of the marker and reprocess the whole

-marker next time.  Hence the input buffer must be large enough to hold the

-longest standard marker in the file.  Standard JPEG markers should normally

-not exceed a few hundred bytes each (DHT tables are typically the longest).

-We recommend at least a 2K buffer for performance reasons, which is much

-larger than any correct marker is likely to be.  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.  (The library can't

-provide this test since it has no idea whether "the buffer is full", or

-even whether there is a fixed-size input buffer.)

-

-The input buffer would need to be 64K to allow for arbitrary COM or APPn

-markers, but these are handled specially: they are either saved into allocated

-memory, or skipped over by calling skip_input_data().  In the former case,

-suspension is handled correctly, and in the latter case, the problem of

-buffer overrun is placed on skip_input_data's shoulders, as explained above.

-Note that if you provide your own marker handling routine for large markers,

-you should consider how to deal with buffer overflow.

-

-Multiple-buffer management:

-

-In some applications it is desirable to store the compressed data in a linked

-list of buffer areas, so as to avoid data copying.  This can be handled by

-having empty_output_buffer() or fill_input_buffer() set the pointer and count

-to reference the next available buffer; FALSE is returned only if no more

-buffers are available.  Although seemingly straightforward, there is a

-pitfall in this approach: the backtrack that occurs when FALSE is returned

-could back up into an earlier buffer.  For example, when fill_input_buffer()

-is called, the current pointer & count indicate the backtrack restart point.

-Since fill_input_buffer() will set the pointer and count to refer to a new

-buffer, the restart position must be saved somewhere else.  Suppose a second

-call to fill_input_buffer() occurs in the same library call, and no

-additional input data is available, so fill_input_buffer must return FALSE.

-If the JPEG library has not moved the pointer/count forward in the current

-buffer, then *the correct restart point is the saved position in the prior

-buffer*.  Prior buffers may be discarded only after the library establishes

-a restart point within a later buffer.  Similar remarks apply for output into

-a chain of buffers.

-

-The library will never attempt to backtrack over a skip_input_data() call,

-so any skipped data can be permanently discarded.  You still have to deal

-with the case of skipping not-yet-received data, however.

-

-It's much simpler to use only a single buffer; when fill_input_buffer() is

-called, move any unconsumed data (beyond the current pointer/count) down to

-the beginning of this buffer and then load new data into the remaining buffer

-space.  This approach requires a little more data copying but is far easier

-to get right.

-

-

-Progressive JPEG support

-------------------------

-

-Progressive JPEG rearranges the stored data into a series of scans of

-increasing quality.  In situations where a JPEG file is transmitted across a

-slow communications link, a decoder can generate a low-quality image very

-quickly from the first scan, then gradually improve the displayed quality as

-more scans are received.  The final image after all scans are complete is

-identical to that of a regular (sequential) JPEG file of the same quality

-setting.  Progressive JPEG files are often slightly smaller than equivalent

-sequential JPEG files, but the possibility of incremental display is the main

-reason for using progressive JPEG.

-

-The IJG encoder library generates progressive JPEG files when given a

-suitable "scan script" defining how to divide the data into scans.

-Creation of progressive JPEG files is otherwise transparent to the encoder.

-Progressive JPEG files can also be read transparently by the decoder library.

-If the decoding application simply uses the library as defined above, it

-will receive a final decoded image without any indication that the file was

-progressive.  Of course, this approach does not allow incremental display.

-To perform incremental display, an application needs to use the decoder

-library's "buffered-image" mode, in which it receives a decoded image

-multiple times.

-

-Each displayed scan requires about as much work to decode as a full JPEG

-image of the same size, so the decoder must be fairly fast in relation to the

-data transmission rate in order to make incremental display useful.  However,

-it is possible to skip displaying the image and simply add the incoming bits

-to the decoder's coefficient buffer.  This is fast because only Huffman

-decoding need be done, not IDCT, upsampling, colorspace conversion, etc.

-The IJG decoder library allows the application to switch dynamically between

-displaying the image and simply absorbing the incoming bits.  A properly

-coded application can automatically adapt the number of display passes to

-suit the time available as the image is received.  Also, a final

-higher-quality display cycle can be performed from the buffered data after

-the end of the file is reached.

-

-Progressive compression:

-

-To create a progressive JPEG file (or a multiple-scan sequential JPEG file),

-set the scan_info cinfo field to point to an array of scan descriptors, and

-perform compression as usual.  Instead of constructing your own scan list,

-you can call the jpeg_simple_progression() helper routine to create a

-recommended progression sequence; this method should be used by all

-applications that don't want to get involved in the nitty-gritty of

-progressive scan sequence design.  (If you want to provide user control of

-scan sequences, you may wish to borrow the scan script reading code found

-in rdswitch.c, so that you can read scan script files just like cjpeg's.)

-When scan_info is not NULL, the compression library will store DCT'd data

-into a buffer array as jpeg_write_scanlines() is called, and will emit all

-the requested scans during jpeg_finish_compress().  This implies that

-multiple-scan output cannot be created with a suspending data destination

-manager, since jpeg_finish_compress() does not support suspension.  We

-should also note that the compressor currently forces Huffman optimization

-mode when creating a progressive JPEG file, because the default Huffman

-tables are unsuitable for progressive files.

-

-Progressive decompression:

-

-When buffered-image mode is not used, the decoder library will read all of

-a multi-scan file during jpeg_start_decompress(), so that it can provide a

-final decoded image.  (Here "multi-scan" means either progressive or

-multi-scan sequential.)  This makes multi-scan files transparent to the

-decoding application.  However, existing applications that used suspending

-input with version 5 of the IJG library will need to be modified to check

-for a suspension return from jpeg_start_decompress().

-

-To perform incremental display, an application must use the library's

-buffered-image mode.  This is described in the next section.

-

-

-Buffered-image mode

--------------------

-

-In buffered-image mode, the library stores the partially decoded image in a

-coefficient buffer, from which it can be read out as many times as desired.

-This mode is typically used for incremental display of progressive JPEG files,

-but it can be used with any JPEG file.  Each scan of a progressive JPEG file

-adds more data (more detail) to the buffered image.  The application can

-display in lockstep with the source file (one display pass per input scan),

-or it can allow input processing to outrun display processing.  By making

-input and display processing run independently, it is possible for the

-application to adapt progressive display to a wide range of data transmission

-rates.

-

-The basic control flow for buffered-image decoding is

-

-        jpeg_create_decompress()

-        set data source

-        jpeg_read_header()

-        set overall decompression parameters

-        cinfo.buffered_image = TRUE;    /* select buffered-image mode */

-        jpeg_start_decompress()

-        for (each output pass) {

-            adjust output decompression parameters if required

-            jpeg_start_output()         /* start a new output pass */

-            for (all scanlines in image) {

-                jpeg_read_scanlines()

-                display scanlines

-            }

-            jpeg_finish_output()        /* terminate output pass */

-        }

-        jpeg_finish_decompress()

-        jpeg_destroy_decompress()

-

-This differs from ordinary unbuffered decoding in that there is an additional

-level of looping.  The application can choose how many output passes to make

-and how to display each pass.

-

-The simplest approach to displaying progressive images is to do one display

-pass for each scan appearing in the input file.  In this case the outer loop

-condition is typically

-        while (! jpeg_input_complete(&cinfo))

-and the start-output call should read

-        jpeg_start_output(&cinfo, cinfo.input_scan_number);

-The second parameter to jpeg_start_output() indicates which scan of the input

-file is to be displayed; the scans are numbered starting at 1 for this

-purpose.  (You can use a loop counter starting at 1 if you like, but using

-the library's input scan counter is easier.)  The library automatically reads

-data as necessary to complete each requested scan, and jpeg_finish_output()

-advances to the next scan or end-of-image marker (hence input_scan_number

-will be incremented by the time control arrives back at jpeg_start_output()).

-With this technique, data is read from the input file only as needed, and

-input and output processing run in lockstep.

-

-After reading the final scan and reaching the end of the input file, the

-buffered image remains available; it can be read additional times by

-repeating the jpeg_start_output()/jpeg_read_scanlines()/jpeg_finish_output()

-sequence.  For example, a useful technique is to use fast one-pass color

-quantization for display passes made while the image is arriving, followed by

-a final display pass using two-pass quantization for highest quality.  This

-is done by changing the library parameters before the final output pass.

-Changing parameters between passes is discussed in detail below.

-

-In general the last scan of a progressive file cannot be recognized as such

-until after it is read, so a post-input display pass is the best approach if

-you want special processing in the final pass.

-

-When done with the image, be sure to call jpeg_finish_decompress() to release

-the buffered image (or just use jpeg_destroy_decompress()).

-

-If input data arrives faster than it can be displayed, the application can

-cause the library to decode input data in advance of what's needed to produce

-output.  This is done by calling the routine jpeg_consume_input().

-The return value is one of the following:

-        JPEG_REACHED_SOS:    reached an SOS marker (the start of a new scan)

-        JPEG_REACHED_EOI:    reached the EOI marker (end of image)

-        JPEG_ROW_COMPLETED:  completed reading one MCU row of compressed data

-        JPEG_SCAN_COMPLETED: completed reading last MCU row of current scan

-        JPEG_SUSPENDED:      suspended before completing any of the above

-(JPEG_SUSPENDED can occur only if a suspending data source is used.)  This

-routine can be called at any time after initializing the JPEG object.  It

-reads some additional data and returns when one of the indicated significant

-events occurs.  (If called after the EOI marker is reached, it will

-immediately return JPEG_REACHED_EOI without attempting to read more data.)

-

-The library's output processing will automatically call jpeg_consume_input()

-whenever the output processing overtakes the input; thus, simple lockstep

-display requires no direct calls to jpeg_consume_input().  But by adding

-calls to jpeg_consume_input(), you can absorb data in advance of what is

-being displayed.  This has two benefits:

-  * You can limit buildup of unprocessed data in your input buffer.

-  * You can eliminate extra display passes by paying attention to the

-    state of the library's input processing.

-

-The first of these benefits only requires interspersing calls to

-jpeg_consume_input() with your display operations and any other processing

-you may be doing.  To avoid wasting cycles due to backtracking, it's best to

-call jpeg_consume_input() only after a hundred or so new bytes have arrived.

-This is discussed further under "I/O suspension", above.  (Note: the JPEG

-library currently is not thread-safe.  You must not call jpeg_consume_input()

-from one thread of control if a different library routine is working on the

-same JPEG object in another thread.)

-

-When input arrives fast enough that more than one new scan is available

-before you start a new output pass, you may as well skip the output pass

-corresponding to the completed scan.  This occurs for free if you pass

-cinfo.input_scan_number as the target scan number to jpeg_start_output().

-The input_scan_number field is simply the index of the scan currently being

-consumed by the input processor.  You can ensure that this is up-to-date by

-emptying the input buffer just before calling jpeg_start_output(): call

-jpeg_consume_input() repeatedly until it returns JPEG_SUSPENDED or

-JPEG_REACHED_EOI.

-

-The target scan number passed to jpeg_start_output() is saved in the

-cinfo.output_scan_number field.  The library's output processing calls

-jpeg_consume_input() whenever the current input scan number and row within

-that scan is less than or equal to the current output scan number and row.

-Thus, input processing can "get ahead" of the output processing but is not

-allowed to "fall behind".  You can achieve several different effects by

-manipulating this interlock rule.  For example, if you pass a target scan

-number greater than the current input scan number, the output processor will

-wait until that scan starts to arrive before producing any output.  (To avoid

-an infinite loop, the target scan number is automatically reset to the last

-scan number when the end of image is reached.  Thus, if you specify a large

-target scan number, the library will just absorb the entire input file and

-then perform an output pass.  This is effectively the same as what

-jpeg_start_decompress() does when you don't select buffered-image mode.)

-When you pass a target scan number equal to the current input scan number,

-the image is displayed no faster than the current input scan arrives.  The

-final possibility is to pass a target scan number less than the current input

-scan number; this disables the input/output interlock and causes the output

-processor to simply display whatever it finds in the image buffer, without

-waiting for input.  (However, the library will not accept a target scan

-number less than one, so you can't avoid waiting for the first scan.)

-

-When data is arriving faster than the output display processing can advance

-through the image, jpeg_consume_input() will store data into the buffered

-image beyond the point at which the output processing is reading data out

-again.  If the input arrives fast enough, it may "wrap around" the buffer to

-the point where the input is more than one whole scan ahead of the output.

-If the output processing simply proceeds through its display pass without

-paying attention to the input, the effect seen on-screen is that the lower

-part of the image is one or more scans better in quality than the upper part.

-Then, when the next output scan is started, you have a choice of what target

-scan number to use.  The recommended choice is to use the current input scan

-number at that time, which implies that you've skipped the output scans

-corresponding to the input scans that were completed while you processed the

-previous output scan.  In this way, the decoder automatically adapts its

-speed to the arriving data, by skipping output scans as necessary to keep up

-with the arriving data.

-

-When using this strategy, you'll want to be sure that you perform a final

-output pass after receiving all the data; otherwise your last display may not

-be full quality across the whole screen.  So the right outer loop logic is

-something like this:

-        do {

-            absorb any waiting input by calling jpeg_consume_input()

-            final_pass = jpeg_input_complete(&cinfo);

-            adjust output decompression parameters if required

-            jpeg_start_output(&cinfo, cinfo.input_scan_number);

-            ...

-            jpeg_finish_output()

-        } while (! final_pass);

-rather than quitting as soon as jpeg_input_complete() returns TRUE.  This

-arrangement makes it simple to use higher-quality decoding parameters

-for the final pass.  But if you don't want to use special parameters for

-the final pass, the right loop logic is like this:

-        for (;;) {

-            absorb any waiting input by calling jpeg_consume_input()

-            jpeg_start_output(&cinfo, cinfo.input_scan_number);

-            ...

-            jpeg_finish_output()

-            if (jpeg_input_complete(&cinfo) &&

-                cinfo.input_scan_number == cinfo.output_scan_number)

-              break;

-        }

-In this case you don't need to know in advance whether an output pass is to

-be the last one, so it's not necessary to have reached EOF before starting

-the final output pass; rather, what you want to test is whether the output

-pass was performed in sync with the final input scan.  This form of the loop

-will avoid an extra output pass whenever the decoder is able (or nearly able)

-to keep up with the incoming data.

-

-When the data transmission speed is high, you might begin a display pass,

-then find that much or all of the file has arrived before you can complete

-the pass.  (You can detect this by noting the JPEG_REACHED_EOI return code

-from jpeg_consume_input(), or equivalently by testing jpeg_input_complete().)

-In this situation you may wish to abort the current display pass and start a

-new one using the newly arrived information.  To do so, just call

-jpeg_finish_output() and then start a new pass with jpeg_start_output().

-

-A variant strategy is to abort and restart display if more than one complete

-scan arrives during an output pass; this can be detected by noting

-JPEG_REACHED_SOS returns and/or examining cinfo.input_scan_number.  This

-idea should be employed with caution, however, since the display process

-might never get to the bottom of the image before being aborted, resulting

-in the lower part of the screen being several passes worse than the upper.

-In most cases it's probably best to abort an output pass only if the whole

-file has arrived and you want to begin the final output pass immediately.

-

-When receiving data across a communication link, we recommend always using

-the current input scan number for the output target scan number; if a

-higher-quality final pass is to be done, it should be started (aborting any

-incomplete output pass) as soon as the end of file is received.  However,

-many other strategies are possible.  For example, the application can examine

-the parameters of the current input scan and decide whether to display it or

-not.  If the scan contains only chroma data, one might choose not to use it

-as the target scan, expecting that the scan will be small and will arrive

-quickly.  To skip to the next scan, call jpeg_consume_input() until it

-returns JPEG_REACHED_SOS or JPEG_REACHED_EOI.  Or just use the next higher

-number as the target scan for jpeg_start_output(); but that method doesn't

-let you inspect the next scan's parameters before deciding to display it.

-

-

-In buffered-image mode, jpeg_start_decompress() never performs input and

-thus never suspends.  An application that uses input suspension with

-buffered-image mode must be prepared for suspension returns from these

-routines:

-* jpeg_start_output() performs input only if you request 2-pass quantization

-  and the target scan isn't fully read yet.  (This is discussed below.)

-* jpeg_read_scanlines(), as always, returns the number of scanlines that it

-  was able to produce before suspending.

-* jpeg_finish_output() will read any markers following the target scan,

-  up to the end of the file or the SOS marker that begins another scan.

-  (But it reads no input if jpeg_consume_input() has already reached the

-  end of the file or a SOS marker beyond the target output scan.)

-* jpeg_finish_decompress() will read until the end of file, and thus can

-  suspend if the end hasn't already been reached (as can be tested by

-  calling jpeg_input_complete()).

-jpeg_start_output(), jpeg_finish_output(), and jpeg_finish_decompress()

-all return TRUE if they completed their tasks, FALSE if they had to suspend.

-In the event of a FALSE return, the application must load more input data

-and repeat the call.  Applications that use non-suspending data sources need

-not check the return values of these three routines.

-

-

-It is possible to change decoding parameters between output passes in the

-buffered-image mode.  The decoder library currently supports only very

-limited changes of parameters.  ONLY THE FOLLOWING parameter changes are

-allowed after jpeg_start_decompress() is called:

-* dct_method can be changed before each call to jpeg_start_output().

-  For example, one could use a fast DCT method for early scans, changing

-  to a higher quality method for the final scan.

-* dither_mode can be changed before each call to jpeg_start_output();

-  of course this has no impact if not using color quantization.  Typically

-  one would use ordered dither for initial passes, then switch to

-  Floyd-Steinberg dither for the final pass.  Caution: changing dither mode

-  can cause more memory to be allocated by the library.  Although the amount

-  of memory involved is not large (a scanline or so), it may cause the

-  initial max_memory_to_use specification to be exceeded, which in the worst

-  case would result in an out-of-memory failure.

-* do_block_smoothing can be changed before each call to jpeg_start_output().

-  This setting is relevant only when decoding a progressive JPEG image.

-  During the first DC-only scan, block smoothing provides a very "fuzzy" look

-  instead of the very "blocky" look seen without it; which is better seems a

-  matter of personal taste.  But block smoothing is nearly always a win

-  during later stages, especially when decoding a successive-approximation

-  image: smoothing helps to hide the slight blockiness that otherwise shows

-  up on smooth gradients until the lowest coefficient bits are sent.

-* Color quantization mode can be changed under the rules described below.

-  You *cannot* change between full-color and quantized output (because that

-  would alter the required I/O buffer sizes), but you can change which

-  quantization method is used.

-

-When generating color-quantized output, changing quantization method is a

-very useful way of switching between high-speed and high-quality display.

-The library allows you to change among its three quantization methods:

-1. Single-pass quantization to a fixed color cube.

-   Selected by cinfo.two_pass_quantize = FALSE and cinfo.colormap = NULL.

-2. Single-pass quantization to an application-supplied colormap.

-   Selected by setting cinfo.colormap to point to the colormap (the value of

-   two_pass_quantize is ignored); also set cinfo.actual_number_of_colors.

-3. Two-pass quantization to a colormap chosen specifically for the image.

-   Selected by cinfo.two_pass_quantize = TRUE and cinfo.colormap = NULL.

-   (This is the default setting selected by jpeg_read_header, but it is

-   probably NOT what you want for the first pass of progressive display!)

-These methods offer successively better quality and lesser speed.  However,

-only the first method is available for quantizing in non-RGB color spaces.

-

-IMPORTANT: because the different quantizer methods have very different

-working-storage requirements, the library requires you to indicate which

-one(s) you intend to use before you call jpeg_start_decompress().  (If we did

-not require this, the max_memory_to_use setting would be a complete fiction.)

-You do this by setting one or more of these three cinfo fields to TRUE:

-        enable_1pass_quant              Fixed color cube colormap

-        enable_external_quant           Externally-supplied colormap

-        enable_2pass_quant              Two-pass custom colormap

-All three are initialized FALSE by jpeg_read_header().  But

-jpeg_start_decompress() automatically sets TRUE the one selected by the

-current two_pass_quantize and colormap settings, so you only need to set the

-enable flags for any other quantization methods you plan to change to later.

-

-After setting the enable flags correctly at jpeg_start_decompress() time, you

-can change to any enabled quantization method by setting two_pass_quantize

-and colormap properly just before calling jpeg_start_output().  The following

-special rules apply:

-1. You must explicitly set cinfo.colormap to NULL when switching to 1-pass

-   or 2-pass mode from a different mode, or when you want the 2-pass

-   quantizer to be re-run to generate a new colormap.

-2. To switch to an external colormap, or to change to a different external

-   colormap than was used on the prior pass, you must call

-   jpeg_new_colormap() after setting cinfo.colormap.

-NOTE: if you want to use the same colormap as was used in the prior pass,

-you should not do either of these things.  This will save some nontrivial

-switchover costs.

-(These requirements exist because cinfo.colormap will always be non-NULL

-after completing a prior output pass, since both the 1-pass and 2-pass

-quantizers set it to point to their output colormaps.  Thus you have to

-do one of these two things to notify the library that something has changed.

-Yup, it's a bit klugy, but it's necessary to do it this way for backwards

-compatibility.)

-

-Note that in buffered-image mode, the library generates any requested colormap

-during jpeg_start_output(), not during jpeg_start_decompress().

-

-When using two-pass quantization, jpeg_start_output() makes a pass over the

-buffered image to determine the optimum color map; it therefore may take a

-significant amount of time, whereas ordinarily it does little work.  The

-progress monitor hook is called during this pass, if defined.  It is also

-important to realize that if the specified target scan number is greater than

-or equal to the current input scan number, jpeg_start_output() will attempt

-to consume input as it makes this pass.  If you use a suspending data source,

-you need to check for a FALSE return from jpeg_start_output() under these

-conditions.  The combination of 2-pass quantization and a not-yet-fully-read

-target scan is the only case in which jpeg_start_output() will consume input.

-

-

-Application authors who support buffered-image mode may be tempted to use it

-for all JPEG images, even single-scan ones.  This will work, but it is

-inefficient: there is no need to create an image-sized coefficient buffer for

-single-scan images.  Requesting buffered-image mode for such an image wastes

-memory.  Worse, it can cost time on large images, since the buffered data has

-to be swapped out or written to a temporary file.  If you are concerned about

-maximum performance on baseline JPEG files, you should use buffered-image

-mode only when the incoming file actually has multiple scans.  This can be

-tested by calling jpeg_has_multiple_scans(), which will return a correct

-result at any time after jpeg_read_header() completes.

-

-It is also worth noting that when you use jpeg_consume_input() to let input

-processing get ahead of output processing, the resulting pattern of access to

-the coefficient buffer is quite nonsequential.  It's best to use the memory

-manager jmemnobs.c if you can (ie, if you have enough real or virtual main

-memory).  If not, at least make sure that max_memory_to_use is set as high as

-possible.  If the JPEG memory manager has to use a temporary file, you will

-probably see a lot of disk traffic and poor performance.  (This could be

-improved with additional work on the memory manager, but we haven't gotten

-around to it yet.)

-

-In some applications it may be convenient to use jpeg_consume_input() for all

-input processing, including reading the initial markers; that is, you may

-wish to call jpeg_consume_input() instead of jpeg_read_header() during

-startup.  This works, but note that you must check for JPEG_REACHED_SOS and

-JPEG_REACHED_EOI return codes as the equivalent of jpeg_read_header's codes.

-Once the first SOS marker has been reached, you must call

-jpeg_start_decompress() before jpeg_consume_input() will consume more input;

-it'll just keep returning JPEG_REACHED_SOS until you do.  If you read a

-tables-only file this way, jpeg_consume_input() will return JPEG_REACHED_EOI

-without ever returning JPEG_REACHED_SOS; be sure to check for this case.

-If this happens, the decompressor will not read any more input until you call

-jpeg_abort() to reset it.  It is OK to call jpeg_consume_input() even when not

-using buffered-image mode, but in that case it's basically a no-op after the

-initial markers have been read: it will just return JPEG_SUSPENDED.

-

-

-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 then 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 when 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.  See jpeg_copy_critical_parameters()

-for an example of copying quantization tables.

-

-

-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.  For example,

-to load a fixed quantization table into table slot "n":

-

-    if (cinfo.quant_tbl_ptrs[n] == NULL)

-      cinfo.quant_tbl_ptrs[n] = jpeg_alloc_quant_table((j_common_ptr) &cinfo);

-    quant_ptr = cinfo.quant_tbl_ptrs[n];        /* quant_ptr is JQUANT_TBL* */

-    for (i = 0; i < 64; i++) {

-      /* Qtable[] is desired quantization table, in natural array order */

-      quant_ptr->quantval[i] = Qtable[i];

-    }

-

-Code to load a fixed Huffman table is typically (for AC table "n"):

-

-    if (cinfo.ac_huff_tbl_ptrs[n] == NULL)

-      cinfo.ac_huff_tbl_ptrs[n] = jpeg_alloc_huff_table((j_common_ptr) &cinfo);

-    huff_ptr = cinfo.ac_huff_tbl_ptrs[n];       /* huff_ptr is JHUFF_TBL* */

-    for (i = 1; i <= 16; i++) {

-      /* counts[i] is number of Huffman codes of length i bits, i=1..16 */

-      huff_ptr->bits[i] = counts[i];

-    }

-    for (i = 0; i < 256; i++) {

-      /* symbols[] is the list of Huffman symbols, in code-length order */

-      huff_ptr->huffval[i] = symbols[i];

-    }

-

-(Note that trying to set cinfo.quant_tbl_ptrs[n] to point directly at a

-constant JQUANT_TBL object is not safe.  If the incoming file happened to

-contain a quantization table definition, your master table would get

-overwritten!  Instead allocate a working table copy and copy the master table

-into it, as illustrated above.  Ditto for Huffman tables, of course.)

-

-You might want to read the tables from a tables-only file, rather than

-hard-wiring them into your application.  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 later, 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

----------------

-

-Some applications may need to insert or extract special data in the JPEG

-datastream.  The JPEG standard provides marker types "COM" (comment) and

-"APP0" through "APP15" (application) to hold application-specific data.

-Unfortunately, the use of these markers is not specified by the standard.

-COM markers are fairly widely used to hold user-supplied text.  The JFIF file

-format spec uses APP0 markers with specified initial strings to hold certain

-data.  Adobe applications use APP14 markers beginning with the string "Adobe"

-for miscellaneous data.  Other APPn markers are rarely seen, but might

-contain almost anything.

-

-If you wish to store user-supplied text, we recommend you use COM markers

-and place readable 7-bit ASCII text in them.  Newline conventions are not

-standardized --- expect to find LF (Unix style), CR/LF (DOS style), or CR

-(Mac style).  A robust COM reader should be able to cope with random binary

-garbage, including nulls, since some applications generate COM markers

-containing non-ASCII junk.  (But yours should not be one of them.)

-

-For program-supplied data, use an APPn marker, and be sure to begin it with an

-identifying string so that you can tell whether the marker is actually yours.

-It's probably best to avoid using APP0 or APP14 for any private markers.

-(NOTE: the upcoming SPIFF standard will use APP8 markers; we recommend you

-not use APP8 markers for any private purposes, either.)

-

-Keep in mind that at most 65533 bytes can be put into one marker, but you

-can have as many markers as you like.

-

-By default, the IJG compression library will write a JFIF APP0 marker if the

-selected JPEG colorspace is grayscale or YCbCr, or an Adobe APP14 marker if

-the selected colorspace is RGB, CMYK, or YCCK.  You can disable this, but

-we don't recommend it.  The decompression library will recognize JFIF and

-Adobe markers and will set the JPEG colorspace properly when one is found.

-

-

-You can write special markers immediately following the datastream header by

-calling jpeg_write_marker() after jpeg_start_compress() and before the first

-call to jpeg_write_scanlines().  When you do this, the markers appear after

-the SOI and the JFIF APP0 and Adobe APP14 markers (if written), but before

-all else.  Specify the marker type parameter as "JPEG_COM" for COM or

-"JPEG_APP0 + n" for APPn.  (Actually, jpeg_write_marker will let you write

-any marker type, but we don't recommend writing any other kinds of marker.)

-For example, to write a user comment string pointed to by comment_text:

-        jpeg_write_marker(cinfo, JPEG_COM, comment_text, strlen(comment_text));

-

-If it's not convenient to store all the marker data in memory at once,

-you can instead call jpeg_write_m_header() followed by multiple calls to

-jpeg_write_m_byte().  If you do it this way, it's your responsibility to

-call jpeg_write_m_byte() exactly the number of times given in the length

-parameter to jpeg_write_m_header().  (This method lets you empty the

-output buffer partway through a marker, which might be important when

-using a suspending data destination module.  In any case, if you are using

-a suspending destination, you should flush its buffer after inserting

-any special markers.  See "I/O suspension".)

-

-Or, if you prefer to synthesize the marker byte sequence yourself,

-you can just cram it straight into the data destination module.

-

-If you are writing JFIF 1.02 extension markers (thumbnail images), don't

-forget to set cinfo.JFIF_minor_version = 2 so that the encoder will write the

-correct JFIF version number in the JFIF header marker.  The library's default

-is to write version 1.01, but that's wrong if you insert any 1.02 extension

-markers.  (We could probably get away with just defaulting to 1.02, but there

-used to be broken decoders that would complain about unknown minor version

-numbers.  To reduce compatibility risks it's safest not to write 1.02 unless

-you are actually using 1.02 extensions.)

-

-

-When reading, two methods of handling special markers are available:

-1. You can ask the library to save the contents of COM and/or APPn markers

-into memory, and then examine them at your leisure afterwards.

-2. You can supply your own routine to process COM and/or APPn markers

-on-the-fly as they are read.

-The first method is simpler to use, especially if you are using a suspending

-data source; writing a marker processor that copes with input suspension is

-not easy (consider what happens if the marker is longer than your available

-input buffer).  However, the second method conserves memory since the marker

-data need not be kept around after it's been processed.

-

-For either method, you'd normally set up marker handling after creating a

-decompression object and before calling jpeg_read_header(), because the

-markers of interest will typically be near the head of the file and so will

-be scanned by jpeg_read_header.  Once you've established a marker handling

-method, it will be used for the life of that decompression object

-(potentially many datastreams), unless you change it.  Marker handling is

-determined separately for COM markers and for each APPn marker code.

-

-

-To save the contents of special markers in memory, call

-        jpeg_save_markers(cinfo, marker_code, length_limit)

-where marker_code is the marker type to save, JPEG_COM or JPEG_APP0+n.

-(To arrange to save all the special marker types, you need to call this

-routine 17 times, for COM and APP0-APP15.)  If the incoming marker is longer

-than length_limit data bytes, only length_limit bytes will be saved; this

-parameter allows you to avoid chewing up memory when you only need to see the

-first few bytes of a potentially large marker.  If you want to save all the

-data, set length_limit to 0xFFFF; that is enough since marker lengths are only

-16 bits.  As a special case, setting length_limit to 0 prevents that marker

-type from being saved at all.  (That is the default behavior, in fact.)

-

-After jpeg_read_header() completes, you can examine the special markers by

-following the cinfo->marker_list pointer chain.  All the special markers in

-the file appear in this list, in order of their occurrence in the file (but

-omitting any markers of types you didn't ask for).  Both the original data

-length and the saved data length are recorded for each list entry; the latter

-will not exceed length_limit for the particular marker type.  Note that these

-lengths exclude the marker length word, whereas the stored representation

-within the JPEG file includes it.  (Hence the maximum data length is really

-only 65533.)

-

-It is possible that additional special markers appear in the file beyond the

-SOS marker at which jpeg_read_header stops; if so, the marker list will be

-extended during reading of the rest of the file.  This is not expected to be

-common, however.  If you are short on memory you may want to reset the length

-limit to zero for all marker types after finishing jpeg_read_header, to

-ensure that the max_memory_to_use setting cannot be exceeded due to addition

-of later markers.

-

-The marker list remains stored until you call jpeg_finish_decompress or

-jpeg_abort, at which point the memory is freed and the list is set to empty.

-(jpeg_destroy also releases the storage, of course.)

-

-Note that the library is internally interested in APP0 and APP14 markers;

-if you try to set a small nonzero length limit on these types, the library

-will silently force the length up to the minimum it wants.  (But you can set

-a zero length limit to prevent them from being saved at all.)  Also, in a

-16-bit environment, the maximum length limit may be constrained to less than

-65533 by malloc() limitations.  It is therefore best not to assume that the

-effective length limit is exactly what you set it to be.

-

-

-If you want to supply your own marker-reading routine, you do it by calling

-jpeg_set_marker_processor().  A marker processor routine must have the

-signature

-        boolean jpeg_marker_parser_method (j_decompress_ptr cinfo)

-Although the marker code is not explicitly passed, the routine can find it

-in cinfo->unread_marker.  At the time of call, the marker proper has been

-read from the data source module.  The processor routine is responsible for

-reading the marker length word and the remaining parameter bytes, if any.

-Return TRUE to indicate success.  (FALSE should be returned only if you are

-using a suspending data source and it tells you to suspend.  See the standard

-marker processors in jdmarker.c for appropriate coding methods if you need to

-use a suspending data source.)

-

-If you override the default APP0 or APP14 processors, it is up to you to

-recognize JFIF and Adobe markers if you want colorspace recognition to occur

-properly.  We recommend copying and extending the default processors if you

-want to do that.  (A better idea is to save these marker types for later

-examination by calling jpeg_save_markers(); that method doesn't interfere

-with the library's own processing of these markers.)

-

-jpeg_set_marker_processor() and jpeg_save_markers() are mutually exclusive

---- if you call one it overrides any previous call to the other, for the

-particular marker type specified.

-

-A simple example of an external COM processor can be found in djpeg.c.

-Also, see jpegtran.c for an example of using jpeg_save_markers.

-

-

-Raw (downsampled) image data

-----------------------------

-

-Some applications need to supply already-downsampled image data to the JPEG

-compressor, or to receive raw downsampled data from the decompressor.  The

-library supports this requirement by allowing the application to write or

-read raw data, bypassing the normal preprocessing or postprocessing steps.

-The interface is different from the standard one and is somewhat harder to

-use.  If your interest is merely in bypassing color conversion, we recommend

-that you use the standard interface and simply set jpeg_color_space =

-in_color_space (or jpeg_color_space = out_color_space for decompression).

-The mechanism described in this section is necessary only to supply or

-receive downsampled image data, in which not all components have the same

-dimensions.

-

-

-To compress raw data, you must supply the data in the colorspace to be used

-in the JPEG file (please read the earlier section on Special color spaces)

-and downsampled to the sampling factors specified in the JPEG parameters.

-You must supply the data in the format used internally by the JPEG library,

-namely a JSAMPIMAGE array.  This is an array of pointers to two-dimensional

-arrays, each of type JSAMPARRAY.  Each 2-D array holds the values for one

-color component.  This structure is necessary since the components are of

-different sizes.  If the image dimensions are not a multiple of the MCU size,

-you must also pad the data correctly (usually, this is done by replicating

-the last column and/or row).  The data must be padded to a multiple of a DCT

-block in each component: that is, each downsampled row must contain a

-multiple of 8 valid samples, and there must be a multiple of 8 sample rows

-for each component.  (For applications such as conversion of digital TV

-images, the standard image size is usually a multiple of the DCT block size,

-so that no padding need actually be done.)

-

-The procedure for compression of raw data is basically the same as normal

-compression, except that you call jpeg_write_raw_data() in place of

-jpeg_write_scanlines().  Before calling jpeg_start_compress(), you must do

-the following:

-  * Set cinfo->raw_data_in to TRUE.  (It is set FALSE by jpeg_set_defaults().)

-    This notifies the library that you will be supplying raw data.

-    Furthermore, set cinfo->do_fancy_downsampling to FALSE if you want to use

-    real downsampled data.  (It is set TRUE by jpeg_set_defaults().)

-  * Ensure jpeg_color_space is correct --- an explicit jpeg_set_colorspace()

-    call is a good idea.  Note that since color conversion is bypassed,

-    in_color_space is ignored, except that jpeg_set_defaults() uses it to

-    choose the default jpeg_color_space setting.

-  * Ensure the sampling factors, cinfo->comp_info[i].h_samp_factor and

-    cinfo->comp_info[i].v_samp_factor, are correct.  Since these indicate the

-    dimensions of the data you are supplying, it's wise to set them

-    explicitly, rather than assuming the library's defaults are what you want.

-

-To pass raw data to the library, call jpeg_write_raw_data() in place of

-jpeg_write_scanlines().  The two routines work similarly except that

-jpeg_write_raw_data takes a JSAMPIMAGE data array rather than JSAMPARRAY.

-The scanlines count passed to and returned from jpeg_write_raw_data is

-measured in terms of the component with the largest v_samp_factor.

-

-jpeg_write_raw_data() processes one MCU row per call, which is to say

-v_samp_factor*DCTSIZE sample rows of each component.  The passed num_lines

-value must be at least max_v_samp_factor*DCTSIZE, and the return value will

-be exactly that amount (or possibly some multiple of that amount, in future

-library versions).  This is true even on the last call at the bottom of the

-image; don't forget to pad your data as necessary.

-

-The required dimensions of the supplied data can be computed for each

-component as

-        cinfo->comp_info[i].width_in_blocks*DCTSIZE  samples per row

-        cinfo->comp_info[i].height_in_blocks*DCTSIZE rows in image

-after jpeg_start_compress() has initialized those fields.  If the valid data

-is smaller than this, it must be padded appropriately.  For some sampling

-factors and image sizes, additional dummy DCT blocks are inserted to make

-the image a multiple of the MCU dimensions.  The library creates such dummy

-blocks itself; it does not read them from your supplied data.  Therefore you

-need never pad by more than DCTSIZE samples.  An example may help here.

-Assume 2h2v downsampling of YCbCr data, that is

-        cinfo->comp_info[0].h_samp_factor = 2           for Y

-        cinfo->comp_info[0].v_samp_factor = 2

-        cinfo->comp_info[1].h_samp_factor = 1           for Cb

-        cinfo->comp_info[1].v_samp_factor = 1

-        cinfo->comp_info[2].h_samp_factor = 1           for Cr

-        cinfo->comp_info[2].v_samp_factor = 1

-and suppose that the nominal image dimensions (cinfo->image_width and

-cinfo->image_height) are 101x101 pixels.  Then jpeg_start_compress() will

-compute downsampled_width = 101 and width_in_blocks = 13 for Y,

-downsampled_width = 51 and width_in_blocks = 7 for Cb and Cr (and the same

-for the height fields).  You must pad the Y data to at least 13*8 = 104

-columns and rows, the Cb/Cr data to at least 7*8 = 56 columns and rows.  The

-MCU height is max_v_samp_factor = 2 DCT rows so you must pass at least 16

-scanlines on each call to jpeg_write_raw_data(), which is to say 16 actual

-sample rows of Y and 8 each of Cb and Cr.  A total of 7 MCU rows are needed,

-so you must pass a total of 7*16 = 112 "scanlines".  The last DCT block row

-of Y data is dummy, so it doesn't matter what you pass for it in the data

-arrays, but the scanlines count must total up to 112 so that all of the Cb

-and Cr data gets passed.

-

-Output suspension is supported with raw-data compression: if the data

-destination module suspends, jpeg_write_raw_data() will return 0.

-In this case the same data rows must be passed again on the next call.

-

-

-Decompression with raw data output implies bypassing all postprocessing.

-You must deal with the color space and sampling factors present in the

-incoming file.  If your application only handles, say, 2h1v YCbCr data,

-you must check for and fail on other color spaces or other sampling factors.

-The library will not convert to a different color space for you.

-

-To obtain raw data output, set cinfo->raw_data_out = TRUE before

-jpeg_start_decompress() (it is set FALSE by jpeg_read_header()).  Be sure to

-verify that the color space and sampling factors are ones you can handle.

-Furthermore, set cinfo->do_fancy_upsampling = FALSE if you want to get real

-downsampled data (it is set TRUE by jpeg_read_header()).

-Then call jpeg_read_raw_data() in place of jpeg_read_scanlines().  The

-decompression process is otherwise the same as usual.

-

-jpeg_read_raw_data() returns one MCU row per call, and thus you must pass a

-buffer of at least max_v_samp_factor*DCTSIZE scanlines (scanline counting is

-the same as for raw-data compression).  The buffer you pass must be large

-enough to hold the actual data plus padding to DCT-block boundaries.  As with

-compression, any entirely dummy DCT blocks are not processed so you need not

-allocate space for them, but the total scanline count includes them.  The

-above example of computing buffer dimensions for raw-data compression is

-equally valid for decompression.

-

-Input suspension is supported with raw-data decompression: if the data source

-module suspends, jpeg_read_raw_data() will return 0.  You can also use

-buffered-image mode to read raw data in multiple passes.

-

-

-Really raw data: DCT coefficients

----------------------------------

-

-It is possible to read or write the contents of a JPEG file as raw DCT

-coefficients.  This facility is mainly intended for use in lossless

-transcoding between different JPEG file formats.  Other possible applications

-include lossless cropping of a JPEG image, lossless reassembly of a

-multi-strip or multi-tile TIFF/JPEG file into a single JPEG datastream, etc.

-

-To read the contents of a JPEG file as DCT coefficients, open the file and do

-jpeg_read_header() as usual.  But instead of calling jpeg_start_decompress()

-and jpeg_read_scanlines(), call jpeg_read_coefficients().  This will read the

-entire image into a set of virtual coefficient-block arrays, one array per

-component.  The return value is a pointer to an array of virtual-array

-descriptors.  Each virtual array can be accessed directly using the JPEG

-memory manager's access_virt_barray method (see Memory management, below,

-and also read structure.txt's discussion of virtual array handling).  Or,

-for simple transcoding to a different JPEG file format, the array list can

-just be handed directly to jpeg_write_coefficients().

-

-Each block in the block arrays contains quantized coefficient values in

-normal array order (not JPEG zigzag order).  The block arrays contain only

-DCT blocks containing real data; any entirely-dummy blocks added to fill out

-interleaved MCUs at the right or bottom edges of the image are discarded

-during reading and are not stored in the block arrays.  (The size of each

-block array can be determined from the width_in_blocks and height_in_blocks

-fields of the component's comp_info entry.)  This is also the data format

-expected by jpeg_write_coefficients().

-

-When you are done using the virtual arrays, call jpeg_finish_decompress()

-to release the array storage and return the decompression object to an idle

-state; or just call jpeg_destroy() if you don't need to reuse the object.

-

-If you use a suspending data source, jpeg_read_coefficients() will return

-NULL if it is forced to suspend; a non-NULL return value indicates successful

-completion.  You need not test for a NULL return value when using a

-non-suspending data source.

-

-It is also possible to call jpeg_read_coefficients() to obtain access to the

-decoder's coefficient arrays during a normal decode cycle in buffered-image

-mode.  This frammish might be useful for progressively displaying an incoming

-image and then re-encoding it without loss.  To do this, decode in buffered-

-image mode as discussed previously, then call jpeg_read_coefficients() after

-the last jpeg_finish_output() call.  The arrays will be available for your use

-until you call jpeg_finish_decompress().

-

-

-To write the contents of a JPEG file as DCT coefficients, you must provide

-the DCT coefficients stored in virtual block arrays.  You can either pass

-block arrays read from an input JPEG file by jpeg_read_coefficients(), or

-allocate virtual arrays from the JPEG compression object and fill them

-yourself.  In either case, jpeg_write_coefficients() is substituted for

-jpeg_start_compress() and jpeg_write_scanlines().  Thus the sequence is

-  * Create compression object

-  * Set all compression parameters as necessary

-  * Request virtual arrays if needed

-  * jpeg_write_coefficients()

-  * jpeg_finish_compress()

-  * Destroy or re-use compression object

-jpeg_write_coefficients() is passed a pointer to an array of virtual block

-array descriptors; the number of arrays is equal to cinfo.num_components.

-

-The virtual arrays need only have been requested, not realized, before

-jpeg_write_coefficients() is called.  A side-effect of

-jpeg_write_coefficients() is to realize any virtual arrays that have been

-requested from the compression object's memory manager.  Thus, when obtaining

-the virtual arrays from the compression object, you should fill the arrays

-after calling jpeg_write_coefficients().  The data is actually written out

-when you call jpeg_finish_compress(); jpeg_write_coefficients() only writes

-the file header.

-

-When writing raw DCT coefficients, it is crucial that the JPEG quantization

-tables and sampling factors match the way the data was encoded, or the

-resulting file will be invalid.  For transcoding from an existing JPEG file,

-we recommend using jpeg_copy_critical_parameters().  This routine initializes

-all the compression parameters to default values (like jpeg_set_defaults()),

-then copies the critical information from a source decompression object.

-The decompression object should have just been used to read the entire

-JPEG input file --- that is, it should be awaiting jpeg_finish_decompress().

-

-jpeg_write_coefficients() marks all tables stored in the compression object

-as needing to be written to the output file (thus, it acts like

-jpeg_start_compress(cinfo, TRUE)).  This is for safety's sake, to avoid

-emitting abbreviated JPEG files by accident.  If you really want to emit an

-abbreviated JPEG file, call jpeg_suppress_tables(), or set the tables'

-individual sent_table flags, between calling jpeg_write_coefficients() and

-jpeg_finish_compress().

-

-

-Progress monitoring

--------------------

-

-Some applications may need to regain control from the JPEG library every so

-often.  The typical use of this feature is to produce a percent-done bar or

-other progress display.  (For a simple example, see cjpeg.c or djpeg.c.)

-Although you do get control back frequently during the data-transferring pass

-(the jpeg_read_scanlines or jpeg_write_scanlines loop), any additional passes

-will occur inside jpeg_finish_compress or jpeg_start_decompress; those

-routines may take a long time to execute, and you don't get control back

-until they are done.

-

-You can define a progress-monitor routine which will be called periodically

-by the library.  No guarantees are made about how often this call will occur,

-so we don't recommend you use it for mouse tracking or anything like that.

-At present, a call will occur once per MCU row, scanline, or sample row

-group, whichever unit is convenient for the current processing mode; so the

-wider the image, the longer the time between calls.  During the data

-transferring pass, only one call occurs per call of jpeg_read_scanlines or

-jpeg_write_scanlines, so don't pass a large number of scanlines at once if

-you want fine resolution in the progress count.  (If you really need to use

-the callback mechanism for time-critical tasks like mouse tracking, you could

-insert additional calls inside some of the library's inner loops.)

-

-To establish a progress-monitor callback, create a struct jpeg_progress_mgr,

-fill in its progress_monitor field with a pointer to your callback routine,

-and set cinfo->progress to point to the struct.  The callback will be called

-whenever cinfo->progress is non-NULL.  (This pointer is set to NULL by

-jpeg_create_compress or jpeg_create_decompress; the library will not change

-it thereafter.  So if you allocate dynamic storage for the progress struct,

-make sure it will live as long as the JPEG object does.  Allocating from the

-JPEG memory manager with lifetime JPOOL_PERMANENT will work nicely.)  You

-can use the same callback routine for both compression and decompression.

-

-The jpeg_progress_mgr struct contains four fields which are set by the library:

-        long pass_counter;      /* work units completed in this pass */

-        long pass_limit;        /* total number of work units in this pass */

-        int completed_passes;   /* passes completed so far */

-        int total_passes;       /* total number of passes expected */

-During any one pass, pass_counter increases from 0 up to (not including)

-pass_limit; the step size is usually but not necessarily 1.  The pass_limit

-value may change from one pass to another.  The expected total number of

-passes is in total_passes, and the number of passes already completed is in

-completed_passes.  Thus the fraction of work completed may be estimated as

-                completed_passes + (pass_counter/pass_limit)

-                --------------------------------------------

-                                total_passes

-ignoring the fact that the passes may not be equal amounts of work.

-

-When decompressing, pass_limit can even change within a pass, because it

-depends on the number of scans in the JPEG file, which isn't always known in

-advance.  The computed fraction-of-work-done may jump suddenly (if the library

-discovers it has overestimated the number of scans) or even decrease (in the

-opposite case).  It is not wise to put great faith in the work estimate.

-

-When using the decompressor's buffered-image mode, the progress monitor work

-estimate is likely to be completely unhelpful, because the library has no way

-to know how many output passes will be demanded of it.  Currently, the library

-sets total_passes based on the assumption that there will be one more output

-pass if the input file end hasn't yet been read (jpeg_input_complete() isn't

-TRUE), but no more output passes if the file end has been reached when the

-output pass is started.  This means that total_passes will rise as additional

-output passes are requested.  If you have a way of determining the input file

-size, estimating progress based on the fraction of the file that's been read

-will probably be more useful than using the library's value.

-

-

-Memory management

------------------

-

-This section covers some key facts about the JPEG library's built-in memory

-manager.  For more info, please read structure.txt'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; so a reasonable safety margin

-should be left when setting max_memory_to_use.

-

-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 or jmemmac.c either,

-since the C library is supposed to take care of deleting files made with

-tmpfile().

-

-

-Memory usage

-------------

-

-Working memory requirements while performing compression or decompression

-depend on image dimensions, image characteristics (such as colorspace and

-JPEG process), and operating mode (application-selected options).

-

-As of v6b, the decompressor requires:

- 1. About 24K in more-or-less-fixed-size data.  This varies a bit depending

-    on operating mode and image characteristics (particularly color vs.

-    grayscale), but it doesn't depend on image dimensions.

- 2. Strip buffers (of size proportional to the image width) for IDCT and

-    upsampling results.  The worst case for commonly used sampling factors

-    is about 34 bytes * width in pixels for a color image.  A grayscale image

-    only needs about 8 bytes per pixel column.

- 3. A full-image DCT coefficient buffer is needed to decode a multi-scan JPEG

-    file (including progressive JPEGs), or whenever you select buffered-image

-    mode.  This takes 2 bytes/coefficient.  At typical 2x2 sampling, that's

-    3 bytes per pixel for a color image.  Worst case (1x1 sampling) requires

-    6 bytes/pixel.  For grayscale, figure 2 bytes/pixel.

- 4. To perform 2-pass color quantization, the decompressor also needs a

-    128K color lookup table and a full-image pixel buffer (3 bytes/pixel).

-This does not count any memory allocated by the application, such as a

-buffer to hold the final output image.

-

-The above figures are valid for 8-bit JPEG data precision and a machine with

-32-bit ints.  For 12-bit JPEG data, double the size of the strip buffers and

-quantization pixel buffer.  The "fixed-size" data will be somewhat smaller

-with 16-bit ints, larger with 64-bit ints.  Also, CMYK or other unusual

-color spaces will require different amounts of space.

-

-The full-image coefficient and pixel buffers, if needed at all, do not

-have to be fully RAM resident; you can have the library use temporary

-files instead when the total memory usage would exceed a limit you set.

-(But if your OS supports virtual memory, it's probably better to just use

-jmemnobs and let the OS do the swapping.)

-

-The compressor's memory requirements are similar, except that it has no need

-for color quantization.  Also, it needs a full-image DCT coefficient buffer

-if Huffman-table optimization is asked for, even if progressive mode is not

-requested.

-

-If you need more detailed information about memory usage in a particular

-situation, you can enable the MEM_STATS code in jmemmgr.c.

-

-

-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.  The IJG code supports 12-bit JPEG 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.

-The sample applications cjpeg and djpeg can support 12-bit mode only for PPM

-and GIF file formats; you must disable the other file formats to compile a

-12-bit cjpeg or djpeg.  (install.txt has more information about that.)

-At present, a 12-bit library can handle *only* 12-bit images, not both

-precisions.  (If you need to include both 8- and 12-bit libraries in a single

-application, you could probably do it by defining NEED_SHORT_EXTERNAL_NAMES

-for just one of the copies.  You'd have to access the 8-bit and 12-bit copies

-from separate application source files.  This is untested ... if you try it,

-we'd like to hear whether it works!)

-

-Note that a 12-bit library always compresses in Huffman optimization mode,

-in order to generate valid Huffman tables.  This is necessary because our

-default Huffman tables only cover 8-bit data.  If you need to output 12-bit

-files in one pass, you'll have to supply suitable default Huffman tables.

-You may also want to supply your own DCT quantization tables; the existing

-quality-scaling code has been developed for 8-bit use, and probably doesn't

-generate especially good tables for 12-bit.

-

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

-

-You can also save a few K by not having text error messages in the library;

-the standard error message table occupies about 5Kb.  This is particularly

-reasonable for embedded applications where there's no good way to display 

-a message anyway.  To do this, remove the creation of the message table

-(jpeg_std_message_table[]) from jerror.c, and alter format_message to do

-something reasonable without it.  You could output the numeric value of the

-message code number, for example.  If you do this, you can also save a couple

-more K by modifying the TRACEMSn() macros in jerror.h to expand to nothing;

-you don't need trace capability anyway, right?

-

-

-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 ANSI C, C++, and pre-ANSI C compilers, using any of

-the popular system include file setups, and some not-so-popular ones too.

-See install.txt 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.txt,

-jmorecfg.h, and jinclude.h.

-

-

-Notes for MS-DOS implementors

------------------------------

-

-The IJG code is designed to work efficiently in 80x86 "small" or "medium"

-memory models (i.e., data pointers are 16 bits unless explicitly declared

-"far"; code pointers can be either size).  You may be able to use small

-model to compile cjpeg or djpeg by itself, but you will probably have to use

-medium model for any larger application.  This won't make much difference in

-performance.  You *will* take a noticeable performance hit if you use a

-large-data memory model (perhaps 10%-25%), and you should avoid "huge" model

-if at all possible.

-

-The JPEG library typically needs 2Kb-3Kb of stack space.  It will also

-malloc about 20K-30K of near heap space while executing (and lots of far

-heap, but that doesn't count in this calculation).  This figure will vary

-depending on selected operating mode, and to a lesser extent on image size.

-There is also about 5Kb-6Kb of constant data which will be allocated in the

-near data segment (about 4Kb of this is the error message table).

-Thus you have perhaps 20K available for other modules' static data and near

-heap space 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.  Another possibility is to move the error message table to far memory;

-this should be doable with only localized hacking on jerror.c.)

-

-About 2K of the near heap space is "permanent" memory that will not be

-released until you destroy the JPEG object.  This is only an issue if you

-save a JPEG object between compression or decompression operations.

-

-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 40 bytes per column for typical sampling ratios (eg, about 25600

-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 32-bit flat-memory-model

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

+USING THE IJG JPEG LIBRARY
+
+Copyright (C) 1994-2011, Thomas G. Lane, Guido Vollbeding.
+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
+        Progressive JPEG support
+        Buffered-image mode
+        Abbreviated datastreams and multiple images
+        Special markers
+        Raw (downsampled) image data
+        Really raw data: DCT coefficients
+        Progress monitoring
+        Memory management
+        Memory usage
+        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, extended-sequential, and progressive
+JPEG processes are supported.  (Our subset includes all features now in common
+use.)  Unsupported ISO options include:
+        * Hierarchical storage
+        * Lossless JPEG
+        * 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, this library is
+used by the free LIBTIFF library to support JPEG compression in TIFF.)
+
+
+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.  This is helpful because 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.  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" or "sample" 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).
+PLEASE NOTE THAT RGB DATA IS THREE SAMPLES PER PIXEL, GRAYSCALE ONLY ONE.
+A remarkable number of people manage to miss this, only to find that their
+programs don't work with grayscale JPEG files.
+
+There is no provision for colormapped input.  JPEG files are always full-color
+or full grayscale (or sometimes another colorspace such as CMYK).  You can
+feed in a colormapped image by expanding it to full-color format.  However
+JPEG often doesn't work very well with source data that has been colormapped,
+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.  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 typically "unsigned char", unless
+you've changed jmorecfg.h.  (You can also change the RGB pixel layout, say
+to B,G,R order, by modifying jmorecfg.h.  But see the restrictions listed in
+that file before doing so.)
+
+A 2-D array of pixels is formed by making a list of pointers to the starts of
+scanlines; so the scanlines need not be physically adjacent in memory.  Even
+if you process just one scanline at a time, you must make a one-element
+pointer array to conform to this structure.  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 simplest 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 output is supported.  (Again, a JPEG file is never
+colormapped.  But you can ask the decompressor to perform on-the-fly color
+quantization to deliver colormapped output.)  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".  (It also has
+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;
+that's why the error handler must be initialized first.
+
+
+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 must be
+assigned one of the J_COLOR_SPACE enum constants, typically 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, below.
+
+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) afterwards.
+
+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 (regardless of
+the previous state of the object).  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, jpeg_destroy()
+should be passed a j_common_ptr.)
+
+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 call
+  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; neither of these routines will call term_destination().
+(See "Compressed data handling", below, for more about that.)
+
+jpeg_destroy() and jpeg_abort() are the only safe calls to make on a JPEG
+object that has reported an error by calling error_exit (see "Error handling"
+for more info).  The internal state of such an object is likely to be out of
+whack.  Either of these two routines will return the object to a known state.
+
+
+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 set desired 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 (non progressive) 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.  Don't forget that grayscale and color JPEGs will return
+different data formats!
+
+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.)
+The return value always equals the change in the value of output_scanline.
+
+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.  (The current implementation returns only a
+few scanlines per call, no matter how large a buffer you pass.)  So you must
+always provide a loop that calls jpeg_read_scanlines() repeatedly until the
+whole image has been read.
+
+
+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 decompression, 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.
+
+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.
+The supplied makefiles build libjpeg.a automatically (see install.txt).
+
+While you can build the JPEG library as a shared library if the whim strikes
+you, we don't really recommend it.  The trouble with shared libraries is that
+at some point you'll probably try to substitute a new version of the library
+without recompiling the calling applications.  That generally doesn't work
+because the parameter struct declarations usually change with each new
+version.  In other words, the library's API is *not* guaranteed binary
+compatible across versions; we only try to ensure source-code compatibility.
+(In hindsight, it might have been smarter to hide the parameter structs from
+applications and introduce a ton of access functions instead.  Too late now,
+however.)
+
+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.
+
+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 and use jmemnobs.c (or another memory manager of
+your own devising).  More info about the minimum system library requirements
+may be found in jinclude.h.
+
+
+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_default_colorspace (j_compress_ptr cinfo)
+        Selects an appropriate JPEG colorspace based on cinfo->in_color_space,
+        and calls jpeg_set_colorspace().  This is actually a subroutine of
+        jpeg_set_defaults().  It's broken out in case you want to change
+        just the colorspace-dependent JPEG parameters.
+
+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 scaling method that
+        can't be expressed as a simple scalar multiplier, in which case the
+        premise of this routine collapses.  Caveat user.
+
+jpeg_default_qtables (j_compress_ptr cinfo, boolean force_baseline)
+        Set default quantization tables with linear q_scale_factor[] values
+        (see below).
+
+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 normal array 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).
+        CAUTION: prior to library version 6a, jpeg_add_quant_table expected
+        the basic table to be given in JPEG zigzag order.  If you need to
+        write code that works with either older or newer versions of this
+        routine, you must check the library version number.  Something like
+        "#if JPEG_LIB_VERSION >= 61" is the right test.
+
+jpeg_simple_progression (j_compress_ptr cinfo)
+        Generates a default scan script for writing a progressive-JPEG file.
+        This is the recommended method of creating a progressive file,
+        unless you want to make a custom scan sequence.  You must ensure that
+        the JPEG color space is set correctly before calling this routine.
+
+
+Compression parameters (cinfo fields) include:
+
+int block_size
+        Set DCT block size.  All N from 1 to 16 are possible.
+        Default is 8 (baseline format).
+        Larger values produce higher compression,
+        smaller values produce higher quality.
+        An exact DCT stage is possible with 1 or 2.
+        With the default quality of 75 and default Luminance qtable
+        the DCT+Quantization stage is lossless for value 1.
+        Note that values other than 8 require a SmartScale capable decoder,
+        introduced with IJG JPEG 8.  Setting the block_size parameter for
+        compression works with version 8c and later.
+
+J_DCT_METHOD dct_method
+        Selects the algorithm used for the DCT step.  Choices are:
+                JDCT_ISLOW: slow but accurate integer algorithm
+                JDCT_IFAST: faster, less accurate integer method
+                JDCT_FLOAT: floating-point method
+                JDCT_DEFAULT: default method (normally JDCT_ISLOW)
+                JDCT_FASTEST: fastest method (normally JDCT_IFAST)
+        The FLOAT method is very slightly more accurate than the ISLOW method,
+        but may give different results on different machines due to varying
+        roundoff behavior.  The integer methods should give the same results
+        on all machines.  On machines with sufficiently fast FP hardware, the
+        floating-point method may also be the fastest.  The IFAST method is
+        considerably less accurate than the other two; its use is not
+        recommended if high quality is a concern.  JDCT_DEFAULT and
+        JDCT_FASTEST are macros configurable by each installation.
+
+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 supported scaling ratios are
+        M/N with all N from 1 to 16, where M is the destination DCT size,
+        which is 8 by default (see block_size parameter above).
+        (The library design allows for arbitrary scaling ratios but this
+        is not likely to be implemented any time soon.)
+
+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 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.
+
+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.)  Defaults are zero (no restarts).
+        One restart marker per MCU row is often a good choice.
+        NOTE: the overhead of restart markers is higher in grayscale JPEG
+        files than in color files, and MUCH higher in progressive JPEGs.
+        If you use restarts, you may want to use larger intervals in those
+        cases.
+
+const jpeg_scan_info * scan_info
+int num_scans
+        By default, scan_info is NULL; this causes the compressor to write a
+        single-scan sequential JPEG file.  If not NULL, scan_info points to
+        an array of scan definition records of length num_scans.  The
+        compressor will then write a JPEG file having one scan for each scan
+        definition record.  This is used to generate noninterleaved or
+        progressive JPEG files.  The library checks that the scan array
+        defines a valid JPEG scan sequence.  (jpeg_simple_progression creates
+        a suitable scan definition array for progressive JPEG.)  This is
+        discussed further under "Progressive JPEG support".
+
+boolean do_fancy_downsampling
+        If TRUE, use direct DCT scaling with DCT size > 8 for downsampling
+        of chroma components.
+        If FALSE, use only DCT size <= 8 and simple separate downsampling.
+        Default is TRUE.
+        For better image stability in multiple generation compression cycles
+        it is preferable that this value matches the corresponding
+        do_fancy_upsampling value in decompression.
+
+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.  The default is zero.
+
+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 JFIF_major_version
+UINT8 JFIF_minor_version
+        The version number to be written into the JFIF marker.
+        jpeg_set_defaults() initializes the version to 1.01 (major=minor=1).
+        You should set it to 1.02 (major=1, minor=2) if you plan to write
+        any JFIF 1.02 extension markers.
+
+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.
+
+int q_scale_factor[NUM_QUANT_TBLS]
+        Linear quantization scaling factors (percentage, initialized 100)
+        for use with jpeg_default_qtables().
+        See rdswitch.c and cjpeg.c for an example of usage.
+        Note that the q_scale_factor[] fields are the "linear" scales, so you
+        have to convert from user-defined ratings via jpeg_quality_scaling().
+        Here is an example code which corresponds to cjpeg -quality 90,70:
+
+                jpeg_set_defaults(cinfo);
+
+                /* Set luminance quality 90. */
+                cinfo->q_scale_factor[0] = jpeg_quality_scaling(90);
+                /* Set chrominance quality 70. */
+                cinfo->q_scale_factor[1] = jpeg_quality_scaling(70);
+
+                jpeg_default_qtables(cinfo, force_baseline);
+
+        CAUTION: You must also set 1x1 subsampling for efficient separate
+        color quality selection, since the default value used by library
+        is 2x2:
+
+                cinfo->comp_info[0].v_samp_factor = 1;
+                cinfo->comp_info[0].h_samp_factor = 1;
+
+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 need to allocate
+        more table structures, jpeg_alloc_huff_table() may be used.
+        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.
+
+
+The actual dimensions of the JPEG image that will be written to the file are
+given by the following fields.  These are computed from the input image
+dimensions and the compression parameters by jpeg_start_compress().  You can
+also call jpeg_calc_jpeg_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.
+
+JDIMENSION jpeg_width           Actual dimensions of output image.
+JDIMENSION jpeg_height
+
+
+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[].  (Beginning in
+        release v6, the compressor library will fill this in automatically;
+        you don't have to.)
+
+
+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 JFIF_major_version              Version information from JFIF marker
+  UINT8 JFIF_minor_version
+  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 determine the basic properties of the
+returned image 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 change this field to request output in a different
+        colorspace.  For example, set it to JCS_GRAYSCALE to get grayscale
+        output from a color file.  (This is useful for previewing: 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.  Currently,
+        the supported scaling ratios are M/N with all M from 1 to 16, where
+        N is the source DCT size, which is 8 for baseline JPEG.  (The library
+        design allows for arbitrary scaling ratios but this is not likely
+        to be implemented any time soon.)  The values are initialized by
+        jpeg_read_header() with the source DCT size.  For baseline JPEG
+        this is 8/8.  If you change only the scale_num value while leaving
+        the other unchanged, then this specifies the DCT scaled size to be
+        applied on the given input.  For baseline JPEG this is equivalent
+        to M/8 scaling, since the source DCT size for baseline JPEG is 8.
+        Smaller scaling ratios permit significantly faster decoding since
+        fewer pixels need be processed and a simpler IDCT method can be used.
+
+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.
+
+J_DITHER_MODE dither_mode
+        Selects color dithering method.  Supported values are:
+                JDITHER_NONE    no dithering: fast, very low quality
+                JDITHER_ORDERED ordered dither: moderate speed and quality
+                JDITHER_FS      Floyd-Steinberg dither: slow, high quality
+        Default is JDITHER_FS.  (At present, ordered dither is implemented
+        only in the single-pass, standard-colormap case.  If you ask for
+        ordered dither when two_pass_quantize is TRUE or when you supply
+        an external color map, you'll get F-S dithering.)
+
+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 suitable color map and sets these two fields itself.
+[Implementation restriction: at present, an externally supplied colormap is
+only accepted for 3-component output color spaces.]
+
+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.
+        CAUTION: if the JPEG library creates its own colormap, the storage
+        pointed to by this field is released by jpeg_finish_decompress().
+        Copy the colormap somewhere else first, if you want to save it.
+
+int actual_number_of_colors
+        The number of colors in the color map.
+
+Additional decompression parameters that the application may set include:
+
+J_DCT_METHOD dct_method
+        Selects the algorithm used for the DCT step.  Choices are the same
+        as described above for compression.
+
+boolean do_fancy_upsampling
+        If TRUE, use direct DCT scaling with DCT size > 8 for upsampling
+        of chroma components.
+        If FALSE, use only DCT size <= 8 and simple separate upsampling.
+        Default is TRUE.
+        For better image stability in multiple generation compression cycles
+        it is preferable that this value matches the corresponding
+        do_fancy_downsampling value in compression.
+
+boolean do_block_smoothing
+        If TRUE, interblock smoothing is applied in early stages of decoding
+        progressive JPEG files; if FALSE, not.  Default is TRUE.  Early
+        progression stages look "fuzzy" with smoothing, "blocky" without.
+        In any case, block smoothing ceases to be applied after the first few
+        AC coefficients are known to full accuracy, so it is relevant only
+        when using buffered-image mode for progressive images.
+
+boolean enable_1pass_quant
+boolean enable_external_quant
+boolean enable_2pass_quant
+        These are significant only in buffered-image mode, which is
+        described in its own section below.
+
+
+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 time will be wasted due to unnecessary data
+copying.  In high-quality modes, rec_outbuf_height is always 1, but some
+faster, lower-quality modes set it to larger values (typically 2 to 4).
+If you are going to ask for a high-speed processing mode, you may as well
+go to the trouble of honoring rec_outbuf_height so as to avoid data copying.
+(An output buffer larger than rec_outbuf_height lines is OK, but won't
+provide any material speed improvement over that height.)
+
+
+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 => RGB
+        YCbCr => GRAYSCALE
+        RGB => GRAYSCALE
+        GRAYSCALE => RGB
+        YCCK => CMYK
+as well as the null transforms.  (Since GRAYSCALE=>RGB is provided, an
+application can force grayscale JPEGs to look like color JPEGs if it only
+wants to handle one case.)
+
+The two-pass color quantizer, jquant2.c, is specialized to handle RGB data
+(it weights distances appropriately for RGB colors).  You'll need to modify
+the code if you want to use it for non-RGB output color spaces.  Note that
+jquant2.c is used to map to an application-supplied colormap as well as for
+the normal two-pass colormap selection process.
+
+CAUTION: it appears that Adobe Photoshop writes inverted data in CMYK JPEG
+files: 0 represents 100% ink coverage, rather than 0% ink as you'd expect.
+This is arguably a bug in Photoshop, but if you need to work with Photoshop
+CMYK files, you will have to deal with it in your application.  We cannot
+"fix" this in the library by inverting the data during the CMYK<=>YCCK
+transform, because that would break other applications, notably Ghostscript.
+Photoshop versions prior to 3.0 write EPS files containing JPEG-encoded CMYK
+data in the same inverted-YCCK representation used in bare JPEG files, but
+the surrounding PostScript code performs an inversion using the PS image
+operator.  I am told that Photoshop 3.0 will write uninverted YCCK in
+EPS/JPEG files, and will omit the PS-level inversion.  (But the data
+polarity used in bare JPEG files will not change in 3.0.)  In either case,
+the JPEG library must not invert the data itself, or else Ghostscript would
+read these EPS files incorrectly.
+
+
+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.  (Beginning
+with IJG version 6b, there is also a void pointer "client_data" in each
+JPEG object, which the application can also use to find related data.
+The library does not touch client_data at all.)
+
+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
+memory buffer or 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 memory
+buffer or 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, the memory
+source manager just makes the buffer pointer and length point to the original
+data in memory.  In this case the buffer-reload procedure will 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() or jpeg_mem_dest() routines of the supplied destination
+managers.
+
+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, int desired)
+        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() or jpeg_mem_src() routines of the supplied source managers.
+
+For more information, consult the memory and 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 emptied 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 not a panacea: nothing is guaranteed about the
+maximum amount of time spent in any one call to the library, so it will not
+eliminate response-time problems in single-threaded applications.  If you
+need 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 previous 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 output
+buffer 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 write out the entire buffer
+after a suspension.  Write 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 compressor does not allow 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, without flushing the buffer afterwards.
+  * 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().
+
+A more significant restriction is that jpeg_finish_compress() cannot suspend.
+This means you cannot use suspension with multi-pass operating modes, namely
+Huffman code optimization and multiple-scan output.  Those modes write the
+whole file during jpeg_finish_compress(), which will certainly result in
+buffer overrun.  (Note that this restriction applies only to compression,
+not decompression.  The decompressor supports input suspension in all of its
+operating modes.)
+
+Decompression suspension:
+
+For decompression suspension, use a fill_input_buffer() routine that simply
+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 four places:
+  * jpeg_read_header(): will return JPEG_SUSPENDED.
+  * jpeg_start_decompress(): will return FALSE, rather than its usual TRUE.
+  * 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(),
+increment the passed pointers past any scanlines successfully read.
+
+Just as with compression, the decompressor will typically backtrack to a
+convenient restart point before suspending.  When fill_input_buffer() is
+called, next_input_byte/bytes_in_buffer point to the current restart point,
+which is where the decompressor will backtrack to if FALSE is returned.
+The data beyond that position must NOT be discarded if you suspend; it needs
+to 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 should return FALSE, which will cause a
+suspension return.  The surrounding application must then arrange to discard
+the recorded 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
+though it had read more data in a non-suspending situation.
+
+The decompressor does not attempt to suspend within standard JPEG markers;
+instead it will backtrack to the start of the marker and reprocess the whole
+marker next time.  Hence the input buffer must be large enough to hold the
+longest standard marker in the file.  Standard JPEG markers should normally
+not exceed a few hundred bytes each (DHT tables are typically the longest).
+We recommend at least a 2K buffer for performance reasons, which is much
+larger than any correct marker is likely to be.  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.  (The library can't
+provide this test since it has no idea whether "the buffer is full", or
+even whether there is a fixed-size input buffer.)
+
+The input buffer would need to be 64K to allow for arbitrary COM or APPn
+markers, but these are handled specially: they are either saved into allocated
+memory, or skipped over by calling skip_input_data().  In the former case,
+suspension is handled correctly, and in the latter case, the problem of
+buffer overrun is placed on skip_input_data's shoulders, as explained above.
+Note that if you provide your own marker handling routine for large markers,
+you should consider how to deal with buffer overflow.
+
+Multiple-buffer management:
+
+In some applications it is desirable to store the compressed data in a linked
+list of buffer areas, so as to avoid data copying.  This can be handled by
+having empty_output_buffer() or fill_input_buffer() set the pointer and count
+to reference the next available buffer; FALSE is returned only if no more
+buffers are available.  Although seemingly straightforward, there is a
+pitfall in this approach: the backtrack that occurs when FALSE is returned
+could back up into an earlier buffer.  For example, when fill_input_buffer()
+is called, the current pointer & count indicate the backtrack restart point.
+Since fill_input_buffer() will set the pointer and count to refer to a new
+buffer, the restart position must be saved somewhere else.  Suppose a second
+call to fill_input_buffer() occurs in the same library call, and no
+additional input data is available, so fill_input_buffer must return FALSE.
+If the JPEG library has not moved the pointer/count forward in the current
+buffer, then *the correct restart point is the saved position in the prior
+buffer*.  Prior buffers may be discarded only after the library establishes
+a restart point within a later buffer.  Similar remarks apply for output into
+a chain of buffers.
+
+The library will never attempt to backtrack over a skip_input_data() call,
+so any skipped data can be permanently discarded.  You still have to deal
+with the case of skipping not-yet-received data, however.
+
+It's much simpler to use only a single buffer; when fill_input_buffer() is
+called, move any unconsumed data (beyond the current pointer/count) down to
+the beginning of this buffer and then load new data into the remaining buffer
+space.  This approach requires a little more data copying but is far easier
+to get right.
+
+
+Progressive JPEG support
+------------------------
+
+Progressive JPEG rearranges the stored data into a series of scans of
+increasing quality.  In situations where a JPEG file is transmitted across a
+slow communications link, a decoder can generate a low-quality image very
+quickly from the first scan, then gradually improve the displayed quality as
+more scans are received.  The final image after all scans are complete is
+identical to that of a regular (sequential) JPEG file of the same quality
+setting.  Progressive JPEG files are often slightly smaller than equivalent
+sequential JPEG files, but the possibility of incremental display is the main
+reason for using progressive JPEG.
+
+The IJG encoder library generates progressive JPEG files when given a
+suitable "scan script" defining how to divide the data into scans.
+Creation of progressive JPEG files is otherwise transparent to the encoder.
+Progressive JPEG files can also be read transparently by the decoder library.
+If the decoding application simply uses the library as defined above, it
+will receive a final decoded image without any indication that the file was
+progressive.  Of course, this approach does not allow incremental display.
+To perform incremental display, an application needs to use the decoder
+library's "buffered-image" mode, in which it receives a decoded image
+multiple times.
+
+Each displayed scan requires about as much work to decode as a full JPEG
+image of the same size, so the decoder must be fairly fast in relation to the
+data transmission rate in order to make incremental display useful.  However,
+it is possible to skip displaying the image and simply add the incoming bits
+to the decoder's coefficient buffer.  This is fast because only Huffman
+decoding need be done, not IDCT, upsampling, colorspace conversion, etc.
+The IJG decoder library allows the application to switch dynamically between
+displaying the image and simply absorbing the incoming bits.  A properly
+coded application can automatically adapt the number of display passes to
+suit the time available as the image is received.  Also, a final
+higher-quality display cycle can be performed from the buffered data after
+the end of the file is reached.
+
+Progressive compression:
+
+To create a progressive JPEG file (or a multiple-scan sequential JPEG file),
+set the scan_info cinfo field to point to an array of scan descriptors, and
+perform compression as usual.  Instead of constructing your own scan list,
+you can call the jpeg_simple_progression() helper routine to create a
+recommended progression sequence; this method should be used by all
+applications that don't want to get involved in the nitty-gritty of
+progressive scan sequence design.  (If you want to provide user control of
+scan sequences, you may wish to borrow the scan script reading code found
+in rdswitch.c, so that you can read scan script files just like cjpeg's.)
+When scan_info is not NULL, the compression library will store DCT'd data
+into a buffer array as jpeg_write_scanlines() is called, and will emit all
+the requested scans during jpeg_finish_compress().  This implies that
+multiple-scan output cannot be created with a suspending data destination
+manager, since jpeg_finish_compress() does not support suspension.  We
+should also note that the compressor currently forces Huffman optimization
+mode when creating a progressive JPEG file, because the default Huffman
+tables are unsuitable for progressive files.
+
+Progressive decompression:
+
+When buffered-image mode is not used, the decoder library will read all of
+a multi-scan file during jpeg_start_decompress(), so that it can provide a
+final decoded image.  (Here "multi-scan" means either progressive or
+multi-scan sequential.)  This makes multi-scan files transparent to the
+decoding application.  However, existing applications that used suspending
+input with version 5 of the IJG library will need to be modified to check
+for a suspension return from jpeg_start_decompress().
+
+To perform incremental display, an application must use the library's
+buffered-image mode.  This is described in the next section.
+
+
+Buffered-image mode
+-------------------
+
+In buffered-image mode, the library stores the partially decoded image in a
+coefficient buffer, from which it can be read out as many times as desired.
+This mode is typically used for incremental display of progressive JPEG files,
+but it can be used with any JPEG file.  Each scan of a progressive JPEG file
+adds more data (more detail) to the buffered image.  The application can
+display in lockstep with the source file (one display pass per input scan),
+or it can allow input processing to outrun display processing.  By making
+input and display processing run independently, it is possible for the
+application to adapt progressive display to a wide range of data transmission
+rates.
+
+The basic control flow for buffered-image decoding is
+
+        jpeg_create_decompress()
+        set data source
+        jpeg_read_header()
+        set overall decompression parameters
+        cinfo.buffered_image = TRUE;    /* select buffered-image mode */
+        jpeg_start_decompress()
+        for (each output pass) {
+            adjust output decompression parameters if required
+            jpeg_start_output()         /* start a new output pass */
+            for (all scanlines in image) {
+                jpeg_read_scanlines()
+                display scanlines
+            }
+            jpeg_finish_output()        /* terminate output pass */
+        }
+        jpeg_finish_decompress()
+        jpeg_destroy_decompress()
+
+This differs from ordinary unbuffered decoding in that there is an additional
+level of looping.  The application can choose how many output passes to make
+and how to display each pass.
+
+The simplest approach to displaying progressive images is to do one display
+pass for each scan appearing in the input file.  In this case the outer loop
+condition is typically
+        while (! jpeg_input_complete(&cinfo))
+and the start-output call should read
+        jpeg_start_output(&cinfo, cinfo.input_scan_number);
+The second parameter to jpeg_start_output() indicates which scan of the input
+file is to be displayed; the scans are numbered starting at 1 for this
+purpose.  (You can use a loop counter starting at 1 if you like, but using
+the library's input scan counter is easier.)  The library automatically reads
+data as necessary to complete each requested scan, and jpeg_finish_output()
+advances to the next scan or end-of-image marker (hence input_scan_number
+will be incremented by the time control arrives back at jpeg_start_output()).
+With this technique, data is read from the input file only as needed, and
+input and output processing run in lockstep.
+
+After reading the final scan and reaching the end of the input file, the
+buffered image remains available; it can be read additional times by
+repeating the jpeg_start_output()/jpeg_read_scanlines()/jpeg_finish_output()
+sequence.  For example, a useful technique is to use fast one-pass color
+quantization for display passes made while the image is arriving, followed by
+a final display pass using two-pass quantization for highest quality.  This
+is done by changing the library parameters before the final output pass.
+Changing parameters between passes is discussed in detail below.
+
+In general the last scan of a progressive file cannot be recognized as such
+until after it is read, so a post-input display pass is the best approach if
+you want special processing in the final pass.
+
+When done with the image, be sure to call jpeg_finish_decompress() to release
+the buffered image (or just use jpeg_destroy_decompress()).
+
+If input data arrives faster than it can be displayed, the application can
+cause the library to decode input data in advance of what's needed to produce
+output.  This is done by calling the routine jpeg_consume_input().
+The return value is one of the following:
+        JPEG_REACHED_SOS:    reached an SOS marker (the start of a new scan)
+        JPEG_REACHED_EOI:    reached the EOI marker (end of image)
+        JPEG_ROW_COMPLETED:  completed reading one MCU row of compressed data
+        JPEG_SCAN_COMPLETED: completed reading last MCU row of current scan
+        JPEG_SUSPENDED:      suspended before completing any of the above
+(JPEG_SUSPENDED can occur only if a suspending data source is used.)  This
+routine can be called at any time after initializing the JPEG object.  It
+reads some additional data and returns when one of the indicated significant
+events occurs.  (If called after the EOI marker is reached, it will
+immediately return JPEG_REACHED_EOI without attempting to read more data.)
+
+The library's output processing will automatically call jpeg_consume_input()
+whenever the output processing overtakes the input; thus, simple lockstep
+display requires no direct calls to jpeg_consume_input().  But by adding
+calls to jpeg_consume_input(), you can absorb data in advance of what is
+being displayed.  This has two benefits:
+  * You can limit buildup of unprocessed data in your input buffer.
+  * You can eliminate extra display passes by paying attention to the
+    state of the library's input processing.
+
+The first of these benefits only requires interspersing calls to
+jpeg_consume_input() with your display operations and any other processing
+you may be doing.  To avoid wasting cycles due to backtracking, it's best to
+call jpeg_consume_input() only after a hundred or so new bytes have arrived.
+This is discussed further under "I/O suspension", above.  (Note: the JPEG
+library currently is not thread-safe.  You must not call jpeg_consume_input()
+from one thread of control if a different library routine is working on the
+same JPEG object in another thread.)
+
+When input arrives fast enough that more than one new scan is available
+before you start a new output pass, you may as well skip the output pass
+corresponding to the completed scan.  This occurs for free if you pass
+cinfo.input_scan_number as the target scan number to jpeg_start_output().
+The input_scan_number field is simply the index of the scan currently being
+consumed by the input processor.  You can ensure that this is up-to-date by
+emptying the input buffer just before calling jpeg_start_output(): call
+jpeg_consume_input() repeatedly until it returns JPEG_SUSPENDED or
+JPEG_REACHED_EOI.
+
+The target scan number passed to jpeg_start_output() is saved in the
+cinfo.output_scan_number field.  The library's output processing calls
+jpeg_consume_input() whenever the current input scan number and row within
+that scan is less than or equal to the current output scan number and row.
+Thus, input processing can "get ahead" of the output processing but is not
+allowed to "fall behind".  You can achieve several different effects by
+manipulating this interlock rule.  For example, if you pass a target scan
+number greater than the current input scan number, the output processor will
+wait until that scan starts to arrive before producing any output.  (To avoid
+an infinite loop, the target scan number is automatically reset to the last
+scan number when the end of image is reached.  Thus, if you specify a large
+target scan number, the library will just absorb the entire input file and
+then perform an output pass.  This is effectively the same as what
+jpeg_start_decompress() does when you don't select buffered-image mode.)
+When you pass a target scan number equal to the current input scan number,
+the image is displayed no faster than the current input scan arrives.  The
+final possibility is to pass a target scan number less than the current input
+scan number; this disables the input/output interlock and causes the output
+processor to simply display whatever it finds in the image buffer, without
+waiting for input.  (However, the library will not accept a target scan
+number less than one, so you can't avoid waiting for the first scan.)
+
+When data is arriving faster than the output display processing can advance
+through the image, jpeg_consume_input() will store data into the buffered
+image beyond the point at which the output processing is reading data out
+again.  If the input arrives fast enough, it may "wrap around" the buffer to
+the point where the input is more than one whole scan ahead of the output.
+If the output processing simply proceeds through its display pass without
+paying attention to the input, the effect seen on-screen is that the lower
+part of the image is one or more scans better in quality than the upper part.
+Then, when the next output scan is started, you have a choice of what target
+scan number to use.  The recommended choice is to use the current input scan
+number at that time, which implies that you've skipped the output scans
+corresponding to the input scans that were completed while you processed the
+previous output scan.  In this way, the decoder automatically adapts its
+speed to the arriving data, by skipping output scans as necessary to keep up
+with the arriving data.
+
+When using this strategy, you'll want to be sure that you perform a final
+output pass after receiving all the data; otherwise your last display may not
+be full quality across the whole screen.  So the right outer loop logic is
+something like this:
+        do {
+            absorb any waiting input by calling jpeg_consume_input()
+            final_pass = jpeg_input_complete(&cinfo);
+            adjust output decompression parameters if required
+            jpeg_start_output(&cinfo, cinfo.input_scan_number);
+            ...
+            jpeg_finish_output()
+        } while (! final_pass);
+rather than quitting as soon as jpeg_input_complete() returns TRUE.  This
+arrangement makes it simple to use higher-quality decoding parameters
+for the final pass.  But if you don't want to use special parameters for
+the final pass, the right loop logic is like this:
+        for (;;) {
+            absorb any waiting input by calling jpeg_consume_input()
+            jpeg_start_output(&cinfo, cinfo.input_scan_number);
+            ...
+            jpeg_finish_output()
+            if (jpeg_input_complete(&cinfo) &&
+                cinfo.input_scan_number == cinfo.output_scan_number)
+              break;
+        }
+In this case you don't need to know in advance whether an output pass is to
+be the last one, so it's not necessary to have reached EOF before starting
+the final output pass; rather, what you want to test is whether the output
+pass was performed in sync with the final input scan.  This form of the loop
+will avoid an extra output pass whenever the decoder is able (or nearly able)
+to keep up with the incoming data.
+
+When the data transmission speed is high, you might begin a display pass,
+then find that much or all of the file has arrived before you can complete
+the pass.  (You can detect this by noting the JPEG_REACHED_EOI return code
+from jpeg_consume_input(), or equivalently by testing jpeg_input_complete().)
+In this situation you may wish to abort the current display pass and start a
+new one using the newly arrived information.  To do so, just call
+jpeg_finish_output() and then start a new pass with jpeg_start_output().
+
+A variant strategy is to abort and restart display if more than one complete
+scan arrives during an output pass; this can be detected by noting
+JPEG_REACHED_SOS returns and/or examining cinfo.input_scan_number.  This
+idea should be employed with caution, however, since the display process
+might never get to the bottom of the image before being aborted, resulting
+in the lower part of the screen being several passes worse than the upper.
+In most cases it's probably best to abort an output pass only if the whole
+file has arrived and you want to begin the final output pass immediately.
+
+When receiving data across a communication link, we recommend always using
+the current input scan number for the output target scan number; if a
+higher-quality final pass is to be done, it should be started (aborting any
+incomplete output pass) as soon as the end of file is received.  However,
+many other strategies are possible.  For example, the application can examine
+the parameters of the current input scan and decide whether to display it or
+not.  If the scan contains only chroma data, one might choose not to use it
+as the target scan, expecting that the scan will be small and will arrive
+quickly.  To skip to the next scan, call jpeg_consume_input() until it
+returns JPEG_REACHED_SOS or JPEG_REACHED_EOI.  Or just use the next higher
+number as the target scan for jpeg_start_output(); but that method doesn't
+let you inspect the next scan's parameters before deciding to display it.
+
+
+In buffered-image mode, jpeg_start_decompress() never performs input and
+thus never suspends.  An application that uses input suspension with
+buffered-image mode must be prepared for suspension returns from these
+routines:
+* jpeg_start_output() performs input only if you request 2-pass quantization
+  and the target scan isn't fully read yet.  (This is discussed below.)
+* jpeg_read_scanlines(), as always, returns the number of scanlines that it
+  was able to produce before suspending.
+* jpeg_finish_output() will read any markers following the target scan,
+  up to the end of the file or the SOS marker that begins another scan.
+  (But it reads no input if jpeg_consume_input() has already reached the
+  end of the file or a SOS marker beyond the target output scan.)
+* jpeg_finish_decompress() will read until the end of file, and thus can
+  suspend if the end hasn't already been reached (as can be tested by
+  calling jpeg_input_complete()).
+jpeg_start_output(), jpeg_finish_output(), and jpeg_finish_decompress()
+all return TRUE if they completed their tasks, FALSE if they had to suspend.
+In the event of a FALSE return, the application must load more input data
+and repeat the call.  Applications that use non-suspending data sources need
+not check the return values of these three routines.
+
+
+It is possible to change decoding parameters between output passes in the
+buffered-image mode.  The decoder library currently supports only very
+limited changes of parameters.  ONLY THE FOLLOWING parameter changes are
+allowed after jpeg_start_decompress() is called:
+* dct_method can be changed before each call to jpeg_start_output().
+  For example, one could use a fast DCT method for early scans, changing
+  to a higher quality method for the final scan.
+* dither_mode can be changed before each call to jpeg_start_output();
+  of course this has no impact if not using color quantization.  Typically
+  one would use ordered dither for initial passes, then switch to
+  Floyd-Steinberg dither for the final pass.  Caution: changing dither mode
+  can cause more memory to be allocated by the library.  Although the amount
+  of memory involved is not large (a scanline or so), it may cause the
+  initial max_memory_to_use specification to be exceeded, which in the worst
+  case would result in an out-of-memory failure.
+* do_block_smoothing can be changed before each call to jpeg_start_output().
+  This setting is relevant only when decoding a progressive JPEG image.
+  During the first DC-only scan, block smoothing provides a very "fuzzy" look
+  instead of the very "blocky" look seen without it; which is better seems a
+  matter of personal taste.  But block smoothing is nearly always a win
+  during later stages, especially when decoding a successive-approximation
+  image: smoothing helps to hide the slight blockiness that otherwise shows
+  up on smooth gradients until the lowest coefficient bits are sent.
+* Color quantization mode can be changed under the rules described below.
+  You *cannot* change between full-color and quantized output (because that
+  would alter the required I/O buffer sizes), but you can change which
+  quantization method is used.
+
+When generating color-quantized output, changing quantization method is a
+very useful way of switching between high-speed and high-quality display.
+The library allows you to change among its three quantization methods:
+1. Single-pass quantization to a fixed color cube.
+   Selected by cinfo.two_pass_quantize = FALSE and cinfo.colormap = NULL.
+2. Single-pass quantization to an application-supplied colormap.
+   Selected by setting cinfo.colormap to point to the colormap (the value of
+   two_pass_quantize is ignored); also set cinfo.actual_number_of_colors.
+3. Two-pass quantization to a colormap chosen specifically for the image.
+   Selected by cinfo.two_pass_quantize = TRUE and cinfo.colormap = NULL.
+   (This is the default setting selected by jpeg_read_header, but it is
+   probably NOT what you want for the first pass of progressive display!)
+These methods offer successively better quality and lesser speed.  However,
+only the first method is available for quantizing in non-RGB color spaces.
+
+IMPORTANT: because the different quantizer methods have very different
+working-storage requirements, the library requires you to indicate which
+one(s) you intend to use before you call jpeg_start_decompress().  (If we did
+not require this, the max_memory_to_use setting would be a complete fiction.)
+You do this by setting one or more of these three cinfo fields to TRUE:
+        enable_1pass_quant              Fixed color cube colormap
+        enable_external_quant           Externally-supplied colormap
+        enable_2pass_quant              Two-pass custom colormap
+All three are initialized FALSE by jpeg_read_header().  But
+jpeg_start_decompress() automatically sets TRUE the one selected by the
+current two_pass_quantize and colormap settings, so you only need to set the
+enable flags for any other quantization methods you plan to change to later.
+
+After setting the enable flags correctly at jpeg_start_decompress() time, you
+can change to any enabled quantization method by setting two_pass_quantize
+and colormap properly just before calling jpeg_start_output().  The following
+special rules apply:
+1. You must explicitly set cinfo.colormap to NULL when switching to 1-pass
+   or 2-pass mode from a different mode, or when you want the 2-pass
+   quantizer to be re-run to generate a new colormap.
+2. To switch to an external colormap, or to change to a different external
+   colormap than was used on the prior pass, you must call
+   jpeg_new_colormap() after setting cinfo.colormap.
+NOTE: if you want to use the same colormap as was used in the prior pass,
+you should not do either of these things.  This will save some nontrivial
+switchover costs.
+(These requirements exist because cinfo.colormap will always be non-NULL
+after completing a prior output pass, since both the 1-pass and 2-pass
+quantizers set it to point to their output colormaps.  Thus you have to
+do one of these two things to notify the library that something has changed.
+Yup, it's a bit klugy, but it's necessary to do it this way for backwards
+compatibility.)
+
+Note that in buffered-image mode, the library generates any requested colormap
+during jpeg_start_output(), not during jpeg_start_decompress().
+
+When using two-pass quantization, jpeg_start_output() makes a pass over the
+buffered image to determine the optimum color map; it therefore may take a
+significant amount of time, whereas ordinarily it does little work.  The
+progress monitor hook is called during this pass, if defined.  It is also
+important to realize that if the specified target scan number is greater than
+or equal to the current input scan number, jpeg_start_output() will attempt
+to consume input as it makes this pass.  If you use a suspending data source,
+you need to check for a FALSE return from jpeg_start_output() under these
+conditions.  The combination of 2-pass quantization and a not-yet-fully-read
+target scan is the only case in which jpeg_start_output() will consume input.
+
+
+Application authors who support buffered-image mode may be tempted to use it
+for all JPEG images, even single-scan ones.  This will work, but it is
+inefficient: there is no need to create an image-sized coefficient buffer for
+single-scan images.  Requesting buffered-image mode for such an image wastes
+memory.  Worse, it can cost time on large images, since the buffered data has
+to be swapped out or written to a temporary file.  If you are concerned about
+maximum performance on baseline JPEG files, you should use buffered-image
+mode only when the incoming file actually has multiple scans.  This can be
+tested by calling jpeg_has_multiple_scans(), which will return a correct
+result at any time after jpeg_read_header() completes.
+
+It is also worth noting that when you use jpeg_consume_input() to let input
+processing get ahead of output processing, the resulting pattern of access to
+the coefficient buffer is quite nonsequential.  It's best to use the memory
+manager jmemnobs.c if you can (ie, if you have enough real or virtual main
+memory).  If not, at least make sure that max_memory_to_use is set as high as
+possible.  If the JPEG memory manager has to use a temporary file, you will
+probably see a lot of disk traffic and poor performance.  (This could be
+improved with additional work on the memory manager, but we haven't gotten
+around to it yet.)
+
+In some applications it may be convenient to use jpeg_consume_input() for all
+input processing, including reading the initial markers; that is, you may
+wish to call jpeg_consume_input() instead of jpeg_read_header() during
+startup.  This works, but note that you must check for JPEG_REACHED_SOS and
+JPEG_REACHED_EOI return codes as the equivalent of jpeg_read_header's codes.
+Once the first SOS marker has been reached, you must call
+jpeg_start_decompress() before jpeg_consume_input() will consume more input;
+it'll just keep returning JPEG_REACHED_SOS until you do.  If you read a
+tables-only file this way, jpeg_consume_input() will return JPEG_REACHED_EOI
+without ever returning JPEG_REACHED_SOS; be sure to check for this case.
+If this happens, the decompressor will not read any more input until you call
+jpeg_abort() to reset it.  It is OK to call jpeg_consume_input() even when not
+using buffered-image mode, but in that case it's basically a no-op after the
+initial markers have been read: it will just return JPEG_SUSPENDED.
+
+
+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 then 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 when 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.  See jpeg_copy_critical_parameters()
+for an example of copying quantization tables.
+
+
+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.  For example,
+to load a fixed quantization table into table slot "n":
+
+    if (cinfo.quant_tbl_ptrs[n] == NULL)
+      cinfo.quant_tbl_ptrs[n] = jpeg_alloc_quant_table((j_common_ptr) &cinfo);
+    quant_ptr = cinfo.quant_tbl_ptrs[n];        /* quant_ptr is JQUANT_TBL* */
+    for (i = 0; i < 64; i++) {
+      /* Qtable[] is desired quantization table, in natural array order */
+      quant_ptr->quantval[i] = Qtable[i];
+    }
+
+Code to load a fixed Huffman table is typically (for AC table "n"):
+
+    if (cinfo.ac_huff_tbl_ptrs[n] == NULL)
+      cinfo.ac_huff_tbl_ptrs[n] = jpeg_alloc_huff_table((j_common_ptr) &cinfo);
+    huff_ptr = cinfo.ac_huff_tbl_ptrs[n];       /* huff_ptr is JHUFF_TBL* */
+    for (i = 1; i <= 16; i++) {
+      /* counts[i] is number of Huffman codes of length i bits, i=1..16 */
+      huff_ptr->bits[i] = counts[i];
+    }
+    for (i = 0; i < 256; i++) {
+      /* symbols[] is the list of Huffman symbols, in code-length order */
+      huff_ptr->huffval[i] = symbols[i];
+    }
+
+(Note that trying to set cinfo.quant_tbl_ptrs[n] to point directly at a
+constant JQUANT_TBL object is not safe.  If the incoming file happened to
+contain a quantization table definition, your master table would get
+overwritten!  Instead allocate a working table copy and copy the master table
+into it, as illustrated above.  Ditto for Huffman tables, of course.)
+
+You might want to read the tables from a tables-only file, rather than
+hard-wiring them into your application.  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 later, 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
+---------------
+
+Some applications may need to insert or extract special data in the JPEG
+datastream.  The JPEG standard provides marker types "COM" (comment) and
+"APP0" through "APP15" (application) to hold application-specific data.
+Unfortunately, the use of these markers is not specified by the standard.
+COM markers are fairly widely used to hold user-supplied text.  The JFIF file
+format spec uses APP0 markers with specified initial strings to hold certain
+data.  Adobe applications use APP14 markers beginning with the string "Adobe"
+for miscellaneous data.  Other APPn markers are rarely seen, but might
+contain almost anything.
+
+If you wish to store user-supplied text, we recommend you use COM markers
+and place readable 7-bit ASCII text in them.  Newline conventions are not
+standardized --- expect to find LF (Unix style), CR/LF (DOS style), or CR
+(Mac style).  A robust COM reader should be able to cope with random binary
+garbage, including nulls, since some applications generate COM markers
+containing non-ASCII junk.  (But yours should not be one of them.)
+
+For program-supplied data, use an APPn marker, and be sure to begin it with an
+identifying string so that you can tell whether the marker is actually yours.
+It's probably best to avoid using APP0 or APP14 for any private markers.
+(NOTE: the upcoming SPIFF standard will use APP8 markers; we recommend you
+not use APP8 markers for any private purposes, either.)
+
+Keep in mind that at most 65533 bytes can be put into one marker, but you
+can have as many markers as you like.
+
+By default, the IJG compression library will write a JFIF APP0 marker if the
+selected JPEG colorspace is grayscale or YCbCr, or an Adobe APP14 marker if
+the selected colorspace is RGB, CMYK, or YCCK.  You can disable this, but
+we don't recommend it.  The decompression library will recognize JFIF and
+Adobe markers and will set the JPEG colorspace properly when one is found.
+
+
+You can write special markers immediately following the datastream header by
+calling jpeg_write_marker() after jpeg_start_compress() and before the first
+call to jpeg_write_scanlines().  When you do this, the markers appear after
+the SOI and the JFIF APP0 and Adobe APP14 markers (if written), but before
+all else.  Specify the marker type parameter as "JPEG_COM" for COM or
+"JPEG_APP0 + n" for APPn.  (Actually, jpeg_write_marker will let you write
+any marker type, but we don't recommend writing any other kinds of marker.)
+For example, to write a user comment string pointed to by comment_text:
+        jpeg_write_marker(cinfo, JPEG_COM, comment_text, strlen(comment_text));
+
+If it's not convenient to store all the marker data in memory at once,
+you can instead call jpeg_write_m_header() followed by multiple calls to
+jpeg_write_m_byte().  If you do it this way, it's your responsibility to
+call jpeg_write_m_byte() exactly the number of times given in the length
+parameter to jpeg_write_m_header().  (This method lets you empty the
+output buffer partway through a marker, which might be important when
+using a suspending data destination module.  In any case, if you are using
+a suspending destination, you should flush its buffer after inserting
+any special markers.  See "I/O suspension".)
+
+Or, if you prefer to synthesize the marker byte sequence yourself,
+you can just cram it straight into the data destination module.
+
+If you are writing JFIF 1.02 extension markers (thumbnail images), don't
+forget to set cinfo.JFIF_minor_version = 2 so that the encoder will write the
+correct JFIF version number in the JFIF header marker.  The library's default
+is to write version 1.01, but that's wrong if you insert any 1.02 extension
+markers.  (We could probably get away with just defaulting to 1.02, but there
+used to be broken decoders that would complain about unknown minor version
+numbers.  To reduce compatibility risks it's safest not to write 1.02 unless
+you are actually using 1.02 extensions.)
+
+
+When reading, two methods of handling special markers are available:
+1. You can ask the library to save the contents of COM and/or APPn markers
+into memory, and then examine them at your leisure afterwards.
+2. You can supply your own routine to process COM and/or APPn markers
+on-the-fly as they are read.
+The first method is simpler to use, especially if you are using a suspending
+data source; writing a marker processor that copes with input suspension is
+not easy (consider what happens if the marker is longer than your available
+input buffer).  However, the second method conserves memory since the marker
+data need not be kept around after it's been processed.
+
+For either method, you'd normally set up marker handling after creating a
+decompression object and before calling jpeg_read_header(), because the
+markers of interest will typically be near the head of the file and so will
+be scanned by jpeg_read_header.  Once you've established a marker handling
+method, it will be used for the life of that decompression object
+(potentially many datastreams), unless you change it.  Marker handling is
+determined separately for COM markers and for each APPn marker code.
+
+
+To save the contents of special markers in memory, call
+        jpeg_save_markers(cinfo, marker_code, length_limit)
+where marker_code is the marker type to save, JPEG_COM or JPEG_APP0+n.
+(To arrange to save all the special marker types, you need to call this
+routine 17 times, for COM and APP0-APP15.)  If the incoming marker is longer
+than length_limit data bytes, only length_limit bytes will be saved; this
+parameter allows you to avoid chewing up memory when you only need to see the
+first few bytes of a potentially large marker.  If you want to save all the
+data, set length_limit to 0xFFFF; that is enough since marker lengths are only
+16 bits.  As a special case, setting length_limit to 0 prevents that marker
+type from being saved at all.  (That is the default behavior, in fact.)
+
+After jpeg_read_header() completes, you can examine the special markers by
+following the cinfo->marker_list pointer chain.  All the special markers in
+the file appear in this list, in order of their occurrence in the file (but
+omitting any markers of types you didn't ask for).  Both the original data
+length and the saved data length are recorded for each list entry; the latter
+will not exceed length_limit for the particular marker type.  Note that these
+lengths exclude the marker length word, whereas the stored representation
+within the JPEG file includes it.  (Hence the maximum data length is really
+only 65533.)
+
+It is possible that additional special markers appear in the file beyond the
+SOS marker at which jpeg_read_header stops; if so, the marker list will be
+extended during reading of the rest of the file.  This is not expected to be
+common, however.  If you are short on memory you may want to reset the length
+limit to zero for all marker types after finishing jpeg_read_header, to
+ensure that the max_memory_to_use setting cannot be exceeded due to addition
+of later markers.
+
+The marker list remains stored until you call jpeg_finish_decompress or
+jpeg_abort, at which point the memory is freed and the list is set to empty.
+(jpeg_destroy also releases the storage, of course.)
+
+Note that the library is internally interested in APP0 and APP14 markers;
+if you try to set a small nonzero length limit on these types, the library
+will silently force the length up to the minimum it wants.  (But you can set
+a zero length limit to prevent them from being saved at all.)  Also, in a
+16-bit environment, the maximum length limit may be constrained to less than
+65533 by malloc() limitations.  It is therefore best not to assume that the
+effective length limit is exactly what you set it to be.
+
+
+If you want to supply your own marker-reading routine, you do it by calling
+jpeg_set_marker_processor().  A marker processor routine must have the
+signature
+        boolean jpeg_marker_parser_method (j_decompress_ptr cinfo)
+Although the marker code is not explicitly passed, the routine can find it
+in cinfo->unread_marker.  At the time of call, the marker proper has been
+read from the data source module.  The processor routine is responsible for
+reading the marker length word and the remaining parameter bytes, if any.
+Return TRUE to indicate success.  (FALSE should be returned only if you are
+using a suspending data source and it tells you to suspend.  See the standard
+marker processors in jdmarker.c for appropriate coding methods if you need to
+use a suspending data source.)
+
+If you override the default APP0 or APP14 processors, it is up to you to
+recognize JFIF and Adobe markers if you want colorspace recognition to occur
+properly.  We recommend copying and extending the default processors if you
+want to do that.  (A better idea is to save these marker types for later
+examination by calling jpeg_save_markers(); that method doesn't interfere
+with the library's own processing of these markers.)
+
+jpeg_set_marker_processor() and jpeg_save_markers() are mutually exclusive
+--- if you call one it overrides any previous call to the other, for the
+particular marker type specified.
+
+A simple example of an external COM processor can be found in djpeg.c.
+Also, see jpegtran.c for an example of using jpeg_save_markers.
+
+
+Raw (downsampled) image data
+----------------------------
+
+Some applications need to supply already-downsampled image data to the JPEG
+compressor, or to receive raw downsampled data from the decompressor.  The
+library supports this requirement by allowing the application to write or
+read raw data, bypassing the normal preprocessing or postprocessing steps.
+The interface is different from the standard one and is somewhat harder to
+use.  If your interest is merely in bypassing color conversion, we recommend
+that you use the standard interface and simply set jpeg_color_space =
+in_color_space (or jpeg_color_space = out_color_space for decompression).
+The mechanism described in this section is necessary only to supply or
+receive downsampled image data, in which not all components have the same
+dimensions.
+
+
+To compress raw data, you must supply the data in the colorspace to be used
+in the JPEG file (please read the earlier section on Special color spaces)
+and downsampled to the sampling factors specified in the JPEG parameters.
+You must supply the data in the format used internally by the JPEG library,
+namely a JSAMPIMAGE array.  This is an array of pointers to two-dimensional
+arrays, each of type JSAMPARRAY.  Each 2-D array holds the values for one
+color component.  This structure is necessary since the components are of
+different sizes.  If the image dimensions are not a multiple of the MCU size,
+you must also pad the data correctly (usually, this is done by replicating
+the last column and/or row).  The data must be padded to a multiple of a DCT
+block in each component: that is, each downsampled row must contain a
+multiple of 8 valid samples, and there must be a multiple of 8 sample rows
+for each component.  (For applications such as conversion of digital TV
+images, the standard image size is usually a multiple of the DCT block size,
+so that no padding need actually be done.)
+
+The procedure for compression of raw data is basically the same as normal
+compression, except that you call jpeg_write_raw_data() in place of
+jpeg_write_scanlines().  Before calling jpeg_start_compress(), you must do
+the following:
+  * Set cinfo->raw_data_in to TRUE.  (It is set FALSE by jpeg_set_defaults().)
+    This notifies the library that you will be supplying raw data.
+    Furthermore, set cinfo->do_fancy_downsampling to FALSE if you want to use
+    real downsampled data.  (It is set TRUE by jpeg_set_defaults().)
+  * Ensure jpeg_color_space is correct --- an explicit jpeg_set_colorspace()
+    call is a good idea.  Note that since color conversion is bypassed,
+    in_color_space is ignored, except that jpeg_set_defaults() uses it to
+    choose the default jpeg_color_space setting.
+  * Ensure the sampling factors, cinfo->comp_info[i].h_samp_factor and
+    cinfo->comp_info[i].v_samp_factor, are correct.  Since these indicate the
+    dimensions of the data you are supplying, it's wise to set them
+    explicitly, rather than assuming the library's defaults are what you want.
+
+To pass raw data to the library, call jpeg_write_raw_data() in place of
+jpeg_write_scanlines().  The two routines work similarly except that
+jpeg_write_raw_data takes a JSAMPIMAGE data array rather than JSAMPARRAY.
+The scanlines count passed to and returned from jpeg_write_raw_data is
+measured in terms of the component with the largest v_samp_factor.
+
+jpeg_write_raw_data() processes one MCU row per call, which is to say
+v_samp_factor*DCTSIZE sample rows of each component.  The passed num_lines
+value must be at least max_v_samp_factor*DCTSIZE, and the return value will
+be exactly that amount (or possibly some multiple of that amount, in future
+library versions).  This is true even on the last call at the bottom of the
+image; don't forget to pad your data as necessary.
+
+The required dimensions of the supplied data can be computed for each
+component as
+        cinfo->comp_info[i].width_in_blocks*DCTSIZE  samples per row
+        cinfo->comp_info[i].height_in_blocks*DCTSIZE rows in image
+after jpeg_start_compress() has initialized those fields.  If the valid data
+is smaller than this, it must be padded appropriately.  For some sampling
+factors and image sizes, additional dummy DCT blocks are inserted to make
+the image a multiple of the MCU dimensions.  The library creates such dummy
+blocks itself; it does not read them from your supplied data.  Therefore you
+need never pad by more than DCTSIZE samples.  An example may help here.
+Assume 2h2v downsampling of YCbCr data, that is
+        cinfo->comp_info[0].h_samp_factor = 2           for Y
+        cinfo->comp_info[0].v_samp_factor = 2
+        cinfo->comp_info[1].h_samp_factor = 1           for Cb
+        cinfo->comp_info[1].v_samp_factor = 1
+        cinfo->comp_info[2].h_samp_factor = 1           for Cr
+        cinfo->comp_info[2].v_samp_factor = 1
+and suppose that the nominal image dimensions (cinfo->image_width and
+cinfo->image_height) are 101x101 pixels.  Then jpeg_start_compress() will
+compute downsampled_width = 101 and width_in_blocks = 13 for Y,
+downsampled_width = 51 and width_in_blocks = 7 for Cb and Cr (and the same
+for the height fields).  You must pad the Y data to at least 13*8 = 104
+columns and rows, the Cb/Cr data to at least 7*8 = 56 columns and rows.  The
+MCU height is max_v_samp_factor = 2 DCT rows so you must pass at least 16
+scanlines on each call to jpeg_write_raw_data(), which is to say 16 actual
+sample rows of Y and 8 each of Cb and Cr.  A total of 7 MCU rows are needed,
+so you must pass a total of 7*16 = 112 "scanlines".  The last DCT block row
+of Y data is dummy, so it doesn't matter what you pass for it in the data
+arrays, but the scanlines count must total up to 112 so that all of the Cb
+and Cr data gets passed.
+
+Output suspension is supported with raw-data compression: if the data
+destination module suspends, jpeg_write_raw_data() will return 0.
+In this case the same data rows must be passed again on the next call.
+
+
+Decompression with raw data output implies bypassing all postprocessing.
+You must deal with the color space and sampling factors present in the
+incoming file.  If your application only handles, say, 2h1v YCbCr data,
+you must check for and fail on other color spaces or other sampling factors.
+The library will not convert to a different color space for you.
+
+To obtain raw data output, set cinfo->raw_data_out = TRUE before
+jpeg_start_decompress() (it is set FALSE by jpeg_read_header()).  Be sure to
+verify that the color space and sampling factors are ones you can handle.
+Furthermore, set cinfo->do_fancy_upsampling = FALSE if you want to get real
+downsampled data (it is set TRUE by jpeg_read_header()).
+Then call jpeg_read_raw_data() in place of jpeg_read_scanlines().  The
+decompression process is otherwise the same as usual.
+
+jpeg_read_raw_data() returns one MCU row per call, and thus you must pass a
+buffer of at least max_v_samp_factor*DCTSIZE scanlines (scanline counting is
+the same as for raw-data compression).  The buffer you pass must be large
+enough to hold the actual data plus padding to DCT-block boundaries.  As with
+compression, any entirely dummy DCT blocks are not processed so you need not
+allocate space for them, but the total scanline count includes them.  The
+above example of computing buffer dimensions for raw-data compression is
+equally valid for decompression.
+
+Input suspension is supported with raw-data decompression: if the data source
+module suspends, jpeg_read_raw_data() will return 0.  You can also use
+buffered-image mode to read raw data in multiple passes.
+
+
+Really raw data: DCT coefficients
+---------------------------------
+
+It is possible to read or write the contents of a JPEG file as raw DCT
+coefficients.  This facility is mainly intended for use in lossless
+transcoding between different JPEG file formats.  Other possible applications
+include lossless cropping of a JPEG image, lossless reassembly of a
+multi-strip or multi-tile TIFF/JPEG file into a single JPEG datastream, etc.
+
+To read the contents of a JPEG file as DCT coefficients, open the file and do
+jpeg_read_header() as usual.  But instead of calling jpeg_start_decompress()
+and jpeg_read_scanlines(), call jpeg_read_coefficients().  This will read the
+entire image into a set of virtual coefficient-block arrays, one array per
+component.  The return value is a pointer to an array of virtual-array
+descriptors.  Each virtual array can be accessed directly using the JPEG
+memory manager's access_virt_barray method (see Memory management, below,
+and also read structure.txt's discussion of virtual array handling).  Or,
+for simple transcoding to a different JPEG file format, the array list can
+just be handed directly to jpeg_write_coefficients().
+
+Each block in the block arrays contains quantized coefficient values in
+normal array order (not JPEG zigzag order).  The block arrays contain only
+DCT blocks containing real data; any entirely-dummy blocks added to fill out
+interleaved MCUs at the right or bottom edges of the image are discarded
+during reading and are not stored in the block arrays.  (The size of each
+block array can be determined from the width_in_blocks and height_in_blocks
+fields of the component's comp_info entry.)  This is also the data format
+expected by jpeg_write_coefficients().
+
+When you are done using the virtual arrays, call jpeg_finish_decompress()
+to release the array storage and return the decompression object to an idle
+state; or just call jpeg_destroy() if you don't need to reuse the object.
+
+If you use a suspending data source, jpeg_read_coefficients() will return
+NULL if it is forced to suspend; a non-NULL return value indicates successful
+completion.  You need not test for a NULL return value when using a
+non-suspending data source.
+
+It is also possible to call jpeg_read_coefficients() to obtain access to the
+decoder's coefficient arrays during a normal decode cycle in buffered-image
+mode.  This frammish might be useful for progressively displaying an incoming
+image and then re-encoding it without loss.  To do this, decode in buffered-
+image mode as discussed previously, then call jpeg_read_coefficients() after
+the last jpeg_finish_output() call.  The arrays will be available for your use
+until you call jpeg_finish_decompress().
+
+
+To write the contents of a JPEG file as DCT coefficients, you must provide
+the DCT coefficients stored in virtual block arrays.  You can either pass
+block arrays read from an input JPEG file by jpeg_read_coefficients(), or
+allocate virtual arrays from the JPEG compression object and fill them
+yourself.  In either case, jpeg_write_coefficients() is substituted for
+jpeg_start_compress() and jpeg_write_scanlines().  Thus the sequence is
+  * Create compression object
+  * Set all compression parameters as necessary
+  * Request virtual arrays if needed
+  * jpeg_write_coefficients()
+  * jpeg_finish_compress()
+  * Destroy or re-use compression object
+jpeg_write_coefficients() is passed a pointer to an array of virtual block
+array descriptors; the number of arrays is equal to cinfo.num_components.
+
+The virtual arrays need only have been requested, not realized, before
+jpeg_write_coefficients() is called.  A side-effect of
+jpeg_write_coefficients() is to realize any virtual arrays that have been
+requested from the compression object's memory manager.  Thus, when obtaining
+the virtual arrays from the compression object, you should fill the arrays
+after calling jpeg_write_coefficients().  The data is actually written out
+when you call jpeg_finish_compress(); jpeg_write_coefficients() only writes
+the file header.
+
+When writing raw DCT coefficients, it is crucial that the JPEG quantization
+tables and sampling factors match the way the data was encoded, or the
+resulting file will be invalid.  For transcoding from an existing JPEG file,
+we recommend using jpeg_copy_critical_parameters().  This routine initializes
+all the compression parameters to default values (like jpeg_set_defaults()),
+then copies the critical information from a source decompression object.
+The decompression object should have just been used to read the entire
+JPEG input file --- that is, it should be awaiting jpeg_finish_decompress().
+
+jpeg_write_coefficients() marks all tables stored in the compression object
+as needing to be written to the output file (thus, it acts like
+jpeg_start_compress(cinfo, TRUE)).  This is for safety's sake, to avoid
+emitting abbreviated JPEG files by accident.  If you really want to emit an
+abbreviated JPEG file, call jpeg_suppress_tables(), or set the tables'
+individual sent_table flags, between calling jpeg_write_coefficients() and
+jpeg_finish_compress().
+
+
+Progress monitoring
+-------------------
+
+Some applications may need to regain control from the JPEG library every so
+often.  The typical use of this feature is to produce a percent-done bar or
+other progress display.  (For a simple example, see cjpeg.c or djpeg.c.)
+Although you do get control back frequently during the data-transferring pass
+(the jpeg_read_scanlines or jpeg_write_scanlines loop), any additional passes
+will occur inside jpeg_finish_compress or jpeg_start_decompress; those
+routines may take a long time to execute, and you don't get control back
+until they are done.
+
+You can define a progress-monitor routine which will be called periodically
+by the library.  No guarantees are made about how often this call will occur,
+so we don't recommend you use it for mouse tracking or anything like that.
+At present, a call will occur once per MCU row, scanline, or sample row
+group, whichever unit is convenient for the current processing mode; so the
+wider the image, the longer the time between calls.  During the data
+transferring pass, only one call occurs per call of jpeg_read_scanlines or
+jpeg_write_scanlines, so don't pass a large number of scanlines at once if
+you want fine resolution in the progress count.  (If you really need to use
+the callback mechanism for time-critical tasks like mouse tracking, you could
+insert additional calls inside some of the library's inner loops.)
+
+To establish a progress-monitor callback, create a struct jpeg_progress_mgr,
+fill in its progress_monitor field with a pointer to your callback routine,
+and set cinfo->progress to point to the struct.  The callback will be called
+whenever cinfo->progress is non-NULL.  (This pointer is set to NULL by
+jpeg_create_compress or jpeg_create_decompress; the library will not change
+it thereafter.  So if you allocate dynamic storage for the progress struct,
+make sure it will live as long as the JPEG object does.  Allocating from the
+JPEG memory manager with lifetime JPOOL_PERMANENT will work nicely.)  You
+can use the same callback routine for both compression and decompression.
+
+The jpeg_progress_mgr struct contains four fields which are set by the library:
+        long pass_counter;      /* work units completed in this pass */
+        long pass_limit;        /* total number of work units in this pass */
+        int completed_passes;   /* passes completed so far */
+        int total_passes;       /* total number of passes expected */
+During any one pass, pass_counter increases from 0 up to (not including)
+pass_limit; the step size is usually but not necessarily 1.  The pass_limit
+value may change from one pass to another.  The expected total number of
+passes is in total_passes, and the number of passes already completed is in
+completed_passes.  Thus the fraction of work completed may be estimated as
+                completed_passes + (pass_counter/pass_limit)
+                --------------------------------------------
+                                total_passes
+ignoring the fact that the passes may not be equal amounts of work.
+
+When decompressing, pass_limit can even change within a pass, because it
+depends on the number of scans in the JPEG file, which isn't always known in
+advance.  The computed fraction-of-work-done may jump suddenly (if the library
+discovers it has overestimated the number of scans) or even decrease (in the
+opposite case).  It is not wise to put great faith in the work estimate.
+
+When using the decompressor's buffered-image mode, the progress monitor work
+estimate is likely to be completely unhelpful, because the library has no way
+to know how many output passes will be demanded of it.  Currently, the library
+sets total_passes based on the assumption that there will be one more output
+pass if the input file end hasn't yet been read (jpeg_input_complete() isn't
+TRUE), but no more output passes if the file end has been reached when the
+output pass is started.  This means that total_passes will rise as additional
+output passes are requested.  If you have a way of determining the input file
+size, estimating progress based on the fraction of the file that's been read
+will probably be more useful than using the library's value.
+
+
+Memory management
+-----------------
+
+This section covers some key facts about the JPEG library's built-in memory
+manager.  For more info, please read structure.txt'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; so a reasonable safety margin
+should be left when setting max_memory_to_use.
+
+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 or jmemmac.c either,
+since the C library is supposed to take care of deleting files made with
+tmpfile().
+
+
+Memory usage
+------------
+
+Working memory requirements while performing compression or decompression
+depend on image dimensions, image characteristics (such as colorspace and
+JPEG process), and operating mode (application-selected options).
+
+As of v6b, the decompressor requires:
+ 1. About 24K in more-or-less-fixed-size data.  This varies a bit depending
+    on operating mode and image characteristics (particularly color vs.
+    grayscale), but it doesn't depend on image dimensions.
+ 2. Strip buffers (of size proportional to the image width) for IDCT and
+    upsampling results.  The worst case for commonly used sampling factors
+    is about 34 bytes * width in pixels for a color image.  A grayscale image
+    only needs about 8 bytes per pixel column.
+ 3. A full-image DCT coefficient buffer is needed to decode a multi-scan JPEG
+    file (including progressive JPEGs), or whenever you select buffered-image
+    mode.  This takes 2 bytes/coefficient.  At typical 2x2 sampling, that's
+    3 bytes per pixel for a color image.  Worst case (1x1 sampling) requires
+    6 bytes/pixel.  For grayscale, figure 2 bytes/pixel.
+ 4. To perform 2-pass color quantization, the decompressor also needs a
+    128K color lookup table and a full-image pixel buffer (3 bytes/pixel).
+This does not count any memory allocated by the application, such as a
+buffer to hold the final output image.
+
+The above figures are valid for 8-bit JPEG data precision and a machine with
+32-bit ints.  For 12-bit JPEG data, double the size of the strip buffers and
+quantization pixel buffer.  The "fixed-size" data will be somewhat smaller
+with 16-bit ints, larger with 64-bit ints.  Also, CMYK or other unusual
+color spaces will require different amounts of space.
+
+The full-image coefficient and pixel buffers, if needed at all, do not
+have to be fully RAM resident; you can have the library use temporary
+files instead when the total memory usage would exceed a limit you set.
+(But if your OS supports virtual memory, it's probably better to just use
+jmemnobs and let the OS do the swapping.)
+
+The compressor's memory requirements are similar, except that it has no need
+for color quantization.  Also, it needs a full-image DCT coefficient buffer
+if Huffman-table optimization is asked for, even if progressive mode is not
+requested.
+
+If you need more detailed information about memory usage in a particular
+situation, you can enable the MEM_STATS code in jmemmgr.c.
+
+
+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.  The IJG code supports 12-bit JPEG 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.
+The sample applications cjpeg and djpeg can support 12-bit mode only for PPM
+and GIF file formats; you must disable the other file formats to compile a
+12-bit cjpeg or djpeg.  (install.txt has more information about that.)
+At present, a 12-bit library can handle *only* 12-bit images, not both
+precisions.  (If you need to include both 8- and 12-bit libraries in a single
+application, you could probably do it by defining NEED_SHORT_EXTERNAL_NAMES
+for just one of the copies.  You'd have to access the 8-bit and 12-bit copies
+from separate application source files.  This is untested ... if you try it,
+we'd like to hear whether it works!)
+
+Note that a 12-bit library always compresses in Huffman optimization mode,
+in order to generate valid Huffman tables.  This is necessary because our
+default Huffman tables only cover 8-bit data.  If you need to output 12-bit
+files in one pass, you'll have to supply suitable default Huffman tables.
+You may also want to supply your own DCT quantization tables; the existing
+quality-scaling code has been developed for 8-bit use, and probably doesn't
+generate especially good tables for 12-bit.
+
+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.
+
+You can also save a few K by not having text error messages in the library;
+the standard error message table occupies about 5Kb.  This is particularly
+reasonable for embedded applications where there's no good way to display 
+a message anyway.  To do this, remove the creation of the message table
+(jpeg_std_message_table[]) from jerror.c, and alter format_message to do
+something reasonable without it.  You could output the numeric value of the
+message code number, for example.  If you do this, you can also save a couple
+more K by modifying the TRACEMSn() macros in jerror.h to expand to nothing;
+you don't need trace capability anyway, right?
+
+
+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 ANSI C, C++, and pre-ANSI C compilers, using any of
+the popular system include file setups, and some not-so-popular ones too.
+See install.txt 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.txt,
+jmorecfg.h, and jinclude.h.
+
+
+Notes for MS-DOS implementors
+-----------------------------
+
+The IJG code is designed to work efficiently in 80x86 "small" or "medium"
+memory models (i.e., data pointers are 16 bits unless explicitly declared
+"far"; code pointers can be either size).  You may be able to use small
+model to compile cjpeg or djpeg by itself, but you will probably have to use
+medium model for any larger application.  This won't make much difference in
+performance.  You *will* take a noticeable performance hit if you use a
+large-data memory model (perhaps 10%-25%), and you should avoid "huge" model
+if at all possible.
+
+The JPEG library typically needs 2Kb-3Kb of stack space.  It will also
+malloc about 20K-30K of near heap space while executing (and lots of far
+heap, but that doesn't count in this calculation).  This figure will vary
+depending on selected operating mode, and to a lesser extent on image size.
+There is also about 5Kb-6Kb of constant data which will be allocated in the
+near data segment (about 4Kb of this is the error message table).
+Thus you have perhaps 20K available for other modules' static data and near
+heap space 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.  Another possibility is to move the error message table to far memory;
+this should be doable with only localized hacking on jerror.c.)
+
+About 2K of the near heap space is "permanent" memory that will not be
+released until you destroy the JPEG object.  This is only an issue if you
+save a JPEG object between compression or decompression operations.
+
+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 40 bytes per column for typical sampling ratios (eg, about 25600
+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 32-bit flat-memory-model
+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.