Notes on the JPEG Library
=========================

This JPEG module is derived from work of the IJG (see below),
and may be copyied and redistributed according to the
conditions under LEGAL ISSUES in ReadMe.txt.
The code has been modified in a variety of ways;
some code (GUI_JPEG.c) has been added to as "glue" to make it
work with emWin.
The original text of this file is below; some things stated may no
longer be correct for the code that ships with emWin.
However, we decided to leave it here because it explains the basic
concepts and structure of JPEG code.

Segger Microcontroller Systeme GmbH, June 2003
====================================================================





IJG JPEG LIBRARY:  SYSTEM ARCHITECTURE

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


This file provides an overview of the architecture of the IJG JPEG software;
that is, the functions of the various modules in the system and the interfaces
between modules.  For more precise details about any data structure or calling
convention, see the include files and comments in the source code.

We assume that the reader is already somewhat familiar with the JPEG standard.
The README file includes references for learning about JPEG.  The file
libjpeg.doc describes the library from the viewpoint of an application
programmer using the library; it's best to read that file before this one.
Also, the file coderules.doc describes the coding style conventions we use.

In this document, JPEG-specific terminology follows the JPEG standard:
  A "component" means a color channel, e.g., Red or Luminance.
  A "sample" is a single component value (i.e., one number in the image data).
  A "coefficient" is a frequency coefficient (a DCT transform output number).
  A "block" is an 8x8 group of samples or coefficients.
  An "MCU" (minimum coded unit) is an interleaved set of blocks of size
	determined by the sampling factors, or a single block in a
	noninterleaved scan.
We do not use the terms "pixel" and "sample" interchangeably.  When we say
pixel, we mean an element of the full-size image, while a sample is an element
of the downsampled image.  Thus the number of samples may vary across
components while the number of pixels does not.  (This terminology is not used
rigorously throughout the code, but it is used in places where confusion would
otherwise result.)


*** System features ***

The IJG distribution contains two parts:
  * A subroutine library for JPEG compression and decompression.
  * cjpeg/djpeg, two sample applications that use the library to transform
    JFIF JPEG files to and from several other image formats.
cjpeg/djpeg are of no great intellectual complexity: they merely add a simple
command-line user interface and I/O routines for several uncompressed image
formats.  This document concentrates on the library itself.

We desire the library to be capable of supporting all JPEG baseline, extended
sequential, and progressive DCT processes.  Hierarchical processes are not
supported.

The library does not support the lossless (spatial) JPEG process.  Lossless
JPEG shares little or no code with lossy JPEG, and would normally be used
without the extensive pre- and post-processing provided by this library.
We feel that lossless JPEG is better handled by a separate library.

Within these limits, any set of compression parameters allowed by the JPEG
spec should be readable for decompression.  (We can be more restrictive about
what formats we can generate.)  Although the system design allows for all
parameter values, some uncommon settings are not yet implemented and may
never be; nonintegral sampling ratios are the prime example.  Furthermore,
we treat 8-bit vs. 12-bit data precision as a compile-time switch, not a
run-time option, because most machines can store 8-bit pixels much more
compactly than 12-bit.

For legal reasons, JPEG arithmetic coding is not currently supported, but
extending the library to include it would be straightforward.

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, libtiff uses this
library to implement JPEG compression within the TIFF file format.)

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.  This code can be omitted if not needed.

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.


*** Portability issues ***

Portability is an essential requirement for the library.  The key portability
issues that show up at the level of system architecture are:

1.  Memory usage.  We want the code to be able to run on PC-class machines
with limited memory.  Images should therefore be processed sequentially (in
strips), to avoid holding the whole image in memory at once.  Where a
full-image buffer is necessary, we should be able to use either virtual memory
or temporary files.

2.  Near/far pointer distinction.  To run efficiently on 80x86 machines, the
code should distinguish "small" objects (kept in near data space) from
"large" ones (kept in far data space).  This is an annoying restriction, but
fortunately it does not impact code quality for less brain-damaged machines,
and the source code clutter turns out to be minimal with sufficient use of
pointer typedefs.

3. Data precision.  We assume that "char" is at least 8 bits, "short" and
"int" at least 16, "long" at least 32.  The code will work fine with larger
data sizes, although memory may be used inefficiently in some cases.  However,
the JPEG compressed datastream must ultimately appear on external storage as a
sequence of 8-bit bytes if it is to conform to the standard.  This may pose a
problem on machines where char is wider than 8 bits.  The library represents
compressed data as an array of values of typedef JOCTET.  If no data type
exactly 8 bits wide is available, custom data source and data destination
modules must be written to unpack and pack the chosen JOCTET datatype into
8-bit external representation.


