structure.doc

game engine, which is useful for everyone who is interested in it. I hope you can enjoy it.

This plan differs a little bit from usual object-oriented structures, in that
only one instance of each object class will exist during execution.  The
reason for having the class structure is that on different runs we may create
different instances (choose to execute different modules).  You can think of
the term "method" as denoting the common interface presented by a particular
set of interchangeable functions, and "object" as denoting a group of related
methods, or the total shared interface behavior of a group of modules.


*** Overall control structure ***

We previously mentioned the need for overall control logic in the compression
and decompression libraries.  In IJG implementations prior to v5, overall
control was mostly provided by "pipeline control" modules, which proved to be
large, unwieldy, and hard to understand.  To improve the situation, the
control logic has been subdivided into multiple modules.  The control modules
consist of:

1. Master control for module selection and initialization.  This has two
responsibilities:

   1A.  Startup initialization at the beginning of image processing.
        The individual processing modules to be used in this run are selected
        and given initialization calls.

   1B.  Per-pass control.  This determines how many passes will be performed
        and calls each active processing module to configure itself
        appropriately at the beginning of each pass.  End-of-pass processing,
	where necessary, is also invoked from the master control module.

   Method selection is partially distributed, in that a particular processing
   module may contain several possible implementations of a particular method,
   which it will select among when given its initialization call.  The master
   control code need only be concerned with decisions that affect more than
   one module.
 
2. Data buffering control.  A separate control module exists for each
   inter-processing-step data buffer.  This module is responsible for
   invoking the processing steps that write or read that data buffer.

Each buffer controller sees the world as follows:

input data => processing step A => buffer => processing step B => output data
                      |              |               |
              ------------------ controller ------------------

The controller knows the dataflow requirements of steps A and B: how much data
they want to accept in one chunk and how much they output in one chunk.  Its
function is to manage its buffer and call A and B at the proper times.

A data buffer control module may itself be viewed as a processing step by a
higher-level control module; thus the control modules form a binary tree with
elementary processing steps at the leaves of the tree.

The control modules are objects.  A considerable amount of flexibility can
be had by replacing implementations of a control module.  For example:
* Merging of adjacent steps in the pipeline is done by replacing a control
  module and its pair of processing-step modules with a single processing-
  step module.  (Hence the possible merges are determined by the tree of
  control modules.)
* In some processing modes, a given interstep buffer need only be a "strip"
  buffer large enough to accommodate the desired data chunk sizes.  In other
  modes, a full-image buffer is needed and several passes are required.
  The control module determines which kind of buffer is used and manipulates
  virtual array buffers as needed.  One or both processing steps may be
  unaware of the multi-pass behavior.

In theory, we might be able to make all of the data buffer controllers
interchangeable and provide just one set of implementations for all.  In
practice, each one contains considerable special-case processing for its
particular job.  The buffer controller concept should be regarded as an
overall system structuring principle, not as a complete description of the
task performed by any one controller.


*** Compression object structure ***

Here is a sketch of the logical structure of the JPEG compression library:

                                                 |-- Colorspace conversion
                  |-- Preprocessing controller --|
                  |                              |-- Downsampling
Main controller --|
                  |                            |-- Forward DCT, quantize
                  |-- Coefficient controller --|
                                               |-- Entropy encoding

This sketch also describes the flow of control (subroutine calls) during
typical image data processing.  Each of the components shown in the diagram is
an "object" which may have several different implementations available.  One
or more source code files contain the actual implementation(s) of each object.

The objects shown above are:

* Main controller: buffer controller for the subsampled-data buffer, which
  holds the preprocessed input data.  This controller invokes preprocessing to
  fill the subsampled-data buffer, and JPEG compression to empty it.  There is
  usually no need for a full-image buffer here; a strip buffer is adequate.

* Preprocessing controller: buffer controller for the downsampling input data
  buffer, which lies between colorspace conversion and downsampling.  Note
  that a unified conversion/downsampling module would probably replace this
  controller entirely.

* Colorspace conversion: converts application image data into the desired
  JPEG color space; also changes the data from pixel-interleaved layout to
  separate component planes.  Processes one pixel row at a time.

* Downsampling: performs reduction of chroma components as required.
  Optionally may perform pixel-level smoothing as well.  Processes a "row
  group" at a time, where a row group is defined as Vmax pixel rows of each
  component before downsampling, and Vk sample rows afterwards (remember Vk
  differs across components).  Some downsampling or smoothing algorithms may
  require context rows above and below the current row group; the
  preprocessing controller is responsible for supplying these rows via proper
  buffering.  The downsampler is responsible for edge expansion at the right
  edge (i.e., extending each sample row to a multiple of 8 samples); but the
  preprocessing controller is responsible for vertical edge expansion (i.e.,
  duplicating the bottom sample row as needed to make a multiple of 8 rows).

