* Colorspace conversion: convert from JPEG color space to output color space,  and change data layout from separate component planes to pixel-interleaved.  Works on one pixel row at a time.* Color quantization: reduce the data to colormapped form, using either an  externally specified colormap or an internally generated one.  This module  is not used for full-color output.  Works on one pixel row at a time; may  require two passes to generate a color map.  Note that the output will  always be a single component representing colormap indexes.  In the current  design, the output values are JSAMPLEs, so an 8-bit compilation cannot  quantize to more than 256 colors.  This is unlikely to be a problem in  practice.* Color reduction: this module handles color precision reduction, e.g.,  generating 15-bit color (5 bits/primary) from JPEG's 24-bit output.  Not quite clear yet how this should be handled... should we merge it with  colorspace conversion???Note that some high-speed operating modes might condense the entirepostprocessing sequence to a single module (upsample, color convert, andquantize in one step).In addition to the above objects, the decompression library includes theseobjects:* Master control: determines the number of passes required, controls overall  and per-pass initialization of the other modules.  This is subdivided into  input and output control: jdinput.c controls only input-side processing,  while jdmaster.c handles overall initialization and output-side control.* Marker reading: decodes JPEG markers (except for RSTn).* Data source manager: supplies the input JPEG datastream.  The source  manager supplied with the library knows how to read from a stdio stream;  for other behaviors, the surrounding application may provide its own source  manager.* Memory manager: same as for compression library.* Error handler: same as for compression library.* Progress monitor: same as for compression library.As with compression, the data source manager, error handler, and progressmonitor are candidates for replacement by a surrounding application.*** Decompression input and output separation ***To support efficient incremental display of progressive JPEG files, thedecompressor is divided into two sections that can run independently:1. Data input includes marker parsing, entropy decoding, and input into the   coefficient controller's DCT coefficient buffer.  Note that this   processing is relatively cheap and fast.2. Data output reads from the DCT coefficient buffer and performs the IDCT   and all postprocessing steps.For a progressive JPEG file, the data input processing is allowed to getarbitrarily far ahead of the data output processing.  (This occurs onlyif the application calls jpeg_consume_input(); otherwise input and outputrun in lockstep, since the input section is called only when the outputsection needs more data.)  In this way the application can avoid makingextra display passes when data is arriving faster than the display passcan run.  Furthermore, it is possible to abort an output pass withoutlosing anything, since the coefficient buffer is read-only as far as theoutput section is concerned.  See libjpeg.doc for more detail.A full-image coefficient array is only created if the JPEG file has multiplescans (or if the application specifies buffered-image mode anyway).  Whenreading a single-scan file, the coefficient controller normally creates onlya one-MCU buffer, so input and output processing must run in lockstep in thiscase.  jpeg_consume_input() is effectively a no-op in this situation.The main impact of dividing the decompressor in this fashion is that we mustbe very careful with shared variables in the cinfo data structure.  Eachvariable that can change during the course of decompression must beclassified as belonging to data input or data output, and each section mustlook only at its own variables.  For example, the data output section may notdepend on any of the variables that describe the current scan in the JPEGfile, because these may change as the data input section advances into a newscan.The progress monitor is (somewhat arbitrarily) defined to treat input of thefile as one pass when buffered-image mode is not used, and to ignore datainput work completely when buffered-image mode is used.  Note that thelibrary has no reliable way to predict the number of passes when dealingwith a progressive JPEG file, nor can it predict the number of output passesin buffered-image mode.  So the work estimate is inherently bogus anyway.No comparable division is currently made in the compression library, becausethere isn't any real need for it.*** Data formats ***Arrays of pixel sample values use the following data structure:    typedef something JSAMPLE;		a pixel component value, 0..MAXJSAMPLE    typedef JSAMPLE *JSAMPROW;		ptr to a row of samples    typedef JSAMPROW *JSAMPARRAY;	ptr to a list of rows    typedef JSAMPARRAY *JSAMPIMAGE;	ptr to a list of color-component arraysThe basic element type JSAMPLE will typically be one of unsigned char,(signed) char, or short.  Short will be used if samples wider than 8 bits areto be supported (this is a compile-time option).  Otherwise, unsigned char isused if possible.  If the compiler only supports signed chars, then it isnecessary to mask off the value when reading.  Thus, all reads of JSAMPLEvalues must be coded as "GETJSAMPLE(value)", where the macro will be definedas "((value) & 0xFF)" on signed-char machines and "((int) (value))" elsewhere.With these conventions, JSAMPLE values can be assumed to be >= 0.  This helpssimplify correct rounding during downsampling, etc.  The JPEG standard'sspecification that sample values run from -128..127 is accommodated bysubtracting 128 just as the sample value is copied into the source array forthe DCT step (this will be an array of signed ints).  Similarly, duringdecompression the output of the IDCT step will be immediately shifted back to0..255.  (NB: different values are required when 12-bit samples are in use.The code is written in terms of MAXJSAMPLE and CENTERJSAMPLE, which will bedefined as 255 and 128 respectively in an 8-bit implementation, and as 4095and 2048 in a 12-bit implementation.)We use a pointer per row, rather than a two-dimensional JSAMPLE array.  Thischoice costs only a small amount of memory and has several benefits:* Code using the data structure doesn't need to know the allocated width of  the rows.  This simplifies edge expansion/compression, since we can work  in an array that's wider than the logical picture width.* Indexing doesn't require multiplication; this is a performance win on many  machines.* Arrays with more than 64K total elements can be supported even on machines  where malloc() cannot allocate chunks larger than 64K.* The rows forming a component array may be allocated at different times  without extra copying.  This trick allows some speedups in smoothing steps  that need access to the previous and next rows.Note that each color component is stored in a separate array; we don't use thetraditional layout in which the components of a pixel are stored together.This simplifies coding of modules that work on each component independently,because they don't need to know how many components there are.  Furthermore,we can read or write each component to a temporary file independently, whichis helpful when dealing with noninterleaved JPEG files.In general, a specific sample value is accessed by code such as	GETJSAMPLE(image[colorcomponent][row][col])where col is measured from the image left edge, but row is measured from thefirst sample row currently in memory.  Either of the first two indexings canbe precomputed by copying the relevant pointer.Since most image-processing applications prefer to work on images in whichthe components of a pixel are stored together, the data passed to or from thesurrounding application uses the traditional convention: a single pixel isrepresented by N consecutive JSAMPLE values, and an image row is an array of(# of color components)*(image width) JSAMPLEs.  One or more rows of data canbe represented by a pointer of type JSAMPARRAY in this scheme.  This scheme isconverted to component-wise storage inside the JPEG library.  (Applicationsthat want to skip JPEG preprocessing or postprocessing will have to contendwith component-wise storage.)Arrays of DCT-coefficient values use the following data structure:    typedef short JCOEF;		a 16-bit signed integer    typedef JCOEF JBLOCK[DCTSIZE2];	an 8x8 block of coefficients    typedef JBLOCK *JBLOCKROW;		ptr to one horizontal row of 8x8 blocks    typedef JBLOCKROW *JBLOCKARRAY;	ptr to a list of such rows    typedef JBLOCKARRAY *JBLOCKIMAGE;	ptr to a list of color component arraysThe underlying type is at least a 16-bit signed integer; while "short" is bigenough on all machines of interest, on some machines it is preferable to use"int" for speed reasons, despite the storage cost.  Coefficients are groupedinto 8x8 blocks (but we always use #defines DCTSIZE and DCTSIZE2 rather than"8" and "64").The contents of a coefficient block may be in either "natural" or zigzaggedorder, and may be true values or divided by the quantization coefficients,depending on where the block is in the processing pipeline.  In the currentlibrary, coefficient blocks are kept in natural order everywhere; the entropycodecs zigzag or dezigzag the data as it is written or read.  The blockscontain quantized coefficients everywhere outside the DCT/IDCT subsystems.(This latter decision may need to be revisited to support variablequantization a la JPEG Part 3.)Notice that the allocation unit is now a row of 8x8 blocks, corresponding toeight rows of samples.  Otherwise the structure is much the same as forsamples, and for the same reasons.On machines where malloc() can't handle a request bigger than 64Kb, this datastructure limits us to rows of less than 512 JBLOCKs, or a picture width of4000+ pixels.  This seems an acceptable restriction.On 80x86 machines, the bottom-level pointer types (JSAMPROW and JBLOCKROW)must be declared as "far" pointers, but the upper levels can be "near"(implying that the pointer lists are allocated in the DS segment).We use a #define symbol FAR, which expands to the "far" keyword whencompiling on 80x86 machines and to nothing elsewhere.*** Suspendable processing ***In some applications it is desirable to use the JPEG library as anincremental, memory-to-memory filter.  In this situation the data source ordestination may be a limited-size buffer, and we can't rely on being able toempty or refill the buffer at arbitrary times.  Instead the application wouldlike to have control return from the library at buffer overflow/underrun, andthen resume compression or decompression at a later time.This scenario is supported for simple cases.  (For anything more complex, werecommend that the application "bite the bullet" and develop real multitaskingcapability.)  The libjpeg.doc file goes into more detail about the usage andlimitations of this capability; here we address the implications for librarystructure.The essence of the problem is that the entropy codec (coder or decoder) mustbe prepared to stop at arbitrary times.  In turn, the controllers that callthe entropy codec must be able to stop before having produced or consumed allthe data that they normally would handle in one call.  That part is reasonablystraightforward: we make the controller call interfaces include "progresscounters" which indicate the number of data chunks successfully processed, andwe require callers to test the counter rather than just assume all of the datawas processed.Rather than trying to restart at an arbitrary point, the current Huffmancodecs are designed to restart at the beginning of the current MCU after asuspension due to buffer overflow/underrun.  At the start of each call, thecodec's internal state is loaded from permanent storage (in the JPEG objectstructures) into local variables.  On successful completion of the MCU, thepermanent state is updated.  (This copying is not very expensive, and may evenlead to *improved* performance if the local variables can be registerized.)If a suspension occurs, the codec simply returns without updating the state,thus effectively reverting to the start of the MCU.  Note that this impliesleaving some data unprocessed in the source/destination buffer (ie, thecompressed partial MCU).  The data source/destination module interfaces arespecified so as to make this possible.  This also implies that the data buffermust be large enough to hold a worst-case compressed MCU; a couple thousandbytes should be enough.