view release on metacpan or  search on metacpan

src/Source/LibJPEG/structure.txt  view on Meta::CPAN

IJG JPEG LIBRARY:  SYSTEM ARCHITECTURE

Copyright (C) 1991-2013, 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 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.txt 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.txt 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 array 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.  The library does not support the
hierarchical or lossless processes defined in the standard.

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.

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.