* Coefficient controller: buffer controller for the DCT-coefficient data.
  This controller handles MCU assembly, including insertion of dummy DCT
  blocks when needed at the right or bottom edge.  When performing
  Huffman-code optimization or emitting a multiscan JPEG file, this
  controller is responsible for buffering the full image.  The equivalent of
  one fully interleaved MCU row of subsampled data is processed per call,
  even when the JPEG file is noninterleaved.

* Forward DCT and quantization: Perform DCT, quantize, and emit coefficients.
  Works on one or more DCT blocks at a time.  (Note: the coefficients are now
  emitted in normal array order, which the entropy encoder is expected to
  convert to zigzag order as necessary.  Prior versions of the IJG code did
  the conversion to zigzag order within the quantization step.)

* Entropy encoding: Perform Huffman or arithmetic entropy coding and emit the
  coded data to the data destination module.  Works on one MCU per call.
  For progressive JPEG, the same DCT blocks are fed to the entropy coder
  during each pass, and the coder must emit the appropriate subset of
  coefficients.

In addition to the above objects, the compression library includes these
objects:

* Master control: determines the number of passes required, controls overall
  and per-pass initialization of the other modules.

* Marker writing: generates JPEG markers (except for RSTn, which is emitted
  by the entropy encoder when needed).

* Data destination manager: writes the output JPEG datastream to its final
  destination (e.g., a file).  The destination manager supplied with the
  library knows how to write to a stdio stream; for other behaviors, the
  surrounding application may provide its own destination manager.

* Memory manager: allocates and releases memory, controls virtual arrays
  (with backing store management, where required).

* Error handler: performs formatting and output of error and trace messages;
  determines handling of nonfatal errors.  The surrounding application may
  override some or all of this object's methods to change error handling.

* Progress monitor: supports output of "percent-done" progress reports.
  This object represents an optional callback to the surrounding application:
  if wanted, it must be supplied by the application.

The error handler, destination manager, and progress monitor objects are
defined as separate objects in order to simplify application-specific
customization of the JPEG library.  A surrounding application may override
individual methods or supply its own all-new implementation of one of these
objects.  The object interfaces for these objects are therefore treated as
part of the application interface of the library, whereas the other objects
are internal to the library.

The error handler and memory manager are shared by JPEG compression and
decompression; the progress monitor, if used, may be shared as well.


*** Decompression object structure ***

Here is a sketch of the logical structure of the JPEG decompression library:

                                               |-- Entropy decoding
                  |-- Coefficient controller --|
                  |                            |-- Dequantize, Inverse DCT
Main controller --|
                  |                               |-- Upsampling
                  |-- Postprocessing controller --|   |-- Colorspace conversion
                                                  |-- Color quantization
                                                  |-- Color precision reduction

As before, this diagram also represents typical control flow.  The objects
shown are:

* Main controller: buffer controller for the subsampled-data buffer, which
  holds the output of JPEG decompression proper.  This controller's primary
  task is to feed the postprocessing procedure.  Some upsampling algorithms
  may require context rows above and below the current row group; when this
  is true, the main controller is responsible for managing its buffer so as
  to make context rows available.  In the current design, the main buffer is
  always a strip buffer; a full-image buffer is never required.

* Coefficient controller: buffer controller for the DCT-coefficient data.
  This controller handles MCU disassembly, including deletion of any dummy
  DCT blocks at the right or bottom edge.  When reading a multiscan JPEG
  file, this controller is responsible for buffering the full image.
  (Buffering DCT coefficients, rather than samples, is necessary to support
  progressive JPEG.)  The equivalent of one fully interleaved MCU row of
  subsampled data is processed per call, even when the source JPEG file is
  noninterleaved.

* Entropy decoding: Read coded data from the data source module and perform
  Huffman or arithmetic entropy decoding.  Works on one MCU per call.
  For progressive JPEG decoding, the coefficient controller supplies the prior
  coefficients of each MCU (initially all zeroes), which the entropy decoder
  modifies in each scan.

* Dequantization and inverse DCT: like it says.  Note that the coefficients
  buffered by the coefficient controller have NOT been dequantized; we
  merge dequantization and inverse DCT into a single step for speed reasons.
  When scaled-down output is asked for, simplified DCT algorithms may be used
  that emit only 1x1, 2x2, or 4x4 samples per DCT block, not the full 8x8.
  Works on one DCT block at a time.

* Postprocessing controller: buffer controller for the color quantization
  input buffer, when quantization is in use.  (Without quantization, this
  controller just calls the upsampler.)  For two-pass quantization, this
  controller is responsible for buffering the full-image data.

* Upsampling: restores chroma components to full size.  (May support more
  general output rescaling, too.  Note that if undersized DCT outputs have
  been emitted by the DCT module, this module must adjust so that properly
  sized outputs are created.)  Works on one row group at a time.  This module
  also calls the color conversion module, so its top level is effectively a
  buffer controller for the upsampling->color conversion buffer.  However, in
  all but the highest-quality operating modes, upsampling and color
  conversion are likely to be merged into a single step.