Shoaib Ahmed / Mbed 2 deprecated uzairkhan

Final 350 project

Dependencies:   uzair Camera_LS_Y201 F7_Ethernet LCD_DISCO_F746NG NetworkAPI SDFileSystem mbed

includes/structure.txt@0:791a779d6220, 2017-07-31 (annotated)

Committer:
shoaib_ahmed
Date:
Mon Jul 31 09:16:35 2017 +0000
Revision:
0:791a779d6220
final project;

Who changed what in which revision?

UserRevisionLine numberNew contents of line
shoaib_ahmed 0:791a779d6220 1 IJG JPEG LIBRARY: SYSTEM ARCHITECTURE
shoaib_ahmed 0:791a779d6220 2
shoaib_ahmed 0:791a779d6220 3 Copyright (C) 1991-2013, Thomas G. Lane, Guido Vollbeding.
shoaib_ahmed 0:791a779d6220 4 This file is part of the Independent JPEG Group's software.
shoaib_ahmed 0:791a779d6220 5 For conditions of distribution and use, see the accompanying README file.
shoaib_ahmed 0:791a779d6220 6
shoaib_ahmed 0:791a779d6220 7
shoaib_ahmed 0:791a779d6220 8 This file provides an overview of the architecture of the IJG JPEG software;
shoaib_ahmed 0:791a779d6220 9 that is, the functions of the various modules in the system and the interfaces
shoaib_ahmed 0:791a779d6220 10 between modules. For more precise details about any data structure or calling
shoaib_ahmed 0:791a779d6220 11 convention, see the include files and comments in the source code.
shoaib_ahmed 0:791a779d6220 12
shoaib_ahmed 0:791a779d6220 13 We assume that the reader is already somewhat familiar with the JPEG standard.
shoaib_ahmed 0:791a779d6220 14 The README file includes references for learning about JPEG. The file
shoaib_ahmed 0:791a779d6220 15 libjpeg.txt describes the library from the viewpoint of an application
shoaib_ahmed 0:791a779d6220 16 programmer using the library; it's best to read that file before this one.
shoaib_ahmed 0:791a779d6220 17 Also, the file coderules.txt describes the coding style conventions we use.
shoaib_ahmed 0:791a779d6220 18
shoaib_ahmed 0:791a779d6220 19 In this document, JPEG-specific terminology follows the JPEG standard:
shoaib_ahmed 0:791a779d6220 20 A "component" means a color channel, e.g., Red or Luminance.
shoaib_ahmed 0:791a779d6220 21 A "sample" is a single component value (i.e., one number in the image data).
shoaib_ahmed 0:791a779d6220 22 A "coefficient" is a frequency coefficient (a DCT transform output number).
shoaib_ahmed 0:791a779d6220 23 A "block" is an array of samples or coefficients.
shoaib_ahmed 0:791a779d6220 24 An "MCU" (minimum coded unit) is an interleaved set of blocks of size
shoaib_ahmed 0:791a779d6220 25 determined by the sampling factors, or a single block in a
shoaib_ahmed 0:791a779d6220 26 noninterleaved scan.
shoaib_ahmed 0:791a779d6220 27 We do not use the terms "pixel" and "sample" interchangeably. When we say
shoaib_ahmed 0:791a779d6220 28 pixel, we mean an element of the full-size image, while a sample is an element
shoaib_ahmed 0:791a779d6220 29 of the downsampled image. Thus the number of samples may vary across
shoaib_ahmed 0:791a779d6220 30 components while the number of pixels does not. (This terminology is not used
shoaib_ahmed 0:791a779d6220 31 rigorously throughout the code, but it is used in places where confusion would
shoaib_ahmed 0:791a779d6220 32 otherwise result.)
shoaib_ahmed 0:791a779d6220 33
shoaib_ahmed 0:791a779d6220 34
shoaib_ahmed 0:791a779d6220 35 *** System features ***
shoaib_ahmed 0:791a779d6220 36
shoaib_ahmed 0:791a779d6220 37 The IJG distribution contains two parts:
shoaib_ahmed 0:791a779d6220 38 * A subroutine library for JPEG compression and decompression.
shoaib_ahmed 0:791a779d6220 39 * cjpeg/djpeg, two sample applications that use the library to transform
shoaib_ahmed 0:791a779d6220 40 JFIF JPEG files to and from several other image formats.
shoaib_ahmed 0:791a779d6220 41 cjpeg/djpeg are of no great intellectual complexity: they merely add a simple
shoaib_ahmed 0:791a779d6220 42 command-line user interface and I/O routines for several uncompressed image
shoaib_ahmed 0:791a779d6220 43 formats. This document concentrates on the library itself.
shoaib_ahmed 0:791a779d6220 44
shoaib_ahmed 0:791a779d6220 45 We desire the library to be capable of supporting all JPEG baseline, extended
shoaib_ahmed 0:791a779d6220 46 sequential, and progressive DCT processes. The library does not support the
shoaib_ahmed 0:791a779d6220 47 hierarchical or lossless processes defined in the standard.
shoaib_ahmed 0:791a779d6220 48
shoaib_ahmed 0:791a779d6220 49 Within these limits, any set of compression parameters allowed by the JPEG
shoaib_ahmed 0:791a779d6220 50 spec should be readable for decompression. (We can be more restrictive about
shoaib_ahmed 0:791a779d6220 51 what formats we can generate.) Although the system design allows for all
shoaib_ahmed 0:791a779d6220 52 parameter values, some uncommon settings are not yet implemented and may
shoaib_ahmed 0:791a779d6220 53 never be; nonintegral sampling ratios are the prime example. Furthermore,
shoaib_ahmed 0:791a779d6220 54 we treat 8-bit vs. 12-bit data precision as a compile-time switch, not a
shoaib_ahmed 0:791a779d6220 55 run-time option, because most machines can store 8-bit pixels much more
shoaib_ahmed 0:791a779d6220 56 compactly than 12-bit.
shoaib_ahmed 0:791a779d6220 57
shoaib_ahmed 0:791a779d6220 58 By itself, the library handles only interchange JPEG datastreams --- in
shoaib_ahmed 0:791a779d6220 59 particular the widely used JFIF file format. The library can be used by
shoaib_ahmed 0:791a779d6220 60 surrounding code to process interchange or abbreviated JPEG datastreams that
shoaib_ahmed 0:791a779d6220 61 are embedded in more complex file formats. (For example, libtiff uses this
shoaib_ahmed 0:791a779d6220 62 library to implement JPEG compression within the TIFF file format.)
shoaib_ahmed 0:791a779d6220 63
shoaib_ahmed 0:791a779d6220 64 The library includes a substantial amount of code that is not covered by the
shoaib_ahmed 0:791a779d6220 65 JPEG standard but is necessary for typical applications of JPEG. These
shoaib_ahmed 0:791a779d6220 66 functions preprocess the image before JPEG compression or postprocess it after
shoaib_ahmed 0:791a779d6220 67 decompression. They include colorspace conversion, downsampling/upsampling,
shoaib_ahmed 0:791a779d6220 68 and color quantization. This code can be omitted if not needed.
shoaib_ahmed 0:791a779d6220 69
shoaib_ahmed 0:791a779d6220 70 A wide range of quality vs. speed tradeoffs are possible in JPEG processing,
shoaib_ahmed 0:791a779d6220 71 and even more so in decompression postprocessing. The decompression library
shoaib_ahmed 0:791a779d6220 72 provides multiple implementations that cover most of the useful tradeoffs,
shoaib_ahmed 0:791a779d6220 73 ranging from very-high-quality down to fast-preview operation. On the
shoaib_ahmed 0:791a779d6220 74 compression side we have generally not provided low-quality choices, since
shoaib_ahmed 0:791a779d6220 75 compression is normally less time-critical. It should be understood that the
shoaib_ahmed 0:791a779d6220 76 low-quality modes may not meet the JPEG standard's accuracy requirements;
shoaib_ahmed 0:791a779d6220 77 nonetheless, they are useful for viewers.
shoaib_ahmed 0:791a779d6220 78
shoaib_ahmed 0:791a779d6220 79
shoaib_ahmed 0:791a779d6220 80 *** Portability issues ***
shoaib_ahmed 0:791a779d6220 81
shoaib_ahmed 0:791a779d6220 82 Portability is an essential requirement for the library. The key portability
shoaib_ahmed 0:791a779d6220 83 issues that show up at the level of system architecture are:
shoaib_ahmed 0:791a779d6220 84
shoaib_ahmed 0:791a779d6220 85 1. Memory usage. We want the code to be able to run on PC-class machines
shoaib_ahmed 0:791a779d6220 86 with limited memory. Images should therefore be processed sequentially (in
shoaib_ahmed 0:791a779d6220 87 strips), to avoid holding the whole image in memory at once. Where a
shoaib_ahmed 0:791a779d6220 88 full-image buffer is necessary, we should be able to use either virtual memory
shoaib_ahmed 0:791a779d6220 89 or temporary files.
shoaib_ahmed 0:791a779d6220 90
shoaib_ahmed 0:791a779d6220 91 2. Near/far pointer distinction. To run efficiently on 80x86 machines, the
shoaib_ahmed 0:791a779d6220 92 code should distinguish "small" objects (kept in near data space) from
shoaib_ahmed 0:791a779d6220 93 "large" ones (kept in far data space). This is an annoying restriction, but
shoaib_ahmed 0:791a779d6220 94 fortunately it does not impact code quality for less brain-damaged machines,
shoaib_ahmed 0:791a779d6220 95 and the source code clutter turns out to be minimal with sufficient use of
shoaib_ahmed 0:791a779d6220 96 pointer typedefs.
shoaib_ahmed 0:791a779d6220 97
shoaib_ahmed 0:791a779d6220 98 3. Data precision. We assume that "char" is at least 8 bits, "short" and
shoaib_ahmed 0:791a779d6220 99 "int" at least 16, "long" at least 32. The code will work fine with larger
shoaib_ahmed 0:791a779d6220 100 data sizes, although memory may be used inefficiently in some cases. However,
shoaib_ahmed 0:791a779d6220 101 the JPEG compressed datastream must ultimately appear on external storage as a
shoaib_ahmed 0:791a779d6220 102 sequence of 8-bit bytes if it is to conform to the standard. This may pose a
shoaib_ahmed 0:791a779d6220 103 problem on machines where char is wider than 8 bits. The library represents
shoaib_ahmed 0:791a779d6220 104 compressed data as an array of values of typedef JOCTET. If no data type
shoaib_ahmed 0:791a779d6220 105 exactly 8 bits wide is available, custom data source and data destination
shoaib_ahmed 0:791a779d6220 106 modules must be written to unpack and pack the chosen JOCTET datatype into
shoaib_ahmed 0:791a779d6220 107 8-bit external representation.
shoaib_ahmed 0:791a779d6220 108
shoaib_ahmed 0:791a779d6220 109
shoaib_ahmed 0:791a779d6220 110 *** System overview ***
shoaib_ahmed 0:791a779d6220 111
shoaib_ahmed 0:791a779d6220 112 The compressor and decompressor are each divided into two main sections:
shoaib_ahmed 0:791a779d6220 113 the JPEG compressor or decompressor proper, and the preprocessing or
shoaib_ahmed 0:791a779d6220 114 postprocessing functions. The interface between these two sections is the
shoaib_ahmed 0:791a779d6220 115 image data that the official JPEG spec regards as its input or output: this
shoaib_ahmed 0:791a779d6220 116 data is in the colorspace to be used for compression, and it is downsampled
shoaib_ahmed 0:791a779d6220 117 to the sampling factors to be used. The preprocessing and postprocessing
shoaib_ahmed 0:791a779d6220 118 steps are responsible for converting a normal image representation to or from
shoaib_ahmed 0:791a779d6220 119 this form. (Those few applications that want to deal with YCbCr downsampled
shoaib_ahmed 0:791a779d6220 120 data can skip the preprocessing or postprocessing step.)
shoaib_ahmed 0:791a779d6220 121
shoaib_ahmed 0:791a779d6220 122 Looking more closely, the compressor library contains the following main
shoaib_ahmed 0:791a779d6220 123 elements:
shoaib_ahmed 0:791a779d6220 124
shoaib_ahmed 0:791a779d6220 125 Preprocessing:
shoaib_ahmed 0:791a779d6220 126 * Color space conversion (e.g., RGB to YCbCr).
shoaib_ahmed 0:791a779d6220 127 * Edge expansion and downsampling. Optionally, this step can do simple
shoaib_ahmed 0:791a779d6220 128 smoothing --- this is often helpful for low-quality source data.
shoaib_ahmed 0:791a779d6220 129 JPEG proper:
shoaib_ahmed 0:791a779d6220 130 * MCU assembly, DCT, quantization.
shoaib_ahmed 0:791a779d6220 131 * Entropy coding (sequential or progressive, Huffman or arithmetic).
shoaib_ahmed 0:791a779d6220 132
shoaib_ahmed 0:791a779d6220 133 In addition to these modules we need overall control, marker generation,
shoaib_ahmed 0:791a779d6220 134 and support code (memory management & error handling). There is also a
shoaib_ahmed 0:791a779d6220 135 module responsible for physically writing the output data --- typically
shoaib_ahmed 0:791a779d6220 136 this is just an interface to fwrite(), but some applications may need to
shoaib_ahmed 0:791a779d6220 137 do something else with the data.
shoaib_ahmed 0:791a779d6220 138
shoaib_ahmed 0:791a779d6220 139 The decompressor library contains the following main elements:
shoaib_ahmed 0:791a779d6220 140
shoaib_ahmed 0:791a779d6220 141 JPEG proper:
shoaib_ahmed 0:791a779d6220 142 * Entropy decoding (sequential or progressive, Huffman or arithmetic).
shoaib_ahmed 0:791a779d6220 143 * Dequantization, inverse DCT, MCU disassembly.
shoaib_ahmed 0:791a779d6220 144 Postprocessing:
shoaib_ahmed 0:791a779d6220 145 * Upsampling. Optionally, this step may be able to do more general
shoaib_ahmed 0:791a779d6220 146 rescaling of the image.
shoaib_ahmed 0:791a779d6220 147 * Color space conversion (e.g., YCbCr to RGB). This step may also
shoaib_ahmed 0:791a779d6220 148 provide gamma adjustment [ currently it does not ].
shoaib_ahmed 0:791a779d6220 149 * Optional color quantization (e.g., reduction to 256 colors).
shoaib_ahmed 0:791a779d6220 150 * Optional color precision reduction (e.g., 24-bit to 15-bit color).
shoaib_ahmed 0:791a779d6220 151 [This feature is not currently implemented.]
shoaib_ahmed 0:791a779d6220 152
shoaib_ahmed 0:791a779d6220 153 We also need overall control, marker parsing, and a data source module.
shoaib_ahmed 0:791a779d6220 154 The support code (memory management & error handling) can be shared with
shoaib_ahmed 0:791a779d6220 155 the compression half of the library.
shoaib_ahmed 0:791a779d6220 156
shoaib_ahmed 0:791a779d6220 157 There may be several implementations of each of these elements, particularly
shoaib_ahmed 0:791a779d6220 158 in the decompressor, where a wide range of speed/quality tradeoffs is very
shoaib_ahmed 0:791a779d6220 159 useful. It must be understood that some of the best speedups involve
shoaib_ahmed 0:791a779d6220 160 merging adjacent steps in the pipeline. For example, upsampling, color space
shoaib_ahmed 0:791a779d6220 161 conversion, and color quantization might all be done at once when using a
shoaib_ahmed 0:791a779d6220 162 low-quality ordered-dither technique. The system architecture is designed to
shoaib_ahmed 0:791a779d6220 163 allow such merging where appropriate.
shoaib_ahmed 0:791a779d6220 164
shoaib_ahmed 0:791a779d6220 165
shoaib_ahmed 0:791a779d6220 166 Note: it is convenient to regard edge expansion (padding to block boundaries)
shoaib_ahmed 0:791a779d6220 167 as a preprocessing/postprocessing function, even though the JPEG spec includes
shoaib_ahmed 0:791a779d6220 168 it in compression/decompression. We do this because downsampling/upsampling
shoaib_ahmed 0:791a779d6220 169 can be simplified a little if they work on padded data: it's not necessary to
shoaib_ahmed 0:791a779d6220 170 have special cases at the right and bottom edges. Therefore the interface
shoaib_ahmed 0:791a779d6220 171 buffer is always an integral number of blocks wide and high, and we expect
shoaib_ahmed 0:791a779d6220 172 compression preprocessing to pad the source data properly. Padding will occur
shoaib_ahmed 0:791a779d6220 173 only to the next block (block_size-sample) boundary. In an interleaved-scan
shoaib_ahmed 0:791a779d6220 174 situation, additional dummy blocks may be used to fill out MCUs, but the MCU
shoaib_ahmed 0:791a779d6220 175 assembly and disassembly logic will create or discard these blocks internally.
shoaib_ahmed 0:791a779d6220 176 (This is advantageous for speed reasons, since we avoid DCTing the dummy
shoaib_ahmed 0:791a779d6220 177 blocks. It also permits a small reduction in file size, because the
shoaib_ahmed 0:791a779d6220 178 compressor can choose dummy block contents so as to minimize their size
shoaib_ahmed 0:791a779d6220 179 in compressed form. Finally, it makes the interface buffer specification
shoaib_ahmed 0:791a779d6220 180 independent of whether the file is actually interleaved or not.)
shoaib_ahmed 0:791a779d6220 181 Applications that wish to deal directly with the downsampled data must
shoaib_ahmed 0:791a779d6220 182 provide similar buffering and padding for odd-sized images.
shoaib_ahmed 0:791a779d6220 183
shoaib_ahmed 0:791a779d6220 184
shoaib_ahmed 0:791a779d6220 185 *** Poor man's object-oriented programming ***
shoaib_ahmed 0:791a779d6220 186
shoaib_ahmed 0:791a779d6220 187 It should be clear by now that we have a lot of quasi-independent processing
shoaib_ahmed 0:791a779d6220 188 steps, many of which have several possible behaviors. To avoid cluttering the
shoaib_ahmed 0:791a779d6220 189 code with lots of switch statements, we use a simple form of object-style
shoaib_ahmed 0:791a779d6220 190 programming to separate out the different possibilities.
shoaib_ahmed 0:791a779d6220 191
shoaib_ahmed 0:791a779d6220 192 For example, two different color quantization algorithms could be implemented
shoaib_ahmed 0:791a779d6220 193 as two separate modules that present the same external interface; at runtime,
shoaib_ahmed 0:791a779d6220 194 the calling code will access the proper module indirectly through an "object".
shoaib_ahmed 0:791a779d6220 195
shoaib_ahmed 0:791a779d6220 196 We can get the limited features we need while staying within portable C.
shoaib_ahmed 0:791a779d6220 197 The basic tool is a function pointer. An "object" is just a struct
shoaib_ahmed 0:791a779d6220 198 containing one or more function pointer fields, each of which corresponds to
shoaib_ahmed 0:791a779d6220 199 a method name in real object-oriented languages. During initialization we
shoaib_ahmed 0:791a779d6220 200 fill in the function pointers with references to whichever module we have
shoaib_ahmed 0:791a779d6220 201 determined we need to use in this run. Then invocation of the module is done
shoaib_ahmed 0:791a779d6220 202 by indirecting through a function pointer; on most machines this is no more
shoaib_ahmed 0:791a779d6220 203 expensive than a switch statement, which would be the only other way of
shoaib_ahmed 0:791a779d6220 204 making the required run-time choice. The really significant benefit, of
shoaib_ahmed 0:791a779d6220 205 course, is keeping the source code clean and well structured.
shoaib_ahmed 0:791a779d6220 206
shoaib_ahmed 0:791a779d6220 207 We can also arrange to have private storage that varies between different
shoaib_ahmed 0:791a779d6220 208 implementations of the same kind of object. We do this by making all the
shoaib_ahmed 0:791a779d6220 209 module-specific object structs be separately allocated entities, which will
shoaib_ahmed 0:791a779d6220 210 be accessed via pointers in the master compression or decompression struct.
shoaib_ahmed 0:791a779d6220 211 The "public" fields or methods for a given kind of object are specified by
shoaib_ahmed 0:791a779d6220 212 a commonly known struct. But a module's initialization code can allocate
shoaib_ahmed 0:791a779d6220 213 a larger struct that contains the common struct as its first member, plus
shoaib_ahmed 0:791a779d6220 214 additional private fields. With appropriate pointer casting, the module's
shoaib_ahmed 0:791a779d6220 215 internal functions can access these private fields. (For a simple example,
shoaib_ahmed 0:791a779d6220 216 see jdatadst.c, which implements the external interface specified by struct
shoaib_ahmed 0:791a779d6220 217 jpeg_destination_mgr, but adds extra fields.)
shoaib_ahmed 0:791a779d6220 218
shoaib_ahmed 0:791a779d6220 219 (Of course this would all be a lot easier if we were using C++, but we are
shoaib_ahmed 0:791a779d6220 220 not yet prepared to assume that everyone has a C++ compiler.)
shoaib_ahmed 0:791a779d6220 221
shoaib_ahmed 0:791a779d6220 222 An important benefit of this scheme is that it is easy to provide multiple
shoaib_ahmed 0:791a779d6220 223 versions of any method, each tuned to a particular case. While a lot of
shoaib_ahmed 0:791a779d6220 224 precalculation might be done to select an optimal implementation of a method,
shoaib_ahmed 0:791a779d6220 225 the cost per invocation is constant. For example, the upsampling step might
shoaib_ahmed 0:791a779d6220 226 have a "generic" method, plus one or more "hardwired" methods for the most
shoaib_ahmed 0:791a779d6220 227 popular sampling factors; the hardwired methods would be faster because they'd
shoaib_ahmed 0:791a779d6220 228 use straight-line code instead of for-loops. The cost to determine which
shoaib_ahmed 0:791a779d6220 229 method to use is paid only once, at startup, and the selection criteria are
shoaib_ahmed 0:791a779d6220 230 hidden from the callers of the method.
shoaib_ahmed 0:791a779d6220 231
shoaib_ahmed 0:791a779d6220 232 This plan differs a little bit from usual object-oriented structures, in that
shoaib_ahmed 0:791a779d6220 233 only one instance of each object class will exist during execution. The
shoaib_ahmed 0:791a779d6220 234 reason for having the class structure is that on different runs we may create
shoaib_ahmed 0:791a779d6220 235 different instances (choose to execute different modules). You can think of
shoaib_ahmed 0:791a779d6220 236 the term "method" as denoting the common interface presented by a particular
shoaib_ahmed 0:791a779d6220 237 set of interchangeable functions, and "object" as denoting a group of related
shoaib_ahmed 0:791a779d6220 238 methods, or the total shared interface behavior of a group of modules.
shoaib_ahmed 0:791a779d6220 239
shoaib_ahmed 0:791a779d6220 240
shoaib_ahmed 0:791a779d6220 241 *** Overall control structure ***
shoaib_ahmed 0:791a779d6220 242
shoaib_ahmed 0:791a779d6220 243 We previously mentioned the need for overall control logic in the compression
shoaib_ahmed 0:791a779d6220 244 and decompression libraries. In IJG implementations prior to v5, overall
shoaib_ahmed 0:791a779d6220 245 control was mostly provided by "pipeline control" modules, which proved to be
shoaib_ahmed 0:791a779d6220 246 large, unwieldy, and hard to understand. To improve the situation, the
shoaib_ahmed 0:791a779d6220 247 control logic has been subdivided into multiple modules. The control modules
shoaib_ahmed 0:791a779d6220 248 consist of:
shoaib_ahmed 0:791a779d6220 249
shoaib_ahmed 0:791a779d6220 250 1. Master control for module selection and initialization. This has two
shoaib_ahmed 0:791a779d6220 251 responsibilities:
shoaib_ahmed 0:791a779d6220 252
shoaib_ahmed 0:791a779d6220 253 1A. Startup initialization at the beginning of image processing.
shoaib_ahmed 0:791a779d6220 254 The individual processing modules to be used in this run are selected
shoaib_ahmed 0:791a779d6220 255 and given initialization calls.
shoaib_ahmed 0:791a779d6220 256
shoaib_ahmed 0:791a779d6220 257 1B. Per-pass control. This determines how many passes will be performed
shoaib_ahmed 0:791a779d6220 258 and calls each active processing module to configure itself
shoaib_ahmed 0:791a779d6220 259 appropriately at the beginning of each pass. End-of-pass processing,
shoaib_ahmed 0:791a779d6220 260 where necessary, is also invoked from the master control module.
shoaib_ahmed 0:791a779d6220 261
shoaib_ahmed 0:791a779d6220 262 Method selection is partially distributed, in that a particular processing
shoaib_ahmed 0:791a779d6220 263 module may contain several possible implementations of a particular method,
shoaib_ahmed 0:791a779d6220 264 which it will select among when given its initialization call. The master
shoaib_ahmed 0:791a779d6220 265 control code need only be concerned with decisions that affect more than
shoaib_ahmed 0:791a779d6220 266 one module.
shoaib_ahmed 0:791a779d6220 267
shoaib_ahmed 0:791a779d6220 268 2. Data buffering control. A separate control module exists for each
shoaib_ahmed 0:791a779d6220 269 inter-processing-step data buffer. This module is responsible for
shoaib_ahmed 0:791a779d6220 270 invoking the processing steps that write or read that data buffer.
shoaib_ahmed 0:791a779d6220 271
shoaib_ahmed 0:791a779d6220 272 Each buffer controller sees the world as follows:
shoaib_ahmed 0:791a779d6220 273
shoaib_ahmed 0:791a779d6220 274 input data => processing step A => buffer => processing step B => output data
shoaib_ahmed 0:791a779d6220 275 | | |
shoaib_ahmed 0:791a779d6220 276 ------------------ controller ------------------
shoaib_ahmed 0:791a779d6220 277
shoaib_ahmed 0:791a779d6220 278 The controller knows the dataflow requirements of steps A and B: how much data
shoaib_ahmed 0:791a779d6220 279 they want to accept in one chunk and how much they output in one chunk. Its
shoaib_ahmed 0:791a779d6220 280 function is to manage its buffer and call A and B at the proper times.
shoaib_ahmed 0:791a779d6220 281
shoaib_ahmed 0:791a779d6220 282 A data buffer control module may itself be viewed as a processing step by a
shoaib_ahmed 0:791a779d6220 283 higher-level control module; thus the control modules form a binary tree with
shoaib_ahmed 0:791a779d6220 284 elementary processing steps at the leaves of the tree.
shoaib_ahmed 0:791a779d6220 285
shoaib_ahmed 0:791a779d6220 286 The control modules are objects. A considerable amount of flexibility can
shoaib_ahmed 0:791a779d6220 287 be had by replacing implementations of a control module. For example:
shoaib_ahmed 0:791a779d6220 288 * Merging of adjacent steps in the pipeline is done by replacing a control
shoaib_ahmed 0:791a779d6220 289 module and its pair of processing-step modules with a single processing-
shoaib_ahmed 0:791a779d6220 290 step module. (Hence the possible merges are determined by the tree of
shoaib_ahmed 0:791a779d6220 291 control modules.)
shoaib_ahmed 0:791a779d6220 292 * In some processing modes, a given interstep buffer need only be a "strip"
shoaib_ahmed 0:791a779d6220 293 buffer large enough to accommodate the desired data chunk sizes. In other
shoaib_ahmed 0:791a779d6220 294 modes, a full-image buffer is needed and several passes are required.
shoaib_ahmed 0:791a779d6220 295 The control module determines which kind of buffer is used and manipulates
shoaib_ahmed 0:791a779d6220 296 virtual array buffers as needed. One or both processing steps may be
shoaib_ahmed 0:791a779d6220 297 unaware of the multi-pass behavior.
shoaib_ahmed 0:791a779d6220 298
shoaib_ahmed 0:791a779d6220 299 In theory, we might be able to make all of the data buffer controllers
shoaib_ahmed 0:791a779d6220 300 interchangeable and provide just one set of implementations for all. In
shoaib_ahmed 0:791a779d6220 301 practice, each one contains considerable special-case processing for its
shoaib_ahmed 0:791a779d6220 302 particular job. The buffer controller concept should be regarded as an
shoaib_ahmed 0:791a779d6220 303 overall system structuring principle, not as a complete description of the
shoaib_ahmed 0:791a779d6220 304 task performed by any one controller.
shoaib_ahmed 0:791a779d6220 305
shoaib_ahmed 0:791a779d6220 306
shoaib_ahmed 0:791a779d6220 307 *** Compression object structure ***
shoaib_ahmed 0:791a779d6220 308
shoaib_ahmed 0:791a779d6220 309 Here is a sketch of the logical structure of the JPEG compression library:
shoaib_ahmed 0:791a779d6220 310
shoaib_ahmed 0:791a779d6220 311 |-- Colorspace conversion
shoaib_ahmed 0:791a779d6220 312 |-- Preprocessing controller --|
shoaib_ahmed 0:791a779d6220 313 | |-- Downsampling
shoaib_ahmed 0:791a779d6220 314 Main controller --|
shoaib_ahmed 0:791a779d6220 315 | |-- Forward DCT, quantize
shoaib_ahmed 0:791a779d6220 316 |-- Coefficient controller --|
shoaib_ahmed 0:791a779d6220 317 |-- Entropy encoding
shoaib_ahmed 0:791a779d6220 318
shoaib_ahmed 0:791a779d6220 319 This sketch also describes the flow of control (subroutine calls) during
shoaib_ahmed 0:791a779d6220 320 typical image data processing. Each of the components shown in the diagram is
shoaib_ahmed 0:791a779d6220 321 an "object" which may have several different implementations available. One
shoaib_ahmed 0:791a779d6220 322 or more source code files contain the actual implementation(s) of each object.
shoaib_ahmed 0:791a779d6220 323
shoaib_ahmed 0:791a779d6220 324 The objects shown above are:
shoaib_ahmed 0:791a779d6220 325
shoaib_ahmed 0:791a779d6220 326 * Main controller: buffer controller for the subsampled-data buffer, which
shoaib_ahmed 0:791a779d6220 327 holds the preprocessed input data. This controller invokes preprocessing to
shoaib_ahmed 0:791a779d6220 328 fill the subsampled-data buffer, and JPEG compression to empty it. There is
shoaib_ahmed 0:791a779d6220 329 usually no need for a full-image buffer here; a strip buffer is adequate.
shoaib_ahmed 0:791a779d6220 330
shoaib_ahmed 0:791a779d6220 331 * Preprocessing controller: buffer controller for the downsampling input data
shoaib_ahmed 0:791a779d6220 332 buffer, which lies between colorspace conversion and downsampling. Note
shoaib_ahmed 0:791a779d6220 333 that a unified conversion/downsampling module would probably replace this
shoaib_ahmed 0:791a779d6220 334 controller entirely.
shoaib_ahmed 0:791a779d6220 335
shoaib_ahmed 0:791a779d6220 336 * Colorspace conversion: converts application image data into the desired
shoaib_ahmed 0:791a779d6220 337 JPEG color space; also changes the data from pixel-interleaved layout to
shoaib_ahmed 0:791a779d6220 338 separate component planes. Processes one pixel row at a time.
shoaib_ahmed 0:791a779d6220 339
shoaib_ahmed 0:791a779d6220 340 * Downsampling: performs reduction of chroma components as required.
shoaib_ahmed 0:791a779d6220 341 Optionally may perform pixel-level smoothing as well. Processes a "row
shoaib_ahmed 0:791a779d6220 342 group" at a time, where a row group is defined as Vmax pixel rows of each
shoaib_ahmed 0:791a779d6220 343 component before downsampling, and Vk sample rows afterwards (remember Vk
shoaib_ahmed 0:791a779d6220 344 differs across components). Some downsampling or smoothing algorithms may
shoaib_ahmed 0:791a779d6220 345 require context rows above and below the current row group; the
shoaib_ahmed 0:791a779d6220 346 preprocessing controller is responsible for supplying these rows via proper
shoaib_ahmed 0:791a779d6220 347 buffering. The downsampler is responsible for edge expansion at the right
shoaib_ahmed 0:791a779d6220 348 edge (i.e., extending each sample row to a multiple of block_size samples);
shoaib_ahmed 0:791a779d6220 349 but the preprocessing controller is responsible for vertical edge expansion
shoaib_ahmed 0:791a779d6220 350 (i.e., duplicating the bottom sample row as needed to make a multiple of
shoaib_ahmed 0:791a779d6220 351 block_size rows).
shoaib_ahmed 0:791a779d6220 352
shoaib_ahmed 0:791a779d6220 353 * Coefficient controller: buffer controller for the DCT-coefficient data.
shoaib_ahmed 0:791a779d6220 354 This controller handles MCU assembly, including insertion of dummy DCT
shoaib_ahmed 0:791a779d6220 355 blocks when needed at the right or bottom edge. When performing
shoaib_ahmed 0:791a779d6220 356 Huffman-code optimization or emitting a multiscan JPEG file, this
shoaib_ahmed 0:791a779d6220 357 controller is responsible for buffering the full image. The equivalent of
shoaib_ahmed 0:791a779d6220 358 one fully interleaved MCU row of subsampled data is processed per call,
shoaib_ahmed 0:791a779d6220 359 even when the JPEG file is noninterleaved.
shoaib_ahmed 0:791a779d6220 360
shoaib_ahmed 0:791a779d6220 361 * Forward DCT and quantization: Perform DCT, quantize, and emit coefficients.
shoaib_ahmed 0:791a779d6220 362 Works on one or more DCT blocks at a time. (Note: the coefficients are now
shoaib_ahmed 0:791a779d6220 363 emitted in normal array order, which the entropy encoder is expected to
shoaib_ahmed 0:791a779d6220 364 convert to zigzag order as necessary. Prior versions of the IJG code did
shoaib_ahmed 0:791a779d6220 365 the conversion to zigzag order within the quantization step.)
shoaib_ahmed 0:791a779d6220 366
shoaib_ahmed 0:791a779d6220 367 * Entropy encoding: Perform Huffman or arithmetic entropy coding and emit the
shoaib_ahmed 0:791a779d6220 368 coded data to the data destination module. Works on one MCU per call.
shoaib_ahmed 0:791a779d6220 369 For progressive JPEG, the same DCT blocks are fed to the entropy coder
shoaib_ahmed 0:791a779d6220 370 during each pass, and the coder must emit the appropriate subset of
shoaib_ahmed 0:791a779d6220 371 coefficients.
shoaib_ahmed 0:791a779d6220 372
shoaib_ahmed 0:791a779d6220 373 In addition to the above objects, the compression library includes these
shoaib_ahmed 0:791a779d6220 374 objects:
shoaib_ahmed 0:791a779d6220 375
shoaib_ahmed 0:791a779d6220 376 * Master control: determines the number of passes required, controls overall
shoaib_ahmed 0:791a779d6220 377 and per-pass initialization of the other modules.
shoaib_ahmed 0:791a779d6220 378
shoaib_ahmed 0:791a779d6220 379 * Marker writing: generates JPEG markers (except for RSTn, which is emitted
shoaib_ahmed 0:791a779d6220 380 by the entropy encoder when needed).
shoaib_ahmed 0:791a779d6220 381
shoaib_ahmed 0:791a779d6220 382 * Data destination manager: writes the output JPEG datastream to its final
shoaib_ahmed 0:791a779d6220 383 destination (e.g., a file). The destination manager supplied with the
shoaib_ahmed 0:791a779d6220 384 library knows how to write to a stdio stream or to a memory buffer;
shoaib_ahmed 0:791a779d6220 385 for other behaviors, the surrounding application may provide its own
shoaib_ahmed 0:791a779d6220 386 destination manager.
shoaib_ahmed 0:791a779d6220 387
shoaib_ahmed 0:791a779d6220 388 * Memory manager: allocates and releases memory, controls virtual arrays
shoaib_ahmed 0:791a779d6220 389 (with backing store management, where required).
shoaib_ahmed 0:791a779d6220 390
shoaib_ahmed 0:791a779d6220 391 * Error handler: performs formatting and output of error and trace messages;
shoaib_ahmed 0:791a779d6220 392 determines handling of nonfatal errors. The surrounding application may
shoaib_ahmed 0:791a779d6220 393 override some or all of this object's methods to change error handling.
shoaib_ahmed 0:791a779d6220 394
shoaib_ahmed 0:791a779d6220 395 * Progress monitor: supports output of "percent-done" progress reports.
shoaib_ahmed 0:791a779d6220 396 This object represents an optional callback to the surrounding application:
shoaib_ahmed 0:791a779d6220 397 if wanted, it must be supplied by the application.
shoaib_ahmed 0:791a779d6220 398
shoaib_ahmed 0:791a779d6220 399 The error handler, destination manager, and progress monitor objects are
shoaib_ahmed 0:791a779d6220 400 defined as separate objects in order to simplify application-specific
shoaib_ahmed 0:791a779d6220 401 customization of the JPEG library. A surrounding application may override
shoaib_ahmed 0:791a779d6220 402 individual methods or supply its own all-new implementation of one of these
shoaib_ahmed 0:791a779d6220 403 objects. The object interfaces for these objects are therefore treated as
shoaib_ahmed 0:791a779d6220 404 part of the application interface of the library, whereas the other objects
shoaib_ahmed 0:791a779d6220 405 are internal to the library.
shoaib_ahmed 0:791a779d6220 406
shoaib_ahmed 0:791a779d6220 407 The error handler and memory manager are shared by JPEG compression and
shoaib_ahmed 0:791a779d6220 408 decompression; the progress monitor, if used, may be shared as well.
shoaib_ahmed 0:791a779d6220 409
shoaib_ahmed 0:791a779d6220 410
shoaib_ahmed 0:791a779d6220 411 *** Decompression object structure ***
shoaib_ahmed 0:791a779d6220 412
shoaib_ahmed 0:791a779d6220 413 Here is a sketch of the logical structure of the JPEG decompression library:
shoaib_ahmed 0:791a779d6220 414
shoaib_ahmed 0:791a779d6220 415 |-- Entropy decoding
shoaib_ahmed 0:791a779d6220 416 |-- Coefficient controller --|
shoaib_ahmed 0:791a779d6220 417 | |-- Dequantize, Inverse DCT
shoaib_ahmed 0:791a779d6220 418 Main controller --|
shoaib_ahmed 0:791a779d6220 419 | |-- Upsampling
shoaib_ahmed 0:791a779d6220 420 |-- Postprocessing controller --| |-- Colorspace conversion
shoaib_ahmed 0:791a779d6220 421 |-- Color quantization
shoaib_ahmed 0:791a779d6220 422 |-- Color precision reduction
shoaib_ahmed 0:791a779d6220 423
shoaib_ahmed 0:791a779d6220 424 As before, this diagram also represents typical control flow. The objects
shoaib_ahmed 0:791a779d6220 425 shown are:
shoaib_ahmed 0:791a779d6220 426
shoaib_ahmed 0:791a779d6220 427 * Main controller: buffer controller for the subsampled-data buffer, which
shoaib_ahmed 0:791a779d6220 428 holds the output of JPEG decompression proper. This controller's primary
shoaib_ahmed 0:791a779d6220 429 task is to feed the postprocessing procedure. Some upsampling algorithms
shoaib_ahmed 0:791a779d6220 430 may require context rows above and below the current row group; when this
shoaib_ahmed 0:791a779d6220 431 is true, the main controller is responsible for managing its buffer so as
shoaib_ahmed 0:791a779d6220 432 to make context rows available. In the current design, the main buffer is
shoaib_ahmed 0:791a779d6220 433 always a strip buffer; a full-image buffer is never required.
shoaib_ahmed 0:791a779d6220 434
shoaib_ahmed 0:791a779d6220 435 * Coefficient controller: buffer controller for the DCT-coefficient data.
shoaib_ahmed 0:791a779d6220 436 This controller handles MCU disassembly, including deletion of any dummy
shoaib_ahmed 0:791a779d6220 437 DCT blocks at the right or bottom edge. When reading a multiscan JPEG
shoaib_ahmed 0:791a779d6220 438 file, this controller is responsible for buffering the full image.
shoaib_ahmed 0:791a779d6220 439 (Buffering DCT coefficients, rather than samples, is necessary to support
shoaib_ahmed 0:791a779d6220 440 progressive JPEG.) The equivalent of one fully interleaved MCU row of
shoaib_ahmed 0:791a779d6220 441 subsampled data is processed per call, even when the source JPEG file is
shoaib_ahmed 0:791a779d6220 442 noninterleaved.
shoaib_ahmed 0:791a779d6220 443
shoaib_ahmed 0:791a779d6220 444 * Entropy decoding: Read coded data from the data source module and perform
shoaib_ahmed 0:791a779d6220 445 Huffman or arithmetic entropy decoding. Works on one MCU per call.
shoaib_ahmed 0:791a779d6220 446 For progressive JPEG decoding, the coefficient controller supplies the prior
shoaib_ahmed 0:791a779d6220 447 coefficients of each MCU (initially all zeroes), which the entropy decoder
shoaib_ahmed 0:791a779d6220 448 modifies in each scan.
shoaib_ahmed 0:791a779d6220 449
shoaib_ahmed 0:791a779d6220 450 * Dequantization and inverse DCT: like it says. Note that the coefficients
shoaib_ahmed 0:791a779d6220 451 buffered by the coefficient controller have NOT been dequantized; we
shoaib_ahmed 0:791a779d6220 452 merge dequantization and inverse DCT into a single step for speed reasons.
shoaib_ahmed 0:791a779d6220 453 When scaled-down output is asked for, simplified DCT algorithms may be used
shoaib_ahmed 0:791a779d6220 454 that need fewer coefficients and emit fewer samples per DCT block, not the
shoaib_ahmed 0:791a779d6220 455 full 8x8. Works on one DCT block at a time.
shoaib_ahmed 0:791a779d6220 456
shoaib_ahmed 0:791a779d6220 457 * Postprocessing controller: buffer controller for the color quantization
shoaib_ahmed 0:791a779d6220 458 input buffer, when quantization is in use. (Without quantization, this
shoaib_ahmed 0:791a779d6220 459 controller just calls the upsampler.) For two-pass quantization, this
shoaib_ahmed 0:791a779d6220 460 controller is responsible for buffering the full-image data.
shoaib_ahmed 0:791a779d6220 461
shoaib_ahmed 0:791a779d6220 462 * Upsampling: restores chroma components to full size. (May support more
shoaib_ahmed 0:791a779d6220 463 general output rescaling, too. Note that if undersized DCT outputs have
shoaib_ahmed 0:791a779d6220 464 been emitted by the DCT module, this module must adjust so that properly
shoaib_ahmed 0:791a779d6220 465 sized outputs are created.) Works on one row group at a time. This module
shoaib_ahmed 0:791a779d6220 466 also calls the color conversion module, so its top level is effectively a
shoaib_ahmed 0:791a779d6220 467 buffer controller for the upsampling->color conversion buffer. However, in
shoaib_ahmed 0:791a779d6220 468 all but the highest-quality operating modes, upsampling and color
shoaib_ahmed 0:791a779d6220 469 conversion are likely to be merged into a single step.
shoaib_ahmed 0:791a779d6220 470
shoaib_ahmed 0:791a779d6220 471 * Colorspace conversion: convert from JPEG color space to output color space,
shoaib_ahmed 0:791a779d6220 472 and change data layout from separate component planes to pixel-interleaved.
shoaib_ahmed 0:791a779d6220 473 Works on one pixel row at a time.
shoaib_ahmed 0:791a779d6220 474
shoaib_ahmed 0:791a779d6220 475 * Color quantization: reduce the data to colormapped form, using either an
shoaib_ahmed 0:791a779d6220 476 externally specified colormap or an internally generated one. This module
shoaib_ahmed 0:791a779d6220 477 is not used for full-color output. Works on one pixel row at a time; may
shoaib_ahmed 0:791a779d6220 478 require two passes to generate a color map. Note that the output will
shoaib_ahmed 0:791a779d6220 479 always be a single component representing colormap indexes. In the current
shoaib_ahmed 0:791a779d6220 480 design, the output values are JSAMPLEs, so an 8-bit compilation cannot
shoaib_ahmed 0:791a779d6220 481 quantize to more than 256 colors. This is unlikely to be a problem in
shoaib_ahmed 0:791a779d6220 482 practice.
shoaib_ahmed 0:791a779d6220 483
shoaib_ahmed 0:791a779d6220 484 * Color reduction: this module handles color precision reduction, e.g.,
shoaib_ahmed 0:791a779d6220 485 generating 15-bit color (5 bits/primary) from JPEG's 24-bit output.
shoaib_ahmed 0:791a779d6220 486 Not quite clear yet how this should be handled... should we merge it with
shoaib_ahmed 0:791a779d6220 487 colorspace conversion???
shoaib_ahmed 0:791a779d6220 488
shoaib_ahmed 0:791a779d6220 489 Note that some high-speed operating modes might condense the entire
shoaib_ahmed 0:791a779d6220 490 postprocessing sequence to a single module (upsample, color convert, and
shoaib_ahmed 0:791a779d6220 491 quantize in one step).
shoaib_ahmed 0:791a779d6220 492
shoaib_ahmed 0:791a779d6220 493 In addition to the above objects, the decompression library includes these
shoaib_ahmed 0:791a779d6220 494 objects:
shoaib_ahmed 0:791a779d6220 495
shoaib_ahmed 0:791a779d6220 496 * Master control: determines the number of passes required, controls overall
shoaib_ahmed 0:791a779d6220 497 and per-pass initialization of the other modules. This is subdivided into
shoaib_ahmed 0:791a779d6220 498 input and output control: jdinput.c controls only input-side processing,
shoaib_ahmed 0:791a779d6220 499 while jdmaster.c handles overall initialization and output-side control.
shoaib_ahmed 0:791a779d6220 500
shoaib_ahmed 0:791a779d6220 501 * Marker reading: decodes JPEG markers (except for RSTn).
shoaib_ahmed 0:791a779d6220 502
shoaib_ahmed 0:791a779d6220 503 * Data source manager: supplies the input JPEG datastream. The source
shoaib_ahmed 0:791a779d6220 504 manager supplied with the library knows how to read from a stdio stream
shoaib_ahmed 0:791a779d6220 505 or from a memory buffer; for other behaviors, the surrounding application
shoaib_ahmed 0:791a779d6220 506 may provide its own source manager.
shoaib_ahmed 0:791a779d6220 507
shoaib_ahmed 0:791a779d6220 508 * Memory manager: same as for compression library.
shoaib_ahmed 0:791a779d6220 509
shoaib_ahmed 0:791a779d6220 510 * Error handler: same as for compression library.
shoaib_ahmed 0:791a779d6220 511
shoaib_ahmed 0:791a779d6220 512 * Progress monitor: same as for compression library.
shoaib_ahmed 0:791a779d6220 513
shoaib_ahmed 0:791a779d6220 514 As with compression, the data source manager, error handler, and progress
shoaib_ahmed 0:791a779d6220 515 monitor are candidates for replacement by a surrounding application.
shoaib_ahmed 0:791a779d6220 516
shoaib_ahmed 0:791a779d6220 517
shoaib_ahmed 0:791a779d6220 518 *** Decompression input and output separation ***
shoaib_ahmed 0:791a779d6220 519
shoaib_ahmed 0:791a779d6220 520 To support efficient incremental display of progressive JPEG files, the
shoaib_ahmed 0:791a779d6220 521 decompressor is divided into two sections that can run independently:
shoaib_ahmed 0:791a779d6220 522
shoaib_ahmed 0:791a779d6220 523 1. Data input includes marker parsing, entropy decoding, and input into the
shoaib_ahmed 0:791a779d6220 524 coefficient controller's DCT coefficient buffer. Note that this
shoaib_ahmed 0:791a779d6220 525 processing is relatively cheap and fast.
shoaib_ahmed 0:791a779d6220 526
shoaib_ahmed 0:791a779d6220 527 2. Data output reads from the DCT coefficient buffer and performs the IDCT
shoaib_ahmed 0:791a779d6220 528 and all postprocessing steps.
shoaib_ahmed 0:791a779d6220 529
shoaib_ahmed 0:791a779d6220 530 For a progressive JPEG file, the data input processing is allowed to get
shoaib_ahmed 0:791a779d6220 531 arbitrarily far ahead of the data output processing. (This occurs only
shoaib_ahmed 0:791a779d6220 532 if the application calls jpeg_consume_input(); otherwise input and output
shoaib_ahmed 0:791a779d6220 533 run in lockstep, since the input section is called only when the output
shoaib_ahmed 0:791a779d6220 534 section needs more data.) In this way the application can avoid making
shoaib_ahmed 0:791a779d6220 535 extra display passes when data is arriving faster than the display pass
shoaib_ahmed 0:791a779d6220 536 can run. Furthermore, it is possible to abort an output pass without
shoaib_ahmed 0:791a779d6220 537 losing anything, since the coefficient buffer is read-only as far as the
shoaib_ahmed 0:791a779d6220 538 output section is concerned. See libjpeg.txt for more detail.
shoaib_ahmed 0:791a779d6220 539
shoaib_ahmed 0:791a779d6220 540 A full-image coefficient array is only created if the JPEG file has multiple
shoaib_ahmed 0:791a779d6220 541 scans (or if the application specifies buffered-image mode anyway). When
shoaib_ahmed 0:791a779d6220 542 reading a single-scan file, the coefficient controller normally creates only
shoaib_ahmed 0:791a779d6220 543 a one-MCU buffer, so input and output processing must run in lockstep in this
shoaib_ahmed 0:791a779d6220 544 case. jpeg_consume_input() is effectively a no-op in this situation.
shoaib_ahmed 0:791a779d6220 545
shoaib_ahmed 0:791a779d6220 546 The main impact of dividing the decompressor in this fashion is that we must
shoaib_ahmed 0:791a779d6220 547 be very careful with shared variables in the cinfo data structure. Each
shoaib_ahmed 0:791a779d6220 548 variable that can change during the course of decompression must be
shoaib_ahmed 0:791a779d6220 549 classified as belonging to data input or data output, and each section must
shoaib_ahmed 0:791a779d6220 550 look only at its own variables. For example, the data output section may not
shoaib_ahmed 0:791a779d6220 551 depend on any of the variables that describe the current scan in the JPEG
shoaib_ahmed 0:791a779d6220 552 file, because these may change as the data input section advances into a new
shoaib_ahmed 0:791a779d6220 553 scan.
shoaib_ahmed 0:791a779d6220 554
shoaib_ahmed 0:791a779d6220 555 The progress monitor is (somewhat arbitrarily) defined to treat input of the
shoaib_ahmed 0:791a779d6220 556 file as one pass when buffered-image mode is not used, and to ignore data
shoaib_ahmed 0:791a779d6220 557 input work completely when buffered-image mode is used. Note that the
shoaib_ahmed 0:791a779d6220 558 library has no reliable way to predict the number of passes when dealing
shoaib_ahmed 0:791a779d6220 559 with a progressive JPEG file, nor can it predict the number of output passes
shoaib_ahmed 0:791a779d6220 560 in buffered-image mode. So the work estimate is inherently bogus anyway.
shoaib_ahmed 0:791a779d6220 561
shoaib_ahmed 0:791a779d6220 562 No comparable division is currently made in the compression library, because
shoaib_ahmed 0:791a779d6220 563 there isn't any real need for it.
shoaib_ahmed 0:791a779d6220 564
shoaib_ahmed 0:791a779d6220 565
shoaib_ahmed 0:791a779d6220 566 *** Data formats ***
shoaib_ahmed 0:791a779d6220 567
shoaib_ahmed 0:791a779d6220 568 Arrays of pixel sample values use the following data structure:
shoaib_ahmed 0:791a779d6220 569
shoaib_ahmed 0:791a779d6220 570 typedef something JSAMPLE; a pixel component value, 0..MAXJSAMPLE
shoaib_ahmed 0:791a779d6220 571 typedef JSAMPLE *JSAMPROW; ptr to a row of samples
shoaib_ahmed 0:791a779d6220 572 typedef JSAMPROW *JSAMPARRAY; ptr to a list of rows
shoaib_ahmed 0:791a779d6220 573 typedef JSAMPARRAY *JSAMPIMAGE; ptr to a list of color-component arrays
shoaib_ahmed 0:791a779d6220 574
shoaib_ahmed 0:791a779d6220 575 The basic element type JSAMPLE will typically be one of unsigned char,
shoaib_ahmed 0:791a779d6220 576 (signed) char, or short. Short will be used if samples wider than 8 bits are
shoaib_ahmed 0:791a779d6220 577 to be supported (this is a compile-time option). Otherwise, unsigned char is
shoaib_ahmed 0:791a779d6220 578 used if possible. If the compiler only supports signed chars, then it is
shoaib_ahmed 0:791a779d6220 579 necessary to mask off the value when reading. Thus, all reads of JSAMPLE
shoaib_ahmed 0:791a779d6220 580 values must be coded as "GETJSAMPLE(value)", where the macro will be defined
shoaib_ahmed 0:791a779d6220 581 as "((value) & 0xFF)" on signed-char machines and "((int) (value))" elsewhere.
shoaib_ahmed 0:791a779d6220 582
shoaib_ahmed 0:791a779d6220 583 With these conventions, JSAMPLE values can be assumed to be >= 0. This helps
shoaib_ahmed 0:791a779d6220 584 simplify correct rounding during downsampling, etc. The JPEG standard's
shoaib_ahmed 0:791a779d6220 585 specification that sample values run from -128..127 is accommodated by
shoaib_ahmed 0:791a779d6220 586 subtracting 128 from the sample value in the DCT step. Similarly, during
shoaib_ahmed 0:791a779d6220 587 decompression the output of the IDCT step will be immediately shifted back to
shoaib_ahmed 0:791a779d6220 588 0..255. (NB: different values are required when 12-bit samples are in use.
shoaib_ahmed 0:791a779d6220 589 The code is written in terms of MAXJSAMPLE and CENTERJSAMPLE, which will be
shoaib_ahmed 0:791a779d6220 590 defined as 255 and 128 respectively in an 8-bit implementation, and as 4095
shoaib_ahmed 0:791a779d6220 591 and 2048 in a 12-bit implementation.)
shoaib_ahmed 0:791a779d6220 592
shoaib_ahmed 0:791a779d6220 593 We use a pointer per row, rather than a two-dimensional JSAMPLE array. This
shoaib_ahmed 0:791a779d6220 594 choice costs only a small amount of memory and has several benefits:
shoaib_ahmed 0:791a779d6220 595 * Code using the data structure doesn't need to know the allocated width of
shoaib_ahmed 0:791a779d6220 596 the rows. This simplifies edge expansion/compression, since we can work
shoaib_ahmed 0:791a779d6220 597 in an array that's wider than the logical picture width.
shoaib_ahmed 0:791a779d6220 598 * Indexing doesn't require multiplication; this is a performance win on many
shoaib_ahmed 0:791a779d6220 599 machines.
shoaib_ahmed 0:791a779d6220 600 * Arrays with more than 64K total elements can be supported even on machines
shoaib_ahmed 0:791a779d6220 601 where malloc() cannot allocate chunks larger than 64K.
shoaib_ahmed 0:791a779d6220 602 * The rows forming a component array may be allocated at different times
shoaib_ahmed 0:791a779d6220 603 without extra copying. This trick allows some speedups in smoothing steps
shoaib_ahmed 0:791a779d6220 604 that need access to the previous and next rows.
shoaib_ahmed 0:791a779d6220 605
shoaib_ahmed 0:791a779d6220 606 Note that each color component is stored in a separate array; we don't use the
shoaib_ahmed 0:791a779d6220 607 traditional layout in which the components of a pixel are stored together.
shoaib_ahmed 0:791a779d6220 608 This simplifies coding of modules that work on each component independently,
shoaib_ahmed 0:791a779d6220 609 because they don't need to know how many components there are. Furthermore,
shoaib_ahmed 0:791a779d6220 610 we can read or write each component to a temporary file independently, which
shoaib_ahmed 0:791a779d6220 611 is helpful when dealing with noninterleaved JPEG files.
shoaib_ahmed 0:791a779d6220 612
shoaib_ahmed 0:791a779d6220 613 In general, a specific sample value is accessed by code such as
shoaib_ahmed 0:791a779d6220 614 GETJSAMPLE(image[colorcomponent][row][col])
shoaib_ahmed 0:791a779d6220 615 where col is measured from the image left edge, but row is measured from the
shoaib_ahmed 0:791a779d6220 616 first sample row currently in memory. Either of the first two indexings can
shoaib_ahmed 0:791a779d6220 617 be precomputed by copying the relevant pointer.
shoaib_ahmed 0:791a779d6220 618
shoaib_ahmed 0:791a779d6220 619
shoaib_ahmed 0:791a779d6220 620 Since most image-processing applications prefer to work on images in which
shoaib_ahmed 0:791a779d6220 621 the components of a pixel are stored together, the data passed to or from the
shoaib_ahmed 0:791a779d6220 622 surrounding application uses the traditional convention: a single pixel is
shoaib_ahmed 0:791a779d6220 623 represented by N consecutive JSAMPLE values, and an image row is an array of
shoaib_ahmed 0:791a779d6220 624 (# of color components)*(image width) JSAMPLEs. One or more rows of data can
shoaib_ahmed 0:791a779d6220 625 be represented by a pointer of type JSAMPARRAY in this scheme. This scheme is
shoaib_ahmed 0:791a779d6220 626 converted to component-wise storage inside the JPEG library. (Applications
shoaib_ahmed 0:791a779d6220 627 that want to skip JPEG preprocessing or postprocessing will have to contend
shoaib_ahmed 0:791a779d6220 628 with component-wise storage.)
shoaib_ahmed 0:791a779d6220 629
shoaib_ahmed 0:791a779d6220 630
shoaib_ahmed 0:791a779d6220 631 Arrays of DCT-coefficient values use the following data structure:
shoaib_ahmed 0:791a779d6220 632
shoaib_ahmed 0:791a779d6220 633 typedef short JCOEF; a 16-bit signed integer
shoaib_ahmed 0:791a779d6220 634 typedef JCOEF JBLOCK[DCTSIZE2]; an 8x8 block of coefficients
shoaib_ahmed 0:791a779d6220 635 typedef JBLOCK *JBLOCKROW; ptr to one horizontal row of 8x8 blocks
shoaib_ahmed 0:791a779d6220 636 typedef JBLOCKROW *JBLOCKARRAY; ptr to a list of such rows
shoaib_ahmed 0:791a779d6220 637 typedef JBLOCKARRAY *JBLOCKIMAGE; ptr to a list of color component arrays
shoaib_ahmed 0:791a779d6220 638
shoaib_ahmed 0:791a779d6220 639 The underlying type is at least a 16-bit signed integer; while "short" is big
shoaib_ahmed 0:791a779d6220 640 enough on all machines of interest, on some machines it is preferable to use
shoaib_ahmed 0:791a779d6220 641 "int" for speed reasons, despite the storage cost. Coefficients are grouped
shoaib_ahmed 0:791a779d6220 642 into 8x8 blocks (but we always use #defines DCTSIZE and DCTSIZE2 rather than
shoaib_ahmed 0:791a779d6220 643 "8" and "64").
shoaib_ahmed 0:791a779d6220 644
shoaib_ahmed 0:791a779d6220 645 The contents of a coefficient block may be in either "natural" or zigzagged
shoaib_ahmed 0:791a779d6220 646 order, and may be true values or divided by the quantization coefficients,
shoaib_ahmed 0:791a779d6220 647 depending on where the block is in the processing pipeline. In the current
shoaib_ahmed 0:791a779d6220 648 library, coefficient blocks are kept in natural order everywhere; the entropy
shoaib_ahmed 0:791a779d6220 649 codecs zigzag or dezigzag the data as it is written or read. The blocks
shoaib_ahmed 0:791a779d6220 650 contain quantized coefficients everywhere outside the DCT/IDCT subsystems.
shoaib_ahmed 0:791a779d6220 651 (This latter decision may need to be revisited to support variable
shoaib_ahmed 0:791a779d6220 652 quantization a la JPEG Part 3.)
shoaib_ahmed 0:791a779d6220 653
shoaib_ahmed 0:791a779d6220 654 Notice that the allocation unit is now a row of 8x8 coefficient blocks,
shoaib_ahmed 0:791a779d6220 655 corresponding to block_size rows of samples. Otherwise the structure
shoaib_ahmed 0:791a779d6220 656 is much the same as for samples, and for the same reasons.
shoaib_ahmed 0:791a779d6220 657
shoaib_ahmed 0:791a779d6220 658 On machines where malloc() can't handle a request bigger than 64Kb, this data
shoaib_ahmed 0:791a779d6220 659 structure limits us to rows of less than 512 JBLOCKs, or a picture width of
shoaib_ahmed 0:791a779d6220 660 4000+ pixels. This seems an acceptable restriction.
shoaib_ahmed 0:791a779d6220 661
shoaib_ahmed 0:791a779d6220 662
shoaib_ahmed 0:791a779d6220 663 On 80x86 machines, the bottom-level pointer types (JSAMPROW and JBLOCKROW)
shoaib_ahmed 0:791a779d6220 664 must be declared as "far" pointers, but the upper levels can be "near"
shoaib_ahmed 0:791a779d6220 665 (implying that the pointer lists are allocated in the DS segment).
shoaib_ahmed 0:791a779d6220 666 We use a #define symbol FAR, which expands to the "far" keyword when
shoaib_ahmed 0:791a779d6220 667 compiling on 80x86 machines and to nothing elsewhere.
shoaib_ahmed 0:791a779d6220 668
shoaib_ahmed 0:791a779d6220 669
shoaib_ahmed 0:791a779d6220 670 *** Suspendable processing ***
shoaib_ahmed 0:791a779d6220 671
shoaib_ahmed 0:791a779d6220 672 In some applications it is desirable to use the JPEG library as an
shoaib_ahmed 0:791a779d6220 673 incremental, memory-to-memory filter. In this situation the data source or
shoaib_ahmed 0:791a779d6220 674 destination may be a limited-size buffer, and we can't rely on being able to
shoaib_ahmed 0:791a779d6220 675 empty or refill the buffer at arbitrary times. Instead the application would
shoaib_ahmed 0:791a779d6220 676 like to have control return from the library at buffer overflow/underrun, and
shoaib_ahmed 0:791a779d6220 677 then resume compression or decompression at a later time.
shoaib_ahmed 0:791a779d6220 678
shoaib_ahmed 0:791a779d6220 679 This scenario is supported for simple cases. (For anything more complex, we
shoaib_ahmed 0:791a779d6220 680 recommend that the application "bite the bullet" and develop real multitasking
shoaib_ahmed 0:791a779d6220 681 capability.) The libjpeg.txt file goes into more detail about the usage and
shoaib_ahmed 0:791a779d6220 682 limitations of this capability; here we address the implications for library
shoaib_ahmed 0:791a779d6220 683 structure.
shoaib_ahmed 0:791a779d6220 684
shoaib_ahmed 0:791a779d6220 685 The essence of the problem is that the entropy codec (coder or decoder) must
shoaib_ahmed 0:791a779d6220 686 be prepared to stop at arbitrary times. In turn, the controllers that call
shoaib_ahmed 0:791a779d6220 687 the entropy codec must be able to stop before having produced or consumed all
shoaib_ahmed 0:791a779d6220 688 the data that they normally would handle in one call. That part is reasonably
shoaib_ahmed 0:791a779d6220 689 straightforward: we make the controller call interfaces include "progress
shoaib_ahmed 0:791a779d6220 690 counters" which indicate the number of data chunks successfully processed, and
shoaib_ahmed 0:791a779d6220 691 we require callers to test the counter rather than just assume all of the data
shoaib_ahmed 0:791a779d6220 692 was processed.
shoaib_ahmed 0:791a779d6220 693
shoaib_ahmed 0:791a779d6220 694 Rather than trying to restart at an arbitrary point, the current Huffman
shoaib_ahmed 0:791a779d6220 695 codecs are designed to restart at the beginning of the current MCU after a
shoaib_ahmed 0:791a779d6220 696 suspension due to buffer overflow/underrun. At the start of each call, the
shoaib_ahmed 0:791a779d6220 697 codec's internal state is loaded from permanent storage (in the JPEG object
shoaib_ahmed 0:791a779d6220 698 structures) into local variables. On successful completion of the MCU, the
shoaib_ahmed 0:791a779d6220 699 permanent state is updated. (This copying is not very expensive, and may even
shoaib_ahmed 0:791a779d6220 700 lead to *improved* performance if the local variables can be registerized.)
shoaib_ahmed 0:791a779d6220 701 If a suspension occurs, the codec simply returns without updating the state,
shoaib_ahmed 0:791a779d6220 702 thus effectively reverting to the start of the MCU. Note that this implies
shoaib_ahmed 0:791a779d6220 703 leaving some data unprocessed in the source/destination buffer (ie, the
shoaib_ahmed 0:791a779d6220 704 compressed partial MCU). The data source/destination module interfaces are
shoaib_ahmed 0:791a779d6220 705 specified so as to make this possible. This also implies that the data buffer
shoaib_ahmed 0:791a779d6220 706 must be large enough to hold a worst-case compressed MCU; a couple thousand
shoaib_ahmed 0:791a779d6220 707 bytes should be enough.
shoaib_ahmed 0:791a779d6220 708
shoaib_ahmed 0:791a779d6220 709 In a successive-approximation AC refinement scan, the progressive Huffman
shoaib_ahmed 0:791a779d6220 710 decoder has to be able to undo assignments of newly nonzero coefficients if it
shoaib_ahmed 0:791a779d6220 711 suspends before the MCU is complete, since decoding requires distinguishing
shoaib_ahmed 0:791a779d6220 712 previously-zero and previously-nonzero coefficients. This is a bit tedious
shoaib_ahmed 0:791a779d6220 713 but probably won't have much effect on performance. Other variants of Huffman
shoaib_ahmed 0:791a779d6220 714 decoding need not worry about this, since they will just store the same values
shoaib_ahmed 0:791a779d6220 715 again if forced to repeat the MCU.
shoaib_ahmed 0:791a779d6220 716
shoaib_ahmed 0:791a779d6220 717 This approach would probably not work for an arithmetic codec, since its
shoaib_ahmed 0:791a779d6220 718 modifiable state is quite large and couldn't be copied cheaply. Instead it
shoaib_ahmed 0:791a779d6220 719 would have to suspend and resume exactly at the point of the buffer end.
shoaib_ahmed 0:791a779d6220 720
shoaib_ahmed 0:791a779d6220 721 The JPEG marker reader is designed to cope with suspension at an arbitrary
shoaib_ahmed 0:791a779d6220 722 point. It does so by backing up to the start of the marker parameter segment,
shoaib_ahmed 0:791a779d6220 723 so the data buffer must be big enough to hold the largest marker of interest.
shoaib_ahmed 0:791a779d6220 724 Again, a couple KB should be adequate. (A special "skip" convention is used
shoaib_ahmed 0:791a779d6220 725 to bypass COM and APPn markers, so these can be larger than the buffer size
shoaib_ahmed 0:791a779d6220 726 without causing problems; otherwise a 64K buffer would be needed in the worst
shoaib_ahmed 0:791a779d6220 727 case.)
shoaib_ahmed 0:791a779d6220 728
shoaib_ahmed 0:791a779d6220 729 The JPEG marker writer currently does *not* cope with suspension.
shoaib_ahmed 0:791a779d6220 730 We feel that this is not necessary; it is much easier simply to require
shoaib_ahmed 0:791a779d6220 731 the application to ensure there is enough buffer space before starting. (An
shoaib_ahmed 0:791a779d6220 732 empty 2K buffer is more than sufficient for the header markers; and ensuring
shoaib_ahmed 0:791a779d6220 733 there are a dozen or two bytes available before calling jpeg_finish_compress()
shoaib_ahmed 0:791a779d6220 734 will suffice for the trailer.) This would not work for writing multi-scan
shoaib_ahmed 0:791a779d6220 735 JPEG files, but we simply do not intend to support that capability with
shoaib_ahmed 0:791a779d6220 736 suspension.
shoaib_ahmed 0:791a779d6220 737
shoaib_ahmed 0:791a779d6220 738
shoaib_ahmed 0:791a779d6220 739 *** Memory manager services ***
shoaib_ahmed 0:791a779d6220 740
shoaib_ahmed 0:791a779d6220 741 The JPEG library's memory manager controls allocation and deallocation of
shoaib_ahmed 0:791a779d6220 742 memory, and it manages large "virtual" data arrays on machines where the
shoaib_ahmed 0:791a779d6220 743 operating system does not provide virtual memory. Note that the same
shoaib_ahmed 0:791a779d6220 744 memory manager serves both compression and decompression operations.
shoaib_ahmed 0:791a779d6220 745
shoaib_ahmed 0:791a779d6220 746 In all cases, allocated objects are tied to a particular compression or
shoaib_ahmed 0:791a779d6220 747 decompression master record, and they will be released when that master
shoaib_ahmed 0:791a779d6220 748 record is destroyed.
shoaib_ahmed 0:791a779d6220 749
shoaib_ahmed 0:791a779d6220 750 The memory manager does not provide explicit deallocation of objects.
shoaib_ahmed 0:791a779d6220 751 Instead, objects are created in "pools" of free storage, and a whole pool
shoaib_ahmed 0:791a779d6220 752 can be freed at once. This approach helps prevent storage-leak bugs, and
shoaib_ahmed 0:791a779d6220 753 it speeds up operations whenever malloc/free are slow (as they often are).
shoaib_ahmed 0:791a779d6220 754 The pools can be regarded as lifetime identifiers for objects. Two
shoaib_ahmed 0:791a779d6220 755 pools/lifetimes are defined:
shoaib_ahmed 0:791a779d6220 756 * JPOOL_PERMANENT lasts until master record is destroyed
shoaib_ahmed 0:791a779d6220 757 * JPOOL_IMAGE lasts until done with image (JPEG datastream)
shoaib_ahmed 0:791a779d6220 758 Permanent lifetime is used for parameters and tables that should be carried
shoaib_ahmed 0:791a779d6220 759 across from one datastream to another; this includes all application-visible
shoaib_ahmed 0:791a779d6220 760 parameters. Image lifetime is used for everything else. (A third lifetime,
shoaib_ahmed 0:791a779d6220 761 JPOOL_PASS = one processing pass, was originally planned. However it was
shoaib_ahmed 0:791a779d6220 762 dropped as not being worthwhile. The actual usage patterns are such that the
shoaib_ahmed 0:791a779d6220 763 peak memory usage would be about the same anyway; and having per-pass storage
shoaib_ahmed 0:791a779d6220 764 substantially complicates the virtual memory allocation rules --- see below.)
shoaib_ahmed 0:791a779d6220 765
shoaib_ahmed 0:791a779d6220 766 The memory manager deals with three kinds of object:
shoaib_ahmed 0:791a779d6220 767 1. "Small" objects. Typically these require no more than 10K-20K total.
shoaib_ahmed 0:791a779d6220 768 2. "Large" objects. These may require tens to hundreds of K depending on
shoaib_ahmed 0:791a779d6220 769 image size. Semantically they behave the same as small objects, but we
shoaib_ahmed 0:791a779d6220 770 distinguish them for two reasons:
shoaib_ahmed 0:791a779d6220 771 * On MS-DOS machines, large objects are referenced by FAR pointers,
shoaib_ahmed 0:791a779d6220 772 small objects by NEAR pointers.
shoaib_ahmed 0:791a779d6220 773 * Pool allocation heuristics may differ for large and small objects.
shoaib_ahmed 0:791a779d6220 774 Note that individual "large" objects cannot exceed the size allowed by
shoaib_ahmed 0:791a779d6220 775 type size_t, which may be 64K or less on some machines.
shoaib_ahmed 0:791a779d6220 776 3. "Virtual" objects. These are large 2-D arrays of JSAMPLEs or JBLOCKs
shoaib_ahmed 0:791a779d6220 777 (typically large enough for the entire image being processed). The
shoaib_ahmed 0:791a779d6220 778 memory manager provides stripwise access to these arrays. On machines
shoaib_ahmed 0:791a779d6220 779 without virtual memory, the rest of the array may be swapped out to a
shoaib_ahmed 0:791a779d6220 780 temporary file.
shoaib_ahmed 0:791a779d6220 781
shoaib_ahmed 0:791a779d6220 782 (Note: JSAMPARRAY and JBLOCKARRAY data structures are a combination of large
shoaib_ahmed 0:791a779d6220 783 objects for the data proper and small objects for the row pointers. For
shoaib_ahmed 0:791a779d6220 784 convenience and speed, the memory manager provides single routines to create
shoaib_ahmed 0:791a779d6220 785 these structures. Similarly, virtual arrays include a small control block
shoaib_ahmed 0:791a779d6220 786 and a JSAMPARRAY or JBLOCKARRAY working buffer, all created with one call.)
shoaib_ahmed 0:791a779d6220 787
shoaib_ahmed 0:791a779d6220 788 In the present implementation, virtual arrays are only permitted to have image
shoaib_ahmed 0:791a779d6220 789 lifespan. (Permanent lifespan would not be reasonable, and pass lifespan is
shoaib_ahmed 0:791a779d6220 790 not very useful since a virtual array's raison d'etre is to store data for
shoaib_ahmed 0:791a779d6220 791 multiple passes through the image.) We also expect that only "small" objects
shoaib_ahmed 0:791a779d6220 792 will be given permanent lifespan, though this restriction is not required by
shoaib_ahmed 0:791a779d6220 793 the memory manager.
shoaib_ahmed 0:791a779d6220 794
shoaib_ahmed 0:791a779d6220 795 In a non-virtual-memory machine, some performance benefit can be gained by
shoaib_ahmed 0:791a779d6220 796 making the in-memory buffers for virtual arrays be as large as possible.
shoaib_ahmed 0:791a779d6220 797 (For small images, the buffers might fit entirely in memory, so blind
shoaib_ahmed 0:791a779d6220 798 swapping would be very wasteful.) The memory manager will adjust the height
shoaib_ahmed 0:791a779d6220 799 of the buffers to fit within a prespecified maximum memory usage. In order
shoaib_ahmed 0:791a779d6220 800 to do this in a reasonably optimal fashion, the manager needs to allocate all
shoaib_ahmed 0:791a779d6220 801 of the virtual arrays at once. Therefore, there isn't a one-step allocation
shoaib_ahmed 0:791a779d6220 802 routine for virtual arrays; instead, there is a "request" routine that simply
shoaib_ahmed 0:791a779d6220 803 allocates the control block, and a "realize" routine (called just once) that
shoaib_ahmed 0:791a779d6220 804 determines space allocation and creates all of the actual buffers. The
shoaib_ahmed 0:791a779d6220 805 realize routine must allow for space occupied by non-virtual large objects.
shoaib_ahmed 0:791a779d6220 806 (We don't bother to factor in the space needed for small objects, on the
shoaib_ahmed 0:791a779d6220 807 grounds that it isn't worth the trouble.)
shoaib_ahmed 0:791a779d6220 808
shoaib_ahmed 0:791a779d6220 809 To support all this, we establish the following protocol for doing business
shoaib_ahmed 0:791a779d6220 810 with the memory manager:
shoaib_ahmed 0:791a779d6220 811 1. Modules must request virtual arrays (which may have only image lifespan)
shoaib_ahmed 0:791a779d6220 812 during the initial setup phase, i.e., in their jinit_xxx routines.
shoaib_ahmed 0:791a779d6220 813 2. All "large" objects (including JSAMPARRAYs and JBLOCKARRAYs) must also be
shoaib_ahmed 0:791a779d6220 814 allocated during initial setup.
shoaib_ahmed 0:791a779d6220 815 3. realize_virt_arrays will be called at the completion of initial setup.
shoaib_ahmed 0:791a779d6220 816 The above conventions ensure that sufficient information is available
shoaib_ahmed 0:791a779d6220 817 for it to choose a good size for virtual array buffers.
shoaib_ahmed 0:791a779d6220 818 Small objects of any lifespan may be allocated at any time. We expect that
shoaib_ahmed 0:791a779d6220 819 the total space used for small objects will be small enough to be negligible
shoaib_ahmed 0:791a779d6220 820 in the realize_virt_arrays computation.
shoaib_ahmed 0:791a779d6220 821
shoaib_ahmed 0:791a779d6220 822 In a virtual-memory machine, we simply pretend that the available space is
shoaib_ahmed 0:791a779d6220 823 infinite, thus causing realize_virt_arrays to decide that it can allocate all
shoaib_ahmed 0:791a779d6220 824 the virtual arrays as full-size in-memory buffers. The overhead of the
shoaib_ahmed 0:791a779d6220 825 virtual-array access protocol is very small when no swapping occurs.
shoaib_ahmed 0:791a779d6220 826
shoaib_ahmed 0:791a779d6220 827 A virtual array can be specified to be "pre-zeroed"; when this flag is set,
shoaib_ahmed 0:791a779d6220 828 never-yet-written sections of the array are set to zero before being made
shoaib_ahmed 0:791a779d6220 829 available to the caller. If this flag is not set, never-written sections
shoaib_ahmed 0:791a779d6220 830 of the array contain garbage. (This feature exists primarily because the
shoaib_ahmed 0:791a779d6220 831 equivalent logic would otherwise be needed in jdcoefct.c for progressive
shoaib_ahmed 0:791a779d6220 832 JPEG mode; we may as well make it available for possible other uses.)
shoaib_ahmed 0:791a779d6220 833
shoaib_ahmed 0:791a779d6220 834 The first write pass on a virtual array is required to occur in top-to-bottom
shoaib_ahmed 0:791a779d6220 835 order; read passes, as well as any write passes after the first one, may
shoaib_ahmed 0:791a779d6220 836 access the array in any order. This restriction exists partly to simplify
shoaib_ahmed 0:791a779d6220 837 the virtual array control logic, and partly because some file systems may not
shoaib_ahmed 0:791a779d6220 838 support seeking beyond the current end-of-file in a temporary file. The main
shoaib_ahmed 0:791a779d6220 839 implication of this restriction is that rearrangement of rows (such as
shoaib_ahmed 0:791a779d6220 840 converting top-to-bottom data order to bottom-to-top) must be handled while
shoaib_ahmed 0:791a779d6220 841 reading data out of the virtual array, not while putting it in.
shoaib_ahmed 0:791a779d6220 842
shoaib_ahmed 0:791a779d6220 843
shoaib_ahmed 0:791a779d6220 844 *** Memory manager internal structure ***
shoaib_ahmed 0:791a779d6220 845
shoaib_ahmed 0:791a779d6220 846 To isolate system dependencies as much as possible, we have broken the
shoaib_ahmed 0:791a779d6220 847 memory manager into two parts. There is a reasonably system-independent
shoaib_ahmed 0:791a779d6220 848 "front end" (jmemmgr.c) and a "back end" that contains only the code
shoaib_ahmed 0:791a779d6220 849 likely to change across systems. All of the memory management methods
shoaib_ahmed 0:791a779d6220 850 outlined above are implemented by the front end. The back end provides
shoaib_ahmed 0:791a779d6220 851 the following routines for use by the front end (none of these routines
shoaib_ahmed 0:791a779d6220 852 are known to the rest of the JPEG code):
shoaib_ahmed 0:791a779d6220 853
shoaib_ahmed 0:791a779d6220 854 jpeg_mem_init, jpeg_mem_term system-dependent initialization/shutdown
shoaib_ahmed 0:791a779d6220 855
shoaib_ahmed 0:791a779d6220 856 jpeg_get_small, jpeg_free_small interface to malloc and free library routines
shoaib_ahmed 0:791a779d6220 857 (or their equivalents)
shoaib_ahmed 0:791a779d6220 858
shoaib_ahmed 0:791a779d6220 859 jpeg_get_large, jpeg_free_large interface to FAR malloc/free in MSDOS machines;
shoaib_ahmed 0:791a779d6220 860 else usually the same as
shoaib_ahmed 0:791a779d6220 861 jpeg_get_small/jpeg_free_small
shoaib_ahmed 0:791a779d6220 862
shoaib_ahmed 0:791a779d6220 863 jpeg_mem_available estimate available memory
shoaib_ahmed 0:791a779d6220 864
shoaib_ahmed 0:791a779d6220 865 jpeg_open_backing_store create a backing-store object
shoaib_ahmed 0:791a779d6220 866
shoaib_ahmed 0:791a779d6220 867 read_backing_store, manipulate a backing-store object
shoaib_ahmed 0:791a779d6220 868 write_backing_store,
shoaib_ahmed 0:791a779d6220 869 close_backing_store
shoaib_ahmed 0:791a779d6220 870
shoaib_ahmed 0:791a779d6220 871 On some systems there will be more than one type of backing-store object
shoaib_ahmed 0:791a779d6220 872 (specifically, in MS-DOS a backing store file might be an area of extended
shoaib_ahmed 0:791a779d6220 873 memory as well as a disk file). jpeg_open_backing_store is responsible for
shoaib_ahmed 0:791a779d6220 874 choosing how to implement a given object. The read/write/close routines
shoaib_ahmed 0:791a779d6220 875 are method pointers in the structure that describes a given object; this
shoaib_ahmed 0:791a779d6220 876 lets them be different for different object types.
shoaib_ahmed 0:791a779d6220 877
shoaib_ahmed 0:791a779d6220 878 It may be necessary to ensure that backing store objects are explicitly
shoaib_ahmed 0:791a779d6220 879 released upon abnormal program termination. For example, MS-DOS won't free
shoaib_ahmed 0:791a779d6220 880 extended memory by itself. To support this, we will expect the main program
shoaib_ahmed 0:791a779d6220 881 or surrounding application to arrange to call self_destruct (typically via
shoaib_ahmed 0:791a779d6220 882 jpeg_destroy) upon abnormal termination. This may require a SIGINT signal
shoaib_ahmed 0:791a779d6220 883 handler or equivalent. We don't want to have the back end module install its
shoaib_ahmed 0:791a779d6220 884 own signal handler, because that would pre-empt the surrounding application's
shoaib_ahmed 0:791a779d6220 885 ability to control signal handling.
shoaib_ahmed 0:791a779d6220 886
shoaib_ahmed 0:791a779d6220 887 The IJG distribution includes several memory manager back end implementations.
shoaib_ahmed 0:791a779d6220 888 Usually the same back end should be suitable for all applications on a given
shoaib_ahmed 0:791a779d6220 889 system, but it is possible for an application to supply its own back end at
shoaib_ahmed 0:791a779d6220 890 need.
shoaib_ahmed 0:791a779d6220 891
shoaib_ahmed 0:791a779d6220 892
shoaib_ahmed 0:791a779d6220 893 *** Implications of DNL marker ***
shoaib_ahmed 0:791a779d6220 894
shoaib_ahmed 0:791a779d6220 895 Some JPEG files may use a DNL marker to postpone definition of the image
shoaib_ahmed 0:791a779d6220 896 height (this would be useful for a fax-like scanner's output, for instance).
shoaib_ahmed 0:791a779d6220 897 In these files the SOF marker claims the image height is 0, and you only
shoaib_ahmed 0:791a779d6220 898 find out the true image height at the end of the first scan.
shoaib_ahmed 0:791a779d6220 899
shoaib_ahmed 0:791a779d6220 900 We could read these files as follows:
shoaib_ahmed 0:791a779d6220 901 1. Upon seeing zero image height, replace it by 65535 (the maximum allowed).
shoaib_ahmed 0:791a779d6220 902 2. When the DNL is found, update the image height in the global image
shoaib_ahmed 0:791a779d6220 903 descriptor.
shoaib_ahmed 0:791a779d6220 904 This implies that control modules must avoid making copies of the image
shoaib_ahmed 0:791a779d6220 905 height, and must re-test for termination after each MCU row. This would
shoaib_ahmed 0:791a779d6220 906 be easy enough to do.
shoaib_ahmed 0:791a779d6220 907
shoaib_ahmed 0:791a779d6220 908 In cases where image-size data structures are allocated, this approach will
shoaib_ahmed 0:791a779d6220 909 result in very inefficient use of virtual memory or much-larger-than-necessary
shoaib_ahmed 0:791a779d6220 910 temporary files. This seems acceptable for something that probably won't be a
shoaib_ahmed 0:791a779d6220 911 mainstream usage. People might have to forgo use of memory-hogging options
shoaib_ahmed 0:791a779d6220 912 (such as two-pass color quantization or noninterleaved JPEG files) if they
shoaib_ahmed 0:791a779d6220 913 want efficient conversion of such files. (One could improve efficiency by
shoaib_ahmed 0:791a779d6220 914 demanding a user-supplied upper bound for the height, less than 65536; in most
shoaib_ahmed 0:791a779d6220 915 cases it could be much less.)
shoaib_ahmed 0:791a779d6220 916
shoaib_ahmed 0:791a779d6220 917 The standard also permits the SOF marker to overestimate the image height,
shoaib_ahmed 0:791a779d6220 918 with a DNL to give the true, smaller height at the end of the first scan.
shoaib_ahmed 0:791a779d6220 919 This would solve the space problems if the overestimate wasn't too great.
shoaib_ahmed 0:791a779d6220 920 However, it implies that you don't even know whether DNL will be used.
shoaib_ahmed 0:791a779d6220 921
shoaib_ahmed 0:791a779d6220 922 This leads to a couple of very serious objections:
shoaib_ahmed 0:791a779d6220 923 1. Testing for a DNL marker must occur in the inner loop of the decompressor's
shoaib_ahmed 0:791a779d6220 924 Huffman decoder; this implies a speed penalty whether the feature is used
shoaib_ahmed 0:791a779d6220 925 or not.
shoaib_ahmed 0:791a779d6220 926 2. There is no way to hide the last-minute change in image height from an
shoaib_ahmed 0:791a779d6220 927 application using the decoder. Thus *every* application using the IJG
shoaib_ahmed 0:791a779d6220 928 library would suffer a complexity penalty whether it cared about DNL or
shoaib_ahmed 0:791a779d6220 929 not.
shoaib_ahmed 0:791a779d6220 930 We currently do not support DNL because of these problems.
shoaib_ahmed 0:791a779d6220 931
shoaib_ahmed 0:791a779d6220 932 A different approach is to insist that DNL-using files be preprocessed by a
shoaib_ahmed 0:791a779d6220 933 separate program that reads ahead to the DNL, then goes back and fixes the SOF
shoaib_ahmed 0:791a779d6220 934 marker. This is a much simpler solution and is probably far more efficient.
shoaib_ahmed 0:791a779d6220 935 Even if one wants piped input, buffering the first scan of the JPEG file needs
shoaib_ahmed 0:791a779d6220 936 a lot smaller temp file than is implied by the maximum-height method. For
shoaib_ahmed 0:791a779d6220 937 this approach we'd simply treat DNL as a no-op in the decompressor (at most,
shoaib_ahmed 0:791a779d6220 938 check that it matches the SOF image height).
shoaib_ahmed 0:791a779d6220 939
shoaib_ahmed 0:791a779d6220 940 We will not worry about making the compressor capable of outputting DNL.
shoaib_ahmed 0:791a779d6220 941 Something similar to the first scheme above could be applied if anyone ever
shoaib_ahmed 0:791a779d6220 942 wants to make that work.