*** System overview ***

The compressor and decompressor are each divided into two main sections:
the JPEG compressor or decompressor proper, and the preprocessing or
postprocessing functions.  The interface between these two sections is the
image data that the official JPEG spec regards as its input or output: this
data is in the colorspace to be used for compression, and it is downsampled
to the sampling factors to be used.  The preprocessing and postprocessing
steps are responsible for converting a normal image representation to or from
this form.  (Those few applications that want to deal with YCbCr downsampled
data can skip the preprocessing or postprocessing step.)

Looking more closely, the compressor library contains the following main
elements:

  Preprocessing:
    * Color space conversion (e.g., RGB to YCbCr).
    * Edge expansion and downsampling.  Optionally, this step can do simple
      smoothing --- this is often helpful for low-quality source data.
  JPEG proper:
    * MCU assembly, DCT, quantization.
    * Entropy coding (sequential or progressive, Huffman or arithmetic).

In addition to these modules we need overall control, marker generation,
and support code (memory management & error handling).  There is also a
module responsible for physically writing the output data --- typically
this is just an interface to fwrite(), but some applications may need to
do something else with the data.

The decompressor library contains the following main elements:

  JPEG proper:
    * Entropy decoding (sequential or progressive, Huffman or arithmetic).
    * Dequantization, inverse DCT, MCU disassembly.
  Postprocessing:
    * Upsampling.  Optionally, this step may be able to do more general
      rescaling of the image.
    * Color space conversion (e.g., YCbCr to RGB).  This step may also
      provide gamma adjustment [ currently it does not ].
    * Optional color quantization (e.g., reduction to 256 colors).
    * Optional color precision reduction (e.g., 24-bit to 15-bit color).
      [This feature is not currently implemented.]

We also need overall control, marker parsing, and a data source module.
The support code (memory management & error handling) can be shared with
the compression half of the library.

There may be several implementations of each of these elements, particularly
in the decompressor, where a wide range of speed/quality tradeoffs is very
useful.  It must be understood that some of the best speedups involve
merging adjacent steps in the pipeline.  For example, upsampling, color space
conversion, and color quantization might all be done at once when using a
low-quality ordered-dither technique.  The system architecture is designed to
allow such merging where appropriate.


Note: it is convenient to regard edge expansion (padding to block boundaries)
as a preprocessing/postprocessing function, even though the JPEG spec includes
it in compression/decompression.  We do this because downsampling/upsampling
can be simplified a little if they work on padded data: it's not necessary to
have special cases at the right and bottom edges.  Therefore the interface
buffer is always an integral number of blocks wide and high, and we expect
compression preprocessing to pad the source data properly.  Padding will occur
only to the next block (8-sample) boundary.  In an interleaved-scan situation,
additional dummy blocks may be used to fill out MCUs, but the MCU assembly and
disassembly logic will create or discard these blocks internally.  (This is
advantageous for speed reasons, since we avoid DCTing the dummy blocks.
It also permits a small reduction in file size, because the compressor can
choose dummy block contents so as to minimize their size in compressed form.
Finally, it makes the interface buffer specification independent of whether
the file is actually interleaved or not.)  Applications that wish to deal
directly with the downsampled data must provide similar buffering and padding
for odd-sized images.


*** Poor man's object-oriented programming ***

It should be clear by now that we have a lot of quasi-independent processing
steps, many of which have several possible behaviors.  To avoid cluttering the
code with lots of switch statements, we use a simple form of object-style
programming to separate out the different possibilities.

For example, two different color quantization algorithms could be implemented
as two separate modules that present the same external interface; at runtime,
the calling code will access the proper module indirectly through an "object".

We can get the limited features we need while staying within portable C.
The basic tool is a function pointer.  An "object" is just a struct
containing one or more function pointer fields, each of which corresponds to
a method name in real object-oriented languages.  During initialization we
fill in the function pointers with references to whichever module we have
determined we need to use in this run.  Then invocation of the module is done
by indirecting through a function pointer; on most machines this is no more
expensive than a switch statement, which would be the only other way of
making the required run-time choice.  The really significant benefit, of
course, is keeping the source code clean and well structured.

We can also arrange to have private storage that varies between different
implementations of the same kind of object.  We do this by making all the
module-specific object structs be separately allocated entities, which will
be accessed via pointers in the master compression or decompression struct.
The "public" fields or methods for a given kind of object are specified by
a commonly known struct.  But a module's initialization code can allocate
a larger struct that contains the common struct as its first member, plus
additional private fields.  With appropriate pointer casting, the